Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update and reorganize XRC overview to make it more useful.

Browse Source 
Emphasize the parts most useful for the new users instead of more advanced
concepts and generally make the text more readable.

Closes #12661.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@66056 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Vadim Zeitlin
2010-11-07 14:00:19 +00:00
parent 955bad410e
commit 5fcef18409
4 changed files with 230 additions and 349 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/doxygen/mainpages/samples.h
View File

@@ -538,10 +538,10 @@ The not very clearly named internat sample demonstrates the wxWidgets
internationalization (i18n for short from now on) features. To be more
precise, it only shows localization support, i.e. support for translating the
program messages into another language while true i18n would also involve
changing the other aspects of the programs behaviour.
changing the other aspects of the program's behaviour.
More information about this sample can be found in the @c readme.txt file in
its directory. Please also see the @ref overview_i18n.
its directory. Please also see the @ref overview_i18n overview.
@sampledir{internat}
@@ -664,9 +664,9 @@ a good starting point for learning how to use wxWidgets.
This samples shows wxBookCtrl family of controls.
Although initially it was written to demonstrate wxNotebook
only, it can now be also used to see wxListbook,
wxChoicebook and wxTreebook in action.
wxChoicebook, wxTreebook and wxToolbook in action.
Test each of the controls, their orientation, images and pages using
commands through menu.
commands through the menu.
@sampledir{notebook}
@@ -922,8 +922,8 @@ wxClipboard and to paste text from it. The GTK version will
use the so called PRIMARY SELECTION, which is the pseudo clipboard under X and
best known from pasting text to the XTerm program.
Last not least: some of the text controls have tooltips and the sample also shows
how tooltips can be centrally disabled and their latency controlled.
Last but not least: some of the text controls have tooltips and the sample also
shows how tooltips can be centrally disabled and their latency controlled.
@sampledir{text}
@@ -1062,7 +1062,19 @@ features supported:
@section page_samples_xrc XRC Sample
@sampleabout{@ref overview_xrc}
This sample shows how to use the various features of the @ref overview_xrc to
create the gui of your program. It starts by loading and showing a frame and
other resources. From its menu or toolbar you can then run the following dialogs:
@li A non-derived wxDialog
@li A derived dialog
@li A dialog containing a large number of controls
@li An uncentred dialog
@li A dialog demonstrating the use of object references and ID ranges
@li A dialog that contains a custom class
@li A dialog with platform-specific features
@li A dialog demonstrating wxArtProvider
@li A dialog saying "VARIABLE EXPANSION ISN'T IMPLEMENTED CURRENTLY" :/
@sampledir{xrc}

541
docs/doxygen/overviews/xrc.h
View File

@@ -36,65 +36,229 @@ There are several advantages to using XRC resources:
XRC was written by Vaclav Slavik.
@li @ref overview_xrc_concepts
@li @ref overview_xrc_gettingstarted
@li @ref overview_xrc_xrcsample
@li @ref overview_xrc_binaryresourcefiles
@li @ref overview_xrc_embeddedresource
@li @ref overview_xrc_cppsample
@li @ref overview_xrc_sample
@li @ref overview_xrc_cppheader
@li @ref overview_xrc_newresourcehandlers
See also the separate @ref overview_xrcformat page for details about the XRC file format.
<hr>
See also the separate @ref overview_xrcformat page for more information, and
details about the XRC file format.
@section overview_xrc_concepts XRC Concepts
@section overview_xrc_gettingstarted Getting Started with XRC
These are the typical steps for using XRC files in your application.
<b> Creating an XRC file </b>
@li Include the appropriate headers: normally "wx/xrc/xmlres.h" will suffice.
@li If you are going to use XRS files (see
@ref overview_xrc_binaryresourcefiles), install wxFileSystem archive
handler first with wxFileSystem::AddHandler(new wxArchiveFSHandler);
@li Call wxXmlResource::Get()->InitAllHandlers() from your wxApp::OnInit
function, and then call wxXmlResource::Get()->Load("myfile.xrc") to load
the resource file.
@li To create a dialog from a resource, create it using the default
constructor, and then load it. For example:
wxXmlResource::Get()->LoadDialog(dlg, this, "dlg1");
@li Set up event tables as usual but use the XRCID(str) macro to translate from
XRC string names to a suitable integer identifier, for example
<tt>EVT_MENU(XRCID("quit"), MyFrame::OnQuit)</tt>.
You will need to write an XRC file. Though this @e can be done by hand in a
text editor, for all but the smallest files it is advisable to use a
specialised tool. Examples of these include:
To create an XRC file, you can use one of the following methods.
@li Create the file by hand.
@li Use wxDesigner <http://www.roebling.de/>, a commercial dialog designer/RAD
tool.
@li Use DialogBlocks <http://www.anthemion.co.uk/dialogblocks/>, a commercial
@e Non-free:
@li wxDesigner <http://www.wxdesigner-software.de/>, a commercial dialog
designer/RAD tool.
@li DialogBlocks <http://www.anthemion.co.uk/dialogblocks/>, a commercial
dialog editor.
@li Use XRCed <http://xrced.sf.net/>, a wxPython-based dialog editor that you
@e Free:
@li XRCed <http://xrced.sf.net/>, a wxPython-based dialog editor that you
can find in the wxPython/tools subdirectory of the wxWidgets SVN archive.
@li Use wxGlade <http://wxglade.sf.net/>, a GUI designer written in wxPython.
At the moment it can generate Python, C++ and XRC.
@li wxFormBuilder <http://wxformbuilder.org/>, a C++-based dialog editor that
can output C++, XRC or python.
A complete list of third-party tools that write to XRC can be found at
<http://www.wxwidgets.org/wiki/index.php/Tools>.
There's a more complete list at <http://www.wxwidgets.org/wiki/index.php/Tools>
It is highly recommended that you use a resource editing tool, since it's
fiddly writing XRC files by hand.
This small demonstration XRC file contains a simple dialog:
@code
<?xml version="1.0" ?>
<resource version="2.3.0.1">
<object class="wxDialog" name="SimpleDialog">
<title>Simple dialog</title>
<object class="wxBoxSizer">
<orient>wxVERTICAL</orient>
<object class="sizeritem">
<object class="wxTextCtrl" name="text"/>
<option>1</option>
<flag>wxALL|wxEXPAND</flag>
<border>10</border>
</object>
<object class="sizeritem">
<object class="wxBoxSizer">
<object class="sizeritem">
<object class="wxButton" name="clickme_btn">
<label>Click</label>
</object>
<flag>wxRIGHT</flag>
<border>10</border>
</object>
<object class="sizeritem">
<object class="wxButton" name="wxID_OK">
<label>OK</label>
</object>
<flag>wxLEFT</flag>
<border>10</border>
</object>
<orient>wxHORIZONTAL</orient>
</object>
<flag>wxALL|wxALIGN_CENTRE</flag>
<border>10</border>
</object>
</object>
</object>
</resource>
@endcode
You can use wxXmlResource::Load in a number of ways. You can pass an XRC file
(XML-based text resource file) or a zip-compressed file (see
@ref overview_xrc_binaryresourcefiles), with extension ZIP or XRS, containing
other XRC.
You can keep all your XRC elements together in one file, or split them between
several.
You can also use embedded C++ resources (see
@ref overview_xrc_embeddedresource).
<b> Loading XRC files </b>
Before you can use XRC in an app, it must first be loaded. This code fragment
shows how to load a single XRC file "resource.xrc" from the current working
directory, plus all the *.xrc files contained in the subdirectory "rc".
@code
#include "wx/xrc/xmlres.h"
bool MyApp::OnInit()
{
...
wxXmlResource::Get()->InitAllHandlers();
wxXmlResource::Get()->Load("resource.xrc");
wxXmlResource::Get()->LoadAllFiles("rc");
...
}
@endcode
It's normal to load any XRC files at the beginning of an app. Though it is
possible to unload a file later, it's seldom necessary.
@section overview_xrc_binaryresourcefiles Using Binary Resource Files
<b> Using an XRC item </b>
The XRC file(s) are now loaded into the app's virtual filesystem. From there,
you must do another sort of load when you want to use an individual object.
Yes, it's confusingly named, but you first Load() the file, and later load each
top-level object when its needed.
This is how you would use the above simple dialog in your code.
@code
void MyClass::ShowDialog()
{
wxDialog dlg;
if (wxXmlResource::Get()->LoadDialog(&dlg, NULL, "SimpleDialog"))
dlg.ShowModal();
}
@endcode
See how simple the code is. All the instantiation is done invisibly by the XRC
system.
Though you'll most often use wxXmlResource::LoadDialog, there are also
equivalents that load a frame, a menu etc; and the generic
wxXmlResource::LoadObject. See wxXmlResource for more details.
<b> Accessing XRC child controls </b>
The last section showed how to load top-level windows like dialogs, but what
about child windows like the wxTextCtrl named "text" that the dialog contains?
You can't 'load' an individual child control in the same way. Instead you use
the XRCCTRL macro to get a pointer to the child. To expand the previous code:
@code
void MyClass::ShowDialog()
{
wxDialog dlg;
if (!wxXmlResource::Get()->LoadDialog(&dlg, NULL, "SimpleDialog"))
return;
wxTextCtrl* pText = XRCCTRL(dlg, "text", wxTextCtrl);
if (pText)
pText->ChangeValue("This is a simple dialog");
dlg.ShowModal();
}
@endcode
XRCCTRL takes a reference to the parent container and uses wxWindow::FindWindow
to search inside it for a wxWindow with the supplied name (here "text"). It
returns a pointer to that control, cast to the type in the third parameter; so
a similar effect could be obtained by writing:
@code
pText = (wxTextCtrl*)(dlg.FindWindowByName("text"));
@endcode
<b> XRC and IDs </b>
The ID of a control is often needed, e.g. for use in an event table
or with wxEvtHandler::Bind. It can easily be found by passing the name of the
control to the XRCID macro:
@code
void MyClass::ShowDialog()
{
wxDialog dlg;
if (!wxXmlResource::Get()->LoadDialog(&dlg, NULL, "SimpleDialog"))
return;
XRCCTRL(dlg, "text", wxTextCtrl)->Bind(wxEVT_COMMAND_TEXT_UPDATED,
wxTextEventHandler(MyClass::OnTextEntered), this, XRCID("text"));
XRCCTRL(dlg, "clickme_btn", wxButton)->Bind(wxEVT_COMMAND_BUTTON_CLICKED,
wxCommandEventHandler(MyClass::OnClickme), this, XRCID("clickme_btn"));
dlg.ShowModal();
}
@endcode
A few points to note:
@li The value of the int returned by XRCID("foo") is guaranteed to be unique
within an app.
@li However that value isn't predictable, and you shouldn't rely on it being
consistent between runs. It certainly won't be the same in different apps.
@li @ref page_stockitems such as wxID_OK work correctly without requiring XRCID
(because, internally, XRCID("wxID_OK") is mapped to wxID_OK).
@li Both XRCID and XRCCTRL use the 'name' of the control (as in
wxWindow::GetName). This is different from the label that the user sees on
e.g. a wxButton.
<b> Subclassing in XRC </b>
You will often want to use subclassed wx controls in your code. There are three
ways to do this from XRC:
@li Very rarely you might need to
@ref overview_xrcformat_extending_custom "create your own wxXmlResourceHandler"
@li Occasionally wxXmlResource::AttachUnknownControl may be best. See
@ref overview_xrcformat_extending_unknown
@li Usually though, the simple 'subclass' keyword will suffice.
Suppose you wanted the wxTextCtrl named "text" to be created as your derived
class MyTextCtrl. The only change needed in the XRC file would be in this line:
@code
<object class="wxTextCtrl" name="text" subclass="MyTextCtrl"/>
@endcode
The only change in your code would be to use MyTextCtrl in XRCCTRL. However for
the subclass to be created successfully, it's important to ensure that it uses
wxWidget's RTTI mechanism: see @ref overview_xrcformat_extending_subclass for
the details.
@section overview_xrc_xrcsample The XRC sample
A major resource for learning how to use XRC is the @sample{xrc}. This
demonstrates all of the standard uses of XRC, and some of the less common ones.
It is strongly suggested that you run it, and look at the well-commented
source code to see how it works.
@section overview_xrc_binaryresourcefiles Binary Resource Files
To compile binary resource files, use the command-line @c wxrc utility. It
takes one or more file parameters (the input XRC files) and the following
@@ -156,301 +320,6 @@ InitXmlResource();
@endcode
@section overview_xrc_cppsample XRC C++ Sample
This is the C++ source file (xrcdemo.cpp) for the XRC sample.
@code
#include "wx/wx.h"
#include "wx/image.h"
#include "wx/xrc/xmlres.h"
// the application icon
#if defined(__WXGTK__) || defined(__WXMOTIF__) || defined(__WXMAC__)
#include "rc/appicon.xpm"
#endif
// ----------------------------------------------------------------------------
// private classes
// ----------------------------------------------------------------------------
// Define a new application type, each program should derive a class from wxApp
class MyApp : public wxApp
{
public:
// override base class virtuals
// ----------------------------
// this one is called on application startup and is a good place for the
// app initialization (doing it here and not in the ctor allows to have an
// error return: if OnInit() returns false, the application terminates)
virtual bool OnInit();
};
// Define a new frame type: this is going to be our main frame
class MyFrame : public wxFrame
{
public:
// ctor(s)
MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size);
// event handlers (these functions should _not_ be virtual)
void OnQuit(wxCommandEvent& event);
void OnAbout(wxCommandEvent& event);
void OnDlg1(wxCommandEvent& event);
void OnDlg2(wxCommandEvent& event);
private:
// any class wishing to process wxWidgets events must use this macro
DECLARE_EVENT_TABLE()
};
// ----------------------------------------------------------------------------
// event tables and other macros for wxWidgets
// ----------------------------------------------------------------------------
BEGIN_EVENT_TABLE(MyFrame, wxFrame)
EVT_MENU(XRCID("menu_quit"), MyFrame::OnQuit)
EVT_MENU(XRCID("menu_about"), MyFrame::OnAbout)
EVT_MENU(XRCID("menu_dlg1"), MyFrame::OnDlg1)
EVT_MENU(XRCID("menu_dlg2"), MyFrame::OnDlg2)
END_EVENT_TABLE()
IMPLEMENT_APP(MyApp)
// ----------------------------------------------------------------------------
// the application class
// ----------------------------------------------------------------------------
// 'Main program' equivalent: the program execution "starts" here
bool MyApp::OnInit()
{
wxImage::AddHandler(new wxGIFHandler);
wxXmlResource::Get()->InitAllHandlers();
wxXmlResource::Get()->Load("rc/resource.xrc");
MyFrame *frame = new MyFrame("XML resources demo",
wxPoint(50, 50), wxSize(450, 340));
frame->Show(true);
return true;
}
// ----------------------------------------------------------------------------
// main frame
// ----------------------------------------------------------------------------
// frame constructor
MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
: wxFrame((wxFrame *)NULL, -1, title, pos, size)
{
SetIcon(wxICON(appicon));
SetMenuBar(wxXmlResource::Get()->LoadMenuBar("mainmenu"));
SetToolBar(wxXmlResource::Get()->LoadToolBar(this, "toolbar"));
}
// event handlers
void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
{
// true is to force the frame to close
Close(true);
}
void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
{
wxString msg;
msg.Printf( wxT("This is the about dialog of XML resources demo.\n")
wxT("Welcome to %s"), wxVERSION_STRING);
wxMessageBox(msg, "About XML resources demo",
wxOK | wxICON_INFORMATION, this);
}
void MyFrame::OnDlg1(wxCommandEvent& WXUNUSED(event))
{
wxDialog dlg;
wxXmlResource::Get()->LoadDialog(&dlg, this, "dlg1");
dlg.ShowModal();
}
void MyFrame::OnDlg2(wxCommandEvent& WXUNUSED(event))
{
wxDialog dlg;
wxXmlResource::Get()->LoadDialog(&dlg, this, "dlg2");
dlg.ShowModal();
}
@endcode
@section overview_xrc_sample XRC Resource File Sample
This is the XML file (resource.xrc) for the XRC sample.
@code
<?xml version="1.0"?>
<resource version="2.3.0.1">
<object class="wxMenuBar" name="mainmenu">
<style>wxMB_DOCKABLE</style>
<object class="wxMenu" name="menu_file">
<label>_File</label>
<style>wxMENU_TEAROFF</style>
<object class="wxMenuItem" name="menu_about">
<label>_About...</label>
<bitmap>filesave.gif</bitmap>
</object>
<object class="separator"/>
<object class="wxMenuItem" name="menu_dlg1">
<label>Dialog 1</label>
</object>
<object class="wxMenuItem" name="menu_dlg2">
<label>Dialog 2</label>
</object>
<object class="separator"/>
<object class="wxMenuItem" name="menu_quit">
<label>E_xit\tAlt-X</label>
</object>
</object>
</object>
<object class="wxToolBar" name="toolbar">
<style>wxTB_FLAT|wxTB_DOCKABLE</style>
<margins>2,2</margins>
<object class="tool" name="menu_open">
<bitmap>fileopen.gif</bitmap>
<tooltip>Open catalog</tooltip>
</object>
<object class="tool" name="menu_save">
<bitmap>filesave.gif</bitmap>
<tooltip>Save catalog</tooltip>
</object>
<object class="tool" name="menu_update">
<bitmap>update.gif</bitmap>
<tooltip>Update catalog - synchronize it with sources</tooltip>
</object>
<separator/>
<object class="tool" name="menu_quotes">
<bitmap>quotes.gif</bitmap>
<toggle>1</toggle>
<tooltip>Display quotes around the string?</tooltip>
</object>
<object class="separator"/>
<object class="tool" name="menu_fuzzy">
<bitmap>fuzzy.gif</bitmap>
<tooltip>Toggled if selected string is fuzzy translation</tooltip>
<toggle>1</toggle>
</object>
</object>
<object class="wxDialog" name="dlg1">
<object class="wxBoxSizer">
<object class="sizeritem">
<object class="wxBitmapButton">
<bitmap>fuzzy.gif</bitmap>
<focus>fileopen.gif</focus>
</object>
</object>
<object class="sizeritem">
<object class="wxPanel">
<object class="wxStaticText">
<label>fdgdfgdfgdfg</label>
</object>
<style>wxBORDER\_SUNKEN</style>
</object>
<flag>wxALIGN_CENTER</flag>
</object>
<object class="sizeritem">
<object class="wxButton">
<label>Buttonek</label>
</object>
<border>10d</border>
<flag>wxALL</flag>
</object>
<object class="sizeritem">
<object class="wxHtmlWindow">
<htmlcode><h1>Hi,</h1>man</htmlcode>
<size>100,45d</size>
</object>
</object>
<object class="sizeritem">
<object class="wxNotebook">
<object class="notebookpage">
<object class="wxPanel">
<object class="wxBoxSizer">
<object class="sizeritem">
<object class="wxHtmlWindow">
<htmlcode>Hello, we are inside a <u>NOTEBOOK</u>...</htmlcode>
<size>50,50d</size>
</object>
<option>1</option>
</object>
</object>
</object>
<label>Page</label>
<image>0</image>
</object>
<object class="notebookpage">
<object class="wxPanel">
<object class="wxBoxSizer">
<object class="sizeritem">
<object class="wxHtmlWindow">
<htmlcode>Hello, we are inside a <u>NOTEBOOK</u>...</htmlcode>
<size>50,50d</size>
</object>
</object>
</object>
</object>
<label>Page 2</label>
<image>1</image>
</object>
<usenotebooksizer>1</usenotebooksizer>
<imagelist>
<size>16,16</size>
<bitmap stock_id="wxART_QUESTION"/>
<bitmap stock_id="wxART_WARNING"/>
</imagelist>
</object>
<flag>wxEXPAND</flag>
</object>
<orient>wxVERTICAL</orient>
</object>
</object>
<object class="wxDialog" name="dlg2">
<object class="wxBoxSizer">
<orient>wxVERTICAL</orient>
<object class="sizeritem" name="dfgdfg">
<object class="wxTextCtrl">
<size>200,200d</size>
<style>wxTE_MULTILINE|wxBORDER_SUNKEN</style>
<value>Hello, this is an ordinary multiline\n textctrl....</value>
</object>
<option>1</option>
<flag>wxEXPAND|wxALL</flag>
<border>10</border>
</object>
<object class="sizeritem">
<object class="wxBoxSizer">
<object class="sizeritem">
<object class="wxButton" name="wxID_OK">
<label>Ok</label>
<default>1</default>
</object>
</object>
<object class="sizeritem">
<object class="wxButton" name="wxID_CANCEL">
<label>Cancel</label>
</object>
<border>10</border>
<flag>wxLEFT</flag>
</object>
</object>
<flag>wxLEFT|wxRIGHT|wxBOTTOM|wxALIGN_RIGHT</flag>
<border>10</border>
</object>
</object>
<title>Second testing dialog</title>
</object>
</resource>
@endcode
@section overview_xrc_cppheader C++ header file generation
Using the @c -e switch together with @c -c, a C++ header file is written

10
docs/doxygen/overviews/xrc_format.h
View File

@@ -217,7 +217,7 @@ For example, "my_dlg" in this snippet:
@endcode
is identical to:
@code
<object_ref ref="template" name="my_dlg">
<object class="wxDialog" name="my_dlg">
<title>My dialog</title>
<size>400,400</size>
<centered>1</centered>
@@ -1798,7 +1798,7 @@ transitions must be handled programatically.
Sizers are handled slightly differently in XRC resources than they are in
wxWindow hierarchy. wxWindow's sizers hierarchy is parallel to the wxWindow
children hieararchy: child windows are children of their parent window and
children hierarchy: child windows are children of their parent window and
the sizer (or sizers) form separate hierarchy attached to the window with
wxWindow::SetSizer().
@@ -1974,7 +1974,7 @@ class-specific properties. All classes support the following properties:
@subsection overview_xrcformat_wxstddialogbuttonsizer wxStdDialogButtonSizer
Unlike other sizers, wxStdDialogButtonSizer doesn't have neither @c sizeritem
Unlike other sizers, wxStdDialogButtonSizer has neither @c sizeritem
nor @c spacer children. Instead, it has one or more children of the
@c button pseudo-class. @c button objects have no properties and they must
always have exactly one child of the @c wxButton class or a class derived from
@@ -2045,7 +2045,7 @@ should be processed on. It is filtered out and ignored on any other platforms.
Possible elemental values are:
@beginDefList
@itemdef{ @c win, Windows }
@itemdef{ @c mac, Mac OS X (or Mac Classic in wxWidgets version supporting it }
@itemdef{ @c mac, Mac OS X (or Mac Classic in wxWidgets version supporting it) }
@itemdef{ @c unix, Any Unix platform @em except OS X }
@itemdef{ @c os2, OS/2 }
@endDefList
@@ -2147,7 +2147,7 @@ Child elements of @c \<object\> are handled by the custom handler and there are
no limitations on them imposed by XRC format.
This is the only mechanism that works for toplevel objects -- custom controls
are accessible using type-unsafe wxXmlResource::LoadObject() method.
are accessible using the type-unsafe wxXmlResource::LoadObject() method.

2
interface/wx/xrc/xh_sizer.h
View File

@@ -62,7 +62,7 @@ protected:
{
...
prottected:
protected:
bool IsSizerNode(wxXmlNode *node) const
{
return IsOfClass(node, "MySizer") ||