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
 153 #define XMLID(str_id) \
 154     wxXmlResource::GetXMLID(_T(str_id))
 155
 156
 157
 158 // This macro returns pointer to particular control in dialog
 159 // created using XML resources. You can use it to set/get values from
 160 // controls.
 161 // Example:
 162 //    wxDialog dlg;
 163 //    wxTheXmlResource->LoadDialog(&dlg, mainFrame, "my_dialog");
 164 //    XMLCTRL(dlg, "my_textctrl", wxTextCtrl)->SetValue(_T("default value"));
 165
 166 #define XMLCTRL(window, id, type) \
 167     ((type*)((window).FindWindow(XMLID(id))))
 168
 169
 170
 171 class WXDLLEXPORT wxXmlResourceHandler : public wxObject
 172 {
 173     public:
 174         wxXmlResourceHandler();
 175         virtual ~wxXmlResourceHandler() {}
 176
 177         // Creates object (menu, dialog, control, ...) from XML node.
 178         // Should check for validity.
 179         // parent is higher-level object (usually window, dialog or panel)
 180         // that is often neccessary to create resource
 181         // if instance != NULL it should not create new instance via 'new' but
 182         // rather use this one and call its Create method
 183         wxObject *CreateResource(wxXmlNode *node, wxObject *parent, wxObject *instance);
 184
 185         // This one is called from CreateResource after variables
 186         // were filled
 187         virtual wxObject *DoCreateResource() = 0;
 188
 189         // Returns TRUE if it understands this node and can create
 190         // resource from it, FALSE otherwise.
 191         virtual bool CanHandle(wxXmlNode *node) = 0;
 192
 193         // Check "platform" property if it matches this platform
 194         // that is, if this node 'exists' under this platform
 195         static bool CheckPlatform(wxXmlNode *node);
 196
 197         void SetParentResource(wxXmlResource *res) { m_Resource = res; }
 198
 199
 200     protected:
 201
 202         wxXmlResource *m_Resource;
 203         wxArrayString m_StyleNames;
 204         wxArrayInt m_StyleValues;
 205
 206         // Variables (filled by CreateResource)
 207         wxXmlNode *m_Node;
 208         wxObject *m_Parent, *m_Instance;
 209         wxWindow *m_ParentAsWindow, *m_InstanceAsWindow;
 210
 211         // --- Handy methods:
 212
 213         // Gets node content from wxXML_ENTITY_NODE
 214         // (the problem is, <tag>content<tag> is represented as
 215         // wxXML_ENTITY_NODE name="tag", content=""
 216         //    |-- wxXML_TEXT_NODE or
 217         //        wxXML_CDATA_SECTION_NODE name="" content="content"
 218         wxString GetNodeContent(wxXmlNode *node);
 219
 220         // Check to see if a param exists
 221         bool HasParam(const wxString& param);
 222
 223         // Finds the node or returns NULL
 224         wxXmlNode *GetParamNode(const wxString& param);
 225         wxString GetParamValue(const wxString& param);
 226
 227         // Add style flag (e.g. wxMB_DOCKABLE) to list of flags
 228         // understood by this handler
 229         void AddStyle(const wxString& name, int value);
 230
 231         // Gets style flags from text in form "flag | flag2| flag3 |..."
 232         // Only understads flags added with AddStyle
 233         int GetStyle(const wxString& param = _T("style"), int defaults = 0);
 234
 235         // Gets text from param and does some convertions:
 236         // - replaces \n, \r, \t by respective chars (according to C syntax)
 237         // - replaces $ by & and $$ by $ (needed for $File => &File because of XML)
 238         // - converts encodings if neccessary
 239         wxString GetText(const wxString& param);
 240
 241         // Return XMLID
 242         int GetID();
 243         wxString GetName();
 244
 245         // Get bool flag (1,t,yes,on,true are TRUE, everything else is FALSE)
 246         bool GetBool(const wxString& param, bool defaultv = FALSE);
 247
 248         // Get integer value from param
 249         long GetLong( const wxString& param, long defaultv = 0 );
 250
 251         // Get colour in HTML syntax (#RRGGBB)
 252         wxColour GetColour(const wxString& param);
 253
 254         wxSize GetSize(const wxString& param = _T("size"));
 255         wxPoint GetPosition(const wxString& param = _T("pos"));
 256
 257         // Sets common window options:
 258         void SetupWindow(wxWindow *wnd);
 259
 260         void CreateChildren(wxObject *parent, bool only_this_handler = FALSE,
 261                           wxXmlNode *children_node = NULL /*stands for
 262                              GetParamNode("children")*/);
 263         wxObject *CreateResFromNode(wxXmlNode *node, wxObject *parent, wxObject *instance = NULL)
 264             { return m_Resource->CreateResFromNode(node, parent, instance); }
 265 };
 266
 267 #define ADD_STYLE(style) AddStyle(_T(#style), style)
 268
 269
 270
 271 #endif // _WX_XMLRES_H_