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"
30 #include "wx/vector.h"
32 #include "wx/xml/xml.h"
34 class WXDLLIMPEXP_FWD_BASE wxFileName
;
36 class WXDLLIMPEXP_FWD_CORE wxMenu
;
37 class WXDLLIMPEXP_FWD_CORE wxMenuBar
;
38 class WXDLLIMPEXP_FWD_CORE wxDialog
;
39 class WXDLLIMPEXP_FWD_CORE wxPanel
;
40 class WXDLLIMPEXP_FWD_CORE wxWindow
;
41 class WXDLLIMPEXP_FWD_CORE wxFrame
;
42 class WXDLLIMPEXP_FWD_CORE wxToolBar
;
44 class WXDLLIMPEXP_FWD_XRC wxXmlResourceHandler
;
45 class WXDLLIMPEXP_FWD_XRC wxXmlSubclassFactory
;
46 class wxXmlSubclassFactories
;
47 class wxXmlResourceModule
;
48 class wxXmlResourceDataRecords
;
50 // These macros indicate current version of XML resources (this information is
51 // encoded in root node of XRC file as "version" property).
53 // Rules for increasing version number:
54 // - change it only if you made incompatible change to the format. Addition
55 // of new attribute to control handler is _not_ incompatible change, because
56 // older versions of the library may ignore it.
57 // - if you change version number, follow these steps:
58 // - set major, minor and release numbers to respective version numbers of
59 // the wxWidgets library (see wx/version.h)
60 // - reset revision to 0 unless the first three are same as before,
61 // in which case you should increase revision by one
62 #define WX_XMLRES_CURRENT_VERSION_MAJOR 2
63 #define WX_XMLRES_CURRENT_VERSION_MINOR 5
64 #define WX_XMLRES_CURRENT_VERSION_RELEASE 3
65 #define WX_XMLRES_CURRENT_VERSION_REVISION 0
66 #define WX_XMLRES_CURRENT_VERSION_STRING _T("2.5.3.0")
68 #define WX_XMLRES_CURRENT_VERSION \
69 (WX_XMLRES_CURRENT_VERSION_MAJOR * 256*256*256 + \
70 WX_XMLRES_CURRENT_VERSION_MINOR * 256*256 + \
71 WX_XMLRES_CURRENT_VERSION_RELEASE * 256 + \
72 WX_XMLRES_CURRENT_VERSION_REVISION)
74 enum wxXmlResourceFlags
77 wxXRC_NO_SUBCLASSING
= 2,
78 wxXRC_NO_RELOADING
= 4
81 // This class holds XML resources from one or more .xml files
82 // (or derived forms, either binary or zipped -- see manual for
84 class WXDLLIMPEXP_XRC wxXmlResource
: public wxObject
88 // Flags: wxXRC_USE_LOCALE
89 // translatable strings will be translated via _()
90 // using the given domain if specified
91 // wxXRC_NO_SUBCLASSING
92 // subclass property of object nodes will be ignored
93 // (useful for previews in XRC editors)
95 // don't check the modification time of the XRC files and
96 // reload them if they have changed on disk
97 wxXmlResource(int flags
= wxXRC_USE_LOCALE
,
98 const wxString
& domain
= wxEmptyString
);
101 // Flags: wxXRC_USE_LOCALE
102 // translatable strings will be translated via _()
103 // using the given domain if specified
104 // wxXRC_NO_SUBCLASSING
105 // subclass property of object nodes will be ignored
106 // (useful for previews in XRC editors)
107 wxXmlResource(const wxString
& filemask
, int flags
= wxXRC_USE_LOCALE
,
108 const wxString
& domain
= wxEmptyString
);
111 virtual ~wxXmlResource();
113 // Loads resources from XML files that match given filemask.
114 // This method understands wxFileSystem URLs if wxUSE_FILESYS.
115 bool Load(const wxString
& filemask
);
117 // Loads resources from single XRC file.
118 bool LoadFile(const wxFileName
& file
);
120 // Loads all XRC files from a directory.
121 bool LoadAllFiles(const wxString
& dirname
);
123 // Unload resource from the given XML file (wildcards not allowed)
124 bool Unload(const wxString
& filename
);
126 // Initialize handlers for all supported controls/windows. This will
127 // make the executable quite big because it forces linking against
128 // most of the wxWidgets library.
129 void InitAllHandlers();
131 // Initialize only a specific handler (or custom handler). Convention says
132 // that handler name is equal to the control's name plus 'XmlHandler', for
133 // example wxTextCtrlXmlHandler, wxHtmlWindowXmlHandler. The XML resource
134 // compiler (xmlres) can create include file that contains initialization
135 // code for all controls used within the resource.
136 void AddHandler(wxXmlResourceHandler
*handler
);
138 // Add a new handler at the begining of the handler list
139 void InsertHandler(wxXmlResourceHandler
*handler
);
141 // Removes all handlers
142 void ClearHandlers();
144 // Registers subclasses factory for use in XRC. This function is not meant
145 // for public use, please see the comment above wxXmlSubclassFactory
147 static void AddSubclassFactory(wxXmlSubclassFactory
*factory
);
149 // Loads menu from resource. Returns NULL on failure.
150 wxMenu
*LoadMenu(const wxString
& name
);
152 // Loads menubar from resource. Returns NULL on failure.
153 wxMenuBar
*LoadMenuBar(wxWindow
*parent
, const wxString
& name
);
155 // Loads menubar from resource. Returns NULL on failure.
156 wxMenuBar
*LoadMenuBar(const wxString
& name
) { return LoadMenuBar(NULL
, name
); }
160 wxToolBar
*LoadToolBar(wxWindow
*parent
, const wxString
& name
);
163 // Loads a dialog. dlg points to parent window (if any).
164 wxDialog
*LoadDialog(wxWindow
*parent
, const wxString
& name
);
166 // Loads a dialog. dlg points to parent window (if any). This form
167 // is used to finish creation of already existing instance (main reason
168 // for this is that you may want to use derived class with new event table)
169 // Example (typical usage):
171 // wxTheXmlResource->LoadDialog(&dlg, mainFrame, "my_dialog");
173 bool LoadDialog(wxDialog
*dlg
, wxWindow
*parent
, const wxString
& name
);
175 // Loads a panel. panel points to parent window (if any).
176 wxPanel
*LoadPanel(wxWindow
*parent
, const wxString
& name
);
178 // Loads a panel. panel points to parent window (if any). This form
179 // is used to finish creation of already existing instance.
180 bool LoadPanel(wxPanel
*panel
, wxWindow
*parent
, const wxString
& name
);
183 wxFrame
*LoadFrame(wxWindow
* parent
, const wxString
& name
);
184 bool LoadFrame(wxFrame
* frame
, wxWindow
*parent
, const wxString
& name
);
186 // Load an object from the resource specifying both the resource name and
187 // the classname. This lets you load nonstandard container windows.
188 wxObject
*LoadObject(wxWindow
*parent
, const wxString
& name
,
189 const wxString
& classname
);
191 // Load an object from the resource specifying both the resource name and
192 // the classname. This form lets you finish the creation of an existing
194 bool LoadObject(wxObject
*instance
, wxWindow
*parent
, const wxString
& name
,
195 const wxString
& classname
);
197 // Loads a bitmap resource from a file.
198 wxBitmap
LoadBitmap(const wxString
& name
);
200 // Loads an icon resource from a file.
201 wxIcon
LoadIcon(const wxString
& name
);
203 // Attaches an unknown control to the given panel/window/dialog.
204 // Unknown controls are used in conjunction with <object class="unknown">.
205 bool AttachUnknownControl(const wxString
& name
, wxWindow
*control
,
206 wxWindow
*parent
= NULL
);
208 // Returns a numeric ID that is equivalent to the string ID used in an XML
209 // resource. If an unknown str_id is requested (i.e. other than wxID_XXX
210 // or integer), a new record is created which associates the given string
211 // with a number. If value_if_not_found == wxID_NONE, the number is obtained via
212 // wxWindow::NewControlId(). Otherwise value_if_not_found is used.
213 // Macro XRCID(name) is provided for convenient use in event tables.
214 static int GetXRCID(const wxString
& str_id
, int value_if_not_found
= wxID_NONE
)
215 { return DoGetXRCID(str_id
.mb_str(), value_if_not_found
); }
217 // version for internal use only
218 static int DoGetXRCID(const char *str_id
, int value_if_not_found
= wxID_NONE
);
221 // Find the string ID with the given numeric value, returns an empty string
222 // if no such ID is found.
224 // Notice that unlike GetXRCID(), which is fast, this operation is slow as
225 // it checks all the IDs used in XRC.
226 static wxString
FindXRCIDById(int numId
);
229 // Returns version information (a.b.c.d = d+ 256*c + 256^2*b + 256^3*a).
230 long GetVersion() const { return m_version
; }
232 // Compares resources version to argument. Returns -1 if resources version
233 // is less than the argument, +1 if greater and 0 if they equal.
234 int CompareVersion(int major
, int minor
, int release
, int revision
) const
235 { return GetVersion() -
236 (major
*256*256*256 + minor
*256*256 + release
*256 + revision
); }
238 //// Singleton accessors.
240 // Gets the global resources object or creates one if none exists.
241 static wxXmlResource
*Get();
243 // Sets the global resources object and returns a pointer to the previous one (may be NULL).
244 static wxXmlResource
*Set(wxXmlResource
*res
);
246 // Returns flags, which may be a bitlist of wxXRC_USE_LOCALE and wxXRC_NO_SUBCLASSING.
247 int GetFlags() const { return m_flags
; }
248 // Set flags after construction.
249 void SetFlags(int flags
) { m_flags
= flags
; }
251 // Get/Set the domain to be passed to the translation functions, defaults
252 // to empty string (no domain).
253 const wxString
& GetDomain() const { return m_domain
; }
254 void SetDomain(const wxString
& domain
);
257 // This function returns the wxXmlNode containing the definition of the
258 // object with the given name or NULL.
260 // It can be used to access additional information defined in the XRC file
261 // and not used by wxXmlResource itself.
262 const wxXmlNode
*GetResourceNode(const wxString
& name
) const
263 { return GetResourceNodeAndLocation(name
, wxString(), true); }
266 // reports input error at position 'context'
267 void ReportError(wxXmlNode
*context
, const wxString
& message
);
269 // override this in derived class to customize errors reporting
270 virtual void DoReportError(const wxString
& xrcFile
, wxXmlNode
*position
,
271 const wxString
& message
);
273 // Scans the resources list for unloaded files and loads them. Also reloads
274 // files that have been modified since last loading.
275 bool UpdateResources();
278 // Common implementation of GetResourceNode() and FindResource(): searches
279 // all top-level or all (if recursive == true) nodes if all loaded XRC
280 // files and returns the node, if found, as well as the path of the file it
281 // was found in if path is non-NULL
282 wxXmlNode
*GetResourceNodeAndLocation(const wxString
& name
,
283 const wxString
& classname
,
284 bool recursive
= false,
285 wxString
*path
= NULL
) const;
288 // Note that these functions are used outside of wxWidgets itself, e.g.
289 // there are several known cases of inheriting from wxXmlResource just to
290 // be able to call FindResource() so we keep them for compatibility even if
291 // their names are not really consistent with GetResourceNode() public
292 // function and FindResource() is also non-const because it changes the
293 // current path of m_curFileSystem to ensure that relative paths work
294 // correctly when CreateResFromNode() is called immediately afterwards
295 // (something const public function intentionally does not do)
297 // Returns the node containing the resource with the given name and class
298 // name unless it's empty (then any class matches) or NULL if not found.
299 wxXmlNode
*FindResource(const wxString
& name
, const wxString
& classname
,
300 bool recursive
= false);
302 // Helper function used by FindResource() to look under the given node.
303 wxXmlNode
*DoFindResource(wxXmlNode
*parent
, const wxString
& name
,
304 const wxString
& classname
, bool recursive
) const;
306 // Creates a resource from information in the given node
307 // (Uses only 'handlerToUse' if != NULL)
308 wxObject
*CreateResFromNode(wxXmlNode
*node
, wxObject
*parent
,
309 wxObject
*instance
= NULL
,
310 wxXmlResourceHandler
*handlerToUse
= NULL
);
312 // Helper of Load() and Unload(): returns the URL corresponding to the
313 // given file if it's indeed a file, otherwise returns the original string
315 static wxString
ConvertFileNameToURL(const wxString
& filename
);
317 // loading resources from archives is impossible without wxFileSystem
319 // Another helper: detect if the filename is a ZIP or XRS file
320 static bool IsArchive(const wxString
& filename
);
321 #endif // wxUSE_FILESYSTEM
324 wxXmlResourceDataRecords
& Data() { return *m_data
; }
325 const wxXmlResourceDataRecords
& Data() const { return *m_data
; }
331 wxVector
<wxXmlResourceHandler
*> m_handlers
;
332 wxXmlResourceDataRecords
*m_data
;
334 wxFileSystem m_curFileSystem
;
335 wxFileSystem
& GetCurFileSystem() { return m_curFileSystem
; }
338 // domain to pass to translation functions, if any.
341 friend class wxXmlResourceHandler
;
342 friend class wxXmlResourceModule
;
344 static wxXmlSubclassFactories
*ms_subclassFactories
;
346 // singleton instance:
347 static wxXmlResource
*ms_instance
;
351 // This macro translates string identifier (as used in XML resource,
352 // e.g. <menuitem id="my_menu">...</menuitem>) to integer id that is needed by
353 // wxWidgets event tables.
355 // BEGIN_EVENT_TABLE(MyFrame, wxFrame)
356 // EVT_MENU(XRCID("quit"), MyFrame::OnQuit)
357 // EVT_MENU(XRCID("about"), MyFrame::OnAbout)
358 // EVT_MENU(XRCID("new"), MyFrame::OnNew)
359 // EVT_MENU(XRCID("open"), MyFrame::OnOpen)
362 #define XRCID(str_id) \
363 wxXmlResource::DoGetXRCID(str_id)
366 // This macro returns pointer to particular control in dialog
367 // created using XML resources. You can use it to set/get values from
371 // wxXmlResource::Get()->LoadDialog(&dlg, mainFrame, "my_dialog");
372 // XRCCTRL(dlg, "my_textctrl", wxTextCtrl)->SetValue(wxT("default value"));
374 #define XRCCTRL(window, id, type) \
375 (wxStaticCast((window).FindWindow(XRCID(id)), type))
377 // This macro returns pointer to sizer item
380 // <object class="spacer" name="area">
381 // <size>400, 300</size>
384 // wxSizerItem* item = XRCSIZERITEM(*this, "area")
386 #define XRCSIZERITEM(window, id) \
387 ((window).GetSizer() ? (window).GetSizer()->GetItemById(XRCID(id)) : NULL)
389 // wxXmlResourceHandler is an abstract base class for resource handlers
390 // capable of creating a control from an XML node.
392 class WXDLLIMPEXP_XRC wxXmlResourceHandler
: public wxObject
394 DECLARE_ABSTRACT_CLASS(wxXmlResourceHandler
)
397 wxXmlResourceHandler();
400 virtual ~wxXmlResourceHandler() {}
402 // Creates an object (menu, dialog, control, ...) from an XML node.
403 // Should check for validity.
404 // parent is a higher-level object (usually window, dialog or panel)
405 // that is often necessary to create the resource.
406 // If instance is non-NULL it should not create a new instance via 'new' but
407 // should rather use this one, and call its Create method.
408 wxObject
*CreateResource(wxXmlNode
*node
, wxObject
*parent
,
411 // This one is called from CreateResource after variables
413 virtual wxObject
*DoCreateResource() = 0;
415 // Returns true if it understands this node and can create
416 // a resource from it, false otherwise.
417 virtual bool CanHandle(wxXmlNode
*node
) = 0;
419 // Sets the parent resource.
420 void SetParentResource(wxXmlResource
*res
) { m_resource
= res
; }
423 wxXmlResource
*m_resource
;
424 wxArrayString m_styleNames
;
425 wxArrayInt m_styleValues
;
427 // Variables (filled by CreateResource)
430 wxObject
*m_parent
, *m_instance
;
431 wxWindow
*m_parentAsWindow
;
433 // --- Handy methods:
435 // Returns true if the node has a property class equal to classname,
436 // e.g. <object class="wxDialog">.
437 bool IsOfClass(wxXmlNode
*node
, const wxString
& classname
);
439 // Gets node content from wxXML_ENTITY_NODE
440 // The problem is, <tag>content<tag> is represented as
441 // wxXML_ENTITY_NODE name="tag", content=""
442 // |-- wxXML_TEXT_NODE or
443 // wxXML_CDATA_SECTION_NODE name="" content="content"
444 wxString
GetNodeContent(wxXmlNode
*node
);
446 // Check to see if a parameter exists.
447 bool HasParam(const wxString
& param
);
449 // Finds the node or returns NULL.
450 wxXmlNode
*GetParamNode(const wxString
& param
);
452 // Finds the parameter value or returns the empty string.
453 wxString
GetParamValue(const wxString
& param
);
455 // Add a style flag (e.g. wxMB_DOCKABLE) to the list of flags
456 // understood by this handler.
457 void AddStyle(const wxString
& name
, int value
);
459 // Add styles common to all wxWindow-derived classes.
460 void AddWindowStyles();
462 // Gets style flags from text in form "flag | flag2| flag3 |..."
463 // Only understands flags added with AddStyle
464 int GetStyle(const wxString
& param
= wxT("style"), int defaults
= 0);
466 // Gets text from param and does some conversions:
467 // - replaces \n, \r, \t by respective chars (according to C syntax)
468 // - replaces _ by & and __ by _ (needed for _File => &File because of XML)
469 // - calls wxGetTranslations (unless disabled in wxXmlResource)
470 wxString
GetText(const wxString
& param
, bool translate
= true);
472 // Returns the XRCID.
475 // Returns the resource name.
478 // Gets a bool flag (1, t, yes, on, true are true, everything else is false).
479 bool GetBool(const wxString
& param
, bool defaultv
= false);
481 // Gets an integer value from the parameter.
482 long GetLong(const wxString
& param
, long defaultv
= 0);
484 // Gets a float value from the parameter.
485 float GetFloat(const wxString
& param
, float defaultv
= 0);
487 // Gets colour in HTML syntax (#RRGGBB).
488 wxColour
GetColour(const wxString
& param
, const wxColour
& defaultv
= wxNullColour
);
490 // Gets the size (may be in dialog units).
491 wxSize
GetSize(const wxString
& param
= wxT("size"),
492 wxWindow
*windowToUse
= NULL
);
494 // Gets the position (may be in dialog units).
495 wxPoint
GetPosition(const wxString
& param
= wxT("pos"));
497 // Gets a dimension (may be in dialog units).
498 wxCoord
GetDimension(const wxString
& param
, wxCoord defaultv
= 0,
499 wxWindow
*windowToUse
= NULL
);
502 wxBitmap
GetBitmap(const wxString
& param
= wxT("bitmap"),
503 const wxArtClient
& defaultArtClient
= wxART_OTHER
,
504 wxSize size
= wxDefaultSize
);
507 wxIcon
GetIcon(const wxString
& param
= wxT("icon"),
508 const wxArtClient
& defaultArtClient
= wxART_OTHER
,
509 wxSize size
= wxDefaultSize
);
511 #if wxUSE_ANIMATIONCTRL
512 // Gets an animation.
513 wxAnimation
GetAnimation(const wxString
& param
= wxT("animation"));
517 wxFont
GetFont(const wxString
& param
= wxT("font"));
519 // Gets the value of a boolean attribute (only "0" and "1" are valid values)
520 bool GetBoolAttr(const wxString
& attr
, bool defaultv
);
523 // Sets common window options.
524 void SetupWindow(wxWindow
*wnd
);
527 void CreateChildren(wxObject
*parent
, bool this_hnd_only
= false);
530 void CreateChildrenPrivately(wxObject
*parent
, wxXmlNode
*rootnode
= NULL
);
532 // Creates a resource from a node.
533 wxObject
*CreateResFromNode(wxXmlNode
*node
,
534 wxObject
*parent
, wxObject
*instance
= NULL
)
535 { return m_resource
->CreateResFromNode(node
, parent
, instance
); }
539 wxFileSystem
& GetCurFileSystem() { return m_resource
->GetCurFileSystem(); }
542 // reports input error at position 'context'
543 void ReportError(wxXmlNode
*context
, const wxString
& message
);
544 // reports input error at m_node
545 void ReportError(const wxString
& message
);
546 // reports input error when parsing parameter with given name
547 void ReportParamError(const wxString
& param
, const wxString
& message
);
551 // Programmer-friendly macros for writing XRC handlers:
553 #define XRC_ADD_STYLE(style) AddStyle(wxT(#style), style)
555 #define XRC_MAKE_INSTANCE(variable, classname) \
556 classname *variable = NULL; \
558 variable = wxStaticCast(m_instance, classname); \
560 variable = new classname;
563 // FIXME -- remove this $%^#$%#$@# as soon as Ron checks his changes in!!
564 WXDLLIMPEXP_XRC
void wxXmlInitResourceModule();
567 // This class is used to create instances of XRC "object" nodes with "subclass"
568 // property. It is _not_ supposed to be used by XRC users, you should instead
569 // register your subclasses via wxWidgets' RTTI mechanism. This class is useful
570 // only for language bindings developer who need a way to implement subclassing
571 // in wxWidgets ports that don't support wxRTTI (e.g. wxPython).
572 class WXDLLIMPEXP_XRC wxXmlSubclassFactory
575 // Try to create instance of given class and return it, return NULL on
577 virtual wxObject
*Create(const wxString
& className
) = 0;
578 virtual ~wxXmlSubclassFactory() {}
582 /* -------------------------------------------------------------------------
583 Backward compatibility macros. Do *NOT* use, they may disappear in future
584 versions of the XRC library!
585 ------------------------------------------------------------------------- */
589 #endif // _WX_XMLRES_H_