[wxWidgets.git] / interface / xrc / xmlres.h

/////////////////////////////////////////////////////////////////////////////
// Name:        xrc/xmlres.h
// Purpose:     documentation for wxXmlResource class
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**
    @class wxXmlResource
    @headerfile xmlres.h wx/xrc/xmlres.h
    
    This is the main class for interacting with the XML-based resource system.
    
    The class holds XML resources from one or more .xml files, binary files or zip
    archive files.
    
    See @ref overview_xrcoverview "XML-based resource system overview" for details.
    
    @library{wxxrc}
    @category{xrc}
*/
class wxXmlResource : public wxObject
{
public:
    //@{
    /**
        Constructor.
        
        @param flags 
        wxXRC_USE_LOCALE: translatable strings will be translated via _().
        wxXRC_NO_SUBCLASSING: subclass property of object nodes will be ignored
        (useful for previews in XRC editors). wxXRC_NO_RELOADING will prevent the
        XRC files from being reloaded from disk in case they have been modified there
        since being last loaded (may slightly speed up loading them).
        
        @param domain 
        The name of the gettext catalog to search for
          translatable strings.  By default all loaded catalogs will be
          searched.  This provides a way to allow the strings to only come
          from a specific catalog.
    */
    wxXmlResource(const wxString& filemask,
                  int flags = wxXRC_USE_LOCALE,
                  const wxString domain = wxEmptyString);
        wxXmlResource(int flags = wxXRC_USE_LOCALE,
                      const wxString domain = wxEmptyString);
    //@}

    /**
        Destructor.
    */
    ~wxXmlResource();

    /**
        Initializes only a specific handler (or custom handler). Convention says
        that the handler name is equal to the control's name plus 'XmlHandler', for
        example
        wxTextCtrlXmlHandler, wxHtmlWindowXmlHandler. The XML resource compiler
        (wxxrc) can create include file that contains initialization code for
        all controls used within the resource. Note that this handler should be
        allocated on the heap, since it will be delete by 
        ClearHandlers() later.
    */
    void AddHandler(wxXmlResourceHandler* handler);

    /**
        Attaches an unknown control to the given panel/window/dialog.
        Unknown controls are used in conjunction with object class="unknown".
    */
    bool AttachUnknownControl(const wxString& name,
                              wxWindow* control,
                              wxWindow* parent = @NULL);

    /**
        Removes all handlers and deletes them (this means that any handlers added using 
        AddHandler() must be allocated on the heap).
    */
    void ClearHandlers();

    /**
        Compares the XRC version to the argument. Returns -1 if the XRC version
        is less than the argument, +1 if greater, and 0 if they equal.
    */
    int CompareVersion(int major, int minor, int release,
                       int revision);

    /**
        Gets the global resources object or creates one if none exists.
    */
#define wxXmlResource* Get()     /* implementation is private */

    /**
        Returns the domain (message catalog) that will be used to load
        translatable strings in the XRC.
    */
    wxChar* GetDomain();

    /**
        Returns flags, which may be a bitlist of wxXRC_USE_LOCALE and
        wxXRC_NO_SUBCLASSING.
    */
    int GetFlags();

    /**
        Returns version information (a.b.c.d = d+ 256*c + 256@c 2*b + 256@c 3*a).
    */
    long GetVersion();

    /**
        Returns a numeric ID that is equivalent to the string ID used in an XML
        resource. If an unknown @e str_id is requested (i.e. other than wxID_XXX
        or integer), a new record is created which associates the given string with
        a number. If @e value_if_not_found is @c wxID_NONE, the number is obtained via
        wxNewId. Otherwise @e value_if_not_found is used.
        Macro @c XRCID(name) is provided for convenient use in event tables.
    */
#define int GetXRCID(const wxString& str_id, int value_if_not_found = -2)     /* implementation is private */

    /**
        Initializes handlers for all supported controls/windows. This will
        make the executable quite big because it forces linking against
        most of the wxWidgets library.
    */
    void InitAllHandlers();

    /**
        Loads resources from XML files that match given filemask.
        This method understands VFS (see filesys.h).
    */
    bool Load(const wxString& filemask);

