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     wxObject* LoadObject(wxWindow* parent, const wxString& name,
 291                          const wxString& classname);
 292     bool LoadObject(wxObject* instance, wxWindow* parent,
 293                     const wxString& name,
 294                     const wxString& classname);
 295     //@}
 296
 297     /**
 298         Loads a panel. @a parent points to the parent window.
 299     */
 300     wxPanel* LoadPanel(wxWindow* parent, const wxString& name);
 301
 302     /**
 303         Loads a panel. @a parent points to the parent window.
 304         This form is used to finish creation of an already existing instance.
 305     */
 306     bool LoadPanel(wxPanel* panel, wxWindow* parent, const wxString& name);
 307
 308     /**
 309         Loads a toolbar.
 310     */
 311     wxToolBar* LoadToolBar(wxWindow* parent, const wxString& name);
 312
 313     /**
 314         Sets the global resources object and returns a pointer to the previous one
 315         (may be @NULL).
 316     */
 317     static wxXmlResource* Set(wxXmlResource* res);
 318
 319     /**
 320         Sets the domain (message catalog) that will be used to load
 321         translatable strings in the XRC.
 322     */
 323     void SetDomain(const wxString& domain);
 324
 325     /**
 326         Sets flags (bitlist of ::wxXmlResourceFlags enumeration values).
 327     */
 328     void SetFlags(int flags);
 329
 330     /**
 331         This function unloads a resource previously loaded by Load().
 332
 333         Returns @true if the resource was successfully unloaded and @false if it
 334         hasn't been found in the list of loaded resources.
 335     */
 336     bool Unload(const wxString& filename);
 337
 338 protected:
 339     /**
 340         Reports error in XRC resources to the user.
 341
 342         Any errors in XRC input files should be reported using this method
 343         (or its wxXmlResourceHandler::ReportError() equivalent). Unlike
 344         wxLogError(), this method presents the error to the user in a more
 345         usable form. In particular, the output is compiler-like and contains
 346         information about the exact location of the error.
 347
 348         @param context XML node the error occurred in or relates to. This can
 349                        be @NULL, but should be the most specific node possible,
 350                        as its line number is what is reported to the user.
 351         @param message Text of the error message. This string should always
 352                        be in English (i.e. not wrapped in _()). It shouldn't
 353                        be a sentence -- it should start with lower-case letter
 354                        and shouldn't have a trailing period or exclamation
 355                        point.
 356
 357         @since 2.9.0
 358
 359         @see wxXmlResourceHandler::ReportError(), DoReportError()
 360      */
 361     void ReportError(wxXmlNode *context, const wxString& message);
 362
 363     /**
 364         Implementation of XRC resources errors reporting.
 365
 366         This method is called by ReportError() and shouldn't be called
 367         directly; use ReportError() or wxXmlResourceHandler::ReportError()
 368         to log errors.
 369
 370         Default implementation uses wxLogError().
 371
 372         @param xrcFile  File the error occurred in or empty string if it
 373                         couldn't be determined.
 374         @param position XML node where the error occurred or @NULL if it
 375                         couldn't be determined.
 376         @param message  Text of the error message. See ReportError()
 377                         documentation for details of the string's format.
 378
 379         @note
 380         You may override this method in a derived class to customize errors
 381         reporting. If you do so, you'll need to either use the derived class
 382         in all your code or call wxXmlResource::Set() to change the global
 383         wxXmlResource instance to your class.
 384
 385         @since 2.9.0
 386
 387         @see ReportError()
 388     */
 389     virtual void DoReportError(const wxString& xrcFile, wxXmlNode *position,
 390                                const wxString& message);
 391 };
 392
 393
 394
 395 /**
 396     @class wxXmlResourceHandler
 397
 398     wxXmlResourceHandler is an abstract base class for resource handlers
 399     capable of creating a control from an XML node.
 400
 401     See @ref overview_xrc for details.
 402
 403     @library{wxxrc}
 404     @category{xrc}
 405 */
 406 class wxXmlResourceHandler : public wxObject
 407 {
 408 public:
 409     /**
 410         Default constructor.
 411     */
 412     wxXmlResourceHandler();
 413
 414     /**
 415         Destructor.
 416     */
 417     virtual ~wxXmlResourceHandler();
 418
 419     /**
 420         Creates an object (menu, dialog, control, ...) from an XML node.
 421         Should check for validity. @a parent is a higher-level object
 422         (usually window, dialog or panel) that is often necessary to
 423         create the resource.
 424
 425         If @b instance is non-@NULL it should not create a new instance via
 426         'new' but should rather use this one, and call its Create method.
 427     */
 428     wxObject* CreateResource(wxXmlNode* node, wxObject* parent,
 429                              wxObject* instance);
 430
 431     /**
 432         Called from CreateResource after variables were filled.
 433     */
 434     virtual wxObject* DoCreateResource() = 0;
 435
 436     /**
 437         Returns @true if it understands this node and can create
 438         a resource from it, @false otherwise.
 439
 440         @note
 441         You must not call any wxXmlResourceHandler methods except IsOfClass()
 442         from this method! The instance is not yet initialized with node data
 443         at the time CanHandle() is called and it is only safe to operate on
 444         node directly or to call IsOfClass().
 445     */
 446     virtual bool CanHandle(wxXmlNode* node) = 0;
 447
 448     /**
 449         Sets the parent resource.
 450     */
 451     void SetParentResource(wxXmlResource* res);
 452
 453
 454 protected:
 455
 456     /**
 457         Add a style flag (e.g. @c wxMB_DOCKABLE) to the list of flags
 458         understood by this handler.
 459     */
 460     void AddStyle(const wxString& name, int value);
 461
 462     /**
 463         Add styles common to all wxWindow-derived classes.
 464     */
 465     void AddWindowStyles();
 466
 467     /**
 468         Creates children.
 469     */
 470     void CreateChildren(wxObject* parent, bool this_hnd_only = false);
 471
 472     /**
 473         Helper function.
 474     */
 475     void CreateChildrenPrivately(wxObject* parent,
 476                                  wxXmlNode* rootnode = NULL);
 477
 478     /**
 479         Creates a resource from a node.
 480     */
 481     wxObject* CreateResFromNode(wxXmlNode* node, wxObject* parent,
 482                                 wxObject* instance = NULL);
 483
 484     /**
 485         Creates an animation (see wxAnimation) from the filename specified in @a param.
 486     */
 487     wxAnimation GetAnimation(const wxString& param = "animation");
 488
 489     /**
 490         Gets a bitmap.
 491     */
 492     wxBitmap GetBitmap(const wxString& param = "bitmap",
 493                        const wxArtClient& defaultArtClient = wxART_OTHER,
 494                        wxSize size = wxDefaultSize);
 495
 496     /**
 497         Gets a bool flag (1, t, yes, on, true are @true, everything else is @false).
 498     */
 499     bool GetBool(const wxString& param, bool defaultv = false);
 500
 501     /**
 502         Gets colour in HTML syntax (\#RRGGBB).
 503     */
 504     wxColour GetColour(const wxString& param,
 505                        const wxColour& defaultColour = wxNullColour);
 506
 507     /**
 508         Returns the current file system.
 509     */
 510     wxFileSystem& GetCurFileSystem();
 511
 512     /**
 513         Gets a dimension (may be in dialog units).
 514     */
 515     wxCoord GetDimension(const wxString& param, wxCoord defaultv = 0,
 516                          wxWindow* windowToUse = 0);
 517
 518     /**
 519         Gets a font.
 520     */
 521     wxFont GetFont(const wxString& param = "font");
 522
 523     /**
 524         Returns the XRCID.
 525     */
 526     int GetID();
 527
 528     /**
 529         Returns an icon.
 530     */
 531     wxIcon GetIcon(const wxString& param = "icon",
 532                    const wxArtClient& defaultArtClient = wxART_OTHER,
 533                    wxSize size = wxDefaultSize);
 534
 535     /**
 536         Gets the integer value from the parameter.
 537     */
 538     long GetLong(const wxString& param, long defaultv = 0);
 539
 540     /**
 541         Returns the resource name.
 542     */
 543     wxString GetName();
 544
 545     /**
 546         Gets node content from wxXML_ENTITY_NODE.
 547     */
 548     wxString GetNodeContent(wxXmlNode* node);
 549
 550     /**
 551         Finds the node or returns @NULL.
 552     */
 553     wxXmlNode* GetParamNode(const wxString& param);
 554
 555     /**
 556         Finds the parameter value or returns the empty string.
 557     */
 558     wxString GetParamValue(const wxString& param);
 559
 560     /**
 561         Gets the position (may be in dialog units).
 562     */
 563     wxPoint GetPosition(const wxString& param = "pos");
 564
 565     /**
 566         Gets the size (may be in dialog units).
 567     */
 568     wxSize GetSize(const wxString& param = "size", wxWindow* windowToUse = 0);
 569
 570     /**
 571         Gets style flags from text in form "flag | flag2| flag3 |..."
 572         Only understands flags added with AddStyle().
 573     */
 574     int GetStyle(const wxString& param = "style", int defaults = 0);
 575
 576     /**
 577         Gets text from param and does some conversions:
 578         - replaces \\n, \\r, \\t by respective characters (according to C syntax)
 579         - replaces @c $ by @c  and @c $$ by @c $ (needed for @c _File to @c File
 580           translation because of XML syntax)
 581         - calls wxGetTranslations (unless disabled in wxXmlResource)
 582     */
 583     wxString GetText(const wxString& param, bool translate = true);
 584
 585     /**
 586         Check to see if a parameter exists.
 587     */
 588     bool HasParam(const wxString& param);
 589
 590     /**
 591         Convenience function.
 592         Returns @true if the node has a property class equal to classname,
 593         e.g. object class="wxDialog".
 594     */
 595     bool IsOfClass(wxXmlNode* node, const wxString& classname);
 596
 597     /**
 598         Sets common window options.
 599     */
 600     void SetupWindow(wxWindow* wnd);
 601
 602     /**
 603         Reports error in XRC resources to the user.
 604
 605         See wxXmlResource::ReportError() for more information.
 606
 607         @since 2.9.0
 608      */
 609     void ReportError(wxXmlNode *context, const wxString& message);
 610
 611     /**
 612         Like ReportError(wxXmlNode*, const wxString&), but uses the node
 613         of currently processed object (m_node) as the context.
 614
 615         @since 2.9.0
 616      */
 617     void ReportError(const wxString& message);
 618
 619     /**
 620         Like ReportError(wxXmlNode*, const wxString&), but uses the node
 621         of parameter @a param of the currently processed object as the context.
 622         This is convenience function for reporting errors in particular
 623         parameters.
 624
 625         @since 2.9.0
 626      */
 627     void ReportParamError(const wxString& param, const wxString& message);
 628 };
 629