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_cppheader
  45 @li @ref overview_xrc_newresourcehandlers
  46
  47 See also the separate @ref overview_xrcformat page for details about the XRC file format.
  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( wxT("This is the about dialog of XML resources demo.\n")
 263                 wxT("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             <image>0</image>
 388           </object>
 389           <object class="notebookpage">
 390             <object class="wxPanel">
 391               <object class="wxBoxSizer">
 392                 <object class="sizeritem">
 393                   <object class="wxHtmlWindow">
 394                     <htmlcode>Hello, we are inside a <u>NOTEBOOK</u>...</htmlcode>
 395                     <size>50,50d</size>
 396                   </object>
 397                 </object>
 398               </object>
 399             </object>
 400             <label>Page 2</label>
 401             <image>1</image>
 402           </object>
 403           <usenotebooksizer>1</usenotebooksizer>
 404         <imagelist>
 405             <size>16,16</size>
 406             <bitmap stock_id="wxART_QUESTION"/>
 407             <bitmap stock_id="wxART_WARNING"/>
 408         </imagelist>
 409         </object>
 410         <flag>wxEXPAND</flag>
 411       </object>
 412       <orient>wxVERTICAL</orient>
 413     </object>
 414   </object>
 415   <object class="wxDialog" name="dlg2">
 416     <object class="wxBoxSizer">
 417       <orient>wxVERTICAL</orient>
 418       <object class="sizeritem" name="dfgdfg">
 419         <object class="wxTextCtrl">
 420           <size>200,200d</size>
 421           <style>wxTE_MULTILINE|wxBORDER_SUNKEN</style>
 422           <value>Hello, this is an ordinary multiline\n         textctrl....</value>
 423         </object>
 424         <option>1</option>
 425         <flag>wxEXPAND|wxALL</flag>
 426         <border>10</border>
 427       </object>
 428       <object class="sizeritem">
 429         <object class="wxBoxSizer">
 430           <object class="sizeritem">
 431             <object class="wxButton" name="wxID_OK">
 432               <label>Ok</label>
 433               <default>1</default>
 434             </object>
 435           </object>
 436           <object class="sizeritem">
 437             <object class="wxButton" name="wxID_CANCEL">
 438               <label>Cancel</label>
 439             </object>
 440             <border>10</border>
 441             <flag>wxLEFT</flag>
 442           </object>
 443         </object>
 444         <flag>wxLEFT|wxRIGHT|wxBOTTOM|wxALIGN_RIGHT</flag>
 445         <border>10</border>
 446       </object>
 447     </object>
 448     <title>Second testing dialog</title>
 449   </object>
 450 </resource>
 451 @endcode
 452
 453
 454 @section overview_xrc_cppheader C++ header file generation
 455
 456 Using the @c -e switch together with @c -c, a C++ header file is written
 457 containing class definitions for the GUI windows defined in the XRC file. This
 458 code generation can make it easier to use XRC and automate program development.
 459 The classes can be used as basis for development, freeing the programmer from
 460 dealing with most of the XRC specifics (e.g. @c XRCCTRL).
 461
 462 For each top level window defined in the XRC file a C++ class definition is
 463 generated, containing as class members the named widgets of the window. A
 464 default constructor for each class is also generated. Inside the constructor
 465 all XRC loading is done and all class members representing widgets are
 466 initialized.
 467
 468 A simple example will help understand how the scheme works. Suppose you have a
 469 XRC file defining a top level window @c TestWnd_Base, which subclasses wxFrame
 470 (any other class like @c wxDialog will do also), and has subwidgets wxTextCtrl A
 471 and wxButton B.
 472
 473 The XRC file and corresponding class definition in the header file will be
 474 something like:
 475
 476 @code
 477 <?xml version="1.0"?>
 478 <resource version="2.3.0.1">
 479     <object class="wxFrame" name="TestWnd_Base">
 480         <size>-1,-1</size>
 481         <title>Test</title>
 482         <object class="wxBoxSizer">
 483             <orient>wxHORIZONTAL</orient>
 484             <object class="sizeritem">
 485                 <object class="wxTextCtrl" name="A">
 486                     <label>Test label</label>
 487                 </object>
 488             </object>
 489             <object class="sizeritem">
 490                 <object class="wxButton" name="B">
 491                     <label>Test button</label>
 492                 </object>
 493             </object>
 494         </object>
 495     </object>
 496 </resource>
 497
 498
 499 class TestWnd_Base : public wxFrame
 500 {
 501 protected:
 502     wxTextCtrl* A;
 503     wxButton* B;
 504
 505 private:
 506     void InitWidgetsFromXRC()
 507     {
 508         wxXmlResource::Get()->LoadObject(this, NULL, "TestWnd", "wxFrame");
 509         A = XRCCTRL(*this, "A", wxTextCtrl);
 510         B = XRCCTRL(*this, "B", wxButton);
 511     }
 512 public:
 513     TestWnd::TestWnd()
 514     {
 515         InitWidgetsFromXRC();
 516     }
 517 };
 518 @endcode
 519
 520 The generated window class can be used as basis for the full window class. The
 521 class members which represent widgets may be accessed by name instead of using
 522 @c XRCCTRL every time you wish to reference them (note that they are
 523 @c protected class members), though you must still use @c XRCID to refer to
 524 widget IDs in the event table.
 525
 526 Example:
 527
 528 @code
 529 #include "resource.h"
 530
 531 class TestWnd : public TestWnd_Base
 532 {
 533 public:
 534     TestWnd()
 535     {
 536         // A, B already initialised at this point
 537         A->SetValue("Updated in TestWnd::TestWnd");
 538         B->SetValue("Nice :)");
 539     }
 540     void OnBPressed(wxEvent& event)
 541     {
 542         Close();
 543     }
 544     DECLARE_EVENT_TABLE();
 545 };
 546
 547 BEGIN_EVENT_TABLE(TestWnd,TestWnd_Base)
 548     EVT_BUTTON(XRCID("B"), TestWnd::OnBPressed)
 549 END_EVENT_TABLE()
 550 @endcode
 551
 552 It is also possible to access the wxSizerItem of a sizer that is part of a
 553 resource. This can be done using @c XRCSIZERITEM as shown.
 554
 555 The resource file can have something like this for a sizer item.
 556
 557 @code
 558 <object class="spacer" name="area">
 559   <size>400, 300</size>
 560 </object>
 561 @endcode
 562
 563 The code can then access the sizer item by using @c XRCSIZERITEM and @c XRCID
 564 together.
 565
 566 @code
 567 wxSizerItem* item = XRCSIZERITEM(*this, "area");
 568 @endcode
 569
 570
 571 @section overview_xrc_newresourcehandlers Adding New Resource Handlers
 572
 573 Adding a new resource handler is pretty easy.
 574
 575 Typically, to add an handler for the @c MyControl class, you'll want to create
 576 the @c xh_mycontrol.h and @c xh_mycontrol.cpp files.
 577
 578 The header needs to contains the @c MyControlXmlHandler class definition:
 579
 580 @code
 581 class MyControlXmlHandler : public wxXmlResourceHandler
 582 {
 583 public:
 584     // Constructor.
 585     MyControlXmlHandler();
 586
 587     // Creates the control and returns a pointer to it.
 588     virtual wxObject *DoCreateResource();
 589
 590     // Returns true if we know how to create a control for the given node.
 591     virtual bool CanHandle(wxXmlNode *node);
 592
 593     // Register with wxWidgets' dynamic class subsystem.
 594     DECLARE_DYNAMIC_CLASS(MyControlXmlHandler)
 595 };
 596 @endcode
 597
 598 The implementation of your custom XML handler will typically look as:
 599
 600 @code
 601 // Register with wxWidgets' dynamic class subsystem.
 602 IMPLEMENT_DYNAMIC_CLASS(MyControlXmlHandler, wxXmlResourceHandler)
 603
 604 MyControlXmlHandler::MyControlXmlHandler()
 605 {
 606     // this call adds support for all wxWindows class styles
 607     // (e.g. wxBORDER_SIMPLE, wxBORDER_SUNKEN, wxWS_EX_* etc etc)
 608     AddWindowStyles();
 609
 610     // if MyControl class supports e.g. MYCONTROL_DEFAULT_STYLE
 611     // you should use:
 612     //     XRC_ADD_STYLE(MYCONTROL_DEFAULT_STYLE);
 613 }
 614
 615 wxObject *MyControlXmlHandler::DoCreateResource()
 616 {
 617     // the following macro will init a pointer named "control"
 618     // with a new instance of the MyControl class, but will NOT
 619     // Create() it!
 620     XRC_MAKE_INSTANCE(control, MyControl)
 621
 622     // this is the point where you'll typically need to do the most
 623     // important changes: here the control is created and initialized.
 624     // You'll want to use the wxXmlResourceHandler's getters to
 625     // do most of your work.
 626     // If e.g. the MyControl::Create function looks like:
 627     //
 628     // bool MyControl::Create(wxWindow *parent, int id,
 629     //                        const wxBitmap &first, const wxPoint &posFirst,
 630     //                        const wxBitmap &second, const wxPoint &posSecond,
 631     //                        const wxString &theTitle, const wxFont &titleFont,
 632     //                        const wxPoint &pos, const wxSize &size,
 633     //                        long style = MYCONTROL_DEFAULT_STYLE,
 634     //                        const wxString &name = wxT("MyControl"));
 635     //
 636     // Then the XRC for your component should look like:
 637     //
 638     //    <object class="MyControl" name="some_name">
 639     //      <first-bitmap>first.xpm</first-bitmap>
 640     //      <second-bitmap>text.xpm</second-bitmap>
 641     //      <first-pos>3,3</first-pos>
 642     //      <second-pos>4,4</second-pos>
 643     //      <the-title>a title</the-title>
 644     //      <title-font>
 645     //        <!-- Standard XRC tags for a font: <size>, <style>, <weight>, etc -->
 646     //      </title-font>
 647     //      <!-- XRC also accepts other usual tags for wxWindow-derived classes:
 648     //           like e.g. <name>, <style>, <size>, <position>, etc -->
 649     //    </object>
 650     //
 651     // And the code to read your custom tags from the XRC file is just:
 652     control->Create(m_parentAsWindow, GetID(),
 653                     GetBitmap(wxT("first-bitmap")),
 654                     GetPosition(wxT("first-pos")),
 655                     GetBitmap(wxT("second-bitmap")),
 656                     GetPosition(wxT("second-pos")),
 657                     GetText(wxT("the-title")),
 658                     GetFont(wxT("title-font")),
 659                     GetPosition(), GetSize(), GetStyle(), GetName());
 660
 661     SetupWindow(control);
 662
 663     return control;
 664 }
 665
 666 bool MyControlXmlHandler::CanHandle(wxXmlNode *node)
 667 {
 668     // this function tells XRC system that this handler can parse
 669     // the <object class="MyControl"> tags
 670     return IsOfClass(node, wxT("MyControl"));
 671 }
 672 @endcode
 673
 674 You may want to check the wxXmlResourceHandler documentation to see how many
 675 built-in getters it contains. It's very easy to retrieve also complex
 676 structures out of XRC files using them.
 677
 678 */
 679