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