]> git.saurik.com Git - wxWidgets.git/blame_incremental - interface/wx/xrc/xmlres.h
Add test for absence of events from wxSpinCtrlDouble ctor.
[wxWidgets.git] / interface / wx / xrc / xmlres.h
... / ...
CommitLineData
1/////////////////////////////////////////////////////////////////////////////
2// Name: xrc/xmlres.h
3// Purpose: interface of wxXmlResource
4// Author: wxWidgets team
5// Licence: wxWindows licence
6/////////////////////////////////////////////////////////////////////////////
7
8/**
9 Flags which can be used with wxXmlResource::wxXmlResource.
10*/
11enum wxXmlResourceFlags
12{
13 /** Translatable strings will be translated via _(). */
14 wxXRC_USE_LOCALE = 1,
15
16 /** Subclass property of object nodes will be ignored (useful for previews in XRC editors). */
17 wxXRC_NO_SUBCLASSING = 2,
18
19 /** Prevent the XRC files from being reloaded from disk in case they have been modified there
20 since being last loaded (may slightly speed up loading them). */
21 wxXRC_NO_RELOADING = 4
22};
23
24
25/**
26 @class wxXmlResource
27
28 This is the main class for interacting with the XML-based resource system.
29
30 The class holds XML resources from one or more .xml files, binary files or zip
31 archive files.
32
33 Note that this is a singleton class and you'll never allocate/deallocate it.
34 Just use the static wxXmlResource::Get() getter.
35
36 @see @ref overview_xrc, @ref overview_xrcformat
37
38 @library{wxxrc}
39 @category{xrc}
40*/
41class wxXmlResource : public wxObject
42{
43public:
44 /**
45 Constructor.
46
47 @param filemask
48 The XRC file, archive file, or wildcard specification that will be
49 used to load all resource files inside a zip archive.
50 @param flags
51 One or more value of the ::wxXmlResourceFlags enumeration.
52 @param domain
53 The name of the gettext catalog to search for translatable strings.
54 By default all loaded catalogs will be searched.
55 This provides a way to allow the strings to only come from a specific catalog.
56 */
57 wxXmlResource(const wxString& filemask,
58 int flags = wxXRC_USE_LOCALE,
59 const wxString& domain = wxEmptyString);
60
61 /**
62 Constructor.
63
64 @param flags
65 One or more value of the ::wxXmlResourceFlags enumeration.
66 @param domain
67 The name of the gettext catalog to search for translatable strings.
68 By default all loaded catalogs will be searched.
69 This provides a way to allow the strings to only come from a specific catalog.
70 */
71 wxXmlResource(int flags = wxXRC_USE_LOCALE,
72 const wxString& domain = wxEmptyString);
73
74 /**
75 Destructor.
76 */
77 virtual ~wxXmlResource();
78
79 /**
80 Initializes only a specific handler (or custom handler).
81 Convention says that the handler name is equal to the control's name plus
82 'XmlHandler', for example wxTextCtrlXmlHandler, wxHtmlWindowXmlHandler.
83
84 The XML resource compiler (wxxrc) can create include file that contains
85 initialization code for all controls used within the resource.
86 Note that this handler must be allocated on the heap, since it will be
87 deleted by ClearHandlers() later.
88 */
89 void AddHandler(wxXmlResourceHandler* handler);
90
91 /**
92 Add a new handler at the begining of the handler list.
93 */
94 void InsertHandler(wxXmlResourceHandler *handler);
95
96
97 /**
98 Attaches an unknown control to the given panel/window/dialog.
99 Unknown controls are used in conjunction with \<object class="unknown"\>.
100 */
101 bool AttachUnknownControl(const wxString& name,
102 wxWindow* control,
103 wxWindow* parent = NULL);
104
105 /**
106 Removes all handlers and deletes them (this means that any handlers
107 added using AddHandler() must be allocated on the heap).
108 */
109 void ClearHandlers();
110
111 /**
112 Registers subclasses factory for use in XRC. This is useful only for
113 language bindings developers who need a way to implement subclassing in
114 wxWidgets ports that don't support wxRTTI (e.g. wxPython).
115 */
116 static void AddSubclassFactory(wxXmlSubclassFactory *factory);
117
118
119 /**
120 Compares the XRC version to the argument.
121
122 Returns -1 if the XRC version is less than the argument,
123 +1 if greater, and 0 if they are equal.
124 */
125 int CompareVersion(int major, int minor, int release, int revision) const;
126
127 /**
128 Returns a string ID corresponding to the given numeric ID.
129
130 The string returned is such that calling GetXRCID() with it as
131 parameter yields @a numId. If there is no string identifier
132 corresponding to the given numeric one, an empty string is returned.
133
134 Notice that, unlike GetXRCID(), this function is slow as it checks all
135 of the identifiers used in XRC.
136
137 @since 2.9.0
138 */
139 static wxString FindXRCIDById(int numId);
140
141 /**
142 Gets the global resources object or creates one if none exists.
143 */
144 static wxXmlResource* Get();
145
146 /**
147 Returns the domain (message catalog) that will be used to load
148 translatable strings in the XRC.
149 */
150 const wxString& GetDomain() const;
151
152 /**
153 Returns flags, which may be a bitlist of ::wxXmlResourceFlags
154 enumeration values.
155 */
156 int GetFlags() const;
157
158 /**
159 Returns the wxXmlNode containing the definition of the object with the
160 given name or @NULL.
161
162 This function recursively searches all the loaded XRC files for an
163 object with the specified @a name. If the object is found, the
164 wxXmlNode corresponding to it is returned, so this function can be used
165 to access additional information defined in the XRC file and not used
166 by wxXmlResource itself, e.g. contents of application-specific XML
167 tags.
168
169 @param name
170 The name of the resource which must be unique for this function to
171 work correctly, if there is more than one resource with the given
172 name the choice of the one returned by this function is undefined.
173 @return
174 The node corresponding to the resource with the given name or @NULL.
175 */
176 const wxXmlNode *GetResourceNode(const wxString& name) const;
177
178 /**
179 Returns version information (a.b.c.d = d + 256*c + 2562*b + 2563*a).
180 */
181 long GetVersion() const;
182
183 /**
184 Returns a numeric ID that is equivalent to the string ID used in an XML resource.
185
186 If an unknown @a str_id is requested (i.e. other than wxID_XXX or integer),
187 a new record is created which associates the given string with a number.
188
189 If @a value_if_not_found is @c wxID_NONE, the number is obtained via
190 wxNewId(). Otherwise @a value_if_not_found is used.
191
192 Macro @c XRCID(name) is provided for convenient use in event tables.
193
194 @note IDs returned by XRCID() cannot be used with the <tt>EVT_*_RANGE</tt>
195 macros, because the order in which they are assigned to symbolic @a name
196 values is not guaranteed.
197 */
198 static int GetXRCID(const wxString& str_id, int value_if_not_found = wxID_NONE);
199
200 /**
201 Initializes handlers for all supported controls/windows.
202
203 This will make the executable quite big because it forces linking against
204 most of the wxWidgets library.
205 */
206 void InitAllHandlers();
207
208 /**
209 Loads resources from XML files that match given filemask.
210
211 Example:
212 @code
213 if (!wxXmlResource::Get()->Load("rc/*.xrc"))
214 wxLogError("Couldn't load resources!");
215 @endcode
216
217 @note
218 If wxUSE_FILESYS is enabled, this method understands wxFileSystem URLs
219 (see wxFileSystem::FindFirst()).
220
221 @note
222 If you are sure that the argument is name of single XRC file (rather
223 than an URL or a wildcard), use LoadFile() instead.
224
225 @see LoadFile(), LoadAllFiles()
226 */
227 bool Load(const wxString& filemask);
228
229 /**
230 Simpler form of Load() for loading a single XRC file.
231
232 @since 2.9.0
233
234 @see Load(), LoadAllFiles()
235 */
236 bool LoadFile(const wxFileName& file);
237
238 /**
239 Loads all .xrc files from directory @a dirname.
240
241 Tries to load as many files as possible; if there's an error while
242 loading one file, it still attempts to load other files.
243
244 @since 2.9.0
245
246 @see LoadFile(), Load()
247 */
248 bool LoadAllFiles(const wxString& dirname);
249
250 /**
251 Loads a bitmap resource from a file.
252 */
253 wxBitmap LoadBitmap(const wxString& name);
254
255 /**
256 Loads a dialog. @a parent points to parent window (if any).
257 */
258 wxDialog* LoadDialog(wxWindow* parent, const wxString& name);
259
260 /**
261 Loads a dialog. @a parent points to parent window (if any).
262
263 This form is used to finish creation of an already existing instance (the main
264 reason for this is that you may want to use derived class with a new event table).
265 Example:
266
267 @code
268 MyDialog dlg;
269 wxXmlResource::Get()->LoadDialog(&dlg, mainFrame, "my_dialog");
270 dlg.ShowModal();
271 @endcode
272 */
273 bool LoadDialog(wxDialog* dlg, wxWindow* parent, const wxString& name);
274
275 /**
276 Loads a frame from the resource. @a parent points to parent window (if any).
277 */
278 wxFrame *LoadFrame(wxWindow* parent, const wxString& name);
279
280 /**
281 Loads the contents of a frame onto an existing wxFrame.
282
283 This form is used to finish creation of an already existing instance
284 (the main reason for this is that you may want to use derived class
285 with a new event table).
286 */
287 bool LoadFrame(wxFrame* frame, wxWindow* parent,
288 const wxString& name);
289
290 /**
291 Loads an icon resource from a file.
292 */
293 wxIcon LoadIcon(const wxString& name);
294
295 /**
296 Loads menu from resource. Returns @NULL on failure.
297 */
298 wxMenu* LoadMenu(const wxString& name);
299
300 //@{
301 /**
302 Loads a menubar from resource. Returns @NULL on failure.
303 */
304 wxMenuBar* LoadMenuBar(wxWindow* parent, const wxString& name);
305 wxMenuBar* LoadMenuBar(const wxString& name);
306 //@}
307
308 //@{
309 /**
310 Load an object from the resource specifying both the resource name and the
311 class name.
312
313 The first overload lets you load nonstandard container windows and returns
314 @NULL on failure. The second one lets you finish the creation of an existing
315 instance and returns @false on failure.
316
317 In either case, only the resources defined at the top level of XRC
318 files can be loaded by this function, use LoadObjectRecursively() if
319 you need to load an object defined deeper in the hierarchy.
320 */
321 wxObject* LoadObject(wxWindow* parent, const wxString& name,
322 const wxString& classname);
323 bool LoadObject(wxObject* instance, wxWindow* parent,
324 const wxString& name,
325 const wxString& classname);
326 //@}
327
328 //@{
329 /**
330 Load an object from anywhere in the resource tree.
331
332 These methods are similar to LoadObject() but may be used to load an
333 object from anywhere in the resource tree and not only the top level.
334 Note that you will very rarely need to do this as in normal use the
335 entire container window (defined at the top level) is loaded and not
336 its individual children but this method can be useful in some
337 particular situations.
338
339 @since 2.9.1
340 */
341 wxObject* LoadObjectRecursively(wxWindow* parent,
342 const wxString& name,
343 const wxString& classname);
344 bool LoadObjectRecursively(wxObject* instance, wxWindow* parent,
345 const wxString& name,
346 const wxString& classname);
347 //@}
348
349 /**
350 Loads a panel. @a parent points to the parent window.
351 */
352 wxPanel* LoadPanel(wxWindow* parent, const wxString& name);
353
354 /**
355 Loads a panel. @a parent points to the parent window.
356 This form is used to finish creation of an already existing instance.
357 */
358 bool LoadPanel(wxPanel* panel, wxWindow* parent, const wxString& name);
359
360 /**
361 Loads a toolbar.
362 */
363 wxToolBar* LoadToolBar(wxWindow* parent, const wxString& name);
364
365 /**
366 Sets the global resources object and returns a pointer to the previous one
367 (may be @NULL).
368 */
369 static wxXmlResource* Set(wxXmlResource* res);
370
371 /**
372 Sets the domain (message catalog) that will be used to load
373 translatable strings in the XRC.
374 */
375 void SetDomain(const wxString& domain);
376
377 /**
378 Sets flags (bitlist of ::wxXmlResourceFlags enumeration values).
379 */
380 void SetFlags(int flags);
381
382 /**
383 This function unloads a resource previously loaded by Load().
384
385 Returns @true if the resource was successfully unloaded and @false if it
386 hasn't been found in the list of loaded resources.
387 */
388 bool Unload(const wxString& filename);
389
390protected:
391 /**
392 Reports error in XRC resources to the user.
393
394 Any errors in XRC input files should be reported using this method
395 (or its wxXmlResourceHandler::ReportError() equivalent). Unlike
396 wxLogError(), this method presents the error to the user in a more
397 usable form. In particular, the output is compiler-like and contains
398 information about the exact location of the error.
399
400 @param context XML node the error occurred in or relates to. This can
401 be @NULL, but should be the most specific node possible,
402 as its line number is what is reported to the user.
403 @param message Text of the error message. This string should always
404 be in English (i.e. not wrapped in _()). It shouldn't
405 be a sentence -- it should start with lower-case letter
406 and shouldn't have a trailing period or exclamation
407 point.
408
409 @since 2.9.0
410
411 @see wxXmlResourceHandler::ReportError(), DoReportError()
412 */
413 void ReportError(const wxXmlNode *context, const wxString& message);
414
415 /**
416 Implementation of XRC resources errors reporting.
417
418 This method is called by ReportError() and shouldn't be called
419 directly; use ReportError() or wxXmlResourceHandler::ReportError()
420 to log errors.
421
422 Default implementation uses wxLogError().
423
424 @param xrcFile File the error occurred in or empty string if it
425 couldn't be determined.
426 @param position XML node where the error occurred or @NULL if it
427 couldn't be determined.
428 @param message Text of the error message. See ReportError()
429 documentation for details of the string's format.
430
431 @note
432 You may override this method in a derived class to customize errors
433 reporting. If you do so, you'll need to either use the derived class
434 in all your code or call wxXmlResource::Set() to change the global
435 wxXmlResource instance to your class.
436
437 @since 2.9.0
438
439 @see ReportError()
440 */
441 virtual void DoReportError(const wxString& xrcFile, const wxXmlNode *position,
442 const wxString& message);
443};
444
445
446
447/**
448 @class wxXmlResourceHandler
449
450 wxXmlResourceHandler is an abstract base class for resource handlers
451 capable of creating a control from an XML node.
452
453 See @ref overview_xrc for details.
454
455 @library{wxxrc}
456 @category{xrc}
457*/
458class wxXmlResourceHandler : public wxObject
459{
460public:
461 /**
462 Default constructor.
463 */
464 wxXmlResourceHandler();
465
466 /**
467 Destructor.
468 */
469 virtual ~wxXmlResourceHandler();
470
471 /**
472 Creates an object (menu, dialog, control, ...) from an XML node.
473 Should check for validity. @a parent is a higher-level object
474 (usually window, dialog or panel) that is often necessary to
475 create the resource.
476
477 If @b instance is non-@NULL it should not create a new instance via
478 'new' but should rather use this one, and call its Create method.
479 */
480 wxObject* CreateResource(wxXmlNode* node, wxObject* parent,
481 wxObject* instance);
482
483 /**
484 Called from CreateResource after variables were filled.
485 */
486 virtual wxObject* DoCreateResource() = 0;
487
488 /**
489 Returns @true if it understands this node and can create
490 a resource from it, @false otherwise.
491
492 @note
493 You must not call any wxXmlResourceHandler methods except IsOfClass()
494 from this method! The instance is not yet initialized with node data
495 at the time CanHandle() is called and it is only safe to operate on
496 node directly or to call IsOfClass().
497 */
498 virtual bool CanHandle(wxXmlNode* node) = 0;
499
500 /**
501 Sets the parent resource.
502 */
503 void SetParentResource(wxXmlResource* res);
504
505
506protected:
507
508 /**
509 Add a style flag (e.g. @c wxMB_DOCKABLE) to the list of flags
510 understood by this handler.
511 */
512 void AddStyle(const wxString& name, int value);
513
514 /**
515 Add styles common to all wxWindow-derived classes.
516 */
517 void AddWindowStyles();
518
519 /**
520 Creates children.
521 */
522 void CreateChildren(wxObject* parent, bool this_hnd_only = false);
523
524 /**
525 Helper function.
526 */
527 void CreateChildrenPrivately(wxObject* parent,
528 wxXmlNode* rootnode = NULL);
529
530 /**
531 Creates a resource from a node.
532 */
533 wxObject* CreateResFromNode(wxXmlNode* node, wxObject* parent,
534 wxObject* instance = NULL);
535
536 /**
537 Creates an animation (see wxAnimation) from the filename specified in @a param.
538 */
539 wxAnimation* GetAnimation(const wxString& param = "animation");
540
541 /**
542 Gets a bitmap.
543 */
544 wxBitmap GetBitmap(const wxString& param = "bitmap",
545 const wxArtClient& defaultArtClient = wxART_OTHER,
546 wxSize size = wxDefaultSize);
547 /**
548 Gets a bitmap from an XmlNode.
549
550 @since 2.9.1
551 */
552 wxBitmap GetBitmap(const wxXmlNode* node,
553 const wxArtClient& defaultArtClient = wxART_OTHER,
554 wxSize size = wxDefaultSize);
555
556 /**
557 Gets a bool flag (1, t, yes, on, true are @true, everything else is @false).
558 */
559 bool GetBool(const wxString& param, bool defaultv = false);
560
561 /**
562 Gets colour in HTML syntax (\#RRGGBB).
563 */
564 wxColour GetColour(const wxString& param,
565 const wxColour& defaultColour = wxNullColour);
566
567 /**
568 Returns the current file system.
569 */
570 wxFileSystem& GetCurFileSystem();
571
572 /**
573 Gets a dimension (may be in dialog units).
574 */
575 wxCoord GetDimension(const wxString& param, wxCoord defaultv = 0,
576 wxWindow* windowToUse = 0);
577
578 /**
579 Gets a direction.
580
581 If the given @a param is not present or has empty value, @a dir is
582 returned by default. Otherwise the value of the parameter is parsed and
583 a warning is generated if it's not one of @c wxLEFT, @c wxTOP, @c
584 wxRIGHT or @c wxBOTTOM.
585
586 @since 2.9.3
587 */
588 wxDirection GetDirection(const wxString& param, wxDirection dir = wxLEFT);
589
590 /**
591 Gets a font.
592 */
593 wxFont GetFont(const wxString& param = "font");
594
595 /**
596 Returns the XRCID.
597 */
598 int GetID();
599
600 /**
601 Returns an icon.
602 */
603 wxIcon GetIcon(const wxString& param = "icon",
604 const wxArtClient& defaultArtClient = wxART_OTHER,
605 wxSize size = wxDefaultSize);
606
607 /**
608 Gets an icon from an XmlNode.
609
610 @since 2.9.1
611 */
612 wxIcon GetIcon(const wxXmlNode* node,
613 const wxArtClient& defaultArtClient = wxART_OTHER,
614 wxSize size = wxDefaultSize);
615
616 /**
617 Returns an icon bundle.
618
619 @note
620 Bundles can be loaded either with stock IDs or from files that contain
621 more than one image (e.g. Windows icon files). If a file contains only
622 single image, a bundle with only one icon will be created.
623
624 @since 2.9.0
625 */
626 wxIconBundle GetIconBundle(const wxString& param,
627 const wxArtClient& defaultArtClient = wxART_OTHER);
628
629 /**
630 Creates an image list from the @a param markup data.
631
632 @return
633 The new instance of wxImageList or @NULL if no data is found.
634
635 @since 2.9.1
636 */
637 wxImageList *GetImageList(const wxString& param = "imagelist");
638
639 /**
640 Gets the integer value from the parameter.
641 */
642 long GetLong(const wxString& param, long defaultv = 0);
643
644 /**
645 Gets a float value from the parameter.
646 */
647 float GetFloat(const wxString& param, float defaultv = 0);
648
649 /**
650 Returns the resource name.
651 */
652 wxString GetName();
653
654 /**
655 Gets node content from wxXML_ENTITY_NODE.
656 */
657 wxString GetNodeContent(wxXmlNode* node);
658
659 /**
660 Finds the node or returns @NULL.
661 */
662 wxXmlNode* GetParamNode(const wxString& param);
663
664 /**
665 Finds the parameter value or returns the empty string.
666 */
667 wxString GetParamValue(const wxString& param);
668
669 /**
670 Returns the node parameter value.
671
672 @since 2.9.1
673 */
674 wxString GetParamValue(const wxXmlNode* node);
675
676 /**
677 Gets the position (may be in dialog units).
678 */
679 wxPoint GetPosition(const wxString& param = "pos");
680
681 /**
682 Gets the size (may be in dialog units).
683 */
684 wxSize GetSize(const wxString& param = "size", wxWindow* windowToUse = 0);
685
686 /**
687 Gets style flags from text in form "flag | flag2| flag3 |..."
688 Only understands flags added with AddStyle().
689 */
690 int GetStyle(const wxString& param = "style", int defaults = 0);
691
692 /**
693 Gets text from param and does some conversions:
694 - replaces \\n, \\r, \\t by respective characters (according to C syntax)
695 - replaces @c $ by @c and @c $$ by @c $ (needed for @c _File to @c File
696 translation because of XML syntax)
697 - calls wxGetTranslations (unless disabled in wxXmlResource)
698 */
699 wxString GetText(const wxString& param, bool translate = true);
700
701 /**
702 Check to see if a parameter exists.
703 */
704 bool HasParam(const wxString& param);
705
706 /**
707 Convenience function.
708 Returns @true if the node has a property class equal to classname,
709 e.g. object class="wxDialog".
710 */
711 bool IsOfClass(wxXmlNode* node, const wxString& classname);
712
713 /**
714 Sets common window options.
715 */
716 void SetupWindow(wxWindow* wnd);
717
718 /**
719 Reports error in XRC resources to the user.
720
721 See wxXmlResource::ReportError() for more information.
722
723 @since 2.9.0
724 */
725 void ReportError(wxXmlNode *context, const wxString& message);
726
727 /**
728 Like ReportError(wxXmlNode*, const wxString&), but uses the node
729 of currently processed object (m_node) as the context.
730
731 @since 2.9.0
732 */
733 void ReportError(const wxString& message);
734
735 /**
736 Like ReportError(wxXmlNode*, const wxString&), but uses the node
737 of parameter @a param of the currently processed object as the context.
738 This is convenience function for reporting errors in particular
739 parameters.
740
741 @since 2.9.0
742 */
743 void ReportParamError(const wxString& param, const wxString& message);
744
745
746 /**
747 After CreateResource has been called this will return the current
748 wxXmlResource object.
749
750 @since 2.9.5
751 */
752 wxXmlResource* GetResource() const;
753
754 /**
755 After CreateResource has been called this will return the XML node
756 being processed.
757
758 @since 2.9.5
759 */
760 wxXmlNode* GetNode() const;
761
762 /**
763 After CreateResource has been called this will return the class name of
764 the XML resource node being processed.
765
766 @since 2.9.5
767 */
768 wxString GetClass() const;
769
770 /**
771 After CreateResource has been called this will return the current
772 item's parent, if any.
773
774 @since 2.9.5
775 */
776 wxObject* GetParent() const;
777
778 /**
779 After CreateResource has been called this will return the instance that
780 the XML resource content should be created upon, if it has already been
781 created. If @NULL then the handler should create the object itself.
782
783 @since 2.9.5
784 */
785 wxObject* GetInstance() const;
786
787 /**
788 After CreateResource has been called this will return the item's parent
789 as a wxWindow.
790
791 @since 2.9.5
792 */
793 wxWindow* GetParentAsWindow() const;
794};
795