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 there
  35         since being last loaded (may slightly speed up loading them).
  36
  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 #define wxXmlResource* Get()     /* implementation is private */
  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 @e 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 @e value_if_not_found is @c wxID_NONE, the number is obtained via
 115         wxNewId. Otherwise @e 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. @e dlg points to parent window (if any).
 141
 142         This form is used to finish creation of an already existing instance (the main
 143         reason
 144         for this is that you may want to use derived class with a new event table).
 145
 146         Example:
 147     */
 148     wxDialog* LoadDialog(wxWindow* parent, const wxString& name);
 149     bool LoadDialog(wxDialog* dlg, wxWindow* parent,
 150                     const wxString& name);
 151     //@}
 152
 153     /**
 154         Loads a frame.
 155     */
 156     bool LoadFrame(wxFrame* frame, wxWindow* parent,
 157                    const wxString& name);
 158
 159     /**
 160         Loads an icon resource from a file.
 161     */
 162     wxIcon LoadIcon(const wxString& name);
 163
 164     /**
 165         Loads menu from resource. Returns @NULL on failure.
 166     */
 167     wxMenu* LoadMenu(const wxString& name);
 168
 169     //@{
 170     /**
 171         Loads a menubar from resource. Returns @NULL on failure.
 172     */
 173     wxMenuBar* LoadMenuBar(wxWindow* parent, const wxString& name);
 174     wxMenuBar* LoadMenuBar(const wxString& name);
 175     //@}
 176
 177     //@{
 178     /**
 179         Load an object from the resource specifying both the resource name and the
 180         class name.
 181
 182         The first overload lets you load nonstandard container windows and returns @c
 183         @NULL
 184         on failure. The second one lets you finish the creation of an existing
 185         instance and returns @false on failure.
 186     */
 187     wxObject* LoadObject(wxWindow* parent, const wxString& name,
 188                          const wxString& classname);
 189     bool LoadObject(wxObject* instance, wxWindow* parent,
 190                     const wxString& name,
 191                     const wxString& classname);
 192     //@}
 193
 194     //@{
 195     /**
 196         Loads a panel. @e panel points to parent window (if any). This form
 197         is used to finish creation of an already existing instance.
 198     */
 199     wxPanel* LoadPanel(wxWindow* parent, const wxString& name);
 200     bool LoadPanel(wxPanel* panel, wxWindow* parent,
 201                    const wxString& name);
 202     //@}
 203
 204     /**
 205         Loads a toolbar.
 206     */
 207     wxToolBar* LoadToolBar(wxWindow* parent, const wxString& name);
 208
 209     /**
 210         Sets the global resources object and returns a pointer to the previous one (may
 211         be @NULL).
 212     */
 213 #define wxXmlResource* Set(wxXmlResource* res)     /* implementation is private */
 214
 215     /**
 216         Sets the domain (message catalog) that will be used to load
 217         translatable strings in the XRC.
 218     */
 219     wxChar* SetDomain(const wxChar* domain);
 220
 221     /**
 222         Sets flags (bitlist of wxXRC_USE_LOCALE and wxXRC_NO_SUBCLASSING).
 223     */
 224     void SetFlags(int flags);
 225
 226     /**
 227         This function unloads a resource previously loaded by
 228         Load().
 229
 230         Returns @true if the resource was successfully unloaded and @false if it
 231         hasn't
 232         been found in the list of loaded resources.
 233     */
 234     bool Unload(const wxString& filename);
 235 };
 236
 237
 238 /**
 239     @class wxXmlResourceHandler
 240     @headerfile xmlres.h wx/xrc/xmlres.h
 241
 242     wxXmlResourceHandler is an abstract base class for resource handlers
 243     capable of creating a control from an XML node.
 244
 245     See @ref overview_xrcoverview "XML-based resource system overview" for details.
 246
 247     @library{wxxrc}
 248     @category{xrc}
 249 */
 250 class wxXmlResourceHandler : public wxObject
 251 {
 252 public:
 253     /**
 254         Default constructor.
 255     */
 256     wxXmlResourceHandler();
 257
 258     /**
 259         Destructor.
 260     */
 261     ~wxXmlResourceHandler();
 262
 263     /**
 264         Add a style flag (e.g. wxMB_DOCKABLE) to the list of flags
 265         understood by this handler.
 266     */
 267     void AddStyle(const wxString& name, int value);
 268
 269     /**
 270         Add styles common to all wxWindow-derived classes.
 271     */
 272     void AddWindowStyles();
 273
 274     /**
 275         Returns @true if it understands this node and can create
 276         a resource from it, @false otherwise.
 277     */
 278     bool CanHandle(wxXmlNode* node);
 279
 280     /**
 281         Creates children.
 282     */
 283     void CreateChildren(wxObject* parent, bool this_hnd_only = @false);
 284
 285     /**
 286         Helper function.
 287     */
 288     void CreateChildrenPrivately(wxObject* parent,
 289                                  wxXmlNode* rootnode = @NULL);
 290
 291     /**
 292         Creates a resource from a node.
 293     */
 294     wxObject* CreateResFromNode(wxXmlNode* node, wxObject* parent,
 295                                 wxObject* instance = @NULL);
 296
 297     /**
 298         Creates an object (menu, dialog, control, ...) from an XML node.
 299         Should check for validity. @e parent is a higher-level object (usually window,
 300         dialog or panel)
 301         that is often necessary to create the resource.
 302         If @b instance is non-@NULL it should not create a new instance via 'new' but
 303         should rather use this one, and call its Create method.
 304     */
 305     wxObject* CreateResource(wxXmlNode* node, wxObject* parent,
 306                              wxObject* instance);
 307
 308     /**
 309         Called from CreateResource after variables
 310         were filled.
 311     */
 312     wxObject* DoCreateResource();
 313
 314     /**
 315         )
 316
 317         Creates a animation from the filename specified in @e param.
 318     */
 319     wxAnimation GetAnimation();
 320
 321     /**
 322         , @b wxSize@e size = wxDefaultSize)
 323
 324         Gets a bitmap.
 325     */
 326     wxBitmap GetBitmap();
 327
 328     /**
 329         Gets a bool flag (1, t, yes, on, @true are @true, everything else is @false).
 330     */
 331     bool GetBool(const wxString& param, bool defaultv = @false);
 332
 333     /**
 334         Gets colour in HTML syntax (#RRGGBB).
 335     */
 336     wxColour GetColour(const wxString& param,
 337                    const wxColour& default = wxNullColour);
 338
 339     /**
 340         Returns the current file system.
 341     */
 342     wxFileSystem GetCurFileSystem();
 343
 344     /**
 345         Gets a dimension (may be in dialog units).
 346     */
 347     wxCoord GetDimension(const wxString& param, wxCoord defaultv = 0);
 348
 349     /**
 350         )
 351
 352         Gets a font.
 353     */
 354     wxFont GetFont();
 355
 356     /**
 357         Returns the XRCID.
 358     */
 359 #define int GetID()     /* implementation is private */
 360
 361     /**
 362         , @b wxSize@e size = wxDefaultSize)
 363
 364         Returns an icon.
 365     */
 366     wxIcon GetIcon();
 367
 368     /**
 369         Gets the integer value from the parameter.
 370     */
 371     long GetLong(const wxString& param, long defaultv = 0);
 372
 373     /**
 374         Returns the resource name.
 375     */
 376     wxString GetName();
 377
 378     /**
 379         Gets node content from wxXML_ENTITY_NODE.
 380     */
 381     wxString GetNodeContent(wxXmlNode* node);
 382
 383     /**
 384         Finds the node or returns @NULL.
 385     */
 386     wxXmlNode* GetParamNode(const wxString& param);
 387
 388     /**
 389         Finds the parameter value or returns the empty string.
 390     */
 391     wxString GetParamValue(const wxString& param);
 392
 393     /**
 394         )
 395
 396         Gets the position (may be in dialog units).
 397     */
 398     wxPoint GetPosition();
 399
 400     /**
 401         )
 402
 403         Gets the size (may be in dialog units).
 404     */
 405     wxSize GetSize();
 406
 407     /**
 408         , @b int@e defaults = 0)
 409
 410         Gets style flags from text in form "flag | flag2| flag3 |..."
 411         Only understands flags added with AddStyle.
 412     */
 413     int GetStyle();
 414
 415     /**
 416         Gets text from param and does some conversions:
 417
 418          replaces \n, \r, \t by respective characters (according to C syntax)
 419          replaces @c $ by @c  and @c $$ by @c $ (needed for @c _File to @c File
 420         translation because of XML syntax)
 421          calls wxGetTranslations (unless disabled in wxXmlResource)
 422     */
 423     wxString GetText(const wxString& param);
 424
 425     /**
 426         Check to see if a parameter exists.
 427     */
 428     bool HasParam(const wxString& param);
 429
 430     /**
 431         Convenience function. Returns @true if the node has a property class equal to
 432         classname,
 433         e.g. object class="wxDialog".
 434     */
 435     bool IsOfClass(wxXmlNode* node, const wxString& classname);
 436
 437     /**
 438         Sets the parent resource.
 439     */
 440     void SetParentResource(wxXmlResource* res);
 441
 442     /**
 443         Sets common window options.
 444     */
 445     void SetupWindow(wxWindow* wnd);
 446 };