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
 339
 340
 341 /**
 342     @class wxXmlResourceHandler
 343
 344     wxXmlResourceHandler is an abstract base class for resource handlers
 345     capable of creating a control from an XML node.
 346
 347     See @ref overview_xrc for details.
 348
 349     @library{wxxrc}
 350     @category{xrc}
 351 */
 352 class wxXmlResourceHandler : public wxObject
 353 {
 354 public:
 355     /**
 356         Default constructor.
 357     */
 358     wxXmlResourceHandler();
 359
 360     /**
 361         Destructor.
 362     */
 363     virtual ~wxXmlResourceHandler();
 364
 365     /**
 366         Creates an object (menu, dialog, control, ...) from an XML node.
 367         Should check for validity. @a parent is a higher-level object
 368         (usually window, dialog or panel) that is often necessary to
 369         create the resource.
 370
 371         If @b instance is non-@NULL it should not create a new instance via
 372         'new' but should rather use this one, and call its Create method.
 373     */
 374     wxObject* CreateResource(wxXmlNode* node, wxObject* parent,
 375                              wxObject* instance);
 376
 377     /**
 378         Called from CreateResource after variables were filled.
 379     */
 380     virtual wxObject* DoCreateResource() = 0;
 381
 382     /**
 383         Returns @true if it understands this node and can create
 384         a resource from it, @false otherwise.
 385
 386         @note
 387         You must not call any wxXmlResourceHandler methods except IsOfClass()
 388         from this method! The instance is not yet initialized with node data
 389         at the time CanHandle() is called and it is only safe to operate on
 390         node directly or to call IsOfClass().
 391     */
 392     virtual bool CanHandle(wxXmlNode* node) = 0;
 393
 394     /**
 395         Sets the parent resource.
 396     */
 397     void SetParentResource(wxXmlResource* res);
 398
 399
 400 protected:
 401
 402     /**
 403         Add a style flag (e.g. @c wxMB_DOCKABLE) to the list of flags
 404         understood by this handler.
 405     */
 406     void AddStyle(const wxString& name, int value);
 407
 408     /**
 409         Add styles common to all wxWindow-derived classes.
 410     */
 411     void AddWindowStyles();
 412
 413     /**
 414         Creates children.
 415     */
 416     void CreateChildren(wxObject* parent, bool this_hnd_only = false);
 417
 418     /**
 419         Helper function.
 420     */
 421     void CreateChildrenPrivately(wxObject* parent,
 422                                  wxXmlNode* rootnode = NULL);
 423
 424     /**
 425         Creates a resource from a node.
 426     */
 427     wxObject* CreateResFromNode(wxXmlNode* node, wxObject* parent,
 428                                 wxObject* instance = NULL);
 429
 430     /**
 431         Creates an animation (see wxAnimation) from the filename specified in @a param.
 432     */
 433     wxAnimation GetAnimation(const wxString& param = "animation");
 434
 435     /**
 436         Gets a bitmap.
 437     */
 438     wxBitmap GetBitmap(const wxString& param = "bitmap",
 439                        const wxArtClient& defaultArtClient = wxART_OTHER,
 440                        wxSize size = wxDefaultSize);
 441
 442     /**
 443         Gets a bool flag (1, t, yes, on, true are @true, everything else is @false).
 444     */
 445     bool GetBool(const wxString& param, bool defaultv = false);
 446
 447     /**
 448         Gets colour in HTML syntax (\#RRGGBB).
 449     */
 450     wxColour GetColour(const wxString& param,
 451                        const wxColour& defaultColour = wxNullColour);
 452
 453     /**
 454         Returns the current file system.
 455     */
 456     wxFileSystem& GetCurFileSystem();
 457
 458     /**
 459         Gets a dimension (may be in dialog units).
 460     */
 461     wxCoord GetDimension(const wxString& param, wxCoord defaultv = 0,
 462                          wxWindow* windowToUse = 0);
 463
 464     /**
 465         Gets a font.
 466     */
 467     wxFont GetFont(const wxString& param = "font");
 468
 469     /**
 470         Returns the XRCID.
 471     */
 472     int GetID();
 473
 474     /**
 475         Returns an icon.
 476     */
 477     wxIcon GetIcon(const wxString& param = "icon",
 478                    const wxArtClient& defaultArtClient = wxART_OTHER,
 479                    wxSize size = wxDefaultSize);
 480
 481     /**
 482         Gets the integer value from the parameter.
 483     */
 484     long GetLong(const wxString& param, long defaultv = 0);
 485
 486     /**
 487         Returns the resource name.
 488     */
 489     wxString GetName();
 490
 491     /**
 492         Gets node content from wxXML_ENTITY_NODE.
 493     */
 494     wxString GetNodeContent(wxXmlNode* node);
 495
 496     /**
 497         Finds the node or returns @NULL.
 498     */
 499     wxXmlNode* GetParamNode(const wxString& param);
 500
 501     /**
 502         Finds the parameter value or returns the empty string.
 503     */
 504     wxString GetParamValue(const wxString& param);
 505
 506     /**
 507         Gets the position (may be in dialog units).
 508     */
 509     wxPoint GetPosition(const wxString& param = "pos");
 510
 511     /**
 512         Gets the size (may be in dialog units).
 513     */
 514     wxSize GetSize(const wxString& param = "size", wxWindow* windowToUse = 0);
 515
 516     /**
 517         Gets style flags from text in form "flag | flag2| flag3 |..."
 518         Only understands flags added with AddStyle().
 519     */
 520     int GetStyle(const wxString& param = "style", int defaults = 0);
 521
 522     /**
 523         Gets text from param and does some conversions:
 524         - replaces \\n, \\r, \\t by respective characters (according to C syntax)
 525         - replaces @c $ by @c  and @c $$ by @c $ (needed for @c _File to @c File
 526           translation because of XML syntax)
 527         - calls wxGetTranslations (unless disabled in wxXmlResource)
 528     */
 529     wxString GetText(const wxString& param, bool translate = true);
 530
 531     /**
 532         Check to see if a parameter exists.
 533     */
 534     bool HasParam(const wxString& param);
 535
 536     /**
 537         Convenience function.
 538         Returns @true if the node has a property class equal to classname,
 539         e.g. object class="wxDialog".
 540     */
 541     bool IsOfClass(wxXmlNode* node, const wxString& classname);
 542
 543     /**
 544         Sets common window options.
 545     */
 546     void SetupWindow(wxWindow* wnd);
 547 };
 548