]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/txrc.tex
fixed typo in dtor docs
[wxWidgets.git] / docs / latex / wx / txrc.tex
CommitLineData
d958c9bd
JS
1\section{XML-based resource system overview}\label{xrcoverview}
2
3Classes: \helpref{wxXmlResource}{wxxmlresource}, \helpref{wxXmlResourceHandler}{wxxmlresourcehandler}
4
bd330a69
JS
5{\bf IMPORTANT NOTE:} XRC is not yet a part of the core wxWindows library, so
6please see the next section for how to compile and link it. Otherwise if you
7try to use it, you will get link errors.
8
d958c9bd
JS
9The XML-based resource system, known as XRC, allows user interface elements such as
10dialogs, menu bars and toolbars, to be stored in text files and loaded into
11the application at run-time. XRC files can also be compiled into binary XRS files or C++
12code, so an XML parser does not need to be linked with the application and load times
13are faster.
14
15There are several advantages to using XRC resources.
16
17\begin{itemize}\itemsep=0pt
18\item Recompiling and linking an application is not necessary if the
19resources change.
20\item If you use a dialog designers that generates C++ code, it can be hard
21to reintegrate this into existing C++ code. Separation of resources and code
22is a more elegant solution.
23\item You can choose between different alternative resource files at run time, if necessary.
24\item The XRC format uses sizers for flexibility, allowing dialogs to be resizable
25and highly portable.
26\item The XRC format is a wxWindows standard,
27and can be generated or postprocessed by any program that understands it. As it is based
28on the XML standard, existing XML editors can be used for simple editing purposes.
29\end{itemize}
30
31XRC was written by Vaclav Slavik.
32
33\subsection{Compiling and using XRC}\label{compilingxrc}
34
35XRC can be found under the 'contrib' hierarchy, in the following directories:
36
37\begin{verbatim}
38 contrib/src/xrc ; XRC source
39 contrib/include/wx/xrc ; XRC headers
40 contrib/samples/xrc ; XRC sample
41 contrib/utils/wxrc ; XRC resource compiler
42 contrib/utils/wxrcedit ; XRC editor (in progress)
43\end{verbatim}
44
45To compile XRC:
46
47\begin{itemize}\itemsep=0pt
48\item Under Windows using VC++, open the contrib/src/xrc/XrcVC.dsw project
49and compile. Also compile contrib/utils/wxrc using wxBase if you wish to compile
50resource files.
51\item Under Unix, XRC should be configured when you configured
52wxWindows. Make XRC by changing directory to contrib/src/xrc and
53type 'make'. Similarly compile contrib/utils/wxrc using wxBase if you wish to compile
54resource files. {\bf Note:} there is currently a
55problem with the wxWindows build system that means that
56only the static version of library can be built at present.
57\end{itemize}
58
59To use XRC:
60
61\begin{itemize}\itemsep=0pt
62\item Under Windows using VC++, link with wxxrc[d].lib.
63\item Under Unix, link with libwxxrc[d].a.
64\end{itemize}
65
66\subsection{XRC concepts}\label{xrcconcepts}
67
68These are the typical steps for using XRC files in your application.
69
70\begin{itemize}\itemsep=0pt
71\item Include the appropriate headers: normally "wx/xrc/xmlres.h" will suffice;
72\item call \verb$wxXmlResource::Get()->InitAllHandlers()$ from your wxApp::OnInit function,
73and then call \verb$wxXmlResource::Get()->Load("myfile.xrc")$ to load the resource file;
74\item to create a dialog from a resource, create it using the default constructor, and then
75load using for example \verb$wxXmlResource::Get()->LoadDialog(&dlg, this, "dlg1")$;
76\item set up event tables as usual but use the \verb$XMLID(str)$ macro to translate from XRC string names
77to a suitable integer identifier, for example \verb$EVT_MENU(XMLID("quit"), MyFrame::OnQuit)$.
78\end{itemize}
79
80To create an XRC file, use one of the following methods.
81
82\begin{itemize}\itemsep=0
83\item Create the file by hand;
84\item use \urlref{wxDesigner}{http://www.roebling.de};
85\item use wxWorkshop (not yet available);
86\item use wxrcedit (the status of this tool is unknown);
87\item convert WIN32 RC files with the tool in contrib/utils/convertrc (the status of this tool is
88unknown).
89\end{itemize}
90
91It is highly recommended that you use a tool such as wxDesigner, since it's fiddly writing
92XRC files by hand.
93
94You can use \helpref{wxXmlResource::Load}{wxxmlresourceload} in a number of ways.
95You can pass an XRC file (XML-based text resource file), an XMB file (compiled binary file)
96or a zip-compressed file (extension ZIP or RSC) containing other XRC or XMB files.
97
98TODO: is the compiled binary format XMB or XRS? How do you handle a C++ resource file?
99
100\subsection{Using binary resource files}\label{binaryresourcefiles}
101
102To compile binary resource files, use the command-line wxrc utility. It takes a single file parameter (the
103input XRC file) and the following switches and options.
104
105\begin{itemize}\itemsep=0
106\item -h (--help): show a help message
107\item -v (--verbose): show verbose logging information
108\item -c (--cpp-code): write C++ source rather than a RSC file
109\item -u (--uncompressed): do not compress XML files (C++ only)
110\item -g (--gettext): output .po catalog (to stdout, or a file if -o is used)
111\item -n (--function) <name>: specify C++ function name (use with -c)
112\item -o (--output) <filename>: specify the output file, such as resource.xrs or resource.cpp
113\item -l (--list-of-handlers) <filename>: output a list of necessary handlers to this file
114\end{itemize}
115
116For example:
117
118\begin{verbatim}
119 % wxrc resource.wrc
120 % wxrc resource.wrc -o resource.wrs
121 % wxrc resource.wrc -v -c -o resource.cpp
122\end{verbatim}
123
124\subsection{XRC C++ sample}\label{xrccppsample}
125
126This is the C++ source file (xrcdemo.cpp) for the XRC sample.
127
128\begin{verbatim}
129/////////////////////////////////////////////////////////////////////////////
130// Name: xmldemo.cpp
131// Purpose: XML resources sample
132// Author: Vaclav Slavik
133// RCS-ID: $Id$
134// Copyright: (c) Vaclav Slavik
135// Licence: wxWindows licence
136/////////////////////////////////////////////////////////////////////////////
137
138// ============================================================================
139// declarations
140// ============================================================================
141
142// ----------------------------------------------------------------------------
143// headers
144// ----------------------------------------------------------------------------
145#ifdef __GNUG__
146 #pragma implementation "xrcdemo.cpp"
147 #pragma interface "xrcdemo.cpp"
148#endif
149
150// For compilers that support precompilation, includes "wx/wx.h".
151#include "wx/wxprec.h"
152
153#ifdef __BORLANDC__
154 #pragma hdrstop
155#endif
156
157// for all others, include the necessary headers (this file is usually all you
158// need because it includes almost all "standard" wxWindows headers)
159#ifndef WX_PRECOMP
160 #include "wx/wx.h"
161#endif
162
163#include "wx/image.h"
164#include "wx/xrc/xmlres.h"
165
166// ----------------------------------------------------------------------------
167// resources
168// ----------------------------------------------------------------------------
169// the application icon
170#if defined(__WXGTK__) || defined(__WXMOTIF__) || defined(__WXMAC__)
171 #include "rc/appicon.xpm"
172#endif
173
174// ----------------------------------------------------------------------------
175// private classes
176// ----------------------------------------------------------------------------
177
178// Define a new application type, each program should derive a class from wxApp
179class MyApp : public wxApp
180{
181public:
182 // override base class virtuals
183 // ----------------------------
184
185 // this one is called on application startup and is a good place for the app
186 // initialization (doing it here and not in the ctor allows to have an error
187 // return: if OnInit() returns false, the application terminates)
188 virtual bool OnInit();
189};
190
191// Define a new frame type: this is going to be our main frame
192class MyFrame : public wxFrame
193{
194public:
195 // ctor(s)
196 MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size);
197
198 // event handlers (these functions should _not_ be virtual)
199 void OnQuit(wxCommandEvent& event);
200 void OnAbout(wxCommandEvent& event);
201 void OnDlg1(wxCommandEvent& event);
202 void OnDlg2(wxCommandEvent& event);
203
204private:
205 // any class wishing to process wxWindows events must use this macro
206 DECLARE_EVENT_TABLE()
207};
208
209// ----------------------------------------------------------------------------
210// event tables and other macros for wxWindows
211// ----------------------------------------------------------------------------
212
213// the event tables connect the wxWindows events with the functions (event
214// handlers) which process them. It can be also done at run-time, but for the
215// simple menu events like this the static method is much simpler.
216BEGIN_EVENT_TABLE(MyFrame, wxFrame)
217 EVT_MENU(XMLID("menu_quit"), MyFrame::OnQuit)
218 EVT_MENU(XMLID("menu_about"), MyFrame::OnAbout)
219 EVT_MENU(XMLID("menu_dlg1"), MyFrame::OnDlg1)
220 EVT_MENU(XMLID("menu_dlg2"), MyFrame::OnDlg2)
221END_EVENT_TABLE()
222
223// Create a new application object: this macro will allow wxWindows to create
224// the application object during program execution (it's better than using a
225// static object for many reasons) and also declares the accessor function
226// wxGetApp() which will return the reference of the right type (i.e. MyApp and
227// not wxApp)
228IMPLEMENT_APP(MyApp)
229
230// ============================================================================
231// implementation
232// ============================================================================
233
234// ----------------------------------------------------------------------------
235// the application class
236// ----------------------------------------------------------------------------
237
238// 'Main program' equivalent: the program execution "starts" here
239bool MyApp::OnInit()
240{
241 wxImage::AddHandler(new wxGIFHandler);
242 wxXmlResource::Get()->InitAllHandlers();
243 wxXmlResource::Get()->Load("rc/resource.xrc");
244
245 MyFrame *frame = new MyFrame("XML resources demo",
246 wxPoint(50, 50), wxSize(450, 340));
247 frame->Show(TRUE);
248 return TRUE;
249}
250
251// ----------------------------------------------------------------------------
252// main frame
253// ----------------------------------------------------------------------------
254
255// frame constructor
256MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
257 : wxFrame((wxFrame *)NULL, -1, title, pos, size)
258{
259 SetIcon(wxICON(appicon));
260
261 SetMenuBar(wxXmlResource::Get()->LoadMenuBar("mainmenu"));
262 SetToolBar(wxXmlResource::Get()->LoadToolBar(this, "toolbar"));
263}
264
265
266// event handlers
267
268void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
269{
270 // TRUE is to force the frame to close
271 Close(TRUE);
272}
273
274void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
275{
276 wxString msg;
277 msg.Printf( _T("This is the about dialog of XML resources demo.\n")
278 _T("Welcome to %s"), wxVERSION_STRING);
279
280 wxMessageBox(msg, "About XML resources demo", wxOK | wxICON_INFORMATION, this);
281}
282
283void MyFrame::OnDlg1(wxCommandEvent& WXUNUSED(event))
284{
285 wxDialog dlg;
286 wxXmlResource::Get()->LoadDialog(&dlg, this, "dlg1");
287 dlg.ShowModal();
288}
289
290
291void MyFrame::OnDlg2(wxCommandEvent& WXUNUSED(event))
292{
293 wxDialog dlg;
294 wxXmlResource::Get()->LoadDialog(&dlg, this, "dlg2");
295 dlg.ShowModal();
296}
297\end{verbatim}
298
299\subsection{XRC resource file sample}\label{xrcsample}
300
301This is the XML file (resource.xrc) for the XRC sample.
302
303\begin{verbatim}
304<?xml version="1.0"?>
305<resource>
306 <object class="wxMenuBar" name="mainmenu">
307 <style>wxMB_DOCKABLE</style>
308 <object class="wxMenu" name="menu_file">
309 <label>$File</label>
310 <style>wxMENU_TEAROFF</style>
311 <object class="wxMenuItem" name="menu_about">
312 <label>$About...</label>
313 <bitmap>filesave.gif</bitmap>
314 </object>
315 <object class="separator"/>
316 <object class="wxMenuItem" name="menu_dlg1">
317 <label>Dialog 1</label>
318 </object>
319 <object class="wxMenuItem" name="menu_dlg2">
320 <label>Dialog 2</label>
321 </object>
322 <object class="separator"/>
323 <object class="wxMenuItem" name="menu_quit">
324 <label>E$xit\tAlt-X</label>
325 </object>
326 </object>
327 </object>
328 <object class="wxToolBar" name="toolbar">
329 <style>wxTB_FLAT|wxTB_DOCKABLE</style>
330 <margins>2,2</margins>
331 <object class="tool" name="menu_open">
332 <bitmap>fileopen.gif</bitmap>
333 <tooltip>Open catalog</tooltip>
334 </object>
335 <object class="tool" name="menu_save">
336 <bitmap>filesave.gif</bitmap>
337 <tooltip>Save catalog</tooltip>
338 </object>
339 <object class="tool" name="menu_update">
340 <bitmap>update.gif</bitmap>
341 <tooltip>Update catalog - synchronize it with sources</tooltip>
342 </object>
343 <separator/>
344 <object class="tool" name="menu_quotes">
345 <bitmap>quotes.gif</bitmap>
346 <toggle>1</toggle>
347 <tooltip>Display quotes around the string?</tooltip>
348 </object>
349 <object class="separator"/>
350 <object class="tool" name="menu_fuzzy">
351 <bitmap>fuzzy.gif</bitmap>
352 <tooltip>Toggled if selected string is fuzzy translation</tooltip>
353 <toggle>1</toggle>
354 </object>
355 </object>
356 <object class="wxDialog" name="dlg1">
357 <object class="wxBoxSizer">
358 <object class="sizeritem">
359 <object class="wxBitmapButton">
360 <bitmap>fuzzy.gif</bitmap>
361 <focus>fileopen.gif</focus>
362 </object>
363 </object>
364 <object class="sizeritem">
365 <object class="wxPanel">
366 <object class="wxStaticText">
367 <label>fdgdfgdfgdfg</label>
368 </object>
369 <style>wxSUNKEN_BORDER</style>
370 </object>
371 <flag>wxALIGN_CENTER</flag>
372 </object>
373 <object class="sizeritem">
374 <object class="wxButton">
375 <label>Buttonek</label>
376 </object>
377 <border>10d</border>
378 <flag>wxALL</flag>
379 </object>
380 <object class="sizeritem">
381 <object class="wxHtmlWindow">
382 <htmlcode>&lt;h1&gt;Hi,&lt;/h1&gt;man</htmlcode>
383 <size>100,45d</size>
384 </object>
385 </object>
386 <object class="sizeritem">
387 <object class="wxNotebook">
388 <object class="notebookpage">
389 <object class="wxPanel">
390 <object class="wxBoxSizer">
391 <object class="sizeritem">
392 <object class="wxHtmlWindow">
393 <htmlcode>Hello, we are inside a &lt;u&gt;NOTEBOOK&lt;/u&gt;...</htmlcode>
394 <size>50,50d</size>
395 </object>
396 <option>1</option>
397 </object>
398 </object>
399 </object>
400 <label>Page</label>
401 </object>
402 <object class="notebookpage">
403 <object class="wxPanel">
404 <object class="wxBoxSizer">
405 <object class="sizeritem">
406 <object class="wxHtmlWindow">
407 <htmlcode>Hello, we are inside a &lt;u&gt;NOTEBOOK&lt;/u&gt;...</htmlcode>
408 <size>50,50d</size>
409 </object>
410 </object>
411 </object>
412 </object>
413 <label>Page 2</label>
414 </object>
415 <usenotebooksizer>1</usenotebooksizer>
416 </object>
417 <flag>wxEXPAND</flag>
418 </object>
419 <orient>wxVERTICAL</orient>
420 </object>
421 </object>
422 <object class="wxDialog" name="dlg2">
423 <object class="wxBoxSizer">
424 <orient>wxVERTICAL</orient>
425 <object class="sizeritem" name="dfgdfg">
426 <object class="wxTextCtrl">
427 <size>200,200d</size>
428 <style>wxTE_MULTILINE|wxSUNKEN_BORDER</style>
429 <value>Hello, this is an ordinary multiline\n textctrl....</value>
430 </object>
431 <option>1</option>
432 <flag>wxEXPAND|wxALL</flag>
433 <border>10</border>
434 </object>
435 <object class="sizeritem">
436 <object class="wxBoxSizer">
437 <object class="sizeritem">
438 <object class="wxButton" name="wxID_OK">
439 <label>Ok</label>
440 <default>1</default>
441 </object>
442 </object>
443 <object class="sizeritem">
444 <object class="wxButton" name="wxID_CANCEL">
445 <label>Cancel</label>
446 </object>
447 <border>10</border>
448 <flag>wxLEFT</flag>
449 </object>
450 </object>
451 <flag>wxLEFT|wxRIGHT|wxBOTTOM|wxALIGN_RIGHT</flag>
452 <border>10</border>
453 </object>
454 </object>
455 <title>Second testing dialog</title>
456 </object>
457</resource>
458\end{verbatim}
459
460\subsection{XRC file format}\label{xrcfileformat}
461
462This section to be written.
463
464\subsection{Adding new resource handlers}\label{newresourcehandlers}
465
466This section to be written.
467
468