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