1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: XML resources
4 // Author: Vaclav Slavik
7 // Copyright: (c) 2000 Vaclav Slavik
8 // Licence: wxWindows licence
9 /////////////////////////////////////////////////////////////////////////////
14 #if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
15 #pragma interface "xmlres.h"
22 #include "wx/string.h"
23 #include "wx/dynarray.h"
24 #include "wx/datetime.h"
26 #include "wx/gdicmn.h"
27 #include "wx/filesys.h"
28 #include "wx/bitmap.h"
30 #include "wx/artprov.h"
32 #include "wx/xml/xml.h"
34 class WXDLLEXPORT wxMenu
;
35 class WXDLLEXPORT wxMenuBar
;
36 class WXDLLEXPORT wxDialog
;
37 class WXDLLEXPORT wxPanel
;
38 class WXDLLEXPORT wxWindow
;
39 class WXDLLEXPORT wxFrame
;
40 class WXDLLEXPORT wxToolBar
;
42 class WXDLLIMPEXP_XRC wxXmlResourceHandler
;
43 class WXDLLIMPEXP_XRC wxXmlSubclassFactory
;
44 class WXDLLIMPEXP_XRC wxXmlSubclassFactoriesList
;
45 class wxXmlResourceModule
;
48 // These macros indicate current version of XML resources (this information is
49 // encoded in root node of XRC file as "version" property).
51 // Rules for increasing version number:
52 // - change it only if you made incompatible change to the format. Addition
53 // of new attribute to control handler is _not_ incompatible change, because
54 // older versions of the library may ignore it.
55 // - if you change version number, follow these steps:
56 // - set major, minor and release numbers to respective version numbers of
57 // the wxWidgets library (see wx/version.h)
58 // - reset revision to 0 unless the first three are same as before,
59 // in which case you should increase revision by one
60 #define WX_XMLRES_CURRENT_VERSION_MAJOR 2
61 #define WX_XMLRES_CURRENT_VERSION_MINOR 5
62 #define WX_XMLRES_CURRENT_VERSION_RELEASE 3
63 #define WX_XMLRES_CURRENT_VERSION_REVISION 0
64 #define WX_XMLRES_CURRENT_VERSION_STRING _T("2.5.3.0")
66 #define WX_XMLRES_CURRENT_VERSION \
67 (WX_XMLRES_CURRENT_VERSION_MAJOR * 256*256*256 + \
68 WX_XMLRES_CURRENT_VERSION_MINOR * 256*256 + \
69 WX_XMLRES_CURRENT_VERSION_RELEASE * 256 + \
70 WX_XMLRES_CURRENT_VERSION_REVISION)
72 class WXDLLIMPEXP_XRC wxXmlResourceDataRecord
75 wxXmlResourceDataRecord() : Doc(NULL
), Time(wxDateTime
::Now()) {}
76 ~wxXmlResourceDataRecord() {delete Doc
;}
84 WX_DECLARE_USER_EXPORTED_OBJARRAY(wxXmlResourceDataRecord
,
85 wxXmlResourceDataRecords
,
88 enum wxXmlResourceFlags
91 wxXRC_NO_SUBCLASSING
= 2,
92 wxXRC_NO_RELOADING
= 4
95 // This class holds XML resources from one or more .xml files
96 // (or derived forms, either binary or zipped -- see manual for
98 class WXDLLIMPEXP_XRC wxXmlResource
: public wxObject
102 // Flags: wxXRC_USE_LOCALE
103 // translatable strings will be translated via _()
104 // wxXRC_NO_SUBCLASSING
105 // subclass property of object nodes will be ignored
106 // (useful for previews in XRC editors)
107 // wxXRC_NO_RELOADING
108 // don't check the modification time of the XRC files and
109 // reload them if they have changed on disk
110 wxXmlResource(int flags
= wxXRC_USE_LOCALE
);
113 // Flags: wxXRC_USE_LOCALE
114 // translatable strings will be translated via _()
115 // wxXRC_NO_SUBCLASSING
116 // subclass property of object nodes will be ignored
117 // (useful for previews in XRC editors)
118 wxXmlResource(const wxString
& filemask
, int flags
= wxXRC_USE_LOCALE
);
123 // Loads resources from XML files that match given filemask.
124 // This method understands VFS (see filesys.h).
125 bool Load(const wxString
& filemask
);
127 // Initialize handlers for all supported controls/windows. This will
128 // make the executable quite big because it forces linking against
129 // most of the wxWidgets library.
130 void InitAllHandlers();
132 // Initialize only a specific handler (or custom handler). Convention says
133 // that handler name is equal to the control's name plus 'XmlHandler', for
134 // example wxTextCtrlXmlHandler, wxHtmlWindowXmlHandler. The XML resource
135 // compiler (xmlres) can create include file that contains initialization
136 // code for all controls used within the resource.
137 void AddHandler(wxXmlResourceHandler
*handler
);
139 // Add a new handler at the begining of the handler list
140 void InsertHandler(wxXmlResourceHandler
*handler
);
142 // Removes all handlers
143 void ClearHandlers();
145 // Registers subclasses factory for use in XRC. This function is not meant
146 // for public use, please see the comment above wxXmlSubclassFactory
148 static void AddSubclassFactory(wxXmlSubclassFactory
*factory
);
150 // Loads menu from resource. Returns NULL on failure.
151 wxMenu
*LoadMenu(const wxString
& name
);
153 // Loads menubar from resource. Returns NULL on failure.
154 wxMenuBar
*LoadMenuBar(wxWindow
*parent
, const wxString
& name
);
156 // Loads menubar from resource. Returns NULL on failure.
157 wxMenuBar
*LoadMenuBar(const wxString
& name
) { return LoadMenuBar(NULL
, name
); }
161 wxToolBar
*LoadToolBar(wxWindow
*parent
, const wxString
& name
);
164 // Loads a dialog. dlg points to parent window (if any).
165 wxDialog
*LoadDialog(wxWindow
*parent
, const wxString
& name
);
167 // Loads a dialog. dlg points to parent window (if any). This form
168 // is used to finish creation of already existing instance (main reason
169 // for this is that you may want to use derived class with new event table)
170 // Example (typical usage):
172 // wxTheXmlResource->LoadDialog(&dlg, mainFrame, "my_dialog");
174 bool LoadDialog(wxDialog
*dlg
, wxWindow
*parent
, const wxString
& name
);
176 // Loads a panel. panel points to parent window (if any).
177 wxPanel
*LoadPanel(wxWindow
*parent
, const wxString
& name
);
179 // Loads a panel. panel points to parent window (if any). This form
180 // is used to finish creation of already existing instance.
181 bool LoadPanel(wxPanel
*panel
, wxWindow
*parent
, const wxString
& name
);
184 wxFrame
*LoadFrame(wxWindow
* parent
, const wxString
& name
);
185 bool LoadFrame(wxFrame
* frame
, wxWindow
*parent
, const wxString
& name
);
187 // Load an object from the resource specifying both the resource name and
188 // the classname. This lets you load nonstandard container windows.
189 wxObject
*LoadObject(wxWindow
*parent
, const wxString
& name
,
190 const wxString
& classname
);
192 // Load an object from the resource specifying both the resource name and
193 // the classname. This form lets you finish the creation of an existing
195 bool LoadObject(wxObject
*instance
, wxWindow
*parent
, const wxString
& name
,
196 const wxString
& classname
);
198 // Loads a bitmap resource from a file.
199 wxBitmap
LoadBitmap(const wxString
& name
);
201 // Loads an icon resource from a file.
202 wxIcon
LoadIcon(const wxString
& name
);
204 // Attaches an unknown control to the given panel/window/dialog.
205 // Unknown controls are used in conjunction with <object class="unknown">.
206 bool AttachUnknownControl(const wxString
& name
, wxWindow
*control
,
207 wxWindow
*parent
= NULL
);
209 // Returns a numeric ID that is equivalent to the string id used in an XML
210 // resource. To be used in event tables.
211 // Macro XRCID is provided for convenience
212 static int GetXRCID(const wxChar
*str_id
);
214 // Returns version information (a.b.c.d = d+ 256*c + 256^2*b + 256^3*a).
215 long GetVersion() const { return m_version
; }
217 // Compares resources version to argument. Returns -1 if resources version
218 // is less than the argument, +1 if greater and 0 if they equal.
219 int CompareVersion(int major
, int minor
, int release
, int revision
) const
220 { return GetVersion() -
221 (major
*256*256*256 + minor
*256*256 + release
*256 + revision
); }
223 //// Singleton accessors.
225 // Gets the global resources object or creates one if none exists.
226 static wxXmlResource
*Get();
228 // Sets the global resources object and returns a pointer to the previous one (may be NULL).
229 static wxXmlResource
*Set(wxXmlResource
*res
);
231 // Returns flags, which may be a bitlist of wxXRC_USE_LOCALE and wxXRC_NO_SUBCLASSING.
232 int GetFlags() const { return m_flags
; }
233 // Set flags after construction.
234 void SetFlags(int flags
) { m_flags
= flags
; }
237 // Scans the resources list for unloaded files and loads them. Also reloads
238 // files that have been modified since last loading.
239 bool UpdateResources();
241 // Finds a resource (calls UpdateResources) and returns a node containing it.
242 wxXmlNode
*FindResource(const wxString
& name
, const wxString
& classname
, bool recursive
= false);
244 // Helper function: finds a resource (calls UpdateResources) and returns a node containing it.
245 wxXmlNode
*DoFindResource(wxXmlNode
*parent
, const wxString
& name
, const wxString
& classname
, bool recursive
);
247 // Creates a resource from information in the given node
248 // (Uses only 'handlerToUse' if != NULL)
249 wxObject
*CreateResFromNode(wxXmlNode
*node
, wxObject
*parent
,
250 wxObject
*instance
= NULL
,
251 wxXmlResourceHandler
*handlerToUse
= NULL
);
258 wxXmlResourceDataRecords m_data
;
260 wxFileSystem m_curFileSystem
;
261 wxFileSystem
& GetCurFileSystem() { return m_curFileSystem
; }
264 friend class wxXmlResourceHandler
;
265 friend class wxXmlResourceModule
;
267 static wxXmlSubclassFactoriesList
*ms_subclassFactories
;
269 // singleton instance:
270 static wxXmlResource
*ms_instance
;
274 // This macro translates string identifier (as used in XML resource,
275 // e.g. <menuitem id="my_menu">...</menuitem>) to integer id that is needed by
276 // wxWidgets event tables.
278 // BEGIN_EVENT_TABLE(MyFrame, wxFrame)
279 // EVT_MENU(XRCID("quit"), MyFrame::OnQuit)
280 // EVT_MENU(XRCID("about"), MyFrame::OnAbout)
281 // EVT_MENU(XRCID("new"), MyFrame::OnNew)
282 // EVT_MENU(XRCID("open"), MyFrame::OnOpen)
285 #define XRCID(str_id) \
286 wxXmlResource::GetXRCID(wxT(str_id))
289 // This macro returns pointer to particular control in dialog
290 // created using XML resources. You can use it to set/get values from
294 // wxXmlResource::Get()->LoadDialog(&dlg, mainFrame, "my_dialog");
295 // XRCCTRL(dlg, "my_textctrl", wxTextCtrl)->SetValue(wxT("default value"));
297 #define XRCCTRL(window, id, type) \
298 (wxStaticCast((window).FindWindow(XRCID(id)), type))
300 // wxXmlResourceHandler is an abstract base class for resource handlers
301 // capable of creating a control from an XML node.
303 class WXDLLIMPEXP_XRC wxXmlResourceHandler
: public wxObject
305 DECLARE_ABSTRACT_CLASS(wxXmlResourceHandler
)
308 wxXmlResourceHandler();
311 virtual ~wxXmlResourceHandler() {}
313 // Creates an object (menu, dialog, control, ...) from an XML node.
314 // Should check for validity.
315 // parent is a higher-level object (usually window, dialog or panel)
316 // that is often necessary to create the resource.
317 // If instance is non-NULL it should not create a new instance via 'new' but
318 // should rather use this one, and call its Create method.
319 wxObject
*CreateResource(wxXmlNode
*node
, wxObject
*parent
,
322 // This one is called from CreateResource after variables
324 virtual wxObject
*DoCreateResource() = 0;
326 // Returns true if it understands this node and can create
327 // a resource from it, false otherwise.
328 virtual bool CanHandle(wxXmlNode
*node
) = 0;
330 // Sets the parent resource.
331 void SetParentResource(wxXmlResource
*res
) { m_resource
= res
; }
334 wxXmlResource
*m_resource
;
335 wxArrayString m_styleNames
;
336 wxArrayInt m_styleValues
;
338 // Variables (filled by CreateResource)
341 wxObject
*m_parent
, *m_instance
;
342 wxWindow
*m_parentAsWindow
;
344 // --- Handy methods:
346 // Returns true if the node has a property class equal to classname,
347 // e.g. <object class="wxDialog">.
348 bool IsOfClass(wxXmlNode
*node
, const wxString
& classname
)
349 { return node
->GetPropVal(wxT("class"), wxEmptyString
) == classname
; }
351 // Gets node content from wxXML_ENTITY_NODE
352 // The problem is, <tag>content<tag> is represented as
353 // wxXML_ENTITY_NODE name="tag", content=""
354 // |-- wxXML_TEXT_NODE or
355 // wxXML_CDATA_SECTION_NODE name="" content="content"
356 wxString
GetNodeContent(wxXmlNode
*node
);
358 // Check to see if a parameter exists.
359 bool HasParam(const wxString
& param
);
361 // Finds the node or returns NULL.
362 wxXmlNode
*GetParamNode(const wxString
& param
);
364 // Finds the parameter value or returns the empty string.
365 wxString
GetParamValue(const wxString
& param
);
367 // Add a style flag (e.g. wxMB_DOCKABLE) to the list of flags
368 // understood by this handler.
369 void AddStyle(const wxString
& name
, int value
);
371 // Add styles common to all wxWindow-derived classes.
372 void AddWindowStyles();
374 // Gets style flags from text in form "flag | flag2| flag3 |..."
375 // Only understands flags added with AddStyle
376 int GetStyle(const wxString
& param
= wxT("style"), int defaults
= 0);
378 // Gets text from param and does some conversions:
379 // - replaces \n, \r, \t by respective chars (according to C syntax)
380 // - replaces _ by & and __ by _ (needed for _File => &File because of XML)
381 // - calls wxGetTranslations (unless disabled in wxXmlResource)
382 wxString
GetText(const wxString
& param
, bool translate
= true);
384 // Returns the XRCID.
387 // Returns the resource name.
390 // Gets a bool flag (1, t, yes, on, true are true, everything else is false).
391 bool GetBool(const wxString
& param
, bool defaultv
= false);
393 // Gets an integer value from the parameter.
394 long GetLong(const wxString
& param
, long defaultv
= 0);
396 // Gets a float value from the parameter.
397 float GetFloat(const wxString
& param
, float defaultv
= 0);
399 // Gets colour in HTML syntax (#RRGGBB).
400 wxColour
GetColour(const wxString
& param
);
402 // Gets the size (may be in dialog units).
403 wxSize
GetSize(const wxString
& param
= wxT("size"),
404 wxWindow
*windowToUse
= NULL
);
406 // Gets the position (may be in dialog units).
407 wxPoint
GetPosition(const wxString
& param
= wxT("pos"));
409 // Gets a dimension (may be in dialog units).
410 wxCoord
GetDimension(const wxString
& param
, wxCoord defaultv
= 0,
411 wxWindow
*windowToUse
= NULL
);
414 wxBitmap
GetBitmap(const wxString
& param
= wxT("bitmap"),
415 const wxArtClient
& defaultArtClient
= wxART_OTHER
,
416 wxSize size
= wxDefaultSize
);
419 wxIcon
GetIcon(const wxString
& param
= wxT("icon"),
420 const wxArtClient
& defaultArtClient
= wxART_OTHER
,
421 wxSize size
= wxDefaultSize
);
424 wxFont
GetFont(const wxString
& param
= wxT("font"));
426 // Sets common window options.
427 void SetupWindow(wxWindow
*wnd
);
430 void CreateChildren(wxObject
*parent
, bool this_hnd_only
= false);
433 void CreateChildrenPrivately(wxObject
*parent
, wxXmlNode
*rootnode
= NULL
);
435 // Creates a resource from a node.
436 wxObject
*CreateResFromNode(wxXmlNode
*node
,
437 wxObject
*parent
, wxObject
*instance
= NULL
)
438 { return m_resource
->CreateResFromNode(node
, parent
, instance
); }
442 wxFileSystem
& GetCurFileSystem() { return m_resource
->GetCurFileSystem(); }
447 // Programmer-friendly macros for writing XRC handlers:
449 #define XRC_ADD_STYLE(style) AddStyle(wxT(#style), style)
451 #define XRC_MAKE_INSTANCE(variable, classname) \
452 classname *variable = NULL; \
454 variable = wxStaticCast(m_instance, classname); \
456 variable = new classname;
459 // FIXME -- remove this $%^#$%#$@# as soon as Ron checks his changes in!!
460 WXDLLIMPEXP_XRC
void wxXmlInitResourceModule();
463 // This class is used to create instances of XRC "object" nodes with "subclass"
464 // property. It is _not_ supposed to be used by XRC users, you should instead
465 // register your subclasses via wxWidgets' RTTI mechanism. This class is useful
466 // only for language bindings developer who need a way to implement subclassing
467 // in wxWidgets ports that don't support wxRTTI (e.g. wxPython).
468 class WXDLLIMPEXP_XRC wxXmlSubclassFactory
471 // Try to create instance of given class and return it, return NULL on
473 virtual wxObject
*Create(const wxString
& className
) = 0;
474 virtual ~wxXmlSubclassFactory() {}
478 /* -------------------------------------------------------------------------
479 Backward compatibility macros. Do *NOT* use, they may disappear in future
480 versions of the XRC library!
481 ------------------------------------------------------------------------- */
482 #if WXWIN_COMPATIBILITY_2_4
483 #define ADD_STYLE XRC_ADD_STYLE
484 #define wxTheXmlResource wxXmlResource::Get()
486 #define XMLCTRL XRCCTRL
487 #define GetXMLID GetXRCID
492 #endif // _WX_XMLRES_H_