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"
22 #include "wx/gdicmn.h"
23 #include "wx/filesys.h"
24 #include "wx/bitmap.h"
26 #include "wx/artprov.h"
27 #include "wx/colour.h"
28 #include "wx/animate.h"
29 #include "wx/dynarray.h"
30 #include "wx/arrstr.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
) {
77 Time
= wxDateTime
::Now();
80 ~wxXmlResourceDataRecord() {delete Doc
;}
90 WX_DECLARE_USER_EXPORTED_OBJARRAY(wxXmlResourceDataRecord
,
91 wxXmlResourceDataRecords
,
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 // using the given domain if specified
111 // wxXRC_NO_SUBCLASSING
112 // subclass property of object nodes will be ignored
113 // (useful for previews in XRC editors)
114 // wxXRC_NO_RELOADING
115 // don't check the modification time of the XRC files and
116 // reload them if they have changed on disk
117 wxXmlResource(int flags
= wxXRC_USE_LOCALE
,
118 const wxString
& domain
= wxEmptyString
);
121 // Flags: wxXRC_USE_LOCALE
122 // translatable strings will be translated via _()
123 // using the given domain if specified
124 // wxXRC_NO_SUBCLASSING
125 // subclass property of object nodes will be ignored
126 // (useful for previews in XRC editors)
127 wxXmlResource(const wxString
& filemask
, int flags
= wxXRC_USE_LOCALE
,
128 const wxString
& domain
= wxEmptyString
);
131 virtual ~wxXmlResource();
133 wxXmlNode
*GetFirstRoot();
135 // Loads resources from XML files that match given filemask.
136 // This method understands VFS (see filesys.h).
137 bool Load(const wxString
& filemask
);
139 // Unload resource from the given XML file (wildcards not allowed)
140 bool Unload(const wxString
& filename
);
142 // Initialize handlers for all supported controls/windows. This will
143 // make the executable quite big because it forces linking against
144 // most of the wxWidgets library.
145 void InitAllHandlers();
147 // Initialize only a specific handler (or custom handler). Convention says
148 // that handler name is equal to the control's name plus 'XmlHandler', for
149 // example wxTextCtrlXmlHandler, wxHtmlWindowXmlHandler. The XML resource
150 // compiler (xmlres) can create include file that contains initialization
151 // code for all controls used within the resource.
152 void AddHandler(wxXmlResourceHandler
*handler
);
154 // Add a new handler at the begining of the handler list
155 void InsertHandler(wxXmlResourceHandler
*handler
);
157 // Removes all handlers
158 void ClearHandlers();
160 // Registers subclasses factory for use in XRC. This function is not meant
161 // for public use, please see the comment above wxXmlSubclassFactory
163 static void AddSubclassFactory(wxXmlSubclassFactory
*factory
);
165 // Loads menu from resource. Returns NULL on failure.
166 wxMenu
*LoadMenu(const wxString
& name
);
168 // Loads menubar from resource. Returns NULL on failure.
169 wxMenuBar
*LoadMenuBar(wxWindow
*parent
, const wxString
& name
);
171 // Loads menubar from resource. Returns NULL on failure.
172 wxMenuBar
*LoadMenuBar(const wxString
& name
) { return LoadMenuBar(NULL
, name
); }
176 wxToolBar
*LoadToolBar(wxWindow
*parent
, const wxString
& name
);
179 // Loads a dialog. dlg points to parent window (if any).
180 wxDialog
*LoadDialog(wxWindow
*parent
, const wxString
& name
);
182 // Loads a dialog. dlg points to parent window (if any). This form
183 // is used to finish creation of already existing instance (main reason
184 // for this is that you may want to use derived class with new event table)
185 // Example (typical usage):
187 // wxTheXmlResource->LoadDialog(&dlg, mainFrame, "my_dialog");
189 bool LoadDialog(wxDialog
*dlg
, wxWindow
*parent
, const wxString
& name
);
191 // Loads a panel. panel points to parent window (if any).
192 wxPanel
*LoadPanel(wxWindow
*parent
, const wxString
& name
);
194 // Loads a panel. panel points to parent window (if any). This form
195 // is used to finish creation of already existing instance.
196 bool LoadPanel(wxPanel
*panel
, wxWindow
*parent
, const wxString
& name
);
199 wxFrame
*LoadFrame(wxWindow
* parent
, const wxString
& name
);
200 bool LoadFrame(wxFrame
* frame
, wxWindow
*parent
, const wxString
& name
);
202 // Load an object from the resource specifying both the resource name and
203 // the classname. This lets you load nonstandard container windows.
204 wxObject
*LoadObject(wxWindow
*parent
, const wxString
& name
,
205 const wxString
& classname
);
207 // Load an object from the resource specifying both the resource name and
208 // the classname. This form lets you finish the creation of an existing
210 bool LoadObject(wxObject
*instance
, wxWindow
*parent
, const wxString
& name
,
211 const wxString
& classname
);
213 // Loads a bitmap resource from a file.
214 wxBitmap
LoadBitmap(const wxString
& name
);
216 // Loads an icon resource from a file.
217 wxIcon
LoadIcon(const wxString
& name
);
219 // Attaches an unknown control to the given panel/window/dialog.
220 // Unknown controls are used in conjunction with <object class="unknown">.
221 bool AttachUnknownControl(const wxString
& name
, wxWindow
*control
,
222 wxWindow
*parent
= NULL
);
224 // Returns a numeric ID that is equivalent to the string ID used in an XML
225 // resource. If an unknown str_id is requested (i.e. other than wxID_XXX
226 // or integer), a new record is created which associates the given string
227 // with a number. If value_if_not_found == wxID_NONE, the number is obtained via
228 // wxWindow::NewControlId(). Otherwise value_if_not_found is used.
229 // Macro XRCID(name) is provided for convenient use in event tables.
230 static int GetXRCID(const wxChar
*str_id
, int value_if_not_found
= wxID_NONE
);
232 // Returns version information (a.b.c.d = d+ 256*c + 256^2*b + 256^3*a).
233 long GetVersion() const { return m_version
; }
235 // Compares resources version to argument. Returns -1 if resources version
236 // is less than the argument, +1 if greater and 0 if they equal.
237 int CompareVersion(int major
, int minor
, int release
, int revision
) const
238 { return GetVersion() -
239 (major
*256*256*256 + minor
*256*256 + release
*256 + revision
); }
241 //// Singleton accessors.
243 // Gets the global resources object or creates one if none exists.
244 static wxXmlResource
*Get();
246 // Sets the global resources object and returns a pointer to the previous one (may be NULL).
247 static wxXmlResource
*Set(wxXmlResource
*res
);
249 // Returns flags, which may be a bitlist of wxXRC_USE_LOCALE and wxXRC_NO_SUBCLASSING.
250 int GetFlags() const { return m_flags
; }
251 // Set flags after construction.
252 void SetFlags(int flags
) { m_flags
= flags
; }
254 // Get/Set the domain to be passed to the translation functions, defaults
255 // to empty string (no domain).
256 const wxString
& GetDomain() const { return m_domain
; }
257 void SetDomain(const wxString
& domain
);
260 // Scans the resources list for unloaded files and loads them. Also reloads
261 // files that have been modified since last loading.
262 bool UpdateResources();
264 // Finds a resource (calls UpdateResources) and returns a node containing it.
265 wxXmlNode
*FindResource(const wxString
& name
, const wxString
& classname
, bool recursive
= false);
267 // Helper function: finds a resource (calls UpdateResources) and returns a node containing it.
268 wxXmlNode
*DoFindResource(wxXmlNode
*parent
, const wxString
& name
, const wxString
& classname
, bool recursive
);
270 // Creates a resource from information in the given node
271 // (Uses only 'handlerToUse' if != NULL)
272 wxObject
*CreateResFromNode(wxXmlNode
*node
, wxObject
*parent
,
273 wxObject
*instance
= NULL
,
274 wxXmlResourceHandler
*handlerToUse
= NULL
);
276 // Helper of Load() and Unload(): returns the URL corresponding to the
277 // given file if it's indeed a file, otherwise returns the original string
279 static wxString
ConvertFileNameToURL(const wxString
& filename
);
281 // loading resources from archives is impossible without wxFileSystem
283 // Another helper: detect if the filename is a ZIP or XRS file
284 static bool IsArchive(const wxString
& filename
);
285 #endif // wxUSE_FILESYSTEM
292 wxXmlResourceDataRecords m_data
;
294 wxFileSystem m_curFileSystem
;
295 wxFileSystem
& GetCurFileSystem() { return m_curFileSystem
; }
298 // domain to pass to translation functions, if any.
301 friend class wxXmlResourceHandler
;
302 friend class wxXmlResourceModule
;
304 static wxXmlSubclassFactoriesList
*ms_subclassFactories
;
306 // singleton instance:
307 static wxXmlResource
*ms_instance
;
311 // This macro translates string identifier (as used in XML resource,
312 // e.g. <menuitem id="my_menu">...</menuitem>) to integer id that is needed by
313 // wxWidgets event tables.
315 // BEGIN_EVENT_TABLE(MyFrame, wxFrame)
316 // EVT_MENU(XRCID("quit"), MyFrame::OnQuit)
317 // EVT_MENU(XRCID("about"), MyFrame::OnAbout)
318 // EVT_MENU(XRCID("new"), MyFrame::OnNew)
319 // EVT_MENU(XRCID("open"), MyFrame::OnOpen)
322 #define XRCID(str_id) \
323 wxXmlResource::GetXRCID(wxT(str_id))
326 // This macro returns pointer to particular control in dialog
327 // created using XML resources. You can use it to set/get values from
331 // wxXmlResource::Get()->LoadDialog(&dlg, mainFrame, "my_dialog");
332 // XRCCTRL(dlg, "my_textctrl", wxTextCtrl)->SetValue(wxT("default value"));
334 #define XRCCTRL(window, id, type) \
335 (wxStaticCast((window).FindWindow(XRCID(id)), type))
337 // wxXmlResourceHandler is an abstract base class for resource handlers
338 // capable of creating a control from an XML node.
340 class WXDLLIMPEXP_XRC wxXmlResourceHandler
: public wxObject
342 DECLARE_ABSTRACT_CLASS(wxXmlResourceHandler
)
345 wxXmlResourceHandler();
348 virtual ~wxXmlResourceHandler() {}
350 // Creates an object (menu, dialog, control, ...) from an XML node.
351 // Should check for validity.
352 // parent is a higher-level object (usually window, dialog or panel)
353 // that is often necessary to create the resource.
354 // If instance is non-NULL it should not create a new instance via 'new' but
355 // should rather use this one, and call its Create method.
356 wxObject
*CreateResource(wxXmlNode
*node
, wxObject
*parent
,
359 // This one is called from CreateResource after variables
361 virtual wxObject
*DoCreateResource() = 0;
363 // Returns true if it understands this node and can create
364 // a resource from it, false otherwise.
365 virtual bool CanHandle(wxXmlNode
*node
) = 0;
367 // Sets the parent resource.
368 void SetParentResource(wxXmlResource
*res
) { m_resource
= res
; }
371 wxXmlResource
*m_resource
;
372 wxArrayString m_styleNames
;
373 wxArrayInt m_styleValues
;
375 // Variables (filled by CreateResource)
378 wxObject
*m_parent
, *m_instance
;
379 wxWindow
*m_parentAsWindow
;
381 // --- Handy methods:
383 // Returns true if the node has a property class equal to classname,
384 // e.g. <object class="wxDialog">.
385 bool IsOfClass(wxXmlNode
*node
, const wxString
& classname
);
387 // Gets node content from wxXML_ENTITY_NODE
388 // The problem is, <tag>content<tag> is represented as
389 // wxXML_ENTITY_NODE name="tag", content=""
390 // |-- wxXML_TEXT_NODE or
391 // wxXML_CDATA_SECTION_NODE name="" content="content"
392 wxString
GetNodeContent(wxXmlNode
*node
);
394 // Check to see if a parameter exists.
395 bool HasParam(const wxString
& param
);
397 // Finds the node or returns NULL.
398 wxXmlNode
*GetParamNode(const wxString
& param
);
400 // Finds the parameter value or returns the empty string.
401 wxString
GetParamValue(const wxString
& param
);
403 // Add a style flag (e.g. wxMB_DOCKABLE) to the list of flags
404 // understood by this handler.
405 void AddStyle(const wxString
& name
, int value
);
407 // Add styles common to all wxWindow-derived classes.
408 void AddWindowStyles();
410 // Gets style flags from text in form "flag | flag2| flag3 |..."
411 // Only understands flags added with AddStyle
412 int GetStyle(const wxString
& param
= wxT("style"), int defaults
= 0);
414 // Gets text from param and does some conversions:
415 // - replaces \n, \r, \t by respective chars (according to C syntax)
416 // - replaces _ by & and __ by _ (needed for _File => &File because of XML)
417 // - calls wxGetTranslations (unless disabled in wxXmlResource)
418 wxString
GetText(const wxString
& param
, bool translate
= true);
420 // Returns the XRCID.
423 // Returns the resource name.
426 // Gets a bool flag (1, t, yes, on, true are true, everything else is false).
427 bool GetBool(const wxString
& param
, bool defaultv
= false);
429 // Gets an integer value from the parameter.
430 long GetLong(const wxString
& param
, long defaultv
= 0);
432 // Gets a float value from the parameter.
433 float GetFloat(const wxString
& param
, float defaultv
= 0);
435 // Gets colour in HTML syntax (#RRGGBB).
436 wxColour
GetColour(const wxString
& param
, const wxColour
& defaultv
= wxNullColour
);
438 // Gets the size (may be in dialog units).
439 wxSize
GetSize(const wxString
& param
= wxT("size"),
440 wxWindow
*windowToUse
= NULL
);
442 // Gets the position (may be in dialog units).
443 wxPoint
GetPosition(const wxString
& param
= wxT("pos"));
445 // Gets a dimension (may be in dialog units).
446 wxCoord
GetDimension(const wxString
& param
, wxCoord defaultv
= 0,
447 wxWindow
*windowToUse
= NULL
);
450 wxBitmap
GetBitmap(const wxString
& param
= wxT("bitmap"),
451 const wxArtClient
& defaultArtClient
= wxART_OTHER
,
452 wxSize size
= wxDefaultSize
);
455 wxIcon
GetIcon(const wxString
& param
= wxT("icon"),
456 const wxArtClient
& defaultArtClient
= wxART_OTHER
,
457 wxSize size
= wxDefaultSize
);
459 #if wxUSE_ANIMATIONCTRL
460 // Gets an animation.
461 wxAnimation
GetAnimation(const wxString
& param
= wxT("animation"));
465 wxFont
GetFont(const wxString
& param
= wxT("font"));
467 // Sets common window options.
468 void SetupWindow(wxWindow
*wnd
);
471 void CreateChildren(wxObject
*parent
, bool this_hnd_only
= false);
474 void CreateChildrenPrivately(wxObject
*parent
, wxXmlNode
*rootnode
= NULL
);
476 // Creates a resource from a node.
477 wxObject
*CreateResFromNode(wxXmlNode
*node
,
478 wxObject
*parent
, wxObject
*instance
= NULL
)
479 { return m_resource
->CreateResFromNode(node
, parent
, instance
); }
483 wxFileSystem
& GetCurFileSystem() { return m_resource
->GetCurFileSystem(); }
488 // Programmer-friendly macros for writing XRC handlers:
490 #define XRC_ADD_STYLE(style) AddStyle(wxT(#style), style)
492 #define XRC_MAKE_INSTANCE(variable, classname) \
493 classname *variable = NULL; \
495 variable = wxStaticCast(m_instance, classname); \
497 variable = new classname;
500 // FIXME -- remove this $%^#$%#$@# as soon as Ron checks his changes in!!
501 WXDLLIMPEXP_XRC
void wxXmlInitResourceModule();
504 // This class is used to create instances of XRC "object" nodes with "subclass"
505 // property. It is _not_ supposed to be used by XRC users, you should instead
506 // register your subclasses via wxWidgets' RTTI mechanism. This class is useful
507 // only for language bindings developer who need a way to implement subclassing
508 // in wxWidgets ports that don't support wxRTTI (e.g. wxPython).
509 class WXDLLIMPEXP_XRC wxXmlSubclassFactory
512 // Try to create instance of given class and return it, return NULL on
514 virtual wxObject
*Create(const wxString
& className
) = 0;
515 virtual ~wxXmlSubclassFactory() {}
519 /* -------------------------------------------------------------------------
520 Backward compatibility macros. Do *NOT* use, they may disappear in future
521 versions of the XRC library!
522 ------------------------------------------------------------------------- */
526 #endif // _WX_XMLRES_H_