interface/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     @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) const;
  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() const;
 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 /**
 236     @class wxXmlResourceHandler
 237     @headerfile xmlres.h wx/xrc/xmlres.h
 238
 239     wxXmlResourceHandler is an abstract base class for resource handlers
 240     capable of creating a control from an XML node.
 241
 242     See @ref overview_xrcoverview "XML-based resource system overview" for details.
 243
 244     @library{wxxrc}
 245     @category{xrc}
 246 */
 247 class wxXmlResourceHandler : public wxObject
 248 {
 249 public:
 250     /**
 251         Default constructor.
 252     */
 253     wxXmlResourceHandler();
 254
 255     /**
 256         Destructor.
 257     */
 258     ~wxXmlResourceHandler();
 259
 260     /**
 261         Add a style flag (e.g. wxMB_DOCKABLE) to the list of flags
 262         understood by this handler.
 263     */
 264     void AddStyle(const wxString& name, int value);
 265
 266     /**
 267         Add styles common to all wxWindow-derived classes.
 268     */
 269     void AddWindowStyles();
 270
 271     /**
 272         Returns @true if it understands this node and can create
 273         a resource from it, @false otherwise.
 274     */
 275     bool CanHandle(wxXmlNode* node);
 276
 277     /**
 278         Creates children.
 279     */
 280     void CreateChildren(wxObject* parent, bool this_hnd_only = false);
 281
 282     /**
 283         Helper function.
 284     */
 285     void CreateChildrenPrivately(wxObject* parent,
 286                                  wxXmlNode* rootnode = NULL);
 287
 288     /**
 289         Creates a resource from a node.
 290     */
 291     wxObject* CreateResFromNode(wxXmlNode* node, wxObject* parent,
 292                                 wxObject* instance = NULL);
 293
 294     /**
 295         Creates an object (menu, dialog, control, ...) from an XML node.
 296         Should check for validity. @a parent is a higher-level object (usually window,
 297         dialog or panel)
 298         that is often necessary to create the resource.
 299         If @b instance is non-@NULL it should not create a new instance via 'new' but
 300         should rather use this one, and call its Create method.
 301     */
 302     wxObject* CreateResource(wxXmlNode* node, wxObject* parent,
 303                              wxObject* instance);
 304
 305     /**
 306         Called from CreateResource after variables
 307         were filled.
 308     */
 309     wxObject* DoCreateResource();
 310
 311     /**
 312         )
 313         Creates a animation() from the filename specified in @e param.
 314     */
 315     wxAnimation GetAnimation();
 316
 317     /**
 318         , @b wxSize@e size = wxDefaultSize)
 319         Gets a bitmap.
 320     */
 321     wxBitmap GetBitmap();
 322
 323     /**
 324         Gets a bool flag (1, t, yes, on, @true are @true, everything else is @false).
 325     */
 326     bool GetBool(const wxString& param, bool defaultv = false);
 327
 328     /**
 329         Gets colour in HTML syntax (#RRGGBB).
 330     */
 331     wxColour GetColour(const wxString& param,
 332                    const wxColour& default = wxNullColour);
 333
 334     /**
 335         Returns the current file system.
 336     */
 337     wxFileSystem GetCurFileSystem();
 338
 339     /**
 340         Gets a dimension (may be in dialog units).
 341     */
 342     wxCoord GetDimension(const wxString& param, wxCoord defaultv = 0);
 343
 344     /**
 345         )
 346         Gets a font.
 347     */
 348     wxFont GetFont();
 349
 350     /**
 351         Returns the XRCID.
 352     */
 353     int GetID();
 354
 355     /**
 356         , @b wxSize@e size = wxDefaultSize)
 357         Returns an icon.
 358     */
 359     wxIcon GetIcon();
 360
 361     /**
 362         Gets the integer value from the parameter.
 363     */
 364     long GetLong(const wxString& param, long defaultv = 0);
 365
 366     /**
 367         Returns the resource name.
 368     */
 369     wxString GetName();
 370
 371     /**
 372         Gets node content from wxXML_ENTITY_NODE.
 373     */
 374     wxString GetNodeContent(wxXmlNode* node);
 375
 376     /**
 377         Finds the node or returns @NULL.
 378     */
 379     wxXmlNode* GetParamNode(const wxString& param);
 380
 381     /**
 382         Finds the parameter value or returns the empty string.
 383     */
 384     wxString GetParamValue(const wxString& param);
 385
 386     /**
 387         )
 388         Gets the position (may be in dialog units).
 389     */
 390     wxPoint GetPosition();
 391
 392     /**
 393         )
 394         Gets the size (may be in dialog units).
 395     */
 396     wxSize GetSize();
 397
 398     /**
 399         , @b int@e defaults = 0)
 400         Gets style flags from text in form "flag | flag2| flag3 |..."
 401         Only understands flags added with AddStyle.
 402     */
 403     int GetStyle();
 404
 405     /**
 406         Gets text from param and does some conversions:
 407          replaces \n, \r, \t by respective characters (according to C syntax)
 408          replaces @c $ by @c  and @c $$ by @c $ (needed for @c _File to @c File
 409         translation because of XML syntax)
 410          calls wxGetTranslations (unless disabled in wxXmlResource)
 411     */
 412     wxString GetText(const wxString& param);
 413
 414     /**
 415         Check to see if a parameter exists.
 416     */
 417     bool HasParam(const wxString& param);
 418
 419     /**
 420         Convenience function. Returns @true if the node has a property class equal to
 421         classname,
 422         e.g. object class="wxDialog".
 423     */
 424     bool IsOfClass(wxXmlNode* node, const wxString& classname);
 425
 426     /**
 427         Sets the parent resource.
 428     */
 429     void SetParentResource(wxXmlResource* res);
 430
 431     /**
 432         Sets common window options.
 433     */
 434     void SetupWindow(wxWindow* wnd);
 435 };
 436