contrib/include/wx/xml/xmlres.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        xmlres.h
   3 // Purpose:     XML resources
   4 // Author:      Vaclav Slavik
   5 // Created:     2000/03/05
   6 // RCS-ID:      $Id$
   7 // Copyright:   (c) 2000 Vaclav Slavik
   8 // Licence:     wxWindows licence
   9 /////////////////////////////////////////////////////////////////////////////
  10
  11 #ifndef _WX_XMLRES_H_
  12 #define _WX_XMLRES_H_
  13
  14 #ifdef __GNUG__
  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
  25 class WXDLLEXPORT wxMenu;
  26 class WXDLLEXPORT wxMenuBar;
  27 class WXDLLEXPORT wxDialog;
  28 class WXDLLEXPORT wxPanel;
  29 class WXDLLEXPORT wxWindow;
  30
  31 class WXDLLEXPORT wxXmlResourceHandler;
  32
  33 #include "wx/xml/xml.h"
  34
  35 enum
  36 {
  37     wxXML_BINARY,
  38     wxXML_ARCHIVE
  39 };
  40
  41
  42
  43 class WXDLLEXPORT wxXmlResourceDataRecord
  44 {
  45     public:
  46         wxXmlResourceDataRecord() : Doc(NULL), Time(wxDateTime::Now()) {}
  47         ~wxXmlResourceDataRecord() {delete Doc;}
  48
  49         wxString File;
  50         wxXmlDocument *Doc;
  51         wxDateTime Time;
  52 };
  53
  54 WX_DECLARE_EXPORTED_OBJARRAY(wxXmlResourceDataRecord, wxXmlResourceDataRecords);
  55
  56 // This class holds XML resources from one or more .xml files
  57 // (or derived forms, either binary or zipped -- see manual for
  58 // details).
  59
  60 class WXDLLEXPORT wxXmlResource : public wxObject
  61 {
  62     public:
  63         wxXmlResource();
  64         wxXmlResource(const wxString& filemask, int type);
  65         ~wxXmlResource();
  66
  67         // Loads resources from XML files that match given filemask.
  68         // This method understands VFS (see filesys.h). Type is one of
  69         // wxXML_TEXT, wxXML_BINARY, wxXML_ARCHIVE and specifies type of
  70         // data to be expected:
  71         //    wxXML_BINARY     - binary version of .xml file, as produced
  72         //                       by wxXmlDocument::SaveBinary
  73         //    wxXML_ARCHIVE    - ZIP archive that contains arbitrary number
  74         //                       of files with .xmb extension
  75         //                       (this kind of ZIP archive is produced by
  76         //                       XML resources compiler that ships with wxWin)
  77         bool Load(const wxString& filemask, int type = wxXML_ARCHIVE);
  78
  79         // Initialize handlers for all supported controls/windows. This will
  80         // make the executable quite big because it forces linking against
  81         // most of wxWin library
  82         void InitAllHandlers();
  83
  84         // Initialize only specific handler (or custom handler). Convention says
  85         // that handler name is equal to control's name plus 'XmlHandler', e.g.
  86         // wxTextCtrlXmlHandler, wxHtmlWindowXmlHandler. XML resource compiler
  87         // (xmlres) can create include file that contains initialization code for
  88         // all controls used within the resource.
  89         void AddHandler(wxXmlResourceHandler *handler);
  90
  91         // Removes all handlers
  92         void ClearHandlers();
  93
  94         // Loads menu from resource. Returns NULL on failure.
  95         wxMenu *LoadMenu(const wxString& name);
  96
  97         // Loads menubar from resource. Returns NULL on failure.
  98         wxMenuBar *LoadMenuBar(const wxString& name);
  99
 100         // Loads dialog. dlg points to parent window (if any). Second form
 101         // is used to finish creation of already existing instance (main reason
 102         // for this is that you may want to use derived class with new event table)
 103         // Example (typical usage):
 104         //      MyDialog dlg;
 105         //      wxTheXmlResource->LoadDialog(&dlg, mainFrame, "my_dialog");
 106         //      dlg->ShowModal();
 107         wxDialog *LoadDialog(wxWindow *parent, const wxString& name);
 108         bool LoadDialog(wxDialog *dlg, wxWindow *parent, const wxString& name);
 109
 110         // Loads panel. panel points to parent window (if any). Second form
 111         // is used to finish creation of already existing instance.
 112         wxPanel *LoadPanel(wxWindow *parent, const wxString& name);
 113         bool LoadPanel(wxPanel *panel, wxWindow *parent, const wxString& name);
 114
 115         // Returns numeric ID that is equivalent to string id used in XML
 116         // resource. To be used in event tables
 117         // Macro XMLID is provided for convenience
 118         static int GetXMLID(const char *str_id);
 119
 120     protected:
 121         // Scans resources list for unloaded files and loads them. Also reloads
 122         // files that have been modified since last loading.
 123         void UpdateResources();
 124
 125         // Finds resource (calls UpdateResources) and returns node containing it
 126         wxXmlNode *FindResource(const wxString& name, const wxString& type);
 127
 128         // Creates resource from info in given node:
 129         wxObject *CreateResFromNode(wxXmlNode *node, wxObject *parent, wxObject *instance = NULL);
 130
 131     private:
 132         wxList m_Handlers;
 133         wxXmlResourceDataRecords m_Data;
 134
 135     friend class wxXmlResourceHandler;
 136 };
 137
 138
 139 // Global instance of resource class. For your convenience.
 140 extern wxXmlResource *wxTheXmlResource;
 141
 142 // This macro translates string identifier (as used in XML resource,
 143 // e.g. <menuitem id="my_menu">...</menuitem>) to integer id that is needed by
 144 // wxWindows event tables.
 145 // Example:
 146 //    BEGIN_EVENT_TABLE(MyFrame, wxFrame)
 147 //       EVT_MENU(XMLID("quit"), MyFrame::OnQuit)
 148 //       EVT_MENU(XMLID("about"), MyFrame::OnAbout)
 149 //       EVT_MENU(XMLID("new"), MyFrame::OnNew)
 150 //       EVT_MENU(XMLID("open"), MyFrame::OnOpen)
 151 //    END_EVENT_TABLE()
 152 #define XMLID(str_id) wxXmlResource::GetXMLID(str_id)
 153
 154
 155 class WXDLLEXPORT wxXmlResourceHandler : public wxObject
 156 {
 157     public:
 158         wxXmlResourceHandler();
 159         virtual ~wxXmlResourceHandler() {}
 160
 161         // Creates object (menu, dialog, control, ...) from XML node.
 162         // Should check for validity.
 163         // parent is higher-level object (usually window, dialog or panel)
 164         // that is often neccessary to create resource
 165         // if instance != NULL it should not create new instance via 'new' but
 166         // rather use this one and call its Create method
 167         wxObject *CreateResource(wxXmlNode *node, wxObject *parent, wxObject *instance);
 168
 169         // This one is called from CreateResource after variables
 170         // were filled
 171         virtual wxObject *DoCreateResource() = 0;
 172
 173         // Returns TRUE if it understands this node and can create
 174         // resource from it, FALSE otherwise.
 175         virtual bool CanHandle(wxXmlNode *node) = 0;
 176
 177         // Check "platform" property if it matches this platform
 178         // that is, if this node 'exists' under this platform
 179         static bool CheckPlatform(wxXmlNode *node);
 180
 181         void SetParentResource(wxXmlResource *res) { m_Resource = res; }
 182
 183
 184     protected:
 185
 186         wxXmlResource *m_Resource;
 187         wxArrayString m_StyleNames;
 188         wxArrayInt m_StyleValues;
 189
 190         // Variables (filled by CreateResource)
 191         wxXmlNode *m_Node;
 192         wxObject *m_Parent, *m_Instance;
 193         wxWindow *m_ParentAsWindow, *m_InstanceAsWindow;
 194
 195         // --- Handy methods:
 196
 197         // Gets node content from wxXML_ENTITY_NODE
 198         // (the problem is, <tag>content<tag> is represented as
 199         // wxXML_ENTITY_NODE name="tag", content=""
 200         //    |-- wxXML_TEXT_NODE or
 201         //        wxXML_CDATA_SECTION_NODE name="" content="content"
 202         wxString GetNodeContent(wxXmlNode *node);
 203
 204         // Check to see if a param exists
 205         bool HasParam(const wxString& param);
 206
 207         // Finds the node or returns NULL
 208         wxXmlNode *GetParamNode(const wxString& param);
 209         wxString GetParamValue(const wxString& param);
 210
 211         // Add style flag (e.g. wxMB_DOCKABLE) to list of flags
 212         // understood by this handler
 213         void AddStyle(const wxString& name, int value);
 214
 215         // Gets style flags from text in form "flag | flag2| flag3 |..."
 216         // Only understads flags added with AddStyle
 217         int GetStyle(const wxString& param = _T("style"), int defaults = 0);
 218
 219         // Gets text from param and does some convertions:
 220         // - replaces \n, \r, \t by respective chars (according to C syntax)
 221         // - replaces $ by & and $$ by $ (needed for $File => &File because of XML)
 222         // - converts encodings if neccessary
 223         wxString GetText(const wxString& param);
 224
 225         // Return XMLID
 226         int GetID();
 227         wxString GetName();
 228
 229         // Get bool flag (1,t,yes,on,true are TRUE, everything else is FALSE)
 230         bool GetBool(const wxString& param, bool defaultv = FALSE);
 231
 232         // Get integer value from param
 233         long GetLong( const wxString& param, long defaultv = 0 );
 234
 235         // Get colour in HTML syntax (#RRGGBB)
 236         wxColour GetColour(const wxString& param);
 237
 238         wxSize GetSize(const wxString& param = _T("size"));
 239         wxPoint GetPosition(const wxString& param = _T("pos"));
 240
 241         // Sets common window options:
 242         void SetupWindow(wxWindow *wnd);
 243
 244         void CreateChildren(wxObject *parent, bool only_this_handler = FALSE,
 245                           wxXmlNode *children_node = NULL /*stands for
 246                              GetParamNode("children")*/);
 247         wxObject *CreateResFromNode(wxXmlNode *node, wxObject *parent, wxObject *instance = NULL)
 248             { return m_Resource->CreateResFromNode(node, parent, instance); }
 249 };
 250
 251 #define ADD_STYLE(style) AddStyle(_T(#style), style)
 252
 253
 254
 255 #endif // _WX_XMLRES_H_