interface/wx/xrc/xmlres.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        xrc/xmlres.h
   3 // Purpose:     interface of wxXmlResource
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     Flags which can be used with wxXmlResource::wxXmlResource.
  11 */
  12 enum wxXmlResourceFlags
  13 {
  14     /** Translatable strings will be translated via _(). */
  15     wxXRC_USE_LOCALE     = 1,
  16
  17     /** Subclass property of object nodes will be ignored (useful for previews in XRC editors). */
  18     wxXRC_NO_SUBCLASSING = 2,
  19
  20     /** Prevent the XRC files from being reloaded from disk in case they have been modified there
  21         since being last loaded (may slightly speed up loading them). */
  22     wxXRC_NO_RELOADING   = 4
  23 };
  24
  25
  26 /**
  27     @class wxXmlResource
  28
  29     This is the main class for interacting with the XML-based resource system.
  30
  31     The class holds XML resources from one or more .xml files, binary files or zip
  32     archive files.
  33
  34     Note that this is a singleton class and you'll never allocate/deallocate it.
  35     Just use the static wxXmlResource::Get() getter.
  36
  37     @see @ref overview_xrc, @ref overview_xrcformat
  38
  39     @library{wxxrc}
  40     @category{xrc}
  41 */
  42 class wxXmlResource : public wxObject
  43 {
  44 public:
  45     /**
  46         Constructor.
  47
  48         @param filemask
  49             The XRC file, archive file, or wildcard specification that will be
  50             used to load all resource files inside a zip archive.
  51         @param flags
  52             One or more value of the ::wxXmlResourceFlags enumeration.
  53         @param domain
  54             The name of the gettext catalog to search for translatable strings.
  55             By default all loaded catalogs will be searched.
  56             This provides a way to allow the strings to only come from a specific catalog.
  57     */
  58     wxXmlResource(const wxString& filemask,
  59                   int flags = wxXRC_USE_LOCALE,
  60                   const wxString& domain = wxEmptyString);
  61
  62     /**
  63         Constructor.
  64
  65         @param flags
  66             One or more value of the ::wxXmlResourceFlags enumeration.
  67         @param domain
  68             The name of the gettext catalog to search for translatable strings.
  69             By default all loaded catalogs will be searched.
  70             This provides a way to allow the strings to only come from a specific catalog.
  71     */
  72     wxXmlResource(int flags = wxXRC_USE_LOCALE,
  73                   const wxString& domain = wxEmptyString);
  74
  75     /**
  76         Destructor.
  77     */
  78     virtual ~wxXmlResource();
  79
  80     /**
  81         Initializes only a specific handler (or custom handler).
  82         Convention says that the handler name is equal to the control's name plus
  83         'XmlHandler', for example wxTextCtrlXmlHandler, wxHtmlWindowXmlHandler.
  84
  85         The XML resource compiler (wxxrc) can create include file that contains
  86         initialization code for all controls used within the resource.
  87         Note that this handler must be allocated on the heap, since it will be
  88         deleted by ClearHandlers() later.
  89     */
  90     void AddHandler(wxXmlResourceHandler* handler);
  91
  92     /**
  93         Attaches an unknown control to the given panel/window/dialog.
  94         Unknown controls are used in conjunction with \<object class="unknown"\>.
  95     */
  96     bool AttachUnknownControl(const wxString& name,
  97                               wxWindow* control,
  98                               wxWindow* parent = NULL);
  99
 100     /**
 101         Removes all handlers and deletes them (this means that any handlers
 102         added using AddHandler() must be allocated on the heap).
 103     */
 104     void ClearHandlers();
 105
 106     /**
 107         Compares the XRC version to the argument.
 108
 109         Returns -1 if the XRC version is less than the argument,
 110         +1 if greater, and 0 if they are equal.
 111     */
 112     int CompareVersion(int major, int minor, int release, int revision) const;
 113
 114     /**
 115         Returns a string ID corresponding to the given numeric ID.
 116
 117         The string returned is such that calling GetXRCID() with it as
 118         parameter yields @a numId. If there is no string identifier
 119         corresponding to the given numeric one, an empty string is returned.
 120
 121         Notice that, unlike GetXRCID(), this function is slow as it checks all
 122         of the identifiers used in XRC.
 123
 124         @since 2.9.0
 125      */
 126     static wxString FindXRCIDById(int numId);
 127
 128     /**
 129         Gets the global resources object or creates one if none exists.
 130     */
 131     static wxXmlResource* Get();
 132
 133     /**
 134         Returns the domain (message catalog) that will be used to load
 135         translatable strings in the XRC.
 136     */
 137     const wxString& GetDomain() const;
 138
 139     /**
 140         Returns flags, which may be a bitlist of ::wxXmlResourceFlags
 141         enumeration values.
 142     */
 143     int GetFlags() const;
 144
 145     /**
 146         Returns the wxXmlNode containing the definition of the object with the
 147         given name or @NULL.
 148
 149         This function recursively searches all the loaded XRC files for an
 150         object with the specified @a name. If the object is found, the
 151         wxXmlNode corresponding to it is returned, so this function can be used
 152         to access additional information defined in the XRC file and not used
 153         by wxXmlResource itself, e.g. contents of application-specific XML
 154         tags.
 155
 156         @param name
 157             The name of the resource which must be unique for this function to
 158             work correctly, if there is more than one resource with the given
 159             name the choice of the one returned by this function is undefined.
 160         @return
 161             The node corresponding to the resource with the given name or @NULL.
 162     */
 163     const wxXmlNode *GetResourceNode(const wxString& name) const;
 164
 165     /**
 166         Returns version information (a.b.c.d = d + 256*c + 2562*b + 2563*a).
 167     */
 168     long GetVersion() const;
 169
 170     /**
 171         Returns a numeric ID that is equivalent to the string ID used in an XML resource.
 172
 173         If an unknown @a str_id is requested (i.e. other than wxID_XXX or integer),
 174         a new record is created which associates the given string with a number.
 175
 176         If @a value_if_not_found is @c wxID_NONE, the number is obtained via
 177         wxNewId(). Otherwise @a value_if_not_found is used.
 178
 179         Macro @c XRCID(name) is provided for convenient use in event tables.
 180
 181         @note IDs returned by XRCID() cannot be used with the <tt>EVT_*_RANGE</tt>
 182               macros, because the order in which they are assigned to symbolic @a name
 183               values is not guaranteed.
 184     */
 185     static int GetXRCID(const wxString& str_id, int value_if_not_found = wxID_NONE);
 186
 187     /**
 188         Initializes handlers for all supported controls/windows.
 189
 190         This will make the executable quite big because it forces linking against
 191         most of the wxWidgets library.
 192     */
 193     void InitAllHandlers();
 194
 195     /**
 196         Loads resources from XML files that match given filemask.
 197
 198         Example:
 199         @code
 200             if (!wxXmlResource::Get()->Load("rc/*.xrc"))
 201                 wxLogError("Couldn't load resources!");
 202         @endcode
 203
 204         @note
 205         If wxUSE_FILESYS is enabled, this method understands wxFileSystem URLs
 206         (see wxFileSystem::FindFirst()).
 207
 208         @note
 209         If you are sure that the argument is name of single XRC file (rather
 210         than an URL or a wildcard), use LoadFile() instead.
 211
 212         @see LoadFile(), LoadAllFiles()
 213     */
 214     bool Load(const wxString& filemask);
 215
 216     /**
 217         Simpler form of Load() for loading a single XRC file.
 218
 219         @since 2.9.0
 220
 221         @see Load(), LoadAllFiles()
 222     */
 223     bool LoadFile(const wxFileName& file);
 224
 225     /**
 226         Loads all .xrc files from directory @a dirname.
 227
 228         Tries to load as many files as possible; if there's an error while
 229         loading one file, it still attempts to load other files.
 230
 231         @since 2.9.0
 232
 233         @see LoadFile(), Load()
 234     */
 235     bool LoadAllFiles(const wxString& dirname);
 236
 237     /**
 238         Loads a bitmap resource from a file.
 239     */
 240     wxBitmap LoadBitmap(const wxString& name);
 241
 242     /**
 243         Loads a dialog. @a parent points to parent window (if any).
 244     */
 245     wxDialog* LoadDialog(wxWindow* parent, const wxString& name);
 246
 247     /**
 248         Loads a dialog. @a parent points to parent window (if any).
 249
 250         This form is used to finish creation of an already existing instance (the main
 251         reason for this is that you may want to use derived class with a new event table).
 252         Example:
 253
 254         @code
 255           MyDialog dlg;
 256           wxXmlResource::Get()->LoadDialog(&dlg, mainFrame, "my_dialog");
 257           dlg.ShowModal();
 258         @endcode
 259     */
 260     bool LoadDialog(wxDialog* dlg, wxWindow* parent, const wxString& name);
 261
 262     /**
 263         Loads a frame.
 264     */
 265     bool LoadFrame(wxFrame* frame, wxWindow* parent,
 266                    const wxString& name);
 267
 268     /**
 269         Loads an icon resource from a file.
 270     */
 271     wxIcon LoadIcon(const wxString& name);
 272
 273     /**
 274         Loads menu from resource. Returns @NULL on failure.
 275     */
 276     wxMenu* LoadMenu(const wxString& name);
 277
 278     //@{
 279     /**
 280         Loads a menubar from resource. Returns @NULL on failure.
 281     */
 282     wxMenuBar* LoadMenuBar(wxWindow* parent, const wxString& name);
 283     wxMenuBar* LoadMenuBar(const wxString& name);
 284     //@}
 285
 286     //@{
 287     /**
 288         Load an object from the resource specifying both the resource name and the
 289         class name.
 290
 291         The first overload lets you load nonstandard container windows and returns
 292         @NULL on failure. The second one lets you finish the creation of an existing
 293         instance and returns @false on failure.
 294
 295         In either case, only the resources defined at the top level of XRC
 296         files can be loaded by this function, use LoadObjectRecursively() if
 297         you need to load an object defined deeper in the hierarchy.
 298     */
 299     wxObject* LoadObject(wxWindow* parent, const wxString& name,
 300                          const wxString& classname);
 301     bool LoadObject(wxObject* instance, wxWindow* parent,
 302                     const wxString& name,
 303                     const wxString& classname);
 304     //@}
 305
 306     //@{
 307     /**
 308         Load an object from anywhere in the resource tree.
 309
 310         These methods are similar to LoadObject() but may be used to load an
 311         object from anywhere in the resource tree and not only the top level.
 312         Note that you will very rarely need to do this as in normal use the
 313         entire container window (defined at the top level) is loaded and not
 314         its individual children but this method can be useful in some
 315         particular situations.
 316
 317         @since 2.9.1
 318     */
 319     wxObject* LoadObjectRecursively(wxWindow* parent,
 320                                     const wxString& name,
 321                                     const wxString& classname);
 322     bool LoadObjectRecursively(wxObject* instance, wxWindow* parent,
 323                     const wxString& name,
 324                     const wxString& classname);
 325     //@}
 326
 327     /**
 328         Loads a panel. @a parent points to the parent window.
 329     */
 330     wxPanel* LoadPanel(wxWindow* parent, const wxString& name);
 331
 332     /**
 333         Loads a panel. @a parent points to the parent window.
 334         This form is used to finish creation of an already existing instance.
 335     */
 336     bool LoadPanel(wxPanel* panel, wxWindow* parent, const wxString& name);
 337
 338     /**
 339         Loads a toolbar.
 340     */
 341     wxToolBar* LoadToolBar(wxWindow* parent, const wxString& name);
 342
 343     /**
 344         Sets the global resources object and returns a pointer to the previous one
 345         (may be @NULL).
 346     */
 347     static wxXmlResource* Set(wxXmlResource* res);
 348
 349     /**
 350         Sets the domain (message catalog) that will be used to load
 351         translatable strings in the XRC.
 352     */
 353     void SetDomain(const wxString& domain);
 354
 355     /**
 356         Sets flags (bitlist of ::wxXmlResourceFlags enumeration values).
 357     */
 358     void SetFlags(int flags);
 359
 360     /**
 361         This function unloads a resource previously loaded by Load().
 362
 363         Returns @true if the resource was successfully unloaded and @false if it
 364         hasn't been found in the list of loaded resources.
 365     */
 366     bool Unload(const wxString& filename);
 367
 368 protected:
 369     /**
 370         Reports error in XRC resources to the user.
 371
 372         Any errors in XRC input files should be reported using this method
 373         (or its wxXmlResourceHandler::ReportError() equivalent). Unlike
 374         wxLogError(), this method presents the error to the user in a more
 375         usable form. In particular, the output is compiler-like and contains
 376         information about the exact location of the error.
 377
 378         @param context XML node the error occurred in or relates to. This can
 379                        be @NULL, but should be the most specific node possible,
 380                        as its line number is what is reported to the user.
 381         @param message Text of the error message. This string should always
 382                        be in English (i.e. not wrapped in _()). It shouldn't
 383                        be a sentence -- it should start with lower-case letter
 384                        and shouldn't have a trailing period or exclamation
 385                        point.
 386
 387         @since 2.9.0
 388
 389         @see wxXmlResourceHandler::ReportError(), DoReportError()
 390      */
 391     void ReportError(wxXmlNode *context, const wxString& message);
 392
 393     /**
 394         Implementation of XRC resources errors reporting.
 395
 396         This method is called by ReportError() and shouldn't be called
 397         directly; use ReportError() or wxXmlResourceHandler::ReportError()
 398         to log errors.
 399
 400         Default implementation uses wxLogError().
 401
 402         @param xrcFile  File the error occurred in or empty string if it
 403                         couldn't be determined.
 404         @param position XML node where the error occurred or @NULL if it
 405                         couldn't be determined.
 406         @param message  Text of the error message. See ReportError()
 407                         documentation for details of the string's format.
 408
 409         @note
 410         You may override this method in a derived class to customize errors
 411         reporting. If you do so, you'll need to either use the derived class
 412         in all your code or call wxXmlResource::Set() to change the global
 413         wxXmlResource instance to your class.
 414
 415         @since 2.9.0
 416
 417         @see ReportError()
 418     */
 419     virtual void DoReportError(const wxString& xrcFile, wxXmlNode *position,
 420                                const wxString& message);
 421 };
 422
 423
 424
 425 /**
 426     @class wxXmlResourceHandler
 427
 428     wxXmlResourceHandler is an abstract base class for resource handlers
 429     capable of creating a control from an XML node.
 430
 431     See @ref overview_xrc for details.
 432
 433     @library{wxxrc}
 434     @category{xrc}
 435 */
 436 class wxXmlResourceHandler : public wxObject
 437 {
 438 public:
 439     /**
 440         Default constructor.
 441     */
 442     wxXmlResourceHandler();
 443
 444     /**
 445         Destructor.
 446     */
 447     virtual ~wxXmlResourceHandler();
 448
 449     /**
 450         Creates an object (menu, dialog, control, ...) from an XML node.
 451         Should check for validity. @a parent is a higher-level object
 452         (usually window, dialog or panel) that is often necessary to
 453         create the resource.
 454
 455         If @b instance is non-@NULL it should not create a new instance via
 456         'new' but should rather use this one, and call its Create method.
 457     */
 458     wxObject* CreateResource(wxXmlNode* node, wxObject* parent,
 459                              wxObject* instance);
 460
 461     /**
 462         Called from CreateResource after variables were filled.
 463     */
 464     virtual wxObject* DoCreateResource() = 0;
 465
 466     /**
 467         Returns @true if it understands this node and can create
 468         a resource from it, @false otherwise.
 469
 470         @note
 471         You must not call any wxXmlResourceHandler methods except IsOfClass()
 472         from this method! The instance is not yet initialized with node data
 473         at the time CanHandle() is called and it is only safe to operate on
 474         node directly or to call IsOfClass().
 475     */
 476     virtual bool CanHandle(wxXmlNode* node) = 0;
 477
 478     /**
 479         Sets the parent resource.
 480     */
 481     void SetParentResource(wxXmlResource* res);
 482
 483
 484 protected:
 485
 486     /**
 487         Add a style flag (e.g. @c wxMB_DOCKABLE) to the list of flags
 488         understood by this handler.
 489     */
 490     void AddStyle(const wxString& name, int value);
 491
 492     /**
 493         Add styles common to all wxWindow-derived classes.
 494     */
 495     void AddWindowStyles();
 496
 497     /**
 498         Creates children.
 499     */
 500     void CreateChildren(wxObject* parent, bool this_hnd_only = false);
 501
 502     /**
 503         Helper function.
 504     */
 505     void CreateChildrenPrivately(wxObject* parent,
 506                                  wxXmlNode* rootnode = NULL);
 507
 508     /**
 509         Creates a resource from a node.
 510     */
 511     wxObject* CreateResFromNode(wxXmlNode* node, wxObject* parent,
 512                                 wxObject* instance = NULL);
 513
 514     /**
 515         Creates an animation (see wxAnimation) from the filename specified in @a param.
 516     */
 517     wxAnimation GetAnimation(const wxString& param = "animation");
 518
 519     /**
 520         Gets a bitmap.
 521     */
 522     wxBitmap GetBitmap(const wxString& param = "bitmap",
 523                        const wxArtClient& defaultArtClient = wxART_OTHER,
 524                        wxSize size = wxDefaultSize);
 525     /**
 526         Gets a bitmap from an XmlNode.
 527
 528         @since 2.9.1
 529     */
 530     wxBitmap GetBitmap(const wxXmlNode* node,
 531                        const wxArtClient& defaultArtClient = wxART_OTHER,
 532                        wxSize size = wxDefaultSize);
 533
 534     /**
 535         Gets a bool flag (1, t, yes, on, true are @true, everything else is @false).
 536     */
 537     bool GetBool(const wxString& param, bool defaultv = false);
 538
 539     /**
 540         Gets colour in HTML syntax (\#RRGGBB).
 541     */
 542     wxColour GetColour(const wxString& param,
 543                        const wxColour& defaultColour = wxNullColour);
 544
 545     /**
 546         Returns the current file system.
 547     */
 548     wxFileSystem& GetCurFileSystem();
 549
 550     /**
 551         Gets a dimension (may be in dialog units).
 552     */
 553     wxCoord GetDimension(const wxString& param, wxCoord defaultv = 0,
 554                          wxWindow* windowToUse = 0);
 555
 556     /**
 557         Gets a font.
 558     */
 559     wxFont GetFont(const wxString& param = "font");
 560
 561     /**
 562         Returns the XRCID.
 563     */
 564     int GetID();
 565
 566     /**
 567         Returns an icon.
 568     */
 569     wxIcon GetIcon(const wxString& param = "icon",
 570                    const wxArtClient& defaultArtClient = wxART_OTHER,
 571                    wxSize size = wxDefaultSize);
 572
 573     /**
 574         Gets an icon from an XmlNode.
 575
 576         @since 2.9.1
 577     */
 578     wxIcon GetIcon(const wxXmlNode* node,
 579                    const wxArtClient& defaultArtClient = wxART_OTHER,
 580                    wxSize size = wxDefaultSize);
 581
 582     /**
 583         Returns an icon bundle.
 584
 585         @note
 586         Bundles can be loaded either with stock IDs or from files that contain
 587         more than one image (e.g. Windows icon files). If a file contains only
 588         single image, a bundle with only one icon will be created.
 589
 590         @since 2.9.0
 591      */
 592     wxIconBundle GetIconBundle(const wxString& param,
 593                                const wxArtClient& defaultArtClient = wxART_OTHER);
 594
 595     /**
 596         Creates an image list from the @a param markup data.
 597
 598         @return
 599             The new instance of wxImageList or @NULL if no data is found.
 600
 601         @since 2.9.1
 602     */
 603     wxImageList *GetImageList(const wxString& param = wxT("imagelist"));
 604
 605     /**
 606         Gets the integer value from the parameter.
 607     */
 608     long GetLong(const wxString& param, long defaultv = 0);
 609
 610     /**
 611         Returns the resource name.
 612     */
 613     wxString GetName();
 614
 615     /**
 616         Gets node content from wxXML_ENTITY_NODE.
 617     */
 618     wxString GetNodeContent(wxXmlNode* node);
 619
 620     /**
 621         Finds the node or returns @NULL.
 622     */
 623     wxXmlNode* GetParamNode(const wxString& param);
 624
 625     /**
 626         Finds the parameter value or returns the empty string.
 627     */
 628     wxString GetParamValue(const wxString& param);
 629
 630     /**
 631         Returns the node parameter value.
 632
 633         @since 2.9.1
 634     */
 635     wxString GetParamValue(const wxXmlNode* node);
 636
 637     /**
 638         Gets the position (may be in dialog units).
 639     */
 640     wxPoint GetPosition(const wxString& param = "pos");
 641
 642     /**
 643         Gets the size (may be in dialog units).
 644     */
 645     wxSize GetSize(const wxString& param = "size", wxWindow* windowToUse = 0);
 646
 647     /**
 648         Gets style flags from text in form "flag | flag2| flag3 |..."
 649         Only understands flags added with AddStyle().
 650     */
 651     int GetStyle(const wxString& param = "style", int defaults = 0);
 652
 653     /**
 654         Gets text from param and does some conversions:
 655         - replaces \\n, \\r, \\t by respective characters (according to C syntax)
 656         - replaces @c $ by @c  and @c $$ by @c $ (needed for @c _File to @c File
 657           translation because of XML syntax)
 658         - calls wxGetTranslations (unless disabled in wxXmlResource)
 659     */
 660     wxString GetText(const wxString& param, bool translate = true);
 661
 662     /**
 663         Check to see if a parameter exists.
 664     */
 665     bool HasParam(const wxString& param);
 666
 667     /**
 668         Convenience function.
 669         Returns @true if the node has a property class equal to classname,
 670         e.g. object class="wxDialog".
 671     */
 672     bool IsOfClass(wxXmlNode* node, const wxString& classname);
 673
 674     /**
 675         Sets common window options.
 676     */
 677     void SetupWindow(wxWindow* wnd);
 678
 679     /**
 680         Reports error in XRC resources to the user.
 681
 682         See wxXmlResource::ReportError() for more information.
 683
 684         @since 2.9.0
 685      */
 686     void ReportError(wxXmlNode *context, const wxString& message);
 687
 688     /**
 689         Like ReportError(wxXmlNode*, const wxString&), but uses the node
 690         of currently processed object (m_node) as the context.
 691
 692         @since 2.9.0
 693      */
 694     void ReportError(const wxString& message);
 695
 696     /**
 697         Like ReportError(wxXmlNode*, const wxString&), but uses the node
 698         of parameter @a param of the currently processed object as the context.
 699         This is convenience function for reporting errors in particular
 700         parameters.
 701
 702         @since 2.9.0
 703      */
 704     void ReportParamError(const wxString& param, const wxString& message);
 705 };
 706