    /**
        Loads a bitmap resource from a file.
    */
    wxBitmap LoadBitmap(const wxString& name);

    //@{
    /**
        Loads a dialog. @e dlg points to parent window (if any).
        
        This form is used to finish creation of an already existing instance (the main
        reason
        for this is that you may want to use derived class with a new event table).
        
        Example:
    */
    wxDialog* LoadDialog(wxWindow* parent, const wxString& name);
        bool LoadDialog(wxDialog* dlg, wxWindow* parent,
                        const wxString& name);
    //@}

    /**
        Loads a frame.
    */
    bool LoadFrame(wxFrame* frame, wxWindow* parent,
                   const wxString& name);

    /**
        Loads an icon resource from a file.
    */
    wxIcon LoadIcon(const wxString& name);

    /**
        Loads menu from resource. Returns @NULL on failure.
    */
    wxMenu* LoadMenu(const wxString& name);

    //@{
    /**
        Loads a menubar from resource. Returns @NULL on failure.
    */
    wxMenuBar* LoadMenuBar(wxWindow* parent, const wxString& name);
        wxMenuBar* LoadMenuBar(const wxString& name);
    //@}

    //@{
    /**
        Load an object from the resource specifying both the resource name and the
        class name.
        
        The first overload lets you load nonstandard container windows and returns @c
        @NULL
        on failure. The second one lets you finish the creation of an existing
        instance and returns @false on failure.
    */
    wxObject* LoadObject(wxWindow* parent, const wxString& name,
                         const wxString& classname);
        bool LoadObject(wxObject* instance, wxWindow* parent,
                        const wxString& name,
                        const wxString& classname);
    //@}

    //@{
    /**
        Loads a panel. @e panel points to parent window (if any). This form
        is used to finish creation of an already existing instance.
    */
    wxPanel* LoadPanel(wxWindow* parent, const wxString& name);
        bool LoadPanel(wxPanel* panel, wxWindow* parent,
                       const wxString& name);
    //@}

    /**
        Loads a toolbar.
    */
    wxToolBar* LoadToolBar(wxWindow* parent, const wxString& name);

    /**
        Sets the global resources object and returns a pointer to the previous one (may
        be @NULL).
    */
#define wxXmlResource* Set(wxXmlResource* res)     /* implementation is private */

    /**
        Sets the domain (message catalog) that will be used to load
        translatable strings in the XRC.
    */
    wxChar* SetDomain(const wxChar* domain);

    /**
        Sets flags (bitlist of wxXRC_USE_LOCALE and wxXRC_NO_SUBCLASSING).
    */
    void SetFlags(int flags);

    /**
        This function unloads a resource previously loaded by 
        Load().
        
        Returns @true if the resource was successfully unloaded and @false if it
        hasn't
        been found in the list of loaded resources.
    */
    bool Unload(const wxString& filename);
};


/**
    @class wxXmlResourceHandler
    @headerfile xmlres.h wx/xrc/xmlres.h
    
    wxXmlResourceHandler is an abstract base class for resource handlers
    capable of creating a control from an XML node.
    
    See @ref overview_xrcoverview "XML-based resource system overview" for details.
    
    @library{wxxrc}
    @category{xrc}
*/
class wxXmlResourceHandler : public wxObject
{
public:
    /**
        Default constructor.
    */
    wxXmlResourceHandler();

    /**
        Destructor.
    */
    ~wxXmlResourceHandler();

    /**
        Add a style flag (e.g. wxMB_DOCKABLE) to the list of flags
        understood by this handler.
    */
    void AddStyle(const wxString& name, int value);

    /**
        Add styles common to all wxWindow-derived classes.
    */
    void AddWindowStyles();

    /**
        Returns @true if it understands this node and can create
        a resource from it, @false otherwise.
    */
    bool CanHandle(wxXmlNode* node);

    /**
        Creates children.
    */
    void CreateChildren(wxObject* parent, bool this_hnd_only = @false);

    /**
        Helper function.
    */
    void CreateChildrenPrivately(wxObject* parent,
                                 wxXmlNode* rootnode = @NULL);

    /**
        Creates a resource from a node.
    */
    wxObject* CreateResFromNode(wxXmlNode* node, wxObject* parent,
                                wxObject* instance = @NULL);

