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         Macro @c XRCID(name) is provided for convenient use in event tables.
 179     */
 180     static int GetXRCID(const wxString& str_id, int value_if_not_found = wxID_NONE);
 181
 182     /**
 183         Initializes handlers for all supported controls/windows.
 184
 185         This will make the executable quite big because it forces linking against
 186         most of the wxWidgets library.
 187     */
 188     void InitAllHandlers();
 189
 190     /**
 191         Loads resources from XML files that match given filemask.
 192
 193         Example:
 194         @code
 195             if (!wxXmlResource::Get()->Load("rc/*.xrc"))
 196                 wxLogError("Couldn't load resources!");
 197         @endcode
 198
 199         @note
 200         If wxUSE_FILESYS is enabled, this method understands wxFileSystem URLs
 201         (see wxFileSystem::FindFirst()).
 202
 203         @note
 204         If you are sure that the argument is name of single XRC file (rather
 205         than an URL or a wildcard), use LoadFile() instead.
 206
 207         @see LoadFile(), LoadAllFiles()
 208     */
 209     bool Load(const wxString& filemask);
 210
 211     /**
 212         Simpler form of Load() for loading a single XRC file.
 213
 214         @since 2.9.0
 215
 216         @see Load(), LoadAllFiles()
 217     */
 218     bool LoadFile(const wxFileName& file);
 219
 220     /**
 221         Loads all .xrc files from directory @a dirname.
 222
 223         Tries to load as many files as possible; if there's an error while
 224         loading one file, it still attempts to load other files.
 225
 226         @since 2.9.0
 227
 228         @see LoadFile(), Load()
 229     */
 230     bool LoadAllFiles(const wxString& dirname);
 231
 232     /**
 233         Loads a bitmap resource from a file.
 234     */
 235     wxBitmap LoadBitmap(const wxString& name);
 236
 237     /**
 238         Loads a dialog. @a parent points to parent window (if any).
 239     */
 240     wxDialog* LoadDialog(wxWindow* parent, const wxString& name);
 241
 242     /**
 243         Loads a dialog. @a parent points to parent window (if any).
 244
 245         This form is used to finish creation of an already existing instance (the main
 246         reason for this is that you may want to use derived class with a new event table).
 247         Example:
 248
 249         @code
 250           MyDialog dlg;
 251           wxXmlResource::Get()->LoadDialog(&dlg, mainFrame, "my_dialog");
 252           dlg.ShowModal();
 253         @endcode
 254     */
 255     bool LoadDialog(wxDialog* dlg, wxWindow* parent, const wxString& name);
 256
 257     /**
 258         Loads a frame.
 259     */
 260     bool LoadFrame(wxFrame* frame, wxWindow* parent,
 261                    const wxString& name);
 262
 263     /**
 264         Loads an icon resource from a file.
 265     */
 266     wxIcon LoadIcon(const wxString& name);
 267
 268     /**
 269         Loads menu from resource. Returns @NULL on failure.
 270     */
 271     wxMenu* LoadMenu(const wxString& name);
 272
 273     //@{
 274     /**
 275         Loads a menubar from resource. Returns @NULL on failure.
 276     */
 277     wxMenuBar* LoadMenuBar(wxWindow* parent, const wxString& name);
 278     wxMenuBar* LoadMenuBar(const wxString& name);
 279     //@}
 280
 281     //@{
 282     /**
 283         Load an object from the resource specifying both the resource name and the
 284         class name.
 285
 286         The first overload lets you load nonstandard container windows and returns
 287         @NULL on failure. The second one lets you finish the creation of an existing
 288         instance and returns @false on failure.
 289
 290         In either case, only the resources defined at the top level of XRC
 291         files can be loaded by this function, use LoadObjectRecursively() if
 292         you need to load an object defined deeper in the hierarchy.
 293     */
 294     wxObject* LoadObject(wxWindow* parent, const wxString& name,
 295                          const wxString& classname);
 296     bool LoadObject(wxObject* instance, wxWindow* parent,
 297                     const wxString& name,
 298                     const wxString& classname);
 299     //@}
 300
 301     //@{
 302     /**
 303         Load an object from anywhere in the resource tree.
 304
 305         These methods are similar to LoadObject() but may be used to load an
 306         object from anywhere in the resource tree and not only the top level.
 307         Note that you will very rarely need to do this as in normal use the
 308         entire container window (defined at the top level) is loaded and not
 309         its individual children but this method can be useful in some
 310         particular situations.
 311
 312         @since 2.9.1
 313     */
 314     wxObject* LoadObjectRecursively(wxWindow* parent,
 315                                     const wxString& name,
 316                                     const wxString& classname);
 317     bool LoadObjectRecursively(wxObject* instance, wxWindow* parent,
 318                     const wxString& name,
 319                     const wxString& classname);
 320     //@}
 321
 322     /**
 323         Loads a panel. @a parent points to the parent window.
 324     */
 325     wxPanel* LoadPanel(wxWindow* parent, const wxString& name);
 326
 327     /**
 328         Loads a panel. @a parent points to the parent window.
 329         This form is used to finish creation of an already existing instance.
 330     */
 331     bool LoadPanel(wxPanel* panel, wxWindow* parent, const wxString& name);
 332
 333     /**
 334         Loads a toolbar.
 335     */
 336     wxToolBar* LoadToolBar(wxWindow* parent, const wxString& name);
 337
 338     /**
 339         Sets the global resources object and returns a pointer to the previous one
 340         (may be @NULL).
 341     */
 342     static wxXmlResource* Set(wxXmlResource* res);
 343
 344     /**
 345         Sets the domain (message catalog) that will be used to load
 346         translatable strings in the XRC.
 347     */
 348     void SetDomain(const wxString& domain);
 349
 350     /**
 351         Sets flags (bitlist of ::wxXmlResourceFlags enumeration values).
 352     */
 353     void SetFlags(int flags);
 354
 355     /**
 356         This function unloads a resource previously loaded by Load().
 357
 358         Returns @true if the resource was successfully unloaded and @false if it
 359         hasn't been found in the list of loaded resources.
 360     */
 361     bool Unload(const wxString& filename);
 362
 363 protected:
 364     /**
 365         Reports error in XRC resources to the user.
 366
 367         Any errors in XRC input files should be reported using this method
 368         (or its wxXmlResourceHandler::ReportError() equivalent). Unlike
 369         wxLogError(), this method presents the error to the user in a more
 370         usable form. In particular, the output is compiler-like and contains
 371         information about the exact location of the error.
 372
 373         @param context XML node the error occurred in or relates to. This can
 374                        be @NULL, but should be the most specific node possible,
 375                        as its line number is what is reported to the user.
 376         @param message Text of the error message. This string should always
 377                        be in English (i.e. not wrapped in _()). It shouldn't
 378                        be a sentence -- it should start with lower-case letter
 379                        and shouldn't have a trailing period or exclamation
 380                        point.
 381
 382         @since 2.9.0
 383
 384         @see wxXmlResourceHandler::ReportError(), DoReportError()
 385      */
 386     void ReportError(wxXmlNode *context, const wxString& message);
 387
 388     /**
 389         Implementation of XRC resources errors reporting.
 390
 391         This method is called by ReportError() and shouldn't be called
 392         directly; use ReportError() or wxXmlResourceHandler::ReportError()
 393         to log errors.
 394
 395         Default implementation uses wxLogError().
 396
 397         @param xrcFile  File the error occurred in or empty string if it
 398                         couldn't be determined.
 399         @param position XML node where the error occurred or @NULL if it
 400                         couldn't be determined.
 401         @param message  Text of the error message. See ReportError()
 402                         documentation for details of the string's format.
 403
 404         @note
 405         You may override this method in a derived class to customize errors
 406         reporting. If you do so, you'll need to either use the derived class
 407         in all your code or call wxXmlResource::Set() to change the global
 408         wxXmlResource instance to your class.
 409
 410         @since 2.9.0
 411
 412         @see ReportError()
 413     */
 414     virtual void DoReportError(const wxString& xrcFile, wxXmlNode *position,
 415                                const wxString& message);
 416 };
 417
 418
 419
 420 /**
 421     @class wxXmlResourceHandler
 422
 423     wxXmlResourceHandler is an abstract base class for resource handlers
 424     capable of creating a control from an XML node.
 425
 426     See @ref overview_xrc for details.
 427
 428     @library{wxxrc}
 429     @category{xrc}
 430 */
 431 class wxXmlResourceHandler : public wxObject
 432 {
 433 public:
 434     /**
 435         Default constructor.
 436     */
 437     wxXmlResourceHandler();
 438
 439     /**
 440         Destructor.
 441     */
 442     virtual ~wxXmlResourceHandler();
 443
 444     /**
 445         Creates an object (menu, dialog, control, ...) from an XML node.
 446         Should check for validity. @a parent is a higher-level object
 447         (usually window, dialog or panel) that is often necessary to
 448         create the resource.
 449
 450         If @b instance is non-@NULL it should not create a new instance via
 451         'new' but should rather use this one, and call its Create method.
 452     */
 453     wxObject* CreateResource(wxXmlNode* node, wxObject* parent,
 454                              wxObject* instance);
 455
 456     /**
 457         Called from CreateResource after variables were filled.
 458     */
 459     virtual wxObject* DoCreateResource() = 0;
 460
 461     /**
 462         Returns @true if it understands this node and can create
 463         a resource from it, @false otherwise.
 464
 465         @note
 466         You must not call any wxXmlResourceHandler methods except IsOfClass()
 467         from this method! The instance is not yet initialized with node data
 468         at the time CanHandle() is called and it is only safe to operate on
 469         node directly or to call IsOfClass().
 470     */
 471     virtual bool CanHandle(wxXmlNode* node) = 0;
 472
 473     /**
 474         Sets the parent resource.
 475     */
 476     void SetParentResource(wxXmlResource* res);
 477
 478
 479 protected:
 480
 481     /**
 482         Add a style flag (e.g. @c wxMB_DOCKABLE) to the list of flags
 483         understood by this handler.
 484     */
 485     void AddStyle(const wxString& name, int value);
 486
 487     /**
 488         Add styles common to all wxWindow-derived classes.
 489     */
 490     void AddWindowStyles();
 491
 492     /**
 493         Creates children.
 494     */
 495     void CreateChildren(wxObject* parent, bool this_hnd_only = false);
 496
 497     /**
 498         Helper function.
 499     */
 500     void CreateChildrenPrivately(wxObject* parent,
 501                                  wxXmlNode* rootnode = NULL);
 502
 503     /**
 504         Creates a resource from a node.
 505     */
 506     wxObject* CreateResFromNode(wxXmlNode* node, wxObject* parent,
 507                                 wxObject* instance = NULL);
 508
 509     /**
 510         Creates an animation (see wxAnimation) from the filename specified in @a param.
 511     */
 512     wxAnimation GetAnimation(const wxString& param = "animation");
 513
 514     /**
 515         Gets a bitmap.
 516     */
 517     wxBitmap GetBitmap(const wxString& param = "bitmap",
 518                        const wxArtClient& defaultArtClient = wxART_OTHER,
 519                        wxSize size = wxDefaultSize);
 520     /**
 521         Gets a bitmap from an XmlNode.
 522
 523         @since 2.9.1
 524     */
 525     wxBitmap GetBitmap(const wxXmlNode* node,
 526                        const wxArtClient& defaultArtClient = wxART_OTHER,
 527                        wxSize size = wxDefaultSize);
 528
 529     /**
 530         Gets a bool flag (1, t, yes, on, true are @true, everything else is @false).
 531     */
 532     bool GetBool(const wxString& param, bool defaultv = false);
 533
 534     /**
 535         Gets colour in HTML syntax (\#RRGGBB).
 536     */
 537     wxColour GetColour(const wxString& param,
 538                        const wxColour& defaultColour = wxNullColour);
 539
 540     /**
 541         Returns the current file system.
 542     */
 543     wxFileSystem& GetCurFileSystem();
 544
 545     /**
 546         Gets a dimension (may be in dialog units).
 547     */
 548     wxCoord GetDimension(const wxString& param, wxCoord defaultv = 0,
 549                          wxWindow* windowToUse = 0);
 550
 551     /**
 552         Gets a font.
 553     */
 554     wxFont GetFont(const wxString& param = "font");
 555
 556     /**
 557         Returns the XRCID.
 558     */
 559     int GetID();
 560
 561     /**
 562         Returns an icon.
 563     */
 564     wxIcon GetIcon(const wxString& param = "icon",
 565                    const wxArtClient& defaultArtClient = wxART_OTHER,
 566                    wxSize size = wxDefaultSize);
 567
 568     /**
 569         Gets an icon from an XmlNode.
 570
 571         @since 2.9.1
 572     */
 573     wxIcon GetIcon(const wxXmlNode* node,
 574                    const wxArtClient& defaultArtClient = wxART_OTHER,
 575                    wxSize size = wxDefaultSize);
 576
 577     /**
 578         Returns an icon bundle.
 579
 580         @note
 581         Bundles can be loaded either with stock IDs or from files that contain
 582         more than one image (e.g. Windows icon files). If a file contains only
 583         single image, a bundle with only one icon will be created.
 584
 585         @since 2.9.0
 586      */
 587     wxIconBundle GetIconBundle(const wxString& param,
 588                                const wxArtClient& defaultArtClient = wxART_OTHER);
 589
 590     /**
 591         Creates an image list from the @a param markup data.
 592
 593         @return
 594             The new instance of wxImageList or @NULL if no data is found.
 595
 596         @since 2.9.1
 597     */
 598     wxImageList *GetImageList(const wxString& param = wxT("imagelist"));
 599
 600     /**
 601         Gets the integer value from the parameter.
 602     */
 603     long GetLong(const wxString& param, long defaultv = 0);
 604
 605     /**
 606         Returns the resource name.
 607     */
 608     wxString GetName();
 609
 610     /**
 611         Gets node content from wxXML_ENTITY_NODE.
 612     */
 613     wxString GetNodeContent(wxXmlNode* node);
 614
 615     /**
 616         Finds the node or returns @NULL.
 617     */
 618     wxXmlNode* GetParamNode(const wxString& param);
 619
 620     /**
 621         Finds the parameter value or returns the empty string.
 622     */
 623     wxString GetParamValue(const wxString& param);
 624
 625     /**
 626         Returns the node parameter value.
 627
 628         @since 2.9.1
 629     */
 630     wxString GetParamValue(const wxXmlNode* node);
 631
 632     /**
 633         Gets the position (may be in dialog units).
 634     */
 635     wxPoint GetPosition(const wxString& param = "pos");
 636
 637     /**
 638         Gets the size (may be in dialog units).
 639     */
 640     wxSize GetSize(const wxString& param = "size", wxWindow* windowToUse = 0);
 641
 642     /**
 643         Gets style flags from text in form "flag | flag2| flag3 |..."
 644         Only understands flags added with AddStyle().
 645     */
 646     int GetStyle(const wxString& param = "style", int defaults = 0);
 647
 648     /**
 649         Gets text from param and does some conversions:
 650         - replaces \\n, \\r, \\t by respective characters (according to C syntax)
 651         - replaces @c $ by @c  and @c $$ by @c $ (needed for @c _File to @c File
 652           translation because of XML syntax)
 653         - calls wxGetTranslations (unless disabled in wxXmlResource)
 654     */
 655     wxString GetText(const wxString& param, bool translate = true);
 656
 657     /**
 658         Check to see if a parameter exists.
 659     */
 660     bool HasParam(const wxString& param);
 661
 662     /**
 663         Convenience function.
 664         Returns @true if the node has a property class equal to classname,
 665         e.g. object class="wxDialog".
 666     */
 667     bool IsOfClass(wxXmlNode* node, const wxString& classname);
 668
 669     /**
 670         Sets common window options.
 671     */
 672     void SetupWindow(wxWindow* wnd);
 673
 674     /**
 675         Reports error in XRC resources to the user.
 676
 677         See wxXmlResource::ReportError() for more information.
 678
 679         @since 2.9.0
 680      */
 681     void ReportError(wxXmlNode *context, const wxString& message);
 682
 683     /**
 684         Like ReportError(wxXmlNode*, const wxString&), but uses the node
 685         of currently processed object (m_node) as the context.
 686
 687         @since 2.9.0
 688      */
 689     void ReportError(const wxString& message);
 690
 691     /**
 692         Like ReportError(wxXmlNode*, const wxString&), but uses the node
 693         of parameter @a param of the currently processed object as the context.
 694         This is convenience function for reporting errors in particular
 695         parameters.
 696
 697         @since 2.9.0
 698      */
 699     void ReportParamError(const wxString& param, const wxString& message);
 700 };
 701