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()
 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()
 217     */
 218     bool LoadFile(const wxFileName& file);
 219
 220     /**
 221         Loads a bitmap resource from a file.
 222     */
 223     wxBitmap LoadBitmap(const wxString& name);
 224
 225     /**
 226         Loads a dialog. @a parent points to parent window (if any).
 227     */
 228     wxDialog* LoadDialog(wxWindow* parent, const wxString& name);
 229
 230     /**
 231         Loads a dialog. @a parent points to parent window (if any).
 232
 233         This form is used to finish creation of an already existing instance (the main
 234         reason for this is that you may want to use derived class with a new event table).
 235         Example:
 236
 237         @code
 238           MyDialog dlg;
 239           wxXmlResource::Get()->LoadDialog(&dlg, mainFrame, "my_dialog");
 240           dlg.ShowModal();
 241         @endcode
 242     */
 243     bool LoadDialog(wxDialog* dlg, wxWindow* parent, const wxString& name);
 244
 245     /**
 246         Loads a frame.
 247     */
 248     bool LoadFrame(wxFrame* frame, wxWindow* parent,
 249                    const wxString& name);
 250
 251     /**
 252         Loads an icon resource from a file.
 253     */
 254     wxIcon LoadIcon(const wxString& name);
 255
 256     /**
 257         Loads menu from resource. Returns @NULL on failure.
 258     */
 259     wxMenu* LoadMenu(const wxString& name);
 260
 261     //@{
 262     /**
 263         Loads a menubar from resource. Returns @NULL on failure.
 264     */
 265     wxMenuBar* LoadMenuBar(wxWindow* parent, const wxString& name);
 266     wxMenuBar* LoadMenuBar(const wxString& name);
 267     //@}
 268
 269     //@{
 270     /**
 271         Load an object from the resource specifying both the resource name and the
 272         class name.
 273
 274         The first overload lets you load nonstandard container windows and returns
 275         @NULL on failure. The second one lets you finish the creation of an existing
 276         instance and returns @false on failure.
 277     */
 278     wxObject* LoadObject(wxWindow* parent, const wxString& name,
 279                          const wxString& classname);
 280     bool LoadObject(wxObject* instance, wxWindow* parent,
 281                     const wxString& name,
 282                     const wxString& classname);
 283     //@}
 284
 285     /**
 286         Loads a panel. @a parent points to the parent window.
 287     */
 288     wxPanel* LoadPanel(wxWindow* parent, const wxString& name);
 289
 290     /**
 291         Loads a panel. @a parent points to the parent window.
 292         This form is used to finish creation of an already existing instance.
 293     */
 294     bool LoadPanel(wxPanel* panel, wxWindow* parent, const wxString& name);
 295
 296     /**
 297         Loads a toolbar.
 298     */
 299     wxToolBar* LoadToolBar(wxWindow* parent, const wxString& name);
 300
 301     /**
 302         Sets the global resources object and returns a pointer to the previous one
 303         (may be @NULL).
 304     */
 305     static wxXmlResource* Set(wxXmlResource* res);
 306
 307     /**
 308         Sets the domain (message catalog) that will be used to load
 309         translatable strings in the XRC.
 310     */
 311     void SetDomain(const wxString& domain);
 312
 313     /**
 314         Sets flags (bitlist of ::wxXmlResourceFlags enumeration values).
 315     */
 316     void SetFlags(int flags);
 317
 318     /**
 319         This function unloads a resource previously loaded by Load().
 320
 321         Returns @true if the resource was successfully unloaded and @false if it
 322         hasn't been found in the list of loaded resources.
 323     */
 324     bool Unload(const wxString& filename);
 325 };
 326
 327
 328
 329 /**
 330     @class wxXmlResourceHandler
 331
 332     wxXmlResourceHandler is an abstract base class for resource handlers
 333     capable of creating a control from an XML node.
 334
 335     See @ref overview_xrc for details.
 336
 337     @library{wxxrc}
 338     @category{xrc}
 339 */
 340 class wxXmlResourceHandler : public wxObject
 341 {
 342 public:
 343     /**
 344         Default constructor.
 345     */
 346     wxXmlResourceHandler();
 347
 348     /**
 349         Destructor.
 350     */
 351     virtual ~wxXmlResourceHandler();
 352
 353     /**
 354         Creates an object (menu, dialog, control, ...) from an XML node.
 355         Should check for validity. @a parent is a higher-level object
 356         (usually window, dialog or panel) that is often necessary to
 357         create the resource.
 358
 359         If @b instance is non-@NULL it should not create a new instance via
 360         'new' but should rather use this one, and call its Create method.
 361     */
 362     wxObject* CreateResource(wxXmlNode* node, wxObject* parent,
 363                              wxObject* instance);
 364
 365     /**
 366         Called from CreateResource after variables were filled.
 367     */
 368     virtual wxObject* DoCreateResource() = 0;
 369
 370     /**
 371         Returns @true if it understands this node and can create
 372         a resource from it, @false otherwise.
 373
 374         @note
 375         You must not call any wxXmlResourceHandler methods except IsOfClass()
 376         from this method! The instance is not yet initialized with node data
 377         at the time CanHandle() is called and it is only safe to operate on
 378         node directly or to call IsOfClass().
 379     */
 380     virtual bool CanHandle(wxXmlNode* node) = 0;
 381
 382     /**
 383         Sets the parent resource.
 384     */
 385     void SetParentResource(wxXmlResource* res);
 386
 387
 388 protected:
 389
 390     /**
 391         Add a style flag (e.g. @c wxMB_DOCKABLE) to the list of flags
 392         understood by this handler.
 393     */
 394     void AddStyle(const wxString& name, int value);
 395
 396     /**
 397         Add styles common to all wxWindow-derived classes.
 398     */
 399     void AddWindowStyles();
 400
 401     /**
 402         Creates children.
 403     */
 404     void CreateChildren(wxObject* parent, bool this_hnd_only = false);
 405
 406     /**
 407         Helper function.
 408     */
 409     void CreateChildrenPrivately(wxObject* parent,
 410                                  wxXmlNode* rootnode = NULL);
 411
 412     /**
 413         Creates a resource from a node.
 414     */
 415     wxObject* CreateResFromNode(wxXmlNode* node, wxObject* parent,
 416                                 wxObject* instance = NULL);
 417
 418     /**
 419         Creates an animation (see wxAnimation) from the filename specified in @a param.
 420     */
 421     wxAnimation GetAnimation(const wxString& param = "animation");
 422
 423     /**
 424         Gets a bitmap.
 425     */
 426     wxBitmap GetBitmap(const wxString& param = "bitmap",
 427                        const wxArtClient& defaultArtClient = wxART_OTHER,
 428                        wxSize size = wxDefaultSize);
 429
 430     /**
 431         Gets a bool flag (1, t, yes, on, true are @true, everything else is @false).
 432     */
 433     bool GetBool(const wxString& param, bool defaultv = false);
 434
 435     /**
 436         Gets colour in HTML syntax (\#RRGGBB).
 437     */
 438     wxColour GetColour(const wxString& param,
 439                        const wxColour& defaultColour = wxNullColour);
 440
 441     /**
 442         Returns the current file system.
 443     */
 444     wxFileSystem& GetCurFileSystem();
 445
 446     /**
 447         Gets a dimension (may be in dialog units).
 448     */
 449     wxCoord GetDimension(const wxString& param, wxCoord defaultv = 0,
 450                          wxWindow* windowToUse = 0);
 451
 452     /**
 453         Gets a font.
 454     */
 455     wxFont GetFont(const wxString& param = "font");
 456
 457     /**
 458         Returns the XRCID.
 459     */
 460     int GetID();
 461
 462     /**
 463         Returns an icon.
 464     */
 465     wxIcon GetIcon(const wxString& param = "icon",
 466                    const wxArtClient& defaultArtClient = wxART_OTHER,
 467                    wxSize size = wxDefaultSize);
 468
 469     /**
 470         Gets the integer value from the parameter.
 471     */
 472     long GetLong(const wxString& param, long defaultv = 0);
 473
 474     /**
 475         Returns the resource name.
 476     */
 477     wxString GetName();
 478
 479     /**
 480         Gets node content from wxXML_ENTITY_NODE.
 481     */
 482     wxString GetNodeContent(wxXmlNode* node);
 483
 484     /**
 485         Finds the node or returns @NULL.
 486     */
 487     wxXmlNode* GetParamNode(const wxString& param);
 488
 489     /**
 490         Finds the parameter value or returns the empty string.
 491     */
 492     wxString GetParamValue(const wxString& param);
 493
 494     /**
 495         Gets the position (may be in dialog units).
 496     */
 497     wxPoint GetPosition(const wxString& param = "pos");
 498
 499     /**
 500         Gets the size (may be in dialog units).
 501     */
 502     wxSize GetSize(const wxString& param = "size", wxWindow* windowToUse = 0);
 503
 504     /**
 505         Gets style flags from text in form "flag | flag2| flag3 |..."
 506         Only understands flags added with AddStyle().
 507     */
 508     int GetStyle(const wxString& param = "style", int defaults = 0);
 509
 510     /**
 511         Gets text from param and does some conversions:
 512         - replaces \\n, \\r, \\t by respective characters (according to C syntax)
 513         - replaces @c $ by @c  and @c $$ by @c $ (needed for @c _File to @c File
 514           translation because of XML syntax)
 515         - calls wxGetTranslations (unless disabled in wxXmlResource)
 516     */
 517     wxString GetText(const wxString& param, bool translate = true);
 518
 519     /**
 520         Check to see if a parameter exists.
 521     */
 522     bool HasParam(const wxString& param);
 523
 524     /**
 525         Convenience function.
 526         Returns @true if the node has a property class equal to classname,
 527         e.g. object class="wxDialog".
 528     */
 529     bool IsOfClass(wxXmlNode* node, const wxString& classname);
 530
 531     /**
 532         Sets common window options.
 533     */
 534     void SetupWindow(wxWindow* wnd);
 535 };
 536