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