1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/xrc/xmlres.h
3 // Purpose: XML resources
4 // Author: Vaclav Slavik
7 // Copyright: (c) 2000 Vaclav Slavik
8 // Licence: wxWindows licence
9 /////////////////////////////////////////////////////////////////////////////
18 #include "wx/string.h"
19 #include "wx/dynarray.h"
20 #include "wx/datetime.h"
21 #include "wx/gdicmn.h"
22 #include "wx/filesys.h"
23 #include "wx/bitmap.h"
25 #include "wx/artprov.h"
26 #include "wx/colour.h"
28 #include "wx/xml/xml.h"
30 class WXDLLEXPORT wxMenu
;
31 class WXDLLEXPORT wxMenuBar
;
32 class WXDLLEXPORT wxDialog
;
33 class WXDLLEXPORT wxPanel
;
34 class WXDLLEXPORT wxWindow
;
35 class WXDLLEXPORT wxFrame
;
36 class WXDLLEXPORT wxToolBar
;
38 class WXDLLIMPEXP_XRC wxXmlResourceHandler
;
39 class WXDLLIMPEXP_XRC wxXmlSubclassFactory
;
40 class WXDLLIMPEXP_XRC wxXmlSubclassFactoriesList
;
41 class wxXmlResourceModule
;
44 // These macros indicate current version of XML resources (this information is
45 // encoded in root node of XRC file as "version" property).
47 // Rules for increasing version number:
48 // - change it only if you made incompatible change to the format. Addition
49 // of new attribute to control handler is _not_ incompatible change, because
50 // older versions of the library may ignore it.
51 // - if you change version number, follow these steps:
52 // - set major, minor and release numbers to respective version numbers of
53 // the wxWidgets library (see wx/version.h)
54 // - reset revision to 0 unless the first three are same as before,
55 // in which case you should increase revision by one
56 #define WX_XMLRES_CURRENT_VERSION_MAJOR 2
57 #define WX_XMLRES_CURRENT_VERSION_MINOR 5
58 #define WX_XMLRES_CURRENT_VERSION_RELEASE 3
59 #define WX_XMLRES_CURRENT_VERSION_REVISION 0
60 #define WX_XMLRES_CURRENT_VERSION_STRING _T("2.5.3.0")
62 #define WX_XMLRES_CURRENT_VERSION \
63 (WX_XMLRES_CURRENT_VERSION_MAJOR * 256*256*256 + \
64 WX_XMLRES_CURRENT_VERSION_MINOR * 256*256 + \
65 WX_XMLRES_CURRENT_VERSION_RELEASE * 256 + \
66 WX_XMLRES_CURRENT_VERSION_REVISION)
68 class WXDLLIMPEXP_XRC wxXmlResourceDataRecord
71 wxXmlResourceDataRecord() : Doc(NULL
) {
73 Time
= wxDateTime
::Now();
76 ~wxXmlResourceDataRecord() {delete Doc
;}
86 WX_DECLARE_USER_EXPORTED_OBJARRAY(wxXmlResourceDataRecord
,
87 wxXmlResourceDataRecords
,
90 WX_DEFINE_USER_EXPORTED_ARRAY_PTR(wxXmlResourceHandler
*,
91 wxXmlResourceHandlers
,
92 class WXDLLIMPEXP_XRC
);
94 enum wxXmlResourceFlags
97 wxXRC_NO_SUBCLASSING
= 2,
98 wxXRC_NO_RELOADING
= 4
101 // This class holds XML resources from one or more .xml files
102 // (or derived forms, either binary or zipped -- see manual for
104 class WXDLLIMPEXP_XRC wxXmlResource
: public wxObject
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 // wxXRC_NO_RELOADING
114 // don't check the modification time of the XRC files and
115 // reload them if they have changed on disk
116 wxXmlResource(int flags
= wxXRC_USE_LOCALE
);
119 // Flags: wxXRC_USE_LOCALE
120 // translatable strings will be translated via _()
121 // wxXRC_NO_SUBCLASSING
122 // subclass property of object nodes will be ignored
123 // (useful for previews in XRC editors)
124 wxXmlResource(const wxString
& filemask
, int flags
= wxXRC_USE_LOCALE
);
129 // Loads resources from XML files that match given filemask.
130 // This method understands VFS (see filesys.h).
131 bool Load(const wxString
& filemask
);
133 // Unload resource from the given XML file (wildcards not allowed)
134 bool Unload(const wxString
& filename
);
136 // Initialize handlers for all supported controls/windows. This will
137 // make the executable quite big because it forces linking against
138 // most of the wxWidgets library.
139 void InitAllHandlers();
141 // Initialize only a specific handler (or custom handler). Convention says
142 // that handler name is equal to the control's name plus 'XmlHandler', for
143 // example wxTextCtrlXmlHandler, wxHtmlWindowXmlHandler. The XML resource
144 // compiler (xmlres) can create include file that contains initialization
145 // code for all controls used within the resource.
146 void AddHandler(wxXmlResourceHandler
*handler
);
148 // Add a new handler at the begining of the handler list
149 void InsertHandler(wxXmlResourceHandler
*handler
);
151 // Removes all handlers
152 void ClearHandlers();
154 // Registers subclasses factory for use in XRC. This function is not meant
155 // for public use, please see the comment above wxXmlSubclassFactory
157 static void AddSubclassFactory(wxXmlSubclassFactory
*factory
);
159 // Loads menu from resource. Returns NULL on failure.
160 wxMenu
*LoadMenu(const wxString
& name
);
162 // Loads menubar from resource. Returns NULL on failure.
163 wxMenuBar
*LoadMenuBar(wxWindow
*parent
, const wxString
& name
);
165 // Loads menubar from resource. Returns NULL on failure.
166 wxMenuBar
*LoadMenuBar(const wxString
& name
) { return LoadMenuBar(NULL
, name
); }
170 wxToolBar
*LoadToolBar(wxWindow
*parent
, const wxString
& name
);
173 // Loads a dialog. dlg points to parent window (if any).
174 wxDialog
*LoadDialog(wxWindow
*parent
, const wxString
& name
);
176 // Loads a dialog. dlg points to parent window (if any). This form
177 // is used to finish creation of already existing instance (main reason
178 // for this is that you may want to use derived class with new event table)
179 // Example (typical usage):
181 // wxTheXmlResource->LoadDialog(&dlg, mainFrame, "my_dialog");
183 bool LoadDialog(wxDialog
*dlg
, wxWindow
*parent
, const wxString
& name
);
185 // Loads a panel. panel points to parent window (if any).
186 wxPanel
*LoadPanel(wxWindow
*parent
, const wxString
& name
);
188 // Loads a panel. panel points to parent window (if any). This form
189 // is used to finish creation of already existing instance.
190 bool LoadPanel(wxPanel
*panel
, wxWindow
*parent
, const wxString
& name
);
193 wxFrame
*LoadFrame(wxWindow
* parent
, const wxString
& name
);
194 bool LoadFrame(wxFrame
* frame
, wxWindow
*parent
, const wxString
& name
);
196 // Load an object from the resource specifying both the resource name and
197 // the classname. This lets you load nonstandard container windows.
198 wxObject
*LoadObject(wxWindow
*parent
, const wxString
& name
,
199 const wxString
& classname
);
201 // Load an object from the resource specifying both the resource name and
202 // the classname. This form lets you finish the creation of an existing
204 bool LoadObject(wxObject
*instance
, wxWindow
*parent
, const wxString
& name
,
205 const wxString
& classname
);
207 // Loads a bitmap resource from a file.
208 wxBitmap
LoadBitmap(const wxString
& name
);
210 // Loads an icon resource from a file.
211 wxIcon
LoadIcon(const wxString
& name
);
213 // Attaches an unknown control to the given panel/window/dialog.
214 // Unknown controls are used in conjunction with <object class="unknown">.
215 bool AttachUnknownControl(const wxString
& name
, wxWindow
*control
,
216 wxWindow
*parent
= NULL
);
218 // Returns a numeric ID that is equivalent to the string ID used in an XML
219 // resource. If an unknown str_id is requested (i.e. other than wxID_XXX
220 // or integer), a new record is created which associates the given string
221 // with a number. If value_if_not_found == wxID_NONE, the number is obtained via
222 // wxNewId(). Otherwise value_if_not_found is used.
223 // Macro XRCID(name) is provided for convenient use in event tables.
224 static int GetXRCID(const wxChar
*str_id
, int value_if_not_found
= wxID_NONE
);
226 // Returns version information (a.b.c.d = d+ 256*c + 256^2*b + 256^3*a).
227 long GetVersion() const { return m_version
; }
229 // Compares resources version to argument. Returns -1 if resources version
230 // is less than the argument, +1 if greater and 0 if they equal.
231 int CompareVersion(int major
, int minor
, int release
, int revision
) const
232 { return GetVersion() -
233 (major
*256*256*256 + minor
*256*256 + release
*256 + revision
); }
235 //// Singleton accessors.
237 // Gets the global resources object or creates one if none exists.
238 static wxXmlResource
*Get();
240 // Sets the global resources object and returns a pointer to the previous one (may be NULL).
241 static wxXmlResource
*Set(wxXmlResource
*res
);
243 // Returns flags, which may be a bitlist of wxXRC_USE_LOCALE and wxXRC_NO_SUBCLASSING.
244 int GetFlags() const { return m_flags
; }
245 // Set flags after construction.
246 void SetFlags(int flags
) { m_flags
= flags
; }
249 // Scans the resources list for unloaded files and loads them. Also reloads
250 // files that have been modified since last loading.
251 bool UpdateResources();
253 // Finds a resource (calls UpdateResources) and returns a node containing it.
254 wxXmlNode
*FindResource(const wxString
& name
, const wxString
& classname
, bool recursive
= false);
256 // Helper function: finds a resource (calls UpdateResources) and returns a node containing it.
257 wxXmlNode
*DoFindResource(wxXmlNode
*parent
, const wxString
& name
, const wxString
& classname
, bool recursive
);
259 // Creates a resource from information in the given node
260 // (Uses only 'handlerToUse' if != NULL)
261 wxObject
*CreateResFromNode(wxXmlNode
*node
, wxObject
*parent
,
262 wxObject
*instance
= NULL
,
263 wxXmlResourceHandler
*handlerToUse
= NULL
);
265 // Helper of Load() and Unload(): returns the URL corresponding to the
266 // given file if it's indeed a file, otherwise returns the original string
268 static wxString
ConvertFileNameToURL(const wxString
& filename
);
270 // loading resources from archives is impossible without wxFileSystem
272 // Another helper: detect if the filename is a ZIP or XRS file
273 static bool IsArchive(const wxString
& filename
);
274 #endif // wxUSE_FILESYSTEM
280 wxXmlResourceHandlers m_handlers
;
281 wxXmlResourceDataRecords m_data
;
283 wxFileSystem m_curFileSystem
;
284 wxFileSystem
& GetCurFileSystem() { return m_curFileSystem
; }
287 friend class wxXmlResourceHandler
;
288 friend class wxXmlResourceModule
;
290 static wxXmlSubclassFactoriesList
*ms_subclassFactories
;
292 // singleton instance:
293 static wxXmlResource
*ms_instance
;
297 // This macro translates string identifier (as used in XML resource,
298 // e.g. <menuitem id="my_menu">...</menuitem>) to integer id that is needed by
299 // wxWidgets event tables.
301 // BEGIN_EVENT_TABLE(MyFrame, wxFrame)
302 // EVT_MENU(XRCID("quit"), MyFrame::OnQuit)
303 // EVT_MENU(XRCID("about"), MyFrame::OnAbout)
304 // EVT_MENU(XRCID("new"), MyFrame::OnNew)
305 // EVT_MENU(XRCID("open"), MyFrame::OnOpen)
308 #define XRCID(str_id) \
309 wxXmlResource::GetXRCID(wxT(str_id))
312 // This macro returns pointer to particular control in dialog
313 // created using XML resources. You can use it to set/get values from
317 // wxXmlResource::Get()->LoadDialog(&dlg, mainFrame, "my_dialog");
318 // XRCCTRL(dlg, "my_textctrl", wxTextCtrl)->SetValue(wxT("default value"));
320 #define XRCCTRL(window, id, type) \
321 (wxStaticCast((window).FindWindow(XRCID(id)), type))
323 // wxXmlResourceHandler is an abstract base class for resource handlers
324 // capable of creating a control from an XML node.
326 class WXDLLIMPEXP_XRC wxXmlResourceHandler
: public wxObject
328 DECLARE_ABSTRACT_CLASS(wxXmlResourceHandler
)
331 wxXmlResourceHandler();
334 virtual ~wxXmlResourceHandler() {}
336 // Creates an object (menu, dialog, control, ...) from an XML node.
337 // Should check for validity.
338 // parent is a higher-level object (usually window, dialog or panel)
339 // that is often necessary to create the resource.
340 // If instance is non-NULL it should not create a new instance via 'new' but
341 // should rather use this one, and call its Create method.
342 wxObject
*CreateResource(wxXmlNode
*node
, wxObject
*parent
,
345 // This one is called from CreateResource after variables
347 virtual wxObject
*DoCreateResource() = 0;
349 // Returns true if it understands this node and can create
350 // a resource from it, false otherwise.
351 virtual bool CanHandle(wxXmlNode
*node
) = 0;
353 // Sets the parent resource.
354 void SetParentResource(wxXmlResource
*res
) { m_resource
= res
; }
357 wxXmlResource
*m_resource
;
358 wxArrayString m_styleNames
;
359 wxArrayInt m_styleValues
;
361 // Variables (filled by CreateResource)
364 wxObject
*m_parent
, *m_instance
;
365 wxWindow
*m_parentAsWindow
;
367 // --- Handy methods:
369 // Returns true if the node has a property class equal to classname,
370 // e.g. <object class="wxDialog">.
371 bool IsOfClass(wxXmlNode
*node
, const wxString
& classname
);
373 // Gets node content from wxXML_ENTITY_NODE
374 // The problem is, <tag>content<tag> is represented as
375 // wxXML_ENTITY_NODE name="tag", content=""
376 // |-- wxXML_TEXT_NODE or
377 // wxXML_CDATA_SECTION_NODE name="" content="content"
378 wxString
GetNodeContent(wxXmlNode
*node
);
380 // Check to see if a parameter exists.
381 bool HasParam(const wxString
& param
);
383 // Finds the node or returns NULL.
384 wxXmlNode
*GetParamNode(const wxString
& param
);
386 // Finds the parameter value or returns the empty string.
387 wxString
GetParamValue(const wxString
& param
);
389 // Add a style flag (e.g. wxMB_DOCKABLE) to the list of flags
390 // understood by this handler.
391 void AddStyle(const wxString
& name
, int value
);
393 // Add styles common to all wxWindow-derived classes.
394 void AddWindowStyles();
396 // Gets style flags from text in form "flag | flag2| flag3 |..."
397 // Only understands flags added with AddStyle
398 int GetStyle(const wxString
& param
= wxT("style"), int defaults
= 0);
400 // Gets text from param and does some conversions:
401 // - replaces \n, \r, \t by respective chars (according to C syntax)
402 // - replaces _ by & and __ by _ (needed for _File => &File because of XML)
403 // - calls wxGetTranslations (unless disabled in wxXmlResource)
404 wxString
GetText(const wxString
& param
, bool translate
= true);
406 // Returns the XRCID.
409 // Returns the resource name.
412 // Gets a bool flag (1, t, yes, on, true are true, everything else is false).
413 bool GetBool(const wxString
& param
, bool defaultv
= false);
415 // Gets an integer value from the parameter.
416 long GetLong(const wxString
& param
, long defaultv
= 0);
418 // Gets a float value from the parameter.
419 float GetFloat(const wxString
& param
, float defaultv
= 0);
421 // Gets colour in HTML syntax (#RRGGBB).
422 wxColour
GetColour(const wxString
& param
, const wxColour
& defaultv
= wxNullColour
);
424 // Gets the size (may be in dialog units).
425 wxSize
GetSize(const wxString
& param
= wxT("size"),
426 wxWindow
*windowToUse
= NULL
);
428 // Gets the position (may be in dialog units).
429 wxPoint
GetPosition(const wxString
& param
= wxT("pos"));
431 // Gets a dimension (may be in dialog units).
432 wxCoord
GetDimension(const wxString
& param
, wxCoord defaultv
= 0,
433 wxWindow
*windowToUse
= NULL
);
436 wxBitmap
GetBitmap(const wxString
& param
= wxT("bitmap"),
437 const wxArtClient
& defaultArtClient
= wxART_OTHER
,
438 wxSize size
= wxDefaultSize
);
441 wxIcon
GetIcon(const wxString
& param
= wxT("icon"),
442 const wxArtClient
& defaultArtClient
= wxART_OTHER
,
443 wxSize size
= wxDefaultSize
);
446 wxFont
GetFont(const wxString
& param
= wxT("font"));
448 // Sets common window options.
449 void SetupWindow(wxWindow
*wnd
);
452 void CreateChildren(wxObject
*parent
, bool this_hnd_only
= false);
455 void CreateChildrenPrivately(wxObject
*parent
, wxXmlNode
*rootnode
= NULL
);
457 // Creates a resource from a node.
458 wxObject
*CreateResFromNode(wxXmlNode
*node
,
459 wxObject
*parent
, wxObject
*instance
= NULL
)
460 { return m_resource
->CreateResFromNode(node
, parent
, instance
); }
464 wxFileSystem
& GetCurFileSystem() { return m_resource
->GetCurFileSystem(); }
469 // Programmer-friendly macros for writing XRC handlers:
471 #define XRC_ADD_STYLE(style) AddStyle(wxT(#style), style)
473 #define XRC_MAKE_INSTANCE(variable, classname) \
474 classname *variable = NULL; \
476 variable = wxStaticCast(m_instance, classname); \
478 variable = new classname;
481 // FIXME -- remove this $%^#$%#$@# as soon as Ron checks his changes in!!
482 WXDLLIMPEXP_XRC
void wxXmlInitResourceModule();
485 // This class is used to create instances of XRC "object" nodes with "subclass"
486 // property. It is _not_ supposed to be used by XRC users, you should instead
487 // register your subclasses via wxWidgets' RTTI mechanism. This class is useful
488 // only for language bindings developer who need a way to implement subclassing
489 // in wxWidgets ports that don't support wxRTTI (e.g. wxPython).
490 class WXDLLIMPEXP_XRC wxXmlSubclassFactory
493 // Try to create instance of given class and return it, return NULL on
495 virtual wxObject
*Create(const wxString
& className
) = 0;
496 virtual ~wxXmlSubclassFactory() {}
500 /* -------------------------------------------------------------------------
501 Backward compatibility macros. Do *NOT* use, they may disappear in future
502 versions of the XRC library!
503 ------------------------------------------------------------------------- */
504 #if WXWIN_COMPATIBILITY_2_4
505 #define ADD_STYLE XRC_ADD_STYLE
506 #define wxTheXmlResource wxXmlResource::Get()
508 #define XMLCTRL XRCCTRL
509 #define GetXMLID GetXRCID
514 #endif // _WX_XMLRES_H_