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