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