    /**
        Creates an object (menu, dialog, control, ...) from an XML node.
        Should check for validity. @e parent is a higher-level object (usually window,
        dialog or panel)
        that is often necessary to create the resource.
        If @b instance is non-@NULL it should not create a new instance via 'new' but
        should rather use this one, and call its Create method.
    */
    wxObject* CreateResource(wxXmlNode* node, wxObject* parent,
                             wxObject* instance);

    /**
        Called from CreateResource after variables
        were filled.
    */
    wxObject* DoCreateResource();

    /**
        )
        
        Creates a animation from the filename specified in @e param.
    */
    wxAnimation GetAnimation();

    /**
        , @b wxSize@e size = wxDefaultSize)
        
        Gets a bitmap.
    */
    wxBitmap GetBitmap();

    /**
        Gets a bool flag (1, t, yes, on, @true are @true, everything else is @false).
    */
    bool GetBool(const wxString& param, bool defaultv = @false);

    /**
        Gets colour in HTML syntax (#RRGGBB).
    */
    wxColour GetColour(const wxString& param,
                       const wxColour& default = wxNullColour);

    /**
        Returns the current file system.
    */
    wxFileSystem GetCurFileSystem();

    /**
        Gets a dimension (may be in dialog units).
    */
    wxCoord GetDimension(const wxString& param, wxCoord defaultv = 0);

    /**
        )
        
        Gets a font.
    */
    wxFont GetFont();

    /**
        Returns the XRCID.
    */
#define int GetID()     /* implementation is private */

    /**
        , @b wxSize@e size = wxDefaultSize)
        
        Returns an icon.
    */
    wxIcon GetIcon();

    /**
        Gets the integer value from the parameter.
    */
    long GetLong(const wxString& param, long defaultv = 0);

    /**
        Returns the resource name.
    */
    wxString GetName();

    /**
        Gets node content from wxXML_ENTITY_NODE.
    */
    wxString GetNodeContent(wxXmlNode* node);

    /**
        Finds the node or returns @NULL.
    */
    wxXmlNode* GetParamNode(const wxString& param);

    /**
        Finds the parameter value or returns the empty string.
    */
    wxString GetParamValue(const wxString& param);

    /**
        )
        
        Gets the position (may be in dialog units).
    */
    wxPoint GetPosition();

    /**
        )
        
        Gets the size (may be in dialog units).
    */
    wxSize GetSize();

    /**
        , @b int@e defaults = 0)
        
        Gets style flags from text in form "flag | flag2| flag3 |..."
        Only understands flags added with AddStyle.
    */
    int GetStyle();

    /**
        Gets text from param and does some conversions:
        
         replaces \n, \r, \t by respective characters (according to C syntax)
         replaces @c $ by @c  and @c $$ by @c $ (needed for @c _File to @c File
        translation because of XML syntax)
         calls wxGetTranslations (unless disabled in wxXmlResource)
    */
    wxString GetText(const wxString& param);

    /**
        Check to see if a parameter exists.
    */
    bool HasParam(const wxString& param);

    /**
        Convenience function. Returns @true if the node has a property class equal to
        classname,
        e.g. object class="wxDialog".
    */
    bool IsOfClass(wxXmlNode* node, const wxString& classname);

    /**
        Sets the parent resource.
    */
    void SetParentResource(wxXmlResource* res);

    /**
        Sets common window options.
    */
    void SetupWindow(wxWindow* wnd);
};
Commit	Line	Data
23324ae1 FM	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: xrc/xmlres.h
	3	// Purpose: documentation for wxXmlResource class
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/**
	10	@class wxXmlResource
	11	@headerfile xmlres.h wx/xrc/xmlres.h
	12
	13	This is the main class for interacting with the XML-based resource system.
	14
	15	The class holds XML resources from one or more .xml files, binary files or zip
	16	archive files.
	17
	18	See @ref overview_xrcoverview "XML-based resource system overview" for details.
	19
	20	@library{wxxrc}
	21	@category{xrc}
	22	*/
	23	class wxXmlResource : public wxObject
	24	{
	25	public:
	26	//@{
	27	/**
	28	Constructor.
	29
	30	@param flags
	31	wxXRC_USE_LOCALE: translatable strings will be translated via _().
	32	wxXRC_NO_SUBCLASSING: subclass property of object nodes will be ignored
	33	(useful for previews in XRC editors). wxXRC_NO_RELOADING will prevent the
	34	XRC files from being reloaded from disk in case they have been modified there
	35	since being last loaded (may slightly speed up loading them).
	36
	37	@param domain
	38	The name of the gettext catalog to search for
	39	translatable strings. By default all loaded catalogs will be
	40	searched. This provides a way to allow the strings to only come
	41	from a specific catalog.
	42	*/
	43	wxXmlResource(const wxString& filemask,
	44	int flags = wxXRC_USE_LOCALE,
	45	const wxString domain = wxEmptyString);
	46	wxXmlResource(int flags = wxXRC_USE_LOCALE,
	47	const wxString domain = wxEmptyString);
	48	//@}
	49
	50	/**
	51	Destructor.
	52	*/
	53	~wxXmlResource();
	54
	55	/**
	56	Initializes only a specific handler (or custom handler). Convention says
	57	that the handler name is equal to the control's name plus 'XmlHandler', for
	58	example
	59	wxTextCtrlXmlHandler, wxHtmlWindowXmlHandler. The XML resource compiler
	60	(wxxrc) can create include file that contains initialization code for
	61	all controls used within the resource. Note that this handler should be
	62	allocated on the heap, since it will be delete by
	63	ClearHandlers() later.
	64	*/
65	void AddHandler(wxXmlResourceHandler* handler);
66
67	/**
68	Attaches an unknown control to the given panel/window/dialog.
69	Unknown controls are used in conjunction with object class="unknown".
70	*/
71	bool AttachUnknownControl(const wxString& name,
72	wxWindow* control,
73	wxWindow* parent = @NULL);
74
75	/**
76	Removes all handlers and deletes them (this means that any handlers added using
77	AddHandler() must be allocated on the heap).
78	*/
79	void ClearHandlers();
80
81	/**
82	Compares the XRC version to the argument. Returns -1 if the XRC version
83	is less than the argument, +1 if greater, and 0 if they equal.
84	*/
85	int CompareVersion(int major, int minor, int release,
86	int revision);
87
88	/**
89	Gets the global resources object or creates one if none exists.
90	*/
91	#define wxXmlResource* Get() /* implementation is private */
92
93	/**
94	Returns the domain (message catalog) that will be used to load
95	translatable strings in the XRC.
96	*/
97	wxChar* GetDomain();
98
99	/**
100	Returns flags, which may be a bitlist of wxXRC_USE_LOCALE and
101	wxXRC_NO_SUBCLASSING.
102	*/
103	int GetFlags();
104
105	/**
106	Returns version information (a.b.c.d = d+ 256c + 256@c 2b + 256@c 3*a).
107	*/
108	long GetVersion();
109
110	/**
111	Returns a numeric ID that is equivalent to the string ID used in an XML
112	resource. If an unknown @e str_id is requested (i.e. other than wxID_XXX
113	or integer), a new record is created which associates the given string with
114	a number. If @e value_if_not_found is @c wxID_NONE, the number is obtained via
115	wxNewId. Otherwise @e value_if_not_found is used.
116	Macro @c XRCID(name) is provided for convenient use in event tables.
117	*/
118	#define int GetXRCID(const wxString& str_id, int value_if_not_found = -2) /* implementation is private */
119
120	/**
121	Initializes handlers for all supported controls/windows. This will
122	make the executable quite big because it forces linking against
123	most of the wxWidgets library.
124	*/
125	void InitAllHandlers();
126
127	/**
128	Loads resources from XML files that match given filemask.
129	This method understands VFS (see filesys.h).
130	*/
131	bool Load(const wxString& filemask);
132
133	/**
134	Loads a bitmap resource from a file.
135	*/
136	wxBitmap LoadBitmap(const wxString& name);
137
138	//@{
139	/**
140	Loads a dialog. @e dlg points to parent window (if any).
141
142	This form is used to finish creation of an already existing instance (the main
143	reason
144	for this is that you may want to use derived class with a new event table).
145
146	Example:
147	*/
148	wxDialog* LoadDialog(wxWindow* parent, const wxString& name);
149	bool LoadDialog(wxDialog* dlg, wxWindow* parent,
150	const wxString& name);
151	//@}
152
153	/**
154	Loads a frame.
155	*/
156	bool LoadFrame(wxFrame* frame, wxWindow* parent,
157	const wxString& name);
158
159	/**
160	Loads an icon resource from a file.
161	*/
162	wxIcon LoadIcon(const wxString& name);
163
164	/**
165	Loads menu from resource. Returns @NULL on failure.
166	*/
167	wxMenu* LoadMenu(const wxString& name);
168
169	//@{
170	/**
171	Loads a menubar from resource. Returns @NULL on failure.
172	*/
173	wxMenuBar* LoadMenuBar(wxWindow* parent, const wxString& name);
174	wxMenuBar* LoadMenuBar(const wxString& name);
175	//@}
176
177	//@{
178	/**
179	Load an object from the resource specifying both the resource name and the
180	class name.
181
182	The first overload lets you load nonstandard container windows and returns @c
183	@NULL
184	on failure. The second one lets you finish the creation of an existing
185	instance and returns @false on failure.
186	*/
187	wxObject* LoadObject(wxWindow* parent, const wxString& name,
188	const wxString& classname);
189	bool LoadObject(wxObject* instance, wxWindow* parent,
190	const wxString& name,
191	const wxString& classname);
192	//@}
193
194	//@{
195	/**
196	Loads a panel. @e panel points to parent window (if any). This form
197	is used to finish creation of an already existing instance.
198	*/
199	wxPanel* LoadPanel(wxWindow* parent, const wxString& name);
200	bool LoadPanel(wxPanel* panel, wxWindow* parent,
201	const wxString& name);
202	//@}
203
204	/**
205	Loads a toolbar.
206	*/
207	wxToolBar* LoadToolBar(wxWindow* parent, const wxString& name);
208
209	/**
210	Sets the global resources object and returns a pointer to the previous one (may
211	be @NULL).
212	*/
213	#define wxXmlResource* Set(wxXmlResource* res) /* implementation is private */
214
215	/**
216	Sets the domain (message catalog) that will be used to load
217	translatable strings in the XRC.
218	*/
219	wxChar* SetDomain(const wxChar* domain);
220
221	/**
222	Sets flags (bitlist of wxXRC_USE_LOCALE and wxXRC_NO_SUBCLASSING).
223	*/
224	void SetFlags(int flags);
225
226	/**
227	This function unloads a resource previously loaded by
228	Load().
229
230	Returns @true if the resource was successfully unloaded and @false if it
231	hasn't
232	been found in the list of loaded resources.
233	*/
234	bool Unload(const wxString& filename);
235	};
236
237
238	/**
239	@class wxXmlResourceHandler
240	@headerfile xmlres.h wx/xrc/xmlres.h
241
242	wxXmlResourceHandler is an abstract base class for resource handlers
243	capable of creating a control from an XML node.
244
245	See @ref overview_xrcoverview "XML-based resource system overview" for details.
246
247	@library{wxxrc}
248	@category{xrc}
249	*/
250	class wxXmlResourceHandler : public wxObject
251	{
252	public:
253	/**
254	Default constructor.
255	*/
256	wxXmlResourceHandler();
257
258	/**
259	Destructor.
260	*/
261	~wxXmlResourceHandler();
262
263	/**
264	Add a style flag (e.g. wxMB_DOCKABLE) to the list of flags
265	understood by this handler.
266	*/
267	void AddStyle(const wxString& name, int value);
268
269	/**
270	Add styles common to all wxWindow-derived classes.
271	*/
272	void AddWindowStyles();
273
274	/**
275	Returns @true if it understands this node and can create
276	a resource from it, @false otherwise.
277	*/
278	bool CanHandle(wxXmlNode* node);
279
280	/**
281	Creates children.
282	*/
283	void CreateChildren(wxObject* parent, bool this_hnd_only = @false);
284
285	/**
286	Helper function.
287	*/
288	void CreateChildrenPrivately(wxObject* parent,
289	wxXmlNode* rootnode = @NULL);
290
291	/**
292	Creates a resource from a node.
293	*/
294	wxObject* CreateResFromNode(wxXmlNode* node, wxObject* parent,
295	wxObject* instance = @NULL);
296
297	/**
298	Creates an object (menu, dialog, control, ...) from an XML node.
299	Should check for validity. @e parent is a higher-level object (usually window,
300	dialog or panel)
301	that is often necessary to create the resource.
302	If @b instance is non-@NULL it should not create a new instance via 'new' but
303	should rather use this one, and call its Create method.
304	*/
305	wxObject* CreateResource(wxXmlNode* node, wxObject* parent,
306	wxObject* instance);
307
308	/**
309	Called from CreateResource after variables
310	were filled.
311	*/
312	wxObject* DoCreateResource();
313
314	/**
315	)
316
317	Creates a animation from the filename specified in @e param.
318	*/
319	wxAnimation GetAnimation();
320
321	/**
322	, @b wxSize@e size = wxDefaultSize)
323
324	Gets a bitmap.
325	*/
326	wxBitmap GetBitmap();
327
328	/**
329	Gets a bool flag (1, t, yes, on, @true are @true, everything else is @false).
330	*/
331	bool GetBool(const wxString& param, bool defaultv = @false);
332
333	/**
334	Gets colour in HTML syntax (#RRGGBB).
335	*/
336	wxColour GetColour(const wxString& param,
337	const wxColour& default = wxNullColour);
338
339	/**
340	Returns the current file system.
341	*/
342	wxFileSystem GetCurFileSystem();
343
344	/**
345	Gets a dimension (may be in dialog units).
346	*/
347	wxCoord GetDimension(const wxString& param, wxCoord defaultv = 0);
348
349	/**
350	)
351
352	Gets a font.
353	*/
354	wxFont GetFont();
355
356	/**
357	Returns the XRCID.
358	*/
359	#define int GetID() /* implementation is private */
360
361	/**
362	, @b wxSize@e size = wxDefaultSize)
363
364	Returns an icon.
365	*/
366	wxIcon GetIcon();
367
368	/**
369	Gets the integer value from the parameter.
370	*/
371	long GetLong(const wxString& param, long defaultv = 0);
372
373	/**
374	Returns the resource name.
375	*/
376	wxString GetName();
377
378	/**
379	Gets node content from wxXML_ENTITY_NODE.
380	*/
381	wxString GetNodeContent(wxXmlNode* node);
382
383	/**
384	Finds the node or returns @NULL.
385	*/
386	wxXmlNode* GetParamNode(const wxString& param);
387
388	/**
389	Finds the parameter value or returns the empty string.
390	*/
391	wxString GetParamValue(const wxString& param);
392
393	/**
394	)
395
396	Gets the position (may be in dialog units).
397	*/
398	wxPoint GetPosition();
399
400	/**
401	)
402
403	Gets the size (may be in dialog units).
404	*/
405	wxSize GetSize();
406
407	/**
408	, @b int@e defaults = 0)
409
410	Gets style flags from text in form "flag \| flag2\| flag3 \|..."
411	Only understands flags added with AddStyle.
412	*/
413	int GetStyle();
414
415	/**
416	Gets text from param and does some conversions:
417
418	replaces \n, \r, \t by respective characters (according to C syntax)
419	replaces @c $ by @c and @c $$ by @c $ (needed for @c _File to @c File
420	translation because of XML syntax)
421	calls wxGetTranslations (unless disabled in wxXmlResource)
422	*/
423	wxString GetText(const wxString& param);
424
425	/**
426	Check to see if a parameter exists.
427	*/
428	bool HasParam(const wxString& param);
429
430	/**
431	Convenience function. Returns @true if the node has a property class equal to
432	classname,
433	e.g. object class="wxDialog".
434	*/
435	bool IsOfClass(wxXmlNode* node, const wxString& classname);
436
437	/**
438	Sets the parent resource.
439	*/
440	void SetParentResource(wxXmlResource* res);
441
442	/**
443	Sets common window options.
444	*/
445	void SetupWindow(wxWindow* wnd);
446	};