]> git.saurik.com Git - wxWidgets.git/blob - include/wx/xrc/xmlres.h
don't crash if (char*)c_str() is used twice in a row on the same string and both...
[wxWidgets.git] / include / wx / xrc / xmlres.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/xrc/xmlres.h
3 // Purpose: XML resources
4 // Author: Vaclav Slavik
5 // Created: 2000/03/05
6 // RCS-ID: $Id$
7 // Copyright: (c) 2000 Vaclav Slavik
8 // Licence: wxWindows licence
9 /////////////////////////////////////////////////////////////////////////////
10
11 #ifndef _WX_XMLRES_H_
12 #define _WX_XMLRES_H_
13
14 #include "wx/defs.h"
15
16 #if wxUSE_XRC
17
18 #include "wx/string.h"
19 #include "wx/dynarray.h"
20 #include "wx/datetime.h"
21 #include "wx/list.h"
22 #include "wx/gdicmn.h"
23 #include "wx/filesys.h"
24 #include "wx/bitmap.h"
25 #include "wx/icon.h"
26 #include "wx/artprov.h"
27 #include "wx/colour.h"
28 #include "wx/animate.h"
29
30 #include "wx/xml/xml.h"
31
32 class WXDLLEXPORT wxMenu;
33 class WXDLLEXPORT wxMenuBar;
34 class WXDLLEXPORT wxDialog;
35 class WXDLLEXPORT wxPanel;
36 class WXDLLEXPORT wxWindow;
37 class WXDLLEXPORT wxFrame;
38 class WXDLLEXPORT wxToolBar;
39
40 class WXDLLIMPEXP_XRC wxXmlResourceHandler;
41 class WXDLLIMPEXP_XRC wxXmlSubclassFactory;
42 class WXDLLIMPEXP_XRC wxXmlSubclassFactoriesList;
43 class wxXmlResourceModule;
44
45
46 // These macros indicate current version of XML resources (this information is
47 // encoded in root node of XRC file as "version" property).
48 //
49 // Rules for increasing version number:
50 // - change it only if you made incompatible change to the format. Addition
51 // of new attribute to control handler is _not_ incompatible change, because
52 // older versions of the library may ignore it.
53 // - if you change version number, follow these steps:
54 // - set major, minor and release numbers to respective version numbers of
55 // the wxWidgets library (see wx/version.h)
56 // - reset revision to 0 unless the first three are same as before,
57 // in which case you should increase revision by one
58 #define WX_XMLRES_CURRENT_VERSION_MAJOR 2
59 #define WX_XMLRES_CURRENT_VERSION_MINOR 5
60 #define WX_XMLRES_CURRENT_VERSION_RELEASE 3
61 #define WX_XMLRES_CURRENT_VERSION_REVISION 0
62 #define WX_XMLRES_CURRENT_VERSION_STRING _T("2.5.3.0")
63
64 #define WX_XMLRES_CURRENT_VERSION \
65 (WX_XMLRES_CURRENT_VERSION_MAJOR * 256*256*256 + \
66 WX_XMLRES_CURRENT_VERSION_MINOR * 256*256 + \
67 WX_XMLRES_CURRENT_VERSION_RELEASE * 256 + \
68 WX_XMLRES_CURRENT_VERSION_REVISION)
69
70 class WXDLLIMPEXP_XRC wxXmlResourceDataRecord
71 {
72 public:
73 wxXmlResourceDataRecord() : Doc(NULL) {
74 #if wxUSE_DATETIME
75 Time = wxDateTime::Now();
76 #endif
77 }
78 ~wxXmlResourceDataRecord() {delete Doc;}
79
80 wxString File;
81 wxXmlDocument *Doc;
82 #if wxUSE_DATETIME
83 wxDateTime Time;
84 #endif
85 };
86
87
88 WX_DECLARE_USER_EXPORTED_OBJARRAY(wxXmlResourceDataRecord,
89 wxXmlResourceDataRecords,
90 WXDLLIMPEXP_XRC);
91
92 enum wxXmlResourceFlags
93 {
94 wxXRC_USE_LOCALE = 1,
95 wxXRC_NO_SUBCLASSING = 2,
96 wxXRC_NO_RELOADING = 4
97 };
98
99 // This class holds XML resources from one or more .xml files
100 // (or derived forms, either binary or zipped -- see manual for
101 // details).
102 class WXDLLIMPEXP_XRC wxXmlResource : public wxObject
103 {
104 public:
105 // Constructor.
106 // Flags: wxXRC_USE_LOCALE
107 // translatable strings will be translated via _()
108 // using the given domain if specified
109 // wxXRC_NO_SUBCLASSING
110 // subclass property of object nodes will be ignored
111 // (useful for previews in XRC editors)
112 // wxXRC_NO_RELOADING
113 // don't check the modification time of the XRC files and
114 // reload them if they have changed on disk
115 wxXmlResource(int flags = wxXRC_USE_LOCALE,
116 const wxString& domain = wxEmptyString);
117
118 // Constructor.
119 // Flags: wxXRC_USE_LOCALE
120 // translatable strings will be translated via _()
121 // using the given domain if specified
122 // wxXRC_NO_SUBCLASSING
123 // subclass property of object nodes will be ignored
124 // (useful for previews in XRC editors)
125 wxXmlResource(const wxString& filemask, int flags = wxXRC_USE_LOCALE,
126 const wxString& domain = wxEmptyString);
127
128 // Destructor.
129 virtual ~wxXmlResource();
130
131 wxXmlNode *GetFirstRoot();
132
133 // Loads resources from XML files that match given filemask.
134 // This method understands VFS (see filesys.h).
135 bool Load(const wxString& filemask);
136
137 // Unload resource from the given XML file (wildcards not allowed)
138 bool Unload(const wxString& filename);
139
140 // Initialize handlers for all supported controls/windows. This will
141 // make the executable quite big because it forces linking against
142 // most of the wxWidgets library.
143 void InitAllHandlers();
144
145 // Initialize only a specific handler (or custom handler). Convention says
146 // that handler name is equal to the control's name plus 'XmlHandler', for
147 // example wxTextCtrlXmlHandler, wxHtmlWindowXmlHandler. The XML resource
148 // compiler (xmlres) can create include file that contains initialization
149 // code for all controls used within the resource.
150 void AddHandler(wxXmlResourceHandler *handler);
151
152 // Add a new handler at the begining of the handler list
153 void InsertHandler(wxXmlResourceHandler *handler);
154
155 // Removes all handlers
156 void ClearHandlers();
157
158 // Registers subclasses factory for use in XRC. This function is not meant
159 // for public use, please see the comment above wxXmlSubclassFactory
160 // definition.
161 static void AddSubclassFactory(wxXmlSubclassFactory *factory);
162
163 // Loads menu from resource. Returns NULL on failure.
164 wxMenu *LoadMenu(const wxString& name);
165
166 // Loads menubar from resource. Returns NULL on failure.
167 wxMenuBar *LoadMenuBar(wxWindow *parent, const wxString& name);
168
169 // Loads menubar from resource. Returns NULL on failure.
170 wxMenuBar *LoadMenuBar(const wxString& name) { return LoadMenuBar(NULL, name); }
171
172 #if wxUSE_TOOLBAR
173 // Loads a toolbar.
174 wxToolBar *LoadToolBar(wxWindow *parent, const wxString& name);
175 #endif
176
177 // Loads a dialog. dlg points to parent window (if any).
178 wxDialog *LoadDialog(wxWindow *parent, const wxString& name);
179
180 // Loads a dialog. dlg points to parent window (if any). This form
181 // is used to finish creation of already existing instance (main reason
182 // for this is that you may want to use derived class with new event table)
183 // Example (typical usage):
184 // MyDialog dlg;
185 // wxTheXmlResource->LoadDialog(&dlg, mainFrame, "my_dialog");
186 // dlg->ShowModal();
187 bool LoadDialog(wxDialog *dlg, wxWindow *parent, const wxString& name);
188
189 // Loads a panel. panel points to parent window (if any).
190 wxPanel *LoadPanel(wxWindow *parent, const wxString& name);
191
192 // Loads a panel. panel points to parent window (if any). This form
193 // is used to finish creation of already existing instance.
194 bool LoadPanel(wxPanel *panel, wxWindow *parent, const wxString& name);
195
196 // Loads a frame.
197 wxFrame *LoadFrame(wxWindow* parent, const wxString& name);
198 bool LoadFrame(wxFrame* frame, wxWindow *parent, const wxString& name);
199
200 // Load an object from the resource specifying both the resource name and
201 // the classname. This lets you load nonstandard container windows.
202 wxObject *LoadObject(wxWindow *parent, const wxString& name,
203 const wxString& classname);
204
205 // Load an object from the resource specifying both the resource name and
206 // the classname. This form lets you finish the creation of an existing
207 // instance.
208 bool LoadObject(wxObject *instance, wxWindow *parent, const wxString& name,
209 const wxString& classname);
210
211 // Loads a bitmap resource from a file.
212 wxBitmap LoadBitmap(const wxString& name);
213
214 // Loads an icon resource from a file.
215 wxIcon LoadIcon(const wxString& name);
216
217 // Attaches an unknown control to the given panel/window/dialog.
218 // Unknown controls are used in conjunction with <object class="unknown">.
219 bool AttachUnknownControl(const wxString& name, wxWindow *control,
220 wxWindow *parent = NULL);
221
222 // Returns a numeric ID that is equivalent to the string ID used in an XML
223 // resource. If an unknown str_id is requested (i.e. other than wxID_XXX
224 // or integer), a new record is created which associates the given string
225 // with a number. If value_if_not_found == wxID_NONE, the number is obtained via
226 // wxWindow::NewControlId(). Otherwise value_if_not_found is used.
227 // Macro XRCID(name) is provided for convenient use in event tables.
228 static int GetXRCID(const wxChar *str_id, int value_if_not_found = wxID_NONE);
229
230 // Returns version information (a.b.c.d = d+ 256*c + 256^2*b + 256^3*a).
231 long GetVersion() const { return m_version; }
232
233 // Compares resources version to argument. Returns -1 if resources version
234 // is less than the argument, +1 if greater and 0 if they equal.
235 int CompareVersion(int major, int minor, int release, int revision) const
236 { return GetVersion() -
237 (major*256*256*256 + minor*256*256 + release*256 + revision); }
238
239 //// Singleton accessors.
240
241 // Gets the global resources object or creates one if none exists.
242 static wxXmlResource *Get();
243
244 // Sets the global resources object and returns a pointer to the previous one (may be NULL).
245 static wxXmlResource *Set(wxXmlResource *res);
246
247 // Returns flags, which may be a bitlist of wxXRC_USE_LOCALE and wxXRC_NO_SUBCLASSING.
248 int GetFlags() const { return m_flags; }
249 // Set flags after construction.
250 void SetFlags(int flags) { m_flags = flags; }
251
252 // Get/Set the domain to be passed to the translation functions, defaults
253 // to empty string (no domain).
254 const wxString& GetDomain() const { return m_domain; }
255 void SetDomain(const wxString& domain);
256
257 protected:
258 // Scans the resources list for unloaded files and loads them. Also reloads
259 // files that have been modified since last loading.
260 bool UpdateResources();
261
262 // Finds a resource (calls UpdateResources) and returns a node containing it.
263 wxXmlNode *FindResource(const wxString& name, const wxString& classname, bool recursive = false);
264
265 // Helper function: finds a resource (calls UpdateResources) and returns a node containing it.
266 wxXmlNode *DoFindResource(wxXmlNode *parent, const wxString& name, const wxString& classname, bool recursive);
267
268 // Creates a resource from information in the given node
269 // (Uses only 'handlerToUse' if != NULL)
270 wxObject *CreateResFromNode(wxXmlNode *node, wxObject *parent,
271 wxObject *instance = NULL,
272 wxXmlResourceHandler *handlerToUse = NULL);
273
274 // Helper of Load() and Unload(): returns the URL corresponding to the
275 // given file if it's indeed a file, otherwise returns the original string
276 // unmodified
277 static wxString ConvertFileNameToURL(const wxString& filename);
278
279 // loading resources from archives is impossible without wxFileSystem
280 #if wxUSE_FILESYSTEM
281 // Another helper: detect if the filename is a ZIP or XRS file
282 static bool IsArchive(const wxString& filename);
283 #endif // wxUSE_FILESYSTEM
284
285 private:
286 long m_version;
287
288 int m_flags;
289 wxList m_handlers;
290 wxXmlResourceDataRecords m_data;
291 #if wxUSE_FILESYSTEM
292 wxFileSystem m_curFileSystem;
293 wxFileSystem& GetCurFileSystem() { return m_curFileSystem; }
294 #endif
295
296 // domain to pass to translation functions, if any.
297 wxString m_domain;
298
299 friend class wxXmlResourceHandler;
300 friend class wxXmlResourceModule;
301
302 static wxXmlSubclassFactoriesList *ms_subclassFactories;
303
304 // singleton instance:
305 static wxXmlResource *ms_instance;
306 };
307
308
309 // This macro translates string identifier (as used in XML resource,
310 // e.g. <menuitem id="my_menu">...</menuitem>) to integer id that is needed by
311 // wxWidgets event tables.
312 // Example:
313 // BEGIN_EVENT_TABLE(MyFrame, wxFrame)
314 // EVT_MENU(XRCID("quit"), MyFrame::OnQuit)
315 // EVT_MENU(XRCID("about"), MyFrame::OnAbout)
316 // EVT_MENU(XRCID("new"), MyFrame::OnNew)
317 // EVT_MENU(XRCID("open"), MyFrame::OnOpen)
318 // END_EVENT_TABLE()
319
320 #define XRCID(str_id) \
321 wxXmlResource::GetXRCID(wxT(str_id))
322
323
324 // This macro returns pointer to particular control in dialog
325 // created using XML resources. You can use it to set/get values from
326 // controls.
327 // Example:
328 // wxDialog dlg;
329 // wxXmlResource::Get()->LoadDialog(&dlg, mainFrame, "my_dialog");
330 // XRCCTRL(dlg, "my_textctrl", wxTextCtrl)->SetValue(wxT("default value"));
331
332 #define XRCCTRL(window, id, type) \
333 (wxStaticCast((window).FindWindow(XRCID(id)), type))
334
335 // wxXmlResourceHandler is an abstract base class for resource handlers
336 // capable of creating a control from an XML node.
337
338 class WXDLLIMPEXP_XRC wxXmlResourceHandler : public wxObject
339 {
340 DECLARE_ABSTRACT_CLASS(wxXmlResourceHandler)
341 public:
342 // Constructor.
343 wxXmlResourceHandler();
344
345 // Destructor.
346 virtual ~wxXmlResourceHandler() {}
347
348 // Creates an object (menu, dialog, control, ...) from an XML node.
349 // Should check for validity.
350 // parent is a higher-level object (usually window, dialog or panel)
351 // that is often necessary to create the resource.
352 // If instance is non-NULL it should not create a new instance via 'new' but
353 // should rather use this one, and call its Create method.
354 wxObject *CreateResource(wxXmlNode *node, wxObject *parent,
355 wxObject *instance);
356
357 // This one is called from CreateResource after variables
358 // were filled.
359 virtual wxObject *DoCreateResource() = 0;
360
361 // Returns true if it understands this node and can create
362 // a resource from it, false otherwise.
363 virtual bool CanHandle(wxXmlNode *node) = 0;
364
365 // Sets the parent resource.
366 void SetParentResource(wxXmlResource *res) { m_resource = res; }
367
368 protected:
369 wxXmlResource *m_resource;
370 wxArrayString m_styleNames;
371 wxArrayInt m_styleValues;
372
373 // Variables (filled by CreateResource)
374 wxXmlNode *m_node;
375 wxString m_class;
376 wxObject *m_parent, *m_instance;
377 wxWindow *m_parentAsWindow;
378
379 // --- Handy methods:
380
381 // Returns true if the node has a property class equal to classname,
382 // e.g. <object class="wxDialog">.
383 bool IsOfClass(wxXmlNode *node, const wxString& classname);
384
385 // Gets node content from wxXML_ENTITY_NODE
386 // The problem is, <tag>content<tag> is represented as
387 // wxXML_ENTITY_NODE name="tag", content=""
388 // |-- wxXML_TEXT_NODE or
389 // wxXML_CDATA_SECTION_NODE name="" content="content"
390 wxString GetNodeContent(wxXmlNode *node);
391
392 // Check to see if a parameter exists.
393 bool HasParam(const wxString& param);
394
395 // Finds the node or returns NULL.
396 wxXmlNode *GetParamNode(const wxString& param);
397
398 // Finds the parameter value or returns the empty string.
399 wxString GetParamValue(const wxString& param);
400
401 // Add a style flag (e.g. wxMB_DOCKABLE) to the list of flags
402 // understood by this handler.
403 void AddStyle(const wxString& name, int value);
404
405 // Add styles common to all wxWindow-derived classes.
406 void AddWindowStyles();
407
408 // Gets style flags from text in form "flag | flag2| flag3 |..."
409 // Only understands flags added with AddStyle
410 int GetStyle(const wxString& param = wxT("style"), int defaults = 0);
411
412 // Gets text from param and does some conversions:
413 // - replaces \n, \r, \t by respective chars (according to C syntax)
414 // - replaces _ by & and __ by _ (needed for _File => &File because of XML)
415 // - calls wxGetTranslations (unless disabled in wxXmlResource)
416 wxString GetText(const wxString& param, bool translate = true);
417
418 // Returns the XRCID.
419 int GetID();
420
421 // Returns the resource name.
422 wxString GetName();
423
424 // Gets a bool flag (1, t, yes, on, true are true, everything else is false).
425 bool GetBool(const wxString& param, bool defaultv = false);
426
427 // Gets an integer value from the parameter.
428 long GetLong(const wxString& param, long defaultv = 0);
429
430 // Gets a float value from the parameter.
431 float GetFloat(const wxString& param, float defaultv = 0);
432
433 // Gets colour in HTML syntax (#RRGGBB).
434 wxColour GetColour(const wxString& param, const wxColour& defaultv = wxNullColour);
435
436 // Gets the size (may be in dialog units).
437 wxSize GetSize(const wxString& param = wxT("size"),
438 wxWindow *windowToUse = NULL);
439
440 // Gets the position (may be in dialog units).
441 wxPoint GetPosition(const wxString& param = wxT("pos"));
442
443 // Gets a dimension (may be in dialog units).
444 wxCoord GetDimension(const wxString& param, wxCoord defaultv = 0,
445 wxWindow *windowToUse = NULL);
446
447 // Gets a bitmap.
448 wxBitmap GetBitmap(const wxString& param = wxT("bitmap"),
449 const wxArtClient& defaultArtClient = wxART_OTHER,
450 wxSize size = wxDefaultSize);
451
452 // Gets an icon.
453 wxIcon GetIcon(const wxString& param = wxT("icon"),
454 const wxArtClient& defaultArtClient = wxART_OTHER,
455 wxSize size = wxDefaultSize);
456
457 #if wxUSE_ANIMATIONCTRL
458 // Gets an animation.
459 wxAnimation GetAnimation(const wxString& param = wxT("animation"));
460 #endif
461
462 // Gets a font.
463 wxFont GetFont(const wxString& param = wxT("font"));
464
465 // Sets common window options.
466 void SetupWindow(wxWindow *wnd);
467
468 // Creates children.
469 void CreateChildren(wxObject *parent, bool this_hnd_only = false);
470
471 // Helper function.
472 void CreateChildrenPrivately(wxObject *parent, wxXmlNode *rootnode = NULL);
473
474 // Creates a resource from a node.
475 wxObject *CreateResFromNode(wxXmlNode *node,
476 wxObject *parent, wxObject *instance = NULL)
477 { return m_resource->CreateResFromNode(node, parent, instance); }
478
479 // helper
480 #if wxUSE_FILESYSTEM
481 wxFileSystem& GetCurFileSystem() { return m_resource->GetCurFileSystem(); }
482 #endif
483 };
484
485
486 // Programmer-friendly macros for writing XRC handlers:
487
488 #define XRC_ADD_STYLE(style) AddStyle(wxT(#style), style)
489
490 #define XRC_MAKE_INSTANCE(variable, classname) \
491 classname *variable = NULL; \
492 if (m_instance) \
493 variable = wxStaticCast(m_instance, classname); \
494 if (!variable) \
495 variable = new classname;
496
497
498 // FIXME -- remove this $%^#$%#$@# as soon as Ron checks his changes in!!
499 WXDLLIMPEXP_XRC void wxXmlInitResourceModule();
500
501
502 // This class is used to create instances of XRC "object" nodes with "subclass"
503 // property. It is _not_ supposed to be used by XRC users, you should instead
504 // register your subclasses via wxWidgets' RTTI mechanism. This class is useful
505 // only for language bindings developer who need a way to implement subclassing
506 // in wxWidgets ports that don't support wxRTTI (e.g. wxPython).
507 class WXDLLIMPEXP_XRC wxXmlSubclassFactory
508 {
509 public:
510 // Try to create instance of given class and return it, return NULL on
511 // failure:
512 virtual wxObject *Create(const wxString& className) = 0;
513 virtual ~wxXmlSubclassFactory() {}
514 };
515
516
517 /* -------------------------------------------------------------------------
518 Backward compatibility macros. Do *NOT* use, they may disappear in future
519 versions of the XRC library!
520 ------------------------------------------------------------------------- */
521
522 #endif // wxUSE_XRC
523
524 #endif // _WX_XMLRES_H_