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