home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / wxos2240.zip / wxWindows-2.4.0 / contrib / include / wx / xrc / xmlres.h < prev   
C/C++ Source or Header  |  2002-12-22  |  18KB  |  480 lines
  1. /////////////////////////////////////////////////////////////////////////////
  2. // Name:        xmlres.h
  3. // Purpose:     XML resources
  4. // Author:      Vaclav Slavik
  5. // Created:     2000/03/05
  6. // RCS-ID:      $Id: xmlres.h,v 1.19.2.5 2002/12/21 00:21:23 VS Exp $
  7. // Copyright:   (c) 2000 Vaclav Slavik
  8. // Licence:     wxWindows licence
  9. /////////////////////////////////////////////////////////////////////////////
  10.  
  11. #ifndef _WX_XMLRES_H_
  12. #define _WX_XMLRES_H_
  13.  
  14. #if defined(__GNUG__) && !defined(__APPLE__)
  15. #pragma interface "xmlres.h"
  16. #endif
  17.  
  18. #include "wx/defs.h"
  19. #include "wx/string.h"
  20. #include "wx/dynarray.h"
  21. #include "wx/datetime.h"
  22. #include "wx/list.h"
  23. #include "wx/gdicmn.h"
  24. #include "wx/filesys.h"
  25. #include "wx/bitmap.h"
  26. #include "wx/icon.h"
  27. #include "wx/artprov.h"
  28.  
  29. #include "wx/xrc/xml.h"
  30.  
  31. class WXDLLEXPORT wxMenu;
  32. class WXDLLEXPORT wxMenuBar;
  33. class WXDLLEXPORT wxDialog;
  34. class WXDLLEXPORT wxPanel;
  35. class WXDLLEXPORT wxWindow;
  36. class WXDLLEXPORT wxFrame;
  37. class WXDLLEXPORT wxToolBar;
  38.  
  39. class WXXMLDLLEXPORT wxXmlResourceHandler;
  40. class WXXMLDLLEXPORT wxXmlSubclassFactory;
  41. class WXXMLDLLEXPORT wxXmlSubclassFactoriesList;
  42. class wxXmlResourceModule;
  43.  
  44.  
  45. // These macros indicate current version of XML resources (this information is
  46. // encoded in root node of XRC file as "version" property).
  47. //
  48. // Rules for increasing version number:
  49. //   - change it only if you made incompatible change to the format. Addition of new
  50. //     attribute to control handler is _not_ incompatible change, because older
  51. //     versions of the library may ignore it.
  52. //   - if you change version number, follow these steps:
  53. //       - set major, minor and release numbers to respective version numbers of
  54. //         the wxWindows library (see wx/version.h)
  55. //       - reset revision to 0 unless the first three are same as before, in which
  56. //         case you should increase revision by one
  57. #define WX_XMLRES_CURRENT_VERSION_MAJOR            2
  58. #define WX_XMLRES_CURRENT_VERSION_MINOR            3
  59. #define WX_XMLRES_CURRENT_VERSION_RELEASE          0
  60. #define WX_XMLRES_CURRENT_VERSION_REVISION         1
  61. #define WX_XMLRES_CURRENT_VERSION_STRING    wxT("2.3.0.1")
  62.  
  63. #define WX_XMLRES_CURRENT_VERSION \
  64.                 (WX_XMLRES_CURRENT_VERSION_MAJOR * 256*256*256 + \
  65.                  WX_XMLRES_CURRENT_VERSION_MINOR * 256*256 + \
  66.                  WX_XMLRES_CURRENT_VERSION_RELEASE * 256 + \
  67.                  WX_XMLRES_CURRENT_VERSION_REVISION)
  68.  
  69. class WXXMLDLLEXPORT wxXmlResourceDataRecord
  70. {
  71. public:
  72.     wxXmlResourceDataRecord() : Doc(NULL), Time(wxDateTime::Now()) {}
  73.     ~wxXmlResourceDataRecord() {delete Doc;}
  74.  
  75.     wxString File;
  76.     wxXmlDocument *Doc;
  77.     wxDateTime Time;
  78. };
  79.  
  80.  
  81. #ifdef WXXMLISDLL
  82. WX_DECLARE_EXPORTED_OBJARRAY(wxXmlResourceDataRecord, wxXmlResourceDataRecords);
  83. #else
  84. WX_DECLARE_OBJARRAY(wxXmlResourceDataRecord, wxXmlResourceDataRecords);
  85. #endif
  86.  
  87. enum wxXmlResourceFlags
  88. {
  89.     wxXRC_USE_LOCALE     = 1,
  90.     wxXRC_NO_SUBCLASSING = 2
  91. };
  92.  
  93. // This class holds XML resources from one or more .xml files
  94. // (or derived forms, either binary or zipped -- see manual for
  95. // details).
  96. class WXXMLDLLEXPORT wxXmlResource : public wxObject
  97. {
  98. public:
  99.     // Constructor.
  100.     // Flags: wxXRC_USE_LOCALE
  101.     //              translatable strings will be translated via _()
  102.     //        wxXRC_NO_SUBCLASSING
  103.     //              subclass property of object nodes will be ignored
  104.     //              (useful for previews in XRC editors)
  105.     wxXmlResource(int flags = wxXRC_USE_LOCALE);
  106.  
  107.     // Constructor.
  108.     // Flags: wxXRC_USE_LOCALE
  109.     //              translatable strings will be translated via _()
  110.     //        wxXRC_NO_SUBCLASSING
  111.     //              subclass property of object nodes will be ignored
  112.     //              (useful for previews in XRC editors)
  113.     wxXmlResource(const wxString& filemask, int flags = wxXRC_USE_LOCALE);
  114.  
  115.     // Destructor.
  116.     ~wxXmlResource();
  117.  
  118.     // Loads resources from XML files that match given filemask.
  119.     // This method understands VFS (see filesys.h).
  120.     bool Load(const wxString& filemask);
  121.  
  122.     // Initialize handlers for all supported controls/windows. This will
  123.     // make the executable quite big because it forces linking against
  124.     // most of the wxWindows library.
  125.     void InitAllHandlers();
  126.  
  127.     // Initialize only a specific handler (or custom handler). Convention says
  128.     // that handler name is equal to the control's name plus 'XmlHandler', for example
  129.     // wxTextCtrlXmlHandler, wxHtmlWindowXmlHandler. The XML resource compiler
  130.     // (xmlres) can create include file that contains initialization code for
  131.     // all controls used within the resource.
  132.     void AddHandler(wxXmlResourceHandler *handler);
  133.  
  134.     // Add a new handler at the begining of the handler list
  135.     void InsertHandler(wxXmlResourceHandler *handler);
  136.  
  137.     // Removes all handlers
  138.     void ClearHandlers();
  139.     
  140.     // Registers subclasses factory for use in XRC. This function is not meant
  141.     // for public use, please see the comment above wxXmlSubclassFactory
  142.     // definition.
  143.     static void AddSubclassFactory(wxXmlSubclassFactory *factory);
  144.  
  145.     // Loads menu from resource. Returns NULL on failure.
  146.     wxMenu *LoadMenu(const wxString& name);
  147.  
  148.     // Loads menubar from resource. Returns NULL on failure.
  149.     wxMenuBar *LoadMenuBar(wxWindow *parent, const wxString& name);
  150.  
  151.     // Loads menubar from resource. Returns NULL on failure.
  152.     wxMenuBar *LoadMenuBar(const wxString& name) { return LoadMenuBar(NULL, name); }
  153.  
  154. #if wxUSE_TOOLBAR
  155.     // Loads a toolbar.
  156.     wxToolBar *LoadToolBar(wxWindow *parent, const wxString& name);
  157. #endif
  158.  
  159.     // Loads a dialog. dlg points to parent window (if any).
  160.     wxDialog *LoadDialog(wxWindow *parent, const wxString& name);
  161.  
  162.     // Loads a dialog. dlg points to parent window (if any). This form
  163.     // is used to finish creation of already existing instance (main reason
  164.     // for this is that you may want to use derived class with new event table)
  165.     // Example (typical usage):
  166.     //      MyDialog dlg;
  167.     //      wxTheXmlResource->LoadDialog(&dlg, mainFrame, "my_dialog");
  168.     //      dlg->ShowModal();
  169.     bool LoadDialog(wxDialog *dlg, wxWindow *parent, const wxString& name);
  170.  
  171.     // Loads a panel. panel points to parent window (if any).
  172.     wxPanel *LoadPanel(wxWindow *parent, const wxString& name);
  173.  
  174.     // Loads a panel. panel points to parent window (if any). This form
  175.     // is used to finish creation of already existing instance.
  176.     bool LoadPanel(wxPanel *panel, wxWindow *parent, const wxString& name);
  177.  
  178.     // Loads a frame.
  179.     wxFrame *LoadFrame(wxWindow* parent, const wxString& name);
  180.     bool LoadFrame(wxFrame* frame, wxWindow *parent, const wxString& name);
  181.  
  182.     // Load an object from the resource specifying both the resource name and
  183.     // the classname.  This lets you load nonstandard container windows.
  184.     wxObject *LoadObject(wxWindow *parent, const wxString& name,
  185.                          const wxString& classname);
  186.  
  187.     // Load an object from the resource specifying both the resource name and
  188.     // the classname.  This form lets you finish the creation of an existing
  189.     // instance.
  190.     bool LoadObject(wxObject *instance, wxWindow *parent, const wxString& name,
  191.                     const wxString& classname);
  192.  
  193.     // Loads a bitmap resource from a file.
  194.     wxBitmap LoadBitmap(const wxString& name);
  195.  
  196.     // Loads an icon resource from a file.
  197.     wxIcon LoadIcon(const wxString& name);
  198.  
  199.     // Attaches an unknown control to the given panel/window/dialog.
  200.     // Unknown controls are used in conjunction with <object class="unknown">.
  201.     bool AttachUnknownControl(const wxString& name, wxWindow *control,
  202.                               wxWindow *parent = NULL);
  203.  
  204.     // Returns a numeric ID that is equivalent to the string id used in an XML
  205.     // resource. To be used in event tables.
  206.     // Macro XRCID is provided for convenience
  207.     static int GetXRCID(const wxChar *str_id);
  208.  
  209.     // Returns version information (a.b.c.d = d+ 256*c + 256^2*b + 256^3*a).
  210.     long GetVersion() const { return m_version; }
  211.  
  212.     // Compares resources version to argument. Returns -1 if resources version
  213.     // is less than the argument, +1 if greater and 0 if they equal.
  214.     int CompareVersion(int major, int minor, int release, int revision) const
  215.         { return GetVersion() -
  216.                  (major*256*256*256 + minor*256*256 + release*256 + revision); }
  217.  
  218. //// Singleton accessors.
  219.  
  220.     // Gets the global resources object or creates one if none exists.
  221.     static wxXmlResource *Get();
  222.  
  223.     // Sets the global resources object and returns a pointer to the previous one (may be NULL).
  224.     static wxXmlResource *Set(wxXmlResource *res);
  225.  
  226.     // Returns flags, which may be a bitlist of wxXRC_USE_LOCALE and wxXRC_NO_SUBCLASSING.
  227.     int GetFlags() const { return m_flags; }
  228.     // Set flags after construction.
  229.     void SetFlags(int flags) { m_flags = flags; }
  230.  
  231. protected:
  232.     // Scans the resources list for unloaded files and loads them. Also reloads
  233.     // files that have been modified since last loading.
  234.     void UpdateResources();
  235.  
  236.     // Finds a resource (calls UpdateResources) and returns a node containing it.
  237.     wxXmlNode *FindResource(const wxString& name, const wxString& classname, bool recursive = FALSE);
  238.  
  239.     // Helper function: finds a resource (calls UpdateResources) and returns a node containing it.
  240.     wxXmlNode *DoFindResource(wxXmlNode *parent, const wxString& name, const wxString& classname, bool recursive);
  241.  
  242.     // Creates a resource from information in the given node.
  243.     wxObject *CreateResFromNode(wxXmlNode *node, wxObject *parent, wxObject *instance = NULL);
  244.  
  245. private:
  246.     long m_version;
  247.  
  248.     int m_flags;
  249.     wxList m_handlers;
  250.     wxXmlResourceDataRecords m_data;
  251. #if wxUSE_FILESYSTEM
  252.     wxFileSystem m_curFileSystem;
  253.     wxFileSystem& GetCurFileSystem() { return m_curFileSystem; }
  254. #endif
  255.  
  256.     friend class wxXmlResourceHandler;
  257.     friend class wxXmlResourceModule;
  258.  
  259.     static wxXmlSubclassFactoriesList *ms_subclassFactories;
  260.  
  261.     // singleton instance:
  262.     static wxXmlResource *ms_instance;
  263. };
  264.  
  265.  
  266. // This macro translates string identifier (as used in XML resource,
  267. // e.g. <menuitem id="my_menu">...</menuitem>) to integer id that is needed by
  268. // wxWindows event tables.
  269. // Example:
  270. //    BEGIN_EVENT_TABLE(MyFrame, wxFrame)
  271. //       EVT_MENU(XRCID("quit"), MyFrame::OnQuit)
  272. //       EVT_MENU(XRCID("about"), MyFrame::OnAbout)
  273. //       EVT_MENU(XRCID("new"), MyFrame::OnNew)
  274. //       EVT_MENU(XRCID("open"), MyFrame::OnOpen)
  275. //    END_EVENT_TABLE()
  276.  
  277. #define XRCID(str_id) \
  278.     wxXmlResource::GetXRCID(wxT(str_id))
  279.  
  280.  
  281. // This macro returns pointer to particular control in dialog
  282. // created using XML resources. You can use it to set/get values from
  283. // controls.
  284. // Example:
  285. //    wxDialog dlg;
  286. //    wxXmlResource::Get()->LoadDialog(&dlg, mainFrame, "my_dialog");
  287. //    XRCCTRL(dlg, "my_textctrl", wxTextCtrl)->SetValue(wxT("default value"));
  288.  
  289. #ifdef __WXDEBUG__
  290. #define XRCCTRL(window, id, type) \
  291.     (wxDynamicCast((window).FindWindow(XRCID(id)), type))
  292. #else
  293. #define XRCCTRL(window, id, type) \
  294.     ((type*)((window).FindWindow(XRCID(id))))
  295. #endif
  296.  
  297. // wxXmlResourceHandler is an abstract base class for resource handlers
  298. // capable of creating a control from an XML node.
  299.  
  300. class WXXMLDLLEXPORT wxXmlResourceHandler : public wxObject
  301. {
  302. public:
  303.     // Constructor.
  304.     wxXmlResourceHandler();
  305.  
  306.     // Destructor.
  307.     virtual ~wxXmlResourceHandler() {}
  308.  
  309.     // Creates an object (menu, dialog, control, ...) from an XML node.
  310.     // Should check for validity.
  311.     // parent is a higher-level object (usually window, dialog or panel)
  312.     // that is often neccessary to create the resource.
  313.     // If instance is non-NULL it should not create a new instance via 'new' but
  314.     // should rather use this one, and call its Create method.
  315.     wxObject *CreateResource(wxXmlNode *node, wxObject *parent,
  316.                              wxObject *instance);
  317.  
  318.     // This one is called from CreateResource after variables
  319.     // were filled.
  320.     virtual wxObject *DoCreateResource() = 0;
  321.  
  322.     // Returns TRUE if it understands this node and can create
  323.     // a resource from it, FALSE otherwise.
  324.     virtual bool CanHandle(wxXmlNode *node) = 0;
  325.  
  326.     // Sets the parent resource.
  327.     void SetParentResource(wxXmlResource *res) { m_resource = res; }
  328.  
  329. protected:
  330.     wxXmlResource *m_resource;
  331.     wxArrayString m_styleNames;
  332.     wxArrayInt m_styleValues;
  333.  
  334.     // Variables (filled by CreateResource)
  335.     wxXmlNode *m_node;
  336.     wxString m_class;
  337.     wxObject *m_parent, *m_instance;
  338.     wxWindow *m_parentAsWindow, *m_instanceAsWindow;
  339.  
  340.     // --- Handy methods:
  341.  
  342.     // Returns true if the node has a property class equal to classname,
  343.     // e.g. <object class="wxDialog">.
  344.     bool IsOfClass(wxXmlNode *node, const wxString& classname)
  345.         { return node->GetPropVal(wxT("class"), wxEmptyString) == classname; }
  346.  
  347.     // Gets node content from wxXML_ENTITY_NODE
  348.     // The problem is, <tag>content<tag> is represented as
  349.     // wxXML_ENTITY_NODE name="tag", content=""
  350.     //    |-- wxXML_TEXT_NODE or
  351.     //        wxXML_CDATA_SECTION_NODE name="" content="content"
  352.     wxString GetNodeContent(wxXmlNode *node);
  353.  
  354.     // Check to see if a parameter exists.
  355.     bool HasParam(const wxString& param);
  356.  
  357.     // Finds the node or returns NULL.
  358.     wxXmlNode *GetParamNode(const wxString& param);
  359.  
  360.     // Finds the parameter value or returns the empty string.
  361.     wxString GetParamValue(const wxString& param);
  362.  
  363.     // Add a style flag (e.g. wxMB_DOCKABLE) to the list of flags
  364.     // understood by this handler.
  365.     void AddStyle(const wxString& name, int value);
  366.  
  367.     // Add styles common to all wxWindow-derived classes.
  368.     void AddWindowStyles();
  369.  
  370.     // Gets style flags from text in form "flag | flag2| flag3 |..."
  371.     // Only understads flags added with AddStyle
  372.     int GetStyle(const wxString& param = wxT("style"), int defaults = 0);
  373.  
  374.     // Gets text from param and does some conversions:
  375.     // - replaces \n, \r, \t by respective chars (according to C syntax)
  376.     // - replaces _ by & and __ by _ (needed for _File => &File because of XML)
  377.     // - calls wxGetTranslations (unless disabled in wxXmlResource)
  378.     wxString GetText(const wxString& param, bool translate = TRUE);
  379.  
  380.     // Returns the XRCID.
  381.     int GetID();
  382.  
  383.     // Returns the resource name.
  384.     wxString GetName();
  385.  
  386.     // Gets a bool flag (1, t, yes, on, true are TRUE, everything else is FALSE).
  387.     bool GetBool(const wxString& param, bool defaultv = FALSE);
  388.  
  389.     // Gets the integer value from the parameter.
  390.     long GetLong( const wxString& param, long defaultv = 0 );
  391.  
  392.     // Gets colour in HTML syntax (#RRGGBB).
  393.     wxColour GetColour(const wxString& param);
  394.  
  395.     // Gets the size (may be in dialog units).
  396.     wxSize GetSize(const wxString& param = wxT("size"));
  397.  
  398.     // Gets the position (may be in dialog units).
  399.     wxPoint GetPosition(const wxString& param = wxT("pos"));
  400.  
  401.     // Gets a dimension (may be in dialog units).
  402.     wxCoord GetDimension(const wxString& param, wxCoord defaultv = 0);
  403.  
  404.     // Gets a bitmap.
  405.     wxBitmap GetBitmap(const wxString& param = wxT("bitmap"),
  406.                        const wxArtClient& defaultArtClient = wxART_OTHER,
  407.                        wxSize size = wxDefaultSize);
  408.  
  409.     // Gets an icon.
  410.     wxIcon GetIcon(const wxString& param = wxT("icon"),
  411.                    const wxArtClient& defaultArtClient = wxART_OTHER,
  412.                    wxSize size = wxDefaultSize);
  413.  
  414.     // Gets a font.
  415.     wxFont GetFont(const wxString& param = wxT("font"));
  416.  
  417.     // Sets common window options.
  418.     void SetupWindow(wxWindow *wnd);
  419.  
  420.     // Creates children.
  421.     void CreateChildren(wxObject *parent, bool this_hnd_only = FALSE);
  422.  
  423.     // Helper function.
  424.     void CreateChildrenPrivately(wxObject *parent, wxXmlNode *rootnode = NULL);
  425.  
  426.     // Creates a resource from a node.
  427.     wxObject *CreateResFromNode(wxXmlNode *node,
  428.                                 wxObject *parent, wxObject *instance = NULL)
  429.         { return m_resource->CreateResFromNode(node, parent, instance); }
  430.  
  431.     // helper
  432. #if wxUSE_FILESYSTEM
  433.     wxFileSystem& GetCurFileSystem() { return m_resource->GetCurFileSystem(); }
  434. #endif
  435. };
  436.  
  437.  
  438. // Programmer-friendly macros for writing XRC handlers:
  439.  
  440. #define XRC_ADD_STYLE(style) AddStyle(wxT(#style), style)
  441.  
  442. #define XRC_MAKE_INSTANCE(variable, classname) \
  443.    classname *variable = NULL; \
  444.    if (m_instance) \
  445.        variable = wxStaticCast(m_instance, classname); \
  446.    if (!variable) \
  447.        variable = new classname;
  448.  
  449.  
  450. // FIXME -- remove this $%^#$%#$@# as soon as Ron checks his changes in!!
  451. void wxXmlInitResourceModule();
  452.  
  453.  
  454. // This class is used to create instances of XRC "object" nodes with "subclass"
  455. // property. It is _not_ supposed to be used by XRC users, you should instead
  456. // register your subclasses via wxWindows' RTTI mechanism. This class is useful
  457. // only for language bindings developer who need a way to implement subclassing
  458. // in wxWindows ports that don't support wxRTTI (e.g. wxPython).
  459. class WXXMLDLLEXPORT wxXmlSubclassFactory
  460. {
  461. public:
  462.     // Try to create instance of given class and return it, return NULL on failure:
  463.     virtual wxObject *Create(const wxString& className) = 0;
  464.     virtual ~wxXmlSubclassFactory() {}
  465. };
  466.  
  467.  
  468. /* -------------------------------------------------------------------------
  469.    Backward compatibility macros. Do *NOT* use, they may disappear in future
  470.    versions of the XRC library!
  471.    ------------------------------------------------------------------------- */
  472. #define ADD_STYLE         XRC_ADD_STYLE
  473. #define wxTheXmlResource  wxXmlResource::Get()
  474. #define XMLID             XRCID
  475. #define XMLCTRL           XRCCTRL
  476. #define GetXMLID          GetXRCID
  477.  
  478.  
  479. #endif // _WX_XMLRES_H_
  480.