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