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