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 licence
   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(const 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, const 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 direction.
 558
 559         If the given @a param is not present or has empty value, @a dir is
 560         returned by default. Otherwise the value of the parameter is parsed and
 561         a warning is generated if it's not one of @c wxLEFT, @c wxTOP, @c
 562         wxRIGHT or @c wxBOTTOM.
 563
 564         @since 2.9.3
 565      */
 566     wxDirection GetDirection(const wxString& param, wxDirection dir = wxLEFT);
 567
 568     /**
 569         Gets a font.
 570     */
 571     wxFont GetFont(const wxString& param = "font");
 572
 573     /**
 574         Returns the XRCID.
 575     */
 576     int GetID();
 577
 578     /**
 579         Returns an icon.
 580     */
 581     wxIcon GetIcon(const wxString& param = "icon",
 582                    const wxArtClient& defaultArtClient = wxART_OTHER,
 583                    wxSize size = wxDefaultSize);
 584
 585     /**
 586         Gets an icon from an XmlNode.
 587
 588         @since 2.9.1
 589     */
 590     wxIcon GetIcon(const wxXmlNode* node,
 591                    const wxArtClient& defaultArtClient = wxART_OTHER,
 592                    wxSize size = wxDefaultSize);
 593
 594     /**
 595         Returns an icon bundle.
 596
 597         @note
 598         Bundles can be loaded either with stock IDs or from files that contain
 599         more than one image (e.g. Windows icon files). If a file contains only
 600         single image, a bundle with only one icon will be created.
 601
 602         @since 2.9.0
 603      */
 604     wxIconBundle GetIconBundle(const wxString& param,
 605                                const wxArtClient& defaultArtClient = wxART_OTHER);
 606
 607     /**
 608         Creates an image list from the @a param markup data.
 609
 610         @return
 611             The new instance of wxImageList or @NULL if no data is found.
 612
 613         @since 2.9.1
 614     */
 615     wxImageList *GetImageList(const wxString& param = wxT("imagelist"));
 616
 617     /**
 618         Gets the integer value from the parameter.
 619     */
 620     long GetLong(const wxString& param, long defaultv = 0);
 621
 622     /**
 623         Returns the resource name.
 624     */
 625     wxString GetName();
 626
 627     /**
 628         Gets node content from wxXML_ENTITY_NODE.
 629     */
 630     wxString GetNodeContent(wxXmlNode* node);
 631
 632     /**
 633         Finds the node or returns @NULL.
 634     */
 635     wxXmlNode* GetParamNode(const wxString& param);
 636
 637     /**
 638         Finds the parameter value or returns the empty string.
 639     */
 640     wxString GetParamValue(const wxString& param);
 641
 642     /**
 643         Returns the node parameter value.
 644
 645         @since 2.9.1
 646     */
 647     wxString GetParamValue(const wxXmlNode* node);
 648
 649     /**
 650         Gets the position (may be in dialog units).
 651     */
 652     wxPoint GetPosition(const wxString& param = "pos");
 653
 654     /**
 655         Gets the size (may be in dialog units).
 656     */
 657     wxSize GetSize(const wxString& param = "size", wxWindow* windowToUse = 0);
 658
 659     /**
 660         Gets style flags from text in form "flag | flag2| flag3 |..."
 661         Only understands flags added with AddStyle().
 662     */
 663     int GetStyle(const wxString& param = "style", int defaults = 0);
 664
 665     /**
 666         Gets text from param and does some conversions:
 667         - replaces \\n, \\r, \\t by respective characters (according to C syntax)
 668         - replaces @c $ by @c  and @c $$ by @c $ (needed for @c _File to @c File
 669           translation because of XML syntax)
 670         - calls wxGetTranslations (unless disabled in wxXmlResource)
 671     */
 672     wxString GetText(const wxString& param, bool translate = true);
 673
 674     /**
 675         Check to see if a parameter exists.
 676     */
 677     bool HasParam(const wxString& param);
 678
 679     /**
 680         Convenience function.
 681         Returns @true if the node has a property class equal to classname,
 682         e.g. object class="wxDialog".
 683     */
 684     bool IsOfClass(wxXmlNode* node, const wxString& classname);
 685
 686     /**
 687         Sets common window options.
 688     */
 689     void SetupWindow(wxWindow* wnd);
 690
 691     /**
 692         Reports error in XRC resources to the user.
 693
 694         See wxXmlResource::ReportError() for more information.
 695
 696         @since 2.9.0
 697      */
 698     void ReportError(wxXmlNode *context, const wxString& message);
 699
 700     /**
 701         Like ReportError(wxXmlNode*, const wxString&), but uses the node
 702         of currently processed object (m_node) as the context.
 703
 704         @since 2.9.0
 705      */
 706     void ReportError(const wxString& message);
 707
 708     /**
 709         Like ReportError(wxXmlNode*, const wxString&), but uses the node
 710         of parameter @a param of the currently processed object as the context.
 711         This is convenience function for reporting errors in particular
 712         parameters.
 713
 714         @since 2.9.0
 715      */
 716     void ReportParamError(const wxString& param, const wxString& message);
 717 };
 718