interface/xrc/xmlres.h

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