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