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     @see @ref overview_xrc, @ref overview_xrcformat
  35
  36     @library{wxxrc}
  37     @category{xrc}
  38 */
  39 class wxXmlResource : public wxObject
  40 {
  41 public:
  42     /**
  43         Constructor.
  44
  45         @param filemask
  46             The XRC file, archive file, or wildcard specification that will be
  47             used to load all resource files inside a zip archive.
  48         @param flags
  49             One or more value of the ::wxXmlResourceFlags enumeration.
  50         @param domain
  51             The name of the gettext catalog to search for translatable strings.
  52             By default all loaded catalogs will be searched.
  53             This provides a way to allow the strings to only come from a specific catalog.
  54     */
  55     wxXmlResource(const wxString& filemask,
  56                   int flags = wxXRC_USE_LOCALE,
  57                   const wxString& domain = wxEmptyString);
  58
  59     /**
  60         Constructor.
  61
  62         @param flags
  63             One or more value of the ::wxXmlResourceFlags enumeration.
  64         @param domain
  65             The name of the gettext catalog to search for translatable strings.
  66             By default all loaded catalogs will be searched.
  67             This provides a way to allow the strings to only come from a specific catalog.
  68     */
  69     wxXmlResource(int flags = wxXRC_USE_LOCALE,
  70                   const wxString& domain = wxEmptyString);
  71
  72     /**
  73         Destructor.
  74     */
  75     virtual ~wxXmlResource();
  76
  77     /**
  78         Initializes only a specific handler (or custom handler).
  79         Convention says that the handler name is equal to the control's name plus
  80         'XmlHandler', for example wxTextCtrlXmlHandler, wxHtmlWindowXmlHandler.
  81
  82         The XML resource compiler (wxxrc) can create include file that contains
  83         initialization code for all controls used within the resource.
  84         Note that this handler must be allocated on the heap, since it will be
  85         deleted by ClearHandlers() later.
  86     */
  87     void AddHandler(wxXmlResourceHandler* handler);
  88
  89     /**
  90         Attaches an unknown control to the given panel/window/dialog.
  91         Unknown controls are used in conjunction with \<object class="unknown"\>.
  92     */
  93     bool AttachUnknownControl(const wxString& name,
  94                               wxWindow* control,
  95                               wxWindow* parent = NULL);
  96
  97     /**
  98         Removes all handlers and deletes them (this means that any handlers
  99         added using AddHandler() must be allocated on the heap).
 100     */
 101     void ClearHandlers();
 102
 103     /**
 104         Compares the XRC version to the argument.
 105
 106         Returns -1 if the XRC version is less than the argument,
 107         +1 if greater, and 0 if they are equal.
 108     */
 109     int CompareVersion(int major, int minor, int release, int revision) const;
 110
 111     /**
 112         Returns a string ID corresponding to the given numeric ID.
 113
 114         The string returned is such that calling GetXRCID() with it as
 115         parameter yields @a numId. If there is no string identifier
 116         corresponding to the given numeric one, an empty string is returned.
 117
 118         Notice that, unlike GetXRCID(), this function is slow as it checks all
 119         of the identifiers used in XRC.
 120
 121         @since 2.9.0
 122      */
 123     static wxString FindXRCIDById(int numId);
 124
 125     /**
 126         Gets the global resources object or creates one if none exists.
 127     */
 128     static wxXmlResource* Get();
 129
 130     /**
 131         Returns the domain (message catalog) that will be used to load
 132         translatable strings in the XRC.
 133     */
 134     const wxString& GetDomain() const;
 135
 136     /**
 137         Returns flags, which may be a bitlist of ::wxXmlResourceFlags
 138         enumeration values.
 139     */
 140     int GetFlags() const;
 141
 142     /**
 143         Returns version information (a.b.c.d = d + 256*c + 2562*b + 2563*a).
 144     */
 145     long GetVersion() const;
 146
 147     /**
 148         Returns a numeric ID that is equivalent to the string ID used in an XML resource.
 149
 150         If an unknown @a str_id is requested (i.e. other than wxID_XXX or integer),
 151         a new record is created which associates the given string with a number.
 152
 153         If @a value_if_not_found is @c wxID_NONE, the number is obtained via
 154         wxNewId(). Otherwise @a value_if_not_found is used.
 155         Macro @c XRCID(name) is provided for convenient use in event tables.
 156     */
 157     static int GetXRCID(const wxString& str_id, int value_if_not_found = wxID_NONE);
 158
 159     /**
 160         Initializes handlers for all supported controls/windows.
 161
 162         This will make the executable quite big because it forces linking against
 163         most of the wxWidgets library.
 164     */
 165     void InitAllHandlers();
 166
 167     /**
 168         Loads resources from XML files that match given filemask.
 169         This method understands VFS (see filesys.h).
 170     */
 171     bool Load(const wxString& filemask);
 172
 173     /**
 174         Loads a bitmap resource from a file.
 175     */
 176     wxBitmap LoadBitmap(const wxString& name);
 177
 178     /**
 179         Loads a dialog. @a parent points to parent window (if any).
 180     */
 181     wxDialog* LoadDialog(wxWindow* parent, const wxString& name);
 182
 183     /**
 184         Loads a dialog. @a parent points to parent window (if any).
 185
 186         This form is used to finish creation of an already existing instance (the main
 187         reason for this is that you may want to use derived class with a new event table).
 188         Example:
 189
 190         @code
 191           MyDialog dlg;
 192           wxTheXmlResource->LoadDialog(&dlg, mainFrame, "my_dialog");
 193           dlg.ShowModal();
 194         @endcode
 195     */
 196     bool LoadDialog(wxDialog* dlg, wxWindow* parent, const wxString& name);
 197
 198     /**
 199         Loads a frame.
 200     */
 201     bool LoadFrame(wxFrame* frame, wxWindow* parent,
 202                    const wxString& name);
 203
 204     /**
 205         Loads an icon resource from a file.
 206     */
 207     wxIcon LoadIcon(const wxString& name);
 208
 209     /**
 210         Loads menu from resource. Returns @NULL on failure.
 211     */
 212     wxMenu* LoadMenu(const wxString& name);
 213
 214     //@{
 215     /**
 216         Loads a menubar from resource. Returns @NULL on failure.
 217     */
 218     wxMenuBar* LoadMenuBar(wxWindow* parent, const wxString& name);
 219     wxMenuBar* LoadMenuBar(const wxString& name);
 220     //@}
 221
 222     //@{
 223     /**
 224         Load an object from the resource specifying both the resource name and the
 225         class name.
 226
 227         The first overload lets you load nonstandard container windows and returns
 228         @NULL on failure. The second one lets you finish the creation of an existing
 229         instance and returns @false on failure.
 230     */
 231     wxObject* LoadObject(wxWindow* parent, const wxString& name,
 232                          const wxString& classname);
 233     bool LoadObject(wxObject* instance, wxWindow* parent,
 234                     const wxString& name,
 235                     const wxString& classname);
 236     //@}
 237
 238     /**
 239         Loads a panel. @a panel points to parent window (if any).
 240     */
 241     wxPanel* LoadPanel(wxWindow* parent, const wxString& name);
 242
 243     /**
 244         Loads a panel. @a panel points to parent window (if any).
 245         This form is used to finish creation of an already existing instance.
 246     */
 247     bool LoadPanel(wxPanel* panel, wxWindow* parent, const wxString& name);
 248
 249     /**
 250         Loads a toolbar.
 251     */
 252     wxToolBar* LoadToolBar(wxWindow* parent, const wxString& name);
 253
 254     /**
 255         Sets the global resources object and returns a pointer to the previous one
 256         (may be @NULL).
 257     */
 258     static wxXmlResource* Set(wxXmlResource* res);
 259
 260     /**
 261         Sets the domain (message catalog) that will be used to load
 262         translatable strings in the XRC.
 263     */
 264     void SetDomain(const wxString& domain);
 265
 266     /**
 267         Sets flags (bitlist of ::wxXmlResourceFlags enumeration values).
 268     */
 269     void SetFlags(int flags);
 270
 271     /**
 272         This function unloads a resource previously loaded by Load().
 273
 274         Returns @true if the resource was successfully unloaded and @false if it
 275         hasn't been found in the list of loaded resources.
 276     */
 277     bool Unload(const wxString& filename);
 278 };
 279
 280
 281
 282 /**
 283     @class wxXmlResourceHandler
 284
 285     wxXmlResourceHandler is an abstract base class for resource handlers
 286     capable of creating a control from an XML node.
 287
 288     See @ref overview_xrc for details.
 289
 290     @library{wxxrc}
 291     @category{xrc}
 292 */
 293 class wxXmlResourceHandler : public wxObject
 294 {
 295 public:
 296     /**
 297         Default constructor.
 298     */
 299     wxXmlResourceHandler();
 300
 301     /**
 302         Destructor.
 303     */
 304     virtual ~wxXmlResourceHandler();
 305
 306     /**
 307         Creates an object (menu, dialog, control, ...) from an XML node.
 308         Should check for validity. @a parent is a higher-level object
 309         (usually window, dialog or panel) that is often necessary to
 310         create the resource.
 311
 312         If @b instance is non-@NULL it should not create a new instance via
 313         'new' but should rather use this one, and call its Create method.
 314     */
 315     wxObject* CreateResource(wxXmlNode* node, wxObject* parent,
 316                              wxObject* instance);
 317
 318     /**
 319         Called from CreateResource after variables were filled.
 320     */
 321     virtual wxObject* DoCreateResource() = 0;
 322
 323     /**
 324         Returns @true if it understands this node and can create
 325         a resource from it, @false otherwise.
 326
 327         @note
 328         You must not call any wxXmlResourceHandler methods except IsOfClass()
 329         from this method! The instance is not yet initialized with node data
 330         at the time CanHandle() is called and it is only safe to operate on
 331         node directly or to call IsOfClass().
 332     */
 333     virtual bool CanHandle(wxXmlNode* node) = 0;
 334
 335     /**
 336         Sets the parent resource.
 337     */
 338     void SetParentResource(wxXmlResource* res);
 339
 340
 341 protected:
 342
 343     /**
 344         Add a style flag (e.g. @c wxMB_DOCKABLE) to the list of flags
 345         understood by this handler.
 346     */
 347     void AddStyle(const wxString& name, int value);
 348
 349     /**
 350         Add styles common to all wxWindow-derived classes.
 351     */
 352     void AddWindowStyles();
 353
 354     /**
 355         Creates children.
 356     */
 357     void CreateChildren(wxObject* parent, bool this_hnd_only = false);
 358
 359     /**
 360         Helper function.
 361     */
 362     void CreateChildrenPrivately(wxObject* parent,
 363                                  wxXmlNode* rootnode = NULL);
 364
 365     /**
 366         Creates a resource from a node.
 367     */
 368     wxObject* CreateResFromNode(wxXmlNode* node, wxObject* parent,
 369                                 wxObject* instance = NULL);
 370
 371     /**
 372         Creates an animation (see wxAnimation) from the filename specified in @a param.
 373     */
 374     wxAnimation GetAnimation(const wxString& param = wxT("animation"));
 375
 376     /**
 377         Gets a bitmap.
 378     */
 379     wxBitmap GetBitmap(const wxString& param = "bitmap",
 380                        const wxArtClient& defaultArtClient = wxART_OTHER,
 381                        wxSize size = wxDefaultSize);
 382
 383     /**
 384         Gets a bool flag (1, t, yes, on, true are @true, everything else is @false).
 385     */
 386     bool GetBool(const wxString& param, bool defaultv = false);
 387
 388     /**
 389         Gets colour in HTML syntax (\#RRGGBB).
 390     */
 391     wxColour GetColour(const wxString& param,
 392                        const wxColour& defaultColour = wxNullColour);
 393
 394     /**
 395         Returns the current file system.
 396     */
 397     wxFileSystem& GetCurFileSystem();
 398
 399     /**
 400         Gets a dimension (may be in dialog units).
 401     */
 402     wxCoord GetDimension(const wxString& param, wxCoord defaultv = 0,
 403                          wxWindow* windowToUse = 0);
 404
 405     /**
 406         Gets a font.
 407     */
 408     wxFont GetFont(const wxString& param = "font");
 409
 410     /**
 411         Returns the XRCID.
 412     */
 413     int GetID();
 414
 415     /**
 416         Returns an icon.
 417     */
 418     wxIcon GetIcon(const wxString& param = "icon",
 419                    const wxArtClient& defaultArtClient = wxART_OTHER,
 420                    wxSize size = wxDefaultSize);
 421
 422     /**
 423         Gets the integer value from the parameter.
 424     */
 425     long GetLong(const wxString& param, long defaultv = 0);
 426
 427     /**
 428         Returns the resource name.
 429     */
 430     wxString GetName();
 431
 432     /**
 433         Gets node content from wxXML_ENTITY_NODE.
 434     */
 435     wxString GetNodeContent(wxXmlNode* node);
 436
 437     /**
 438         Finds the node or returns @NULL.
 439     */
 440     wxXmlNode* GetParamNode(const wxString& param);
 441
 442     /**
 443         Finds the parameter value or returns the empty string.
 444     */
 445     wxString GetParamValue(const wxString& param);
 446
 447     /**
 448         Gets the position (may be in dialog units).
 449     */
 450     wxPoint GetPosition(const wxString& param = wxT("pos"));
 451
 452     /**
 453         Gets the size (may be in dialog units).
 454     */
 455     wxSize GetSize(const wxString& param = "size", wxWindow* windowToUse = 0);
 456
 457     /**
 458         Gets style flags from text in form "flag | flag2| flag3 |..."
 459         Only understands flags added with AddStyle().
 460     */
 461     int GetStyle(const wxString& param = wxT("style"), int defaults = 0);
 462
 463     /**
 464         Gets text from param and does some conversions:
 465         - replaces \\n, \\r, \\t by respective characters (according to C syntax)
 466         - replaces @c $ by @c  and @c $$ by @c $ (needed for @c _File to @c File
 467           translation because of XML syntax)
 468         - calls wxGetTranslations (unless disabled in wxXmlResource)
 469     */
 470     wxString GetText(const wxString& param, bool translate = true);
 471
 472     /**
 473         Check to see if a parameter exists.
 474     */
 475     bool HasParam(const wxString& param);
 476
 477     /**
 478         Convenience function.
 479         Returns @true if the node has a property class equal to classname,
 480         e.g. object class="wxDialog".
 481     */
 482     bool IsOfClass(wxXmlNode* node, const wxString& classname);
 483
 484     /**
 485         Sets common window options.
 486     */
 487     void SetupWindow(wxWindow* wnd);
 488 };
 489