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