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/arrstr.h"
21 #include "wx/datetime.h"
23 #include "wx/gdicmn.h"
24 #include "wx/filesys.h"
25 #include "wx/bitmap.h"
27 #include "wx/artprov.h"
28 #include "wx/colour.h"
29 #include "wx/animate.h"
31 #include "wx/xml/xml.h"
33 class WXDLLEXPORT wxMenu
;
34 class WXDLLEXPORT wxMenuBar
;
35 class WXDLLEXPORT wxDialog
;
36 class WXDLLEXPORT wxPanel
;
37 class WXDLLEXPORT wxWindow
;
38 class WXDLLEXPORT wxFrame
;
39 class WXDLLEXPORT wxToolBar
;
41 class WXDLLIMPEXP_XRC wxXmlResourceHandler
;
42 class WXDLLIMPEXP_XRC wxXmlSubclassFactory
;
43 class WXDLLIMPEXP_XRC wxXmlSubclassFactoriesList
;
44 class wxXmlResourceModule
;
47 // These macros indicate current version of XML resources (this information is
48 // encoded in root node of XRC file as "version" property).
50 // Rules for increasing version number:
51 // - change it only if you made incompatible change to the format. Addition
52 // of new attribute to control handler is _not_ incompatible change, because
53 // older versions of the library may ignore it.
54 // - if you change version number, follow these steps:
55 // - set major, minor and release numbers to respective version numbers of
56 // the wxWidgets library (see wx/version.h)
57 // - reset revision to 0 unless the first three are same as before,
58 // in which case you should increase revision by one
59 #define WX_XMLRES_CURRENT_VERSION_MAJOR 2
60 #define WX_XMLRES_CURRENT_VERSION_MINOR 5
61 #define WX_XMLRES_CURRENT_VERSION_RELEASE 3
62 #define WX_XMLRES_CURRENT_VERSION_REVISION 0
63 #define WX_XMLRES_CURRENT_VERSION_STRING _T("2.5.3.0")
65 #define WX_XMLRES_CURRENT_VERSION \
66 (WX_XMLRES_CURRENT_VERSION_MAJOR * 256*256*256 + \
67 WX_XMLRES_CURRENT_VERSION_MINOR * 256*256 + \
68 WX_XMLRES_CURRENT_VERSION_RELEASE * 256 + \
69 WX_XMLRES_CURRENT_VERSION_REVISION)
71 class WXDLLIMPEXP_XRC wxXmlResourceDataRecord
74 wxXmlResourceDataRecord() : Doc(NULL
) {
76 Time
= wxDateTime
::Now();
79 ~wxXmlResourceDataRecord() {delete Doc
;}
89 WX_DECLARE_USER_EXPORTED_OBJARRAY(wxXmlResourceDataRecord
,
90 wxXmlResourceDataRecords
,
93 enum wxXmlResourceFlags
96 wxXRC_NO_SUBCLASSING
= 2,
97 wxXRC_NO_RELOADING
= 4
100 // This class holds XML resources from one or more .xml files
101 // (or derived forms, either binary or zipped -- see manual for
103 class WXDLLIMPEXP_XRC wxXmlResource
: public wxObject
107 // Flags: wxXRC_USE_LOCALE
108 // translatable strings will be translated via _()
109 // using the given domain if specified
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
,
117 const wxString
& domain
= wxEmptyString
);
120 // Flags: wxXRC_USE_LOCALE
121 // translatable strings will be translated via _()
122 // using the given domain if specified
123 // wxXRC_NO_SUBCLASSING
124 // subclass property of object nodes will be ignored
125 // (useful for previews in XRC editors)
126 wxXmlResource(const wxString
& filemask
, int flags
= wxXRC_USE_LOCALE
,
127 const wxString
& domain
= wxEmptyString
);
130 virtual ~wxXmlResource();
132 wxXmlNode
*GetFirstRoot();
134 // Loads resources from XML files that match given filemask.
135 // This method understands VFS (see filesys.h).
136 bool Load(const wxString
& filemask
);
138 // Unload resource from the given XML file (wildcards not allowed)
139 bool Unload(const wxString
& filename
);
141 // Initialize handlers for all supported controls/windows. This will
142 // make the executable quite big because it forces linking against
143 // most of the wxWidgets library.
144 void InitAllHandlers();
146 // Initialize only a specific handler (or custom handler). Convention says
147 // that handler name is equal to the control's name plus 'XmlHandler', for
148 // example wxTextCtrlXmlHandler, wxHtmlWindowXmlHandler. The XML resource
149 // compiler (xmlres) can create include file that contains initialization
150 // code for all controls used within the resource.
151 void AddHandler(wxXmlResourceHandler
*handler
);
153 // Add a new handler at the begining of the handler list
154 void InsertHandler(wxXmlResourceHandler
*handler
);
156 // Removes all handlers
157 void ClearHandlers();
159 // Registers subclasses factory for use in XRC. This function is not meant
160 // for public use, please see the comment above wxXmlSubclassFactory
162 static void AddSubclassFactory(wxXmlSubclassFactory
*factory
);
164 // Loads menu from resource. Returns NULL on failure.
165 wxMenu
*LoadMenu(const wxString
& name
);
167 // Loads menubar from resource. Returns NULL on failure.
168 wxMenuBar
*LoadMenuBar(wxWindow
*parent
, const wxString
& name
);
170 // Loads menubar from resource. Returns NULL on failure.
171 wxMenuBar
*LoadMenuBar(const wxString
& name
) { return LoadMenuBar(NULL
, name
); }
175 wxToolBar
*LoadToolBar(wxWindow
*parent
, const wxString
& name
);
178 // Loads a dialog. dlg points to parent window (if any).
179 wxDialog
*LoadDialog(wxWindow
*parent
, const wxString
& name
);
181 // Loads a dialog. dlg points to parent window (if any). This form
182 // is used to finish creation of already existing instance (main reason
183 // for this is that you may want to use derived class with new event table)
184 // Example (typical usage):
186 // wxTheXmlResource->LoadDialog(&dlg, mainFrame, "my_dialog");
188 bool LoadDialog(wxDialog
*dlg
, wxWindow
*parent
, const wxString
& name
);
190 // Loads a panel. panel points to parent window (if any).
191 wxPanel
*LoadPanel(wxWindow
*parent
, const wxString
& name
);
193 // Loads a panel. panel points to parent window (if any). This form
194 // is used to finish creation of already existing instance.
195 bool LoadPanel(wxPanel
*panel
, wxWindow
*parent
, const wxString
& name
);
198 wxFrame
*LoadFrame(wxWindow
* parent
, const wxString
& name
);
199 bool LoadFrame(wxFrame
* frame
, wxWindow
*parent
, const wxString
& name
);
201 // Load an object from the resource specifying both the resource name and
202 // the classname. This lets you load nonstandard container windows.
203 wxObject
*LoadObject(wxWindow
*parent
, const wxString
& name
,
204 const wxString
& classname
);
206 // Load an object from the resource specifying both the resource name and
207 // the classname. This form lets you finish the creation of an existing
209 bool LoadObject(wxObject
*instance
, wxWindow
*parent
, const wxString
& name
,
210 const wxString
& classname
);
212 // Loads a bitmap resource from a file.
213 wxBitmap
LoadBitmap(const wxString
& name
);
215 // Loads an icon resource from a file.
216 wxIcon
LoadIcon(const wxString
& name
);
218 // Attaches an unknown control to the given panel/window/dialog.
219 // Unknown controls are used in conjunction with <object class="unknown">.
220 bool AttachUnknownControl(const wxString
& name
, wxWindow
*control
,
221 wxWindow
*parent
= NULL
);
223 // Returns a numeric ID that is equivalent to the string ID used in an XML
224 // resource. If an unknown str_id is requested (i.e. other than wxID_XXX
225 // or integer), a new record is created which associates the given string
226 // with a number. If value_if_not_found == wxID_NONE, the number is obtained via
227 // wxWindow::NewControlId(). Otherwise value_if_not_found is used.
228 // Macro XRCID(name) is provided for convenient use in event tables.
229 static int GetXRCID(const wxChar
*str_id
, int value_if_not_found
= wxID_NONE
);
231 // Returns version information (a.b.c.d = d+ 256*c + 256^2*b + 256^3*a).
232 long GetVersion() const { return m_version
; }
234 // Compares resources version to argument. Returns -1 if resources version
235 // is less than the argument, +1 if greater and 0 if they equal.
236 int CompareVersion(int major
, int minor
, int release
, int revision
) const
237 { return GetVersion() -
238 (major
*256*256*256 + minor
*256*256 + release
*256 + revision
); }
240 //// Singleton accessors.
242 // Gets the global resources object or creates one if none exists.
243 static wxXmlResource
*Get();
245 // Sets the global resources object and returns a pointer to the previous one (may be NULL).
246 static wxXmlResource
*Set(wxXmlResource
*res
);
248 // Returns flags, which may be a bitlist of wxXRC_USE_LOCALE and wxXRC_NO_SUBCLASSING.
249 int GetFlags() const { return m_flags
; }
250 // Set flags after construction.
251 void SetFlags(int flags
) { m_flags
= flags
; }
253 // Get/Set the domain to be passed to the translation functions, defaults
254 // to empty string (no domain).
255 const wxString
& GetDomain() const { return m_domain
; }
256 void SetDomain(const wxString
& domain
);
259 // Scans the resources list for unloaded files and loads them. Also reloads
260 // files that have been modified since last loading.
261 bool UpdateResources();
263 // Finds a resource (calls UpdateResources) and returns a node containing it.
264 wxXmlNode
*FindResource(const wxString
& name
, const wxString
& classname
, bool recursive
= false);
266 // Helper function: finds a resource (calls UpdateResources) and returns a node containing it.
267 wxXmlNode
*DoFindResource(wxXmlNode
*parent
, const wxString
& name
, const wxString
& classname
, bool recursive
);
269 // Creates a resource from information in the given node
270 // (Uses only 'handlerToUse' if != NULL)
271 wxObject
*CreateResFromNode(wxXmlNode
*node
, wxObject
*parent
,
272 wxObject
*instance
= NULL
,
273 wxXmlResourceHandler
*handlerToUse
= NULL
);
275 // Helper of Load() and Unload(): returns the URL corresponding to the
276 // given file if it's indeed a file, otherwise returns the original string
278 static wxString
ConvertFileNameToURL(const wxString
& filename
);
280 // loading resources from archives is impossible without wxFileSystem
282 // Another helper: detect if the filename is a ZIP or XRS file
283 static bool IsArchive(const wxString
& filename
);
284 #endif // wxUSE_FILESYSTEM
291 wxXmlResourceDataRecords m_data
;
293 wxFileSystem m_curFileSystem
;
294 wxFileSystem
& GetCurFileSystem() { return m_curFileSystem
; }
297 // domain to pass to translation functions, if any.
300 friend class wxXmlResourceHandler
;
301 friend class wxXmlResourceModule
;
303 static wxXmlSubclassFactoriesList
*ms_subclassFactories
;
305 // singleton instance:
306 static wxXmlResource
*ms_instance
;
310 // This macro translates string identifier (as used in XML resource,
311 // e.g. <menuitem id="my_menu">...</menuitem>) to integer id that is needed by
312 // wxWidgets event tables.
314 // BEGIN_EVENT_TABLE(MyFrame, wxFrame)
315 // EVT_MENU(XRCID("quit"), MyFrame::OnQuit)
316 // EVT_MENU(XRCID("about"), MyFrame::OnAbout)
317 // EVT_MENU(XRCID("new"), MyFrame::OnNew)
318 // EVT_MENU(XRCID("open"), MyFrame::OnOpen)
321 #define XRCID(str_id) \
322 wxXmlResource::GetXRCID(wxT(str_id))
325 // This macro returns pointer to particular control in dialog
326 // created using XML resources. You can use it to set/get values from
330 // wxXmlResource::Get()->LoadDialog(&dlg, mainFrame, "my_dialog");
331 // XRCCTRL(dlg, "my_textctrl", wxTextCtrl)->SetValue(wxT("default value"));
333 #define XRCCTRL(window, id, type) \
334 (wxStaticCast((window).FindWindow(XRCID(id)), type))
336 // wxXmlResourceHandler is an abstract base class for resource handlers
337 // capable of creating a control from an XML node.
339 class WXDLLIMPEXP_XRC wxXmlResourceHandler
: public wxObject
341 DECLARE_ABSTRACT_CLASS(wxXmlResourceHandler
)
344 wxXmlResourceHandler();
347 virtual ~wxXmlResourceHandler() {}
349 // Creates an object (menu, dialog, control, ...) from an XML node.
350 // Should check for validity.
351 // parent is a higher-level object (usually window, dialog or panel)
352 // that is often necessary to create the resource.
353 // If instance is non-NULL it should not create a new instance via 'new' but
354 // should rather use this one, and call its Create method.
355 wxObject
*CreateResource(wxXmlNode
*node
, wxObject
*parent
,
358 // This one is called from CreateResource after variables
360 virtual wxObject
*DoCreateResource() = 0;
362 // Returns true if it understands this node and can create
363 // a resource from it, false otherwise.
364 virtual bool CanHandle(wxXmlNode
*node
) = 0;
366 // Sets the parent resource.
367 void SetParentResource(wxXmlResource
*res
) { m_resource
= res
; }
370 wxXmlResource
*m_resource
;
371 wxArrayString m_styleNames
;
372 wxArrayInt m_styleValues
;
374 // Variables (filled by CreateResource)
377 wxObject
*m_parent
, *m_instance
;
378 wxWindow
*m_parentAsWindow
;
380 // --- Handy methods:
382 // Returns true if the node has a property class equal to classname,
383 // e.g. <object class="wxDialog">.
384 bool IsOfClass(wxXmlNode
*node
, const wxString
& classname
);
386 // Gets node content from wxXML_ENTITY_NODE
387 // The problem is, <tag>content<tag> is represented as
388 // wxXML_ENTITY_NODE name="tag", content=""
389 // |-- wxXML_TEXT_NODE or
390 // wxXML_CDATA_SECTION_NODE name="" content="content"
391 wxString
GetNodeContent(wxXmlNode
*node
);
393 // Check to see if a parameter exists.
394 bool HasParam(const wxString
& param
);
396 // Finds the node or returns NULL.
397 wxXmlNode
*GetParamNode(const wxString
& param
);
399 // Finds the parameter value or returns the empty string.
400 wxString
GetParamValue(const wxString
& param
);
402 // Add a style flag (e.g. wxMB_DOCKABLE) to the list of flags
403 // understood by this handler.
404 void AddStyle(const wxString
& name
, int value
);
406 // Add styles common to all wxWindow-derived classes.
407 void AddWindowStyles();
409 // Gets style flags from text in form "flag | flag2| flag3 |..."
410 // Only understands flags added with AddStyle
411 int GetStyle(const wxString
& param
= wxT("style"), int defaults
= 0);
413 // Gets text from param and does some conversions:
414 // - replaces \n, \r, \t by respective chars (according to C syntax)
415 // - replaces _ by & and __ by _ (needed for _File => &File because of XML)
416 // - calls wxGetTranslations (unless disabled in wxXmlResource)
417 wxString
GetText(const wxString
& param
, bool translate
= true);
419 // Returns the XRCID.
422 // Returns the resource name.
425 // Gets a bool flag (1, t, yes, on, true are true, everything else is false).
426 bool GetBool(const wxString
& param
, bool defaultv
= false);
428 // Gets an integer value from the parameter.
429 long GetLong(const wxString
& param
, long defaultv
= 0);
431 // Gets a float value from the parameter.
432 float GetFloat(const wxString
& param
, float defaultv
= 0);
434 // Gets colour in HTML syntax (#RRGGBB).
435 wxColour
GetColour(const wxString
& param
, const wxColour
& defaultv
= wxNullColour
);
437 // Gets the size (may be in dialog units).
438 wxSize
GetSize(const wxString
& param
= wxT("size"),
439 wxWindow
*windowToUse
= NULL
);
441 // Gets the position (may be in dialog units).
442 wxPoint
GetPosition(const wxString
& param
= wxT("pos"));
444 // Gets a dimension (may be in dialog units).
445 wxCoord
GetDimension(const wxString
& param
, wxCoord defaultv
= 0,
446 wxWindow
*windowToUse
= NULL
);
449 wxBitmap
GetBitmap(const wxString
& param
= wxT("bitmap"),
450 const wxArtClient
& defaultArtClient
= wxART_OTHER
,
451 wxSize size
= wxDefaultSize
);
454 wxIcon
GetIcon(const wxString
& param
= wxT("icon"),
455 const wxArtClient
& defaultArtClient
= wxART_OTHER
,
456 wxSize size
= wxDefaultSize
);
458 #if wxUSE_ANIMATIONCTRL
459 // Gets an animation.
460 wxAnimation
GetAnimation(const wxString
& param
= wxT("animation"));
464 wxFont
GetFont(const wxString
& param
= wxT("font"));
466 // Sets common window options.
467 void SetupWindow(wxWindow
*wnd
);
470 void CreateChildren(wxObject
*parent
, bool this_hnd_only
= false);
473 void CreateChildrenPrivately(wxObject
*parent
, wxXmlNode
*rootnode
= NULL
);
475 // Creates a resource from a node.
476 wxObject
*CreateResFromNode(wxXmlNode
*node
,
477 wxObject
*parent
, wxObject
*instance
= NULL
)
478 { return m_resource
->CreateResFromNode(node
, parent
, instance
); }
482 wxFileSystem
& GetCurFileSystem() { return m_resource
->GetCurFileSystem(); }
487 // Programmer-friendly macros for writing XRC handlers:
489 #define XRC_ADD_STYLE(style) AddStyle(wxT(#style), style)
491 #define XRC_MAKE_INSTANCE(variable, classname) \
492 classname *variable = NULL; \
494 variable = wxStaticCast(m_instance, classname); \
496 variable = new classname;
499 // FIXME -- remove this $%^#$%#$@# as soon as Ron checks his changes in!!
500 WXDLLIMPEXP_XRC
void wxXmlInitResourceModule();
503 // This class is used to create instances of XRC "object" nodes with "subclass"
504 // property. It is _not_ supposed to be used by XRC users, you should instead
505 // register your subclasses via wxWidgets' RTTI mechanism. This class is useful
506 // only for language bindings developer who need a way to implement subclassing
507 // in wxWidgets ports that don't support wxRTTI (e.g. wxPython).
508 class WXDLLIMPEXP_XRC wxXmlSubclassFactory
511 // Try to create instance of given class and return it, return NULL on
513 virtual wxObject
*Create(const wxString
& className
) = 0;
514 virtual ~wxXmlSubclassFactory() {}
518 /* -------------------------------------------------------------------------
519 Backward compatibility macros. Do *NOT* use, they may disappear in future
520 versions of the XRC library!
521 ------------------------------------------------------------------------- */
525 #endif // _WX_XMLRES_H_