docs/doxygen/overviews/xrc.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        xrc.h
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10
  11 @page overview_xrc XML Based Resource System (XRC)
  12
  13 Classes: wxXmlResource, wxXmlResourceHandler
  14
  15 The XML-based resource system, known as XRC, allows user interface elements
  16 such as dialogs, menu bars and toolbars, to be stored in text files and loaded
  17 into the application at run-time. XRC files can also be compiled into binary
  18 XRS files or C++ code (the former makes it possible to store all resources in a
  19 single file and the latter is useful when you want to embed the resources into
  20 the executable).
  21
  22 There are several advantages to using XRC resources:
  23
  24 @li Recompiling and linking an application is not necessary if the resources
  25     change.
  26 @li If you use a dialog designer that generates C++ code, it can be hard to
  27     reintegrate this into existing C++ code. Separation of resources and code
  28     is a more elegant solution.
  29 @li You can choose between different alternative resource files at run time, if
  30     necessary.
  31 @li The XRC format uses sizers for flexibility, allowing dialogs to be
  32     resizable and highly portable.
  33 @li The XRC format is a wxWidgets standard, and can be generated or
  34     postprocessed by any program that understands it. As it is basedon the XML
  35     standard, existing XML editors can be used for simple editing purposes.
  36
  37 XRC was written by Vaclav Slavik.
  38
  39 @li @ref overview_xrc_concepts
  40 @li @ref overview_xrc_binaryresourcefiles
  41 @li @ref overview_xrc_embeddedresource
  42 @li @ref overview_xrc_cppsample
  43 @li @ref overview_xrc_sample
  44 @li @ref overview_xrc_fileformat
  45 @li @ref overview_xrc_cppheader
  46 @li @ref overview_xrc_newresourcehandlers
  47
  48
  49 <hr>
  50
  51
  52 @section overview_xrc_concepts XRC Concepts
  53
  54 These are the typical steps for using XRC files in your application.
  55
  56 @li Include the appropriate headers: normally "wx/xrc/xmlres.h" will suffice.
  57 @li If you are going to use XRS files (see
  58     @ref overview_xrc_binaryresourcefiles), install wxFileSystem archive
  59     handler first with wxFileSystem::AddHandler(new wxArchiveFSHandler);
  60 @li Call wxXmlResource::Get()->InitAllHandlers() from your wxApp::OnInit
  61     function, and then call wxXmlResource::Get()->Load("myfile.xrc") to load
  62     the resource file.
  63 @li To create a dialog from a resource, create it using the default
  64     constructor, and then load it. For example:
  65     wxXmlResource::Get()->LoadDialog(dlg, this, "dlg1");
  66 @li Set up event tables as usual but use the XRCID(str) macro to translate from
  67     XRC string names to a suitable integer identifier, for example
  68     <tt>EVT_MENU(XRCID("quit"), MyFrame::OnQuit)</tt>.
  69
  70 To create an XRC file, you can use one of the following methods.
  71
  72 @li Create the file by hand.
  73 @li Use wxDesigner <http://www.roebling.de/>, a commercial dialog designer/RAD
  74     tool.
  75 @li Use DialogBlocks <http://www.anthemion.co.uk/dialogblocks/>, a commercial
  76     dialog editor.
  77 @li Use XRCed <http://xrced.sf.net/>, a wxPython-based dialog editor that you
  78     can find in the wxPython/tools subdirectory of the wxWidgets SVN archive.
  79 @li Use wxGlade <http://wxglade.sf.net/>, a GUI designer written in wxPython.
  80     At the moment it can generate Python, C++ and XRC.
  81
  82 A complete list of third-party tools that write to XRC can be found at
  83 <http://www.wxwidgets.org/wiki/index.php/Tools>.
  84
  85 It is highly recommended that you use a resource editing tool, since it's
  86 fiddly writing XRC files by hand.
  87
  88 You can use wxXmlResource::Load in a number of ways. You can pass an XRC file
  89 (XML-based text resource file) or a zip-compressed file (see
  90 @ref overview_xrc_binaryresourcefiles), with extension ZIP or XRS, containing
  91 other XRC.
  92
  93 You can also use embedded C++ resources (see
  94 @ref overview_xrc_embeddedresource).
  95
  96
  97 @section overview_xrc_binaryresourcefiles Using Binary Resource Files
  98
  99 To compile binary resource files, use the command-line @c wxrc utility. It
 100 takes one or more file parameters (the input XRC files) and the following
 101 switches and options:
 102
 103 @li -h (--help): Show a help message.
 104 @li -v (--verbose): Show verbose logging information.
 105 @li -c (--cpp-code): Write C++ source rather than a XRS file.
 106 @li -e (--extra-cpp-code): If used together with -c, generates C++ header file
 107     containing class definitions for the windows defined by the XRC file (see
 108     special subsection).
 109 @li -u (--uncompressed): Do not compress XML files (C++ only).
 110 @li -g (--gettext): Output underscore-wrapped strings that poEdit or gettext
 111     can scan. Outputs to stdout, or a file if -o is used.
 112 @li -n (--function) @<name@>: Specify C++ function name (use with -c).
 113 @li -o (--output) @<filename@>: Specify the output file, such as resource.xrs
 114     or resource.cpp.
 115 @li -l (--list-of-handlers) @<filename@>: Output a list of necessary handlers
 116     to this file.
 117
 118 For example:
 119
 120 @code
 121 $ wxrc resource.xrc
 122 $ wxrc resource.xrc -o resource.xrs
 123 $ wxrc resource.xrc -v -c -o resource.cpp
 124 @endcode
 125
 126 @note XRS file is essentially a renamed ZIP archive which means that you can
 127 manipulate it with standard ZIP tools. Note that if you are using XRS files,
 128 you have to initialize the wxFileSystem archive handler first! It is a simple
 129 thing to do:
 130
 131 @code
 132 #include <wx/filesys.h>
 133 #include <wx/fs_arc.h>
 134 ...
 135 wxFileSystem::AddHandler(new wxArchiveFSHandler);
 136 @endcode
 137
 138
 139 @section overview_xrc_embeddedresource Using Embedded Resources
 140
 141 It is sometimes useful to embed resources in the executable itself instead of
 142 loading an external file (e.g. when your app is small and consists only of one
 143 exe file). XRC provides means to convert resources into regular C++ file that
 144 can be compiled and included in the executable.
 145
 146 Use the @c -c switch to @c wxrc utility to produce C++ file with embedded
 147 resources. This file will contain a function called @c InitXmlResource (unless
 148 you override this with a command line switch). Use it to load the resource:
 149
 150 @code
 151 extern void InitXmlResource(); // defined in generated file
 152 ...
 153 wxXmlResource::Get()->InitAllHandlers();
 154 InitXmlResource();
 155 ...
 156 @endcode
 157
 158
 159 @section overview_xrc_cppsample XRC C++ Sample
 160
 161 This is the C++ source file (xrcdemo.cpp) for the XRC sample.
 162
 163 @code
 164 #include "wx/wx.h"
 165 #include "wx/image.h"
 166 #include "wx/xrc/xmlres.h"
 167
 168 // the application icon
 169 #if defined(__WXGTK__) || defined(__WXMOTIF__) || defined(__WXMAC__)
 170     #include "rc/appicon.xpm"
 171 #endif
 172
 173 // ----------------------------------------------------------------------------
 174 // private classes
 175 // ----------------------------------------------------------------------------
 176
 177 // Define a new application type, each program should derive a class from wxApp
 178 class MyApp : public wxApp
 179 {
 180 public:
 181     // override base class virtuals
 182     // ----------------------------
 183
 184     // this one is called on application startup and is a good place for the
 185     // app initialization (doing it here and not in the ctor allows to have an
 186     // error return: if OnInit() returns false, the application terminates)
 187     virtual bool OnInit();
 188 };
 189
 190 // Define a new frame type: this is going to be our main frame
 191 class MyFrame : public wxFrame
 192 {
 193 public:
 194     // ctor(s)
 195     MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size);
 196
 197     // event handlers (these functions should _not_ be virtual)
 198     void OnQuit(wxCommandEvent& event);
 199     void OnAbout(wxCommandEvent& event);
 200     void OnDlg1(wxCommandEvent& event);
 201     void OnDlg2(wxCommandEvent& event);
 202
 203 private:
 204     // any class wishing to process wxWidgets events must use this macro
 205     DECLARE_EVENT_TABLE()
 206 };
 207
 208 // ----------------------------------------------------------------------------
 209 // event tables and other macros for wxWidgets
 210 // ----------------------------------------------------------------------------
 211
 212 BEGIN_EVENT_TABLE(MyFrame, wxFrame)
 213     EVT_MENU(XRCID("menu_quit"),  MyFrame::OnQuit)
 214     EVT_MENU(XRCID("menu_about"), MyFrame::OnAbout)
 215     EVT_MENU(XRCID("menu_dlg1"), MyFrame::OnDlg1)
 216     EVT_MENU(XRCID("menu_dlg2"), MyFrame::OnDlg2)
 217 END_EVENT_TABLE()
 218
 219 IMPLEMENT_APP(MyApp)
 220
 221 // ----------------------------------------------------------------------------
 222 // the application class
 223 // ----------------------------------------------------------------------------
 224
 225 // 'Main program' equivalent: the program execution "starts" here
 226 bool MyApp::OnInit()
 227 {
 228     wxImage::AddHandler(new wxGIFHandler);
 229     wxXmlResource::Get()->InitAllHandlers();
 230     wxXmlResource::Get()->Load("rc/resource.xrc");
 231
 232     MyFrame *frame = new MyFrame("XML resources demo",
 233                                  wxPoint(50, 50), wxSize(450, 340));
 234     frame->Show(true);
 235     return true;
 236 }
 237
 238 // ----------------------------------------------------------------------------
 239 // main frame
 240 // ----------------------------------------------------------------------------
 241
 242 // frame constructor
 243 MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
 244 : wxFrame((wxFrame *)NULL, -1, title, pos, size)
 245 {
 246     SetIcon(wxICON(appicon));
 247
 248     SetMenuBar(wxXmlResource::Get()->LoadMenuBar("mainmenu"));
 249     SetToolBar(wxXmlResource::Get()->LoadToolBar(this, "toolbar"));
 250 }
 251
 252 // event handlers
 253 void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
 254 {
 255     // true is to force the frame to close
 256     Close(true);
 257 }
 258
 259 void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
 260 {
 261     wxString msg;
 262     msg.Printf( _T("This is the about dialog of XML resources demo.\n")
 263                 _T("Welcome to %s"), wxVERSION_STRING);
 264
 265     wxMessageBox(msg, "About XML resources demo",
 266                  wxOK | wxICON_INFORMATION, this);
 267 }
 268
 269 void MyFrame::OnDlg1(wxCommandEvent& WXUNUSED(event))
 270 {
 271     wxDialog dlg;
 272     wxXmlResource::Get()->LoadDialog(&dlg, this, "dlg1");
 273     dlg.ShowModal();
 274 }
 275
 276 void MyFrame::OnDlg2(wxCommandEvent& WXUNUSED(event))
 277 {
 278     wxDialog dlg;
 279     wxXmlResource::Get()->LoadDialog(&dlg, this, "dlg2");
 280     dlg.ShowModal();
 281 }
 282 @endcode
 283
 284
 285 @section overview_xrc_sample XRC Resource File Sample
 286
 287 This is the XML file (resource.xrc) for the XRC sample.
 288
 289 @code
 290 <?xml version="1.0"?>
 291 <resource version="2.3.0.1">
 292   <object class="wxMenuBar" name="mainmenu">
 293     <style>wxMB_DOCKABLE</style>
 294     <object class="wxMenu" name="menu_file">
 295       <label>_File</label>
 296       <style>wxMENU_TEAROFF</style>
 297       <object class="wxMenuItem" name="menu_about">
 298         <label>_About...</label>
 299         <bitmap>filesave.gif</bitmap>
 300       </object>
 301       <object class="separator"/>
 302       <object class="wxMenuItem" name="menu_dlg1">
 303         <label>Dialog 1</label>
 304       </object>
 305       <object class="wxMenuItem" name="menu_dlg2">
 306         <label>Dialog 2</label>
 307       </object>
 308       <object class="separator"/>
 309       <object class="wxMenuItem" name="menu_quit">
 310         <label>E_xit\tAlt-X</label>
 311       </object>
 312     </object>
 313   </object>
 314   <object class="wxToolBar" name="toolbar">
 315     <style>wxTB_FLAT|wxTB_DOCKABLE</style>
 316     <margins>2,2</margins>
 317     <object class="tool" name="menu_open">
 318       <bitmap>fileopen.gif</bitmap>
 319       <tooltip>Open catalog</tooltip>
 320     </object>
 321     <object class="tool" name="menu_save">
 322       <bitmap>filesave.gif</bitmap>
 323       <tooltip>Save catalog</tooltip>
 324     </object>
 325     <object class="tool" name="menu_update">
 326       <bitmap>update.gif</bitmap>
 327       <tooltip>Update catalog - synchronize it with sources</tooltip>
 328     </object>
 329     <separator/>
 330     <object class="tool" name="menu_quotes">
 331       <bitmap>quotes.gif</bitmap>
 332       <toggle>1</toggle>
 333       <tooltip>Display quotes around the string?</tooltip>
 334     </object>
 335     <object class="separator"/>
 336     <object class="tool" name="menu_fuzzy">
 337       <bitmap>fuzzy.gif</bitmap>
 338       <tooltip>Toggled if selected string is fuzzy translation</tooltip>
 339       <toggle>1</toggle>
 340     </object>
 341   </object>
 342   <object class="wxDialog" name="dlg1">
 343     <object class="wxBoxSizer">
 344       <object class="sizeritem">
 345         <object class="wxBitmapButton">
 346           <bitmap>fuzzy.gif</bitmap>
 347           <focus>fileopen.gif</focus>
 348         </object>
 349       </object>
 350       <object class="sizeritem">
 351         <object class="wxPanel">
 352           <object class="wxStaticText">
 353             <label>fdgdfgdfgdfg</label>
 354           </object>
 355           <style>wxBORDER\_SUNKEN</style>
 356         </object>
 357         <flag>wxALIGN_CENTER</flag>
 358       </object>
 359       <object class="sizeritem">
 360         <object class="wxButton">
 361           <label>Buttonek</label>
 362         </object>
 363         <border>10d</border>
 364         <flag>wxALL</flag>
 365       </object>
 366       <object class="sizeritem">
 367         <object class="wxHtmlWindow">
 368           <htmlcode><h1>Hi,</h1>man</htmlcode>
 369           <size>100,45d</size>
 370         </object>
 371       </object>
 372       <object class="sizeritem">
 373         <object class="wxNotebook">
 374           <object class="notebookpage">
 375             <object class="wxPanel">
 376               <object class="wxBoxSizer">
 377                 <object class="sizeritem">
 378                   <object class="wxHtmlWindow">
 379                     <htmlcode>Hello, we are inside a <u>NOTEBOOK</u>...</htmlcode>
 380                     <size>50,50d</size>
 381                   </object>
 382                   <option>1</option>
 383                 </object>
 384               </object>
 385             </object>
 386             <label>Page</label>
 387           </object>
 388           <object class="notebookpage">
 389             <object class="wxPanel">
 390               <object class="wxBoxSizer">
 391                 <object class="sizeritem">
 392                   <object class="wxHtmlWindow">
 393                     <htmlcode>Hello, we are inside a <u>NOTEBOOK</u>...</htmlcode>
 394                     <size>50,50d</size>
 395                   </object>
 396                 </object>
 397               </object>
 398             </object>
 399             <label>Page 2</label>
 400           </object>
 401           <usenotebooksizer>1</usenotebooksizer>
 402         </object>
 403         <flag>wxEXPAND</flag>
 404       </object>
 405       <orient>wxVERTICAL</orient>
 406     </object>
 407   </object>
 408   <object class="wxDialog" name="dlg2">
 409     <object class="wxBoxSizer">
 410       <orient>wxVERTICAL</orient>
 411       <object class="sizeritem" name="dfgdfg">
 412         <object class="wxTextCtrl">
 413           <size>200,200d</size>
 414           <style>wxTE_MULTILINE|wxBORDER_SUNKEN</style>
 415           <value>Hello, this is an ordinary multiline\n         textctrl....</value>
 416         </object>
 417         <option>1</option>
 418         <flag>wxEXPAND|wxALL</flag>
 419         <border>10</border>
 420       </object>
 421       <object class="sizeritem">
 422         <object class="wxBoxSizer">
 423           <object class="sizeritem">
 424             <object class="wxButton" name="wxID_OK">
 425               <label>Ok</label>
 426               <default>1</default>
 427             </object>
 428           </object>
 429           <object class="sizeritem">
 430             <object class="wxButton" name="wxID_CANCEL">
 431               <label>Cancel</label>
 432             </object>
 433             <border>10</border>
 434             <flag>wxLEFT</flag>
 435           </object>
 436         </object>
 437         <flag>wxLEFT|wxRIGHT|wxBOTTOM|wxALIGN_RIGHT</flag>
 438         <border>10</border>
 439       </object>
 440     </object>
 441     <title>Second testing dialog</title>
 442   </object>
 443 </resource>
 444 @endcode
 445
 446
 447 @section overview_xrc_fileformat XRC File Format
 448
 449 Please see Technical Note 14 (docs/tech/tn0014.txt) in your wxWidgets
 450 distribution.
 451
 452
 453 @section overview_xrc_cppheader C++ header file generation
 454
 455 Using the @c -e switch together with @c -c, a C++ header file is written
 456 containing class definitions for the GUI windows defined in the XRC file. This
 457 code generation can make it easier to use XRC and automate program development.
 458 The classes can be used as basis for development, freeing the programmer from
 459 dealing with most of the XRC specifics (e.g. @c XRCCTRL).
 460
 461 For each top level window defined in the XRC file a C++ class definition is
 462 generated, containing as class members the named widgets of the window. A
 463 default constructor for each class is also generated. Inside the constructor
 464 all XRC loading is done and all class members representing widgets are
 465 initialized.
 466
 467 A simple example will help understand how the scheme works. Suppose you have a
 468 XRC file defining a top level window @c TestWnd_Base, which subclasses wxFrame
 469 (any other class like @c wxDialog will do also), and has subwidgets wxTextCtrl A
 470 and wxButton B.
 471
 472 The XRC file and corresponding class definition in the header file will be
 473 something like:
 474
 475 @code
 476 <?xml version="1.0"?>
 477 <resource version="2.3.0.1">
 478     <object class="wxFrame" name="TestWnd_Base">
 479         <size>-1,-1</size>
 480         <title>Test</title>
 481         <object class="wxBoxSizer">
 482             <orient>wxHORIZONTAL</orient>
 483             <object class="sizeritem">
 484                 <object class="wxTextCtrl" name="A">
 485                     <label>Test label</label>
 486                 </object>
 487             </object>
 488             <object class="sizeritem">
 489                 <object class="wxButton" name="B">
 490                     <label>Test button</label>
 491                 </object>
 492             </object>
 493         </object>
 494     </object>
 495 </resource>
 496
 497
 498 class TestWnd_Base : public wxFrame
 499 {
 500 protected:
 501     wxTextCtrl* A;
 502     wxButton* B;
 503
 504 private:
 505     void InitWidgetsFromXRC()
 506     {
 507         wxXmlResource::Get()->LoadObject(this, NULL, "TestWnd", "wxFrame");
 508         A = XRCCTRL(*this, "A", wxTextCtrl);
 509         B = XRCCTRL(*this, "B", wxButton);
 510     }
 511 public:
 512     TestWnd::TestWnd()
 513     {
 514         InitWidgetsFromXRC();
 515     }
 516 };
 517 @endcode
 518
 519 The generated window class can be used as basis for the full window class. The
 520 class members which represent widgets may be accessed by name instead of using
 521 @c XRCCTRL every time you wish to reference them (note that they are
 522 @c protected class members), though you must still use @c XRCID to refer to
 523 widget IDs in the event table.
 524
 525 Example:
 526
 527 @code
 528 #include "resource.h"
 529
 530 class TestWnd : public TestWnd_Base
 531 {
 532 public:
 533     TestWnd()
 534     {
 535         // A, B already initialised at this point
 536         A->SetValue("Updated in TestWnd::TestWnd");
 537         B->SetValue("Nice :)");
 538     }
 539     void OnBPressed(wxEvent& event)
 540     {
 541         Close();
 542     }
 543     DECLARE_EVENT_TABLE();
 544 };
 545
 546 BEGIN_EVENT_TABLE(TestWnd,TestWnd_Base)
 547     EVT_BUTTON(XRCID("B"), TestWnd::OnBPressed)
 548 END_EVENT_TABLE()
 549 @endcode
 550
 551 It is also possible to access the wxSizerItem of a sizer that is part of a
 552 resource. This can be done using @c XRCSIZERITEM as shown.
 553
 554 The resource file can have something like this for a sizer item.
 555
 556 @code
 557 <object class="spacer" name="area">
 558   <size>400, 300</size>
 559 </object>
 560 @endcode
 561
 562 The code can then access the sizer item by using @c XRCSIZERITEM and @c XRCID
 563 together.
 564
 565 @code
 566 wxSizerItem* item = XRCSIZERITEM(*this, "area");
 567 @endcode
 568
 569
 570 @section overview_xrc_newresourcehandlers Adding New Resource Handlers
 571
 572 Adding a new resource handler is pretty easy.
 573
 574 Typically, to add an handler for the @c MyControl class, you'll want to create
 575 the @c xh_mycontrol.h and @c xh_mycontrol.cpp files.
 576
 577 The header needs to contains the @c MyControlXmlHandler class definition:
 578
 579 @code
 580 class MyControlXmlHandler : public wxXmlResourceHandler
 581 {
 582 public:
 583     // Constructor.
 584     MyControlXmlHandler();
 585
 586     // Creates the control and returns a pointer to it.
 587     virtual wxObject *DoCreateResource();
 588
 589     // Returns true if we know how to create a control for the given node.
 590     virtual bool CanHandle(wxXmlNode *node);
 591
 592     // Register with wxWidgets' dynamic class subsystem.
 593     DECLARE_DYNAMIC_CLASS(MyControlXmlHandler)
 594 };
 595 @endcode
 596
 597 The implementation of your custom XML handler will typically look as:
 598
 599 @code
 600 // Register with wxWidgets' dynamic class subsystem.
 601 IMPLEMENT_DYNAMIC_CLASS(MyControlXmlHandler, wxXmlResourceHandler)
 602
 603 MyControlXmlHandler::MyControlXmlHandler()
 604 {
 605     // this call adds support for all wxWindows class styles
 606     // (e.g. wxBORDER_SIMPLE, wxBORDER_SUNKEN, wxWS_EX_* etc etc)
 607     AddWindowStyles();
 608
 609     // if MyControl class supports e.g. MYCONTROL_DEFAULT_STYLE
 610     // you should use:
 611     //     XRC_ADD_STYLE(MYCONTROL_DEFAULT_STYLE);
 612 }
 613
 614 wxObject *MyControlXmlHandler::DoCreateResource()
 615 {
 616     // the following macro will init a pointer named "control"
 617     // with a new instance of the MyControl class, but will NOT
 618     // Create() it!
 619     XRC_MAKE_INSTANCE(control, MyControl)
 620
 621     // this is the point where you'll typically need to do the most
 622     // important changes: here the control is created and initialized.
 623     // You'll want to use the wxXmlResourceHandler's getters to
 624     // do most of your work.
 625     // If e.g. the MyControl::Create function looks like:
 626     //
 627     // bool MyControl::Create(wxWindow *parent, int id,
 628     //                        const wxBitmap &first, const wxPoint &posFirst,
 629     //                        const wxBitmap &second, const wxPoint &posSecond,
 630     //                        const wxString &theTitle, const wxFont &titleFont,
 631     //                        const wxPoint &pos, const wxSize &size,
 632     //                        long style = MYCONTROL_DEFAULT_STYLE,
 633     //                        const wxString &name = wxT("MyControl"));
 634     //
 635     // Then the XRC for your component should look like:
 636     //
 637     //    <object class="MyControl" name="some_name">
 638     //      <first-bitmap>first.xpm</first-bitmap>
 639     //      <second-bitmap>text.xpm</second-bitmap>
 640     //      <first-pos>3,3</first-pos>
 641     //      <second-pos>4,4</second-pos>
 642     //      <the-title>a title</the-title>
 643     //      <title-font>
 644     //        <!-- Standard XRC tags for a font: <size>, <style>, <weight>, etc -->
 645     //      </title-font>
 646     //      <!-- XRC also accepts other usual tags for wxWindow-derived classes:
 647     //           like e.g. <name>, <style>, <size>, <position>, etc -->
 648     //    </object>
 649     //
 650     // And the code to read your custom tags from the XRC file is just:
 651     control->Create(m_parentAsWindow, GetID(),
 652                     GetBitmap(wxT("first-bitmap")),
 653                     GetPosition(wxT("first-pos")),
 654                     GetBitmap(wxT("second-bitmap")),
 655                     GetPosition(wxT("second-pos")),
 656                     GetText(wxT("the-title")),
 657                     GetFont(wxT("title-font")),
 658                     GetPosition(), GetSize(), GetStyle(), GetName());
 659
 660     SetupWindow(control);
 661
 662     return control;
 663 }
 664
 665 bool MyControlXmlHandler::CanHandle(wxXmlNode *node)
 666 {
 667     // this function tells XRC system that this handler can parse
 668     // the <object class="MyControl"> tags
 669     return IsOfClass(node, wxT("MyControl"));
 670 }
 671 @endcode
 672
 673 You may want to check the wxXmlResourceHandler documentation to see how many
 674 built-in getters it contains. It's very easy to retrieve also complex
 675 structures out of XRC files using them.
 676
 677 */
 678