]>
Commit | Line | Data |
---|---|---|
1 | \section{XML-based resource system overview}\label{xrcoverview} | |
2 | ||
3 | Classes: \helpref{wxXmlResource}{wxxmlresource}, \helpref{wxXmlResourceHandler}{wxxmlresourcehandler} | |
4 | ||
5 | {\bf IMPORTANT NOTE:} XRC is not yet a part of the core wxWindows library, so | |
6 | please see the next section for how to compile and link it. Otherwise if you | |
7 | try to use it, you will get link errors. | |
8 | ||
9 | The XML-based resource system, known as XRC, allows user interface elements such as | |
10 | dialogs, menu bars and toolbars, to be stored in text files and loaded into | |
11 | the application at run-time. XRC files can also be compiled into binary XRS files or C++ | |
12 | code, so an XML parser does not need to be linked with the application and load times | |
13 | are faster. | |
14 | ||
15 | There 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 | |
19 | resources change. | |
20 | \item If you use a dialog designers that generates C++ code, it can be hard | |
21 | to reintegrate this into existing C++ code. Separation of resources and code | |
22 | is 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 | |
25 | and highly portable. | |
26 | \item The XRC format is a wxWindows standard, | |
27 | and can be generated or postprocessed by any program that understands it. As it is based | |
28 | on the XML standard, existing XML editors can be used for simple editing purposes. | |
29 | \end{itemize} | |
30 | ||
31 | XRC was written by Vaclav Slavik. | |
32 | ||
33 | \subsection{Compiling and using XRC}\label{compilingxrc} | |
34 | ||
35 | XRC 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 | ||
45 | To compile XRC: | |
46 | ||
47 | \begin{itemize}\itemsep=0pt | |
48 | \item Under Windows using VC++, open the contrib/src/xrc/XrcVC.dsw project | |
49 | and compile. Also compile contrib/utils/wxrc using wxBase if you wish to compile | |
50 | resource files. | |
51 | \item Under Unix, XRC should be configured when you configured | |
52 | wxWindows. Make XRC by changing directory to contrib/src/xrc and | |
53 | type 'make'. Similarly compile contrib/utils/wxrc using wxBase if you wish to compile | |
54 | resource files. {\bf Note:} there is currently a | |
55 | problem with the wxWindows build system that means that | |
56 | only the static version of library can be built at present. | |
57 | \end{itemize} | |
58 | ||
59 | To 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 | ||
68 | These 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 {\tt wxXmlResource::Get()->InitAllHandlers()} from your wxApp::OnInit function, | |
73 | and then call {\tt 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 | |
75 | load using for example {\tt wxXmlResource::Get()->LoadDialog(&dlg, this, "dlg1");} | |
76 | \item set up event tables as usual but use the {\tt XRCID(str)} macro to translate from XRC string names | |
77 | to a suitable integer identifier, for example {\tt EVT\_MENU(XRCID("quit"), MyFrame::OnQuit)}. | |
78 | \end{itemize} | |
79 | ||
80 | To 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}, a commercial dialog designer/RAD tool; | |
85 | \item use \urlref{XRCed}{http://www.mema.ucl.ac.be/~rolinsky/xrced/}, a wxPython-based | |
86 | dialog editor that you can find in the {\tt wxPython/tools} subdirectory of the wxWindows | |
87 | CVS archive; | |
88 | \item use \urlref{wxWorkshop}{http://wxworkshop.sourceforge.net} (under development); | |
89 | \item use wxrcedit ({\tt utils/contrib/wxrcedit}) (under development); | |
90 | \item convert WIN32 RC files to XRC with the tool in {\tt contrib/utils/convertrc}. | |
91 | \end{itemize} | |
92 | ||
93 | It is highly recommended that you use a tool such as wxDesigner, since it's fiddly writing | |
94 | XRC files by hand. | |
95 | ||
96 | You can use \helpref{wxXmlResource::Load}{wxxmlresourceload} in a number of ways. | |
97 | You can pass an XRC file (XML-based text resource file), an XMB file (compiled binary file) | |
98 | or a zip-compressed file (extension ZIP or RSC) containing other XRC or XMB files. | |
99 | ||
100 | TODO: is the compiled binary format XMB or XRS? How do you handle a C++ resource file? | |
101 | ||
102 | \subsection{Using binary resource files}\label{binaryresourcefiles} | |
103 | ||
104 | To compile binary resource files, use the command-line wxrc utility. It takes a single file parameter (the | |
105 | input XRC file) and the following switches and options. | |
106 | ||
107 | \begin{itemize}\itemsep=0 | |
108 | \item -h (--help): show a help message | |
109 | \item -v (--verbose): show verbose logging information | |
110 | \item -c (--cpp-code): write C++ source rather than a RSC file | |
111 | \item -u (--uncompressed): do not compress XML files (C++ only) | |
112 | \item -g (--gettext): output .po catalog (to stdout, or a file if -o is used) | |
113 | \item -n (--function) <name>: specify C++ function name (use with -c) | |
114 | \item -o (--output) <filename>: specify the output file, such as resource.xrs or resource.cpp | |
115 | \item -l (--list-of-handlers) <filename>: output a list of necessary handlers to this file | |
116 | \end{itemize} | |
117 | ||
118 | For example: | |
119 | ||
120 | \begin{verbatim} | |
121 | % wxrc resource.wrc | |
122 | % wxrc resource.wrc -o resource.wrs | |
123 | % wxrc resource.wrc -v -c -o resource.cpp | |
124 | \end{verbatim} | |
125 | ||
126 | \subsection{XRC C++ sample}\label{xrccppsample} | |
127 | ||
128 | This is the C++ source file (xrcdemo.cpp) for the XRC sample. | |
129 | ||
130 | \begin{verbatim} | |
131 | #include "wx/wx.h" | |
132 | #include "wx/image.h" | |
133 | #include "wx/xrc/xmlres.h" | |
134 | ||
135 | // the application icon | |
136 | #if defined(__WXGTK__) || defined(__WXMOTIF__) || defined(__WXMAC__) | |
137 | #include "rc/appicon.xpm" | |
138 | #endif | |
139 | ||
140 | // ---------------------------------------------------------------------------- | |
141 | // private classes | |
142 | // ---------------------------------------------------------------------------- | |
143 | ||
144 | // Define a new application type, each program should derive a class from wxApp | |
145 | class MyApp : public wxApp | |
146 | { | |
147 | public: | |
148 | // override base class virtuals | |
149 | // ---------------------------- | |
150 | ||
151 | // this one is called on application startup and is a good place for the app | |
152 | // initialization (doing it here and not in the ctor allows to have an error | |
153 | // return: if OnInit() returns false, the application terminates) | |
154 | virtual bool OnInit(); | |
155 | }; | |
156 | ||
157 | // Define a new frame type: this is going to be our main frame | |
158 | class MyFrame : public wxFrame | |
159 | { | |
160 | public: | |
161 | // ctor(s) | |
162 | MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size); | |
163 | ||
164 | // event handlers (these functions should _not_ be virtual) | |
165 | void OnQuit(wxCommandEvent& event); | |
166 | void OnAbout(wxCommandEvent& event); | |
167 | void OnDlg1(wxCommandEvent& event); | |
168 | void OnDlg2(wxCommandEvent& event); | |
169 | ||
170 | private: | |
171 | // any class wishing to process wxWindows events must use this macro | |
172 | DECLARE_EVENT_TABLE() | |
173 | }; | |
174 | ||
175 | // ---------------------------------------------------------------------------- | |
176 | // event tables and other macros for wxWindows | |
177 | // ---------------------------------------------------------------------------- | |
178 | ||
179 | BEGIN_EVENT_TABLE(MyFrame, wxFrame) | |
180 | EVT_MENU(XRCID("menu_quit"), MyFrame::OnQuit) | |
181 | EVT_MENU(XRCID("menu_about"), MyFrame::OnAbout) | |
182 | EVT_MENU(XRCID("menu_dlg1"), MyFrame::OnDlg1) | |
183 | EVT_MENU(XRCID("menu_dlg2"), MyFrame::OnDlg2) | |
184 | END_EVENT_TABLE() | |
185 | ||
186 | IMPLEMENT_APP(MyApp) | |
187 | ||
188 | // ---------------------------------------------------------------------------- | |
189 | // the application class | |
190 | // ---------------------------------------------------------------------------- | |
191 | ||
192 | // 'Main program' equivalent: the program execution "starts" here | |
193 | bool MyApp::OnInit() | |
194 | { | |
195 | wxImage::AddHandler(new wxGIFHandler); | |
196 | wxXmlResource::Get()->InitAllHandlers(); | |
197 | wxXmlResource::Get()->Load("rc/resource.xrc"); | |
198 | ||
199 | MyFrame *frame = new MyFrame("XML resources demo", | |
200 | wxPoint(50, 50), wxSize(450, 340)); | |
201 | frame->Show(TRUE); | |
202 | return TRUE; | |
203 | } | |
204 | ||
205 | // ---------------------------------------------------------------------------- | |
206 | // main frame | |
207 | // ---------------------------------------------------------------------------- | |
208 | ||
209 | // frame constructor | |
210 | MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size) | |
211 | : wxFrame((wxFrame *)NULL, -1, title, pos, size) | |
212 | { | |
213 | SetIcon(wxICON(appicon)); | |
214 | ||
215 | SetMenuBar(wxXmlResource::Get()->LoadMenuBar("mainmenu")); | |
216 | SetToolBar(wxXmlResource::Get()->LoadToolBar(this, "toolbar")); | |
217 | } | |
218 | ||
219 | // event handlers | |
220 | void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event)) | |
221 | { | |
222 | // TRUE is to force the frame to close | |
223 | Close(TRUE); | |
224 | } | |
225 | ||
226 | void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event)) | |
227 | { | |
228 | wxString msg; | |
229 | msg.Printf( _T("This is the about dialog of XML resources demo.\n") | |
230 | _T("Welcome to %s"), wxVERSION_STRING); | |
231 | ||
232 | wxMessageBox(msg, "About XML resources demo", wxOK | wxICON_INFORMATION, this); | |
233 | } | |
234 | ||
235 | void MyFrame::OnDlg1(wxCommandEvent& WXUNUSED(event)) | |
236 | { | |
237 | wxDialog dlg; | |
238 | wxXmlResource::Get()->LoadDialog(&dlg, this, "dlg1"); | |
239 | dlg.ShowModal(); | |
240 | } | |
241 | ||
242 | void MyFrame::OnDlg2(wxCommandEvent& WXUNUSED(event)) | |
243 | { | |
244 | wxDialog dlg; | |
245 | wxXmlResource::Get()->LoadDialog(&dlg, this, "dlg2"); | |
246 | dlg.ShowModal(); | |
247 | } | |
248 | \end{verbatim} | |
249 | ||
250 | \subsection{XRC resource file sample}\label{xrcsample} | |
251 | ||
252 | This is the XML file (resource.xrc) for the XRC sample. | |
253 | ||
254 | \begin{verbatim} | |
255 | <?xml version="1.0"?> | |
256 | <resource version="2.3.0.1"> | |
257 | <object class="wxMenuBar" name="mainmenu"> | |
258 | <style>wxMB_DOCKABLE</style> | |
259 | <object class="wxMenu" name="menu_file"> | |
260 | <label>_File</label> | |
261 | <style>wxMENU_TEAROFF</style> | |
262 | <object class="wxMenuItem" name="menu_about"> | |
263 | <label>_About...</label> | |
264 | <bitmap>filesave.gif</bitmap> | |
265 | </object> | |
266 | <object class="separator"/> | |
267 | <object class="wxMenuItem" name="menu_dlg1"> | |
268 | <label>Dialog 1</label> | |
269 | </object> | |
270 | <object class="wxMenuItem" name="menu_dlg2"> | |
271 | <label>Dialog 2</label> | |
272 | </object> | |
273 | <object class="separator"/> | |
274 | <object class="wxMenuItem" name="menu_quit"> | |
275 | <label>E_xit\tAlt-X</label> | |
276 | </object> | |
277 | </object> | |
278 | </object> | |
279 | <object class="wxToolBar" name="toolbar"> | |
280 | <style>wxTB_FLAT|wxTB_DOCKABLE</style> | |
281 | <margins>2,2</margins> | |
282 | <object class="tool" name="menu_open"> | |
283 | <bitmap>fileopen.gif</bitmap> | |
284 | <tooltip>Open catalog</tooltip> | |
285 | </object> | |
286 | <object class="tool" name="menu_save"> | |
287 | <bitmap>filesave.gif</bitmap> | |
288 | <tooltip>Save catalog</tooltip> | |
289 | </object> | |
290 | <object class="tool" name="menu_update"> | |
291 | <bitmap>update.gif</bitmap> | |
292 | <tooltip>Update catalog - synchronize it with sources</tooltip> | |
293 | </object> | |
294 | <separator/> | |
295 | <object class="tool" name="menu_quotes"> | |
296 | <bitmap>quotes.gif</bitmap> | |
297 | <toggle>1</toggle> | |
298 | <tooltip>Display quotes around the string?</tooltip> | |
299 | </object> | |
300 | <object class="separator"/> | |
301 | <object class="tool" name="menu_fuzzy"> | |
302 | <bitmap>fuzzy.gif</bitmap> | |
303 | <tooltip>Toggled if selected string is fuzzy translation</tooltip> | |
304 | <toggle>1</toggle> | |
305 | </object> | |
306 | </object> | |
307 | <object class="wxDialog" name="dlg1"> | |
308 | <object class="wxBoxSizer"> | |
309 | <object class="sizeritem"> | |
310 | <object class="wxBitmapButton"> | |
311 | <bitmap>fuzzy.gif</bitmap> | |
312 | <focus>fileopen.gif</focus> | |
313 | </object> | |
314 | </object> | |
315 | <object class="sizeritem"> | |
316 | <object class="wxPanel"> | |
317 | <object class="wxStaticText"> | |
318 | <label>fdgdfgdfgdfg</label> | |
319 | </object> | |
320 | <style>wxSUNKEN_BORDER</style> | |
321 | </object> | |
322 | <flag>wxALIGN_CENTER</flag> | |
323 | </object> | |
324 | <object class="sizeritem"> | |
325 | <object class="wxButton"> | |
326 | <label>Buttonek</label> | |
327 | </object> | |
328 | <border>10d</border> | |
329 | <flag>wxALL</flag> | |
330 | </object> | |
331 | <object class="sizeritem"> | |
332 | <object class="wxHtmlWindow"> | |
333 | <htmlcode><h1>Hi,</h1>man</htmlcode> | |
334 | <size>100,45d</size> | |
335 | </object> | |
336 | </object> | |
337 | <object class="sizeritem"> | |
338 | <object class="wxNotebook"> | |
339 | <object class="notebookpage"> | |
340 | <object class="wxPanel"> | |
341 | <object class="wxBoxSizer"> | |
342 | <object class="sizeritem"> | |
343 | <object class="wxHtmlWindow"> | |
344 | <htmlcode>Hello, we are inside a <u>NOTEBOOK</u>...</htmlcode> | |
345 | <size>50,50d</size> | |
346 | </object> | |
347 | <option>1</option> | |
348 | </object> | |
349 | </object> | |
350 | </object> | |
351 | <label>Page</label> | |
352 | </object> | |
353 | <object class="notebookpage"> | |
354 | <object class="wxPanel"> | |
355 | <object class="wxBoxSizer"> | |
356 | <object class="sizeritem"> | |
357 | <object class="wxHtmlWindow"> | |
358 | <htmlcode>Hello, we are inside a <u>NOTEBOOK</u>...</htmlcode> | |
359 | <size>50,50d</size> | |
360 | </object> | |
361 | </object> | |
362 | </object> | |
363 | </object> | |
364 | <label>Page 2</label> | |
365 | </object> | |
366 | <usenotebooksizer>1</usenotebooksizer> | |
367 | </object> | |
368 | <flag>wxEXPAND</flag> | |
369 | </object> | |
370 | <orient>wxVERTICAL</orient> | |
371 | </object> | |
372 | </object> | |
373 | <object class="wxDialog" name="dlg2"> | |
374 | <object class="wxBoxSizer"> | |
375 | <orient>wxVERTICAL</orient> | |
376 | <object class="sizeritem" name="dfgdfg"> | |
377 | <object class="wxTextCtrl"> | |
378 | <size>200,200d</size> | |
379 | <style>wxTE_MULTILINE|wxSUNKEN_BORDER</style> | |
380 | <value>Hello, this is an ordinary multiline\n textctrl....</value> | |
381 | </object> | |
382 | <option>1</option> | |
383 | <flag>wxEXPAND|wxALL</flag> | |
384 | <border>10</border> | |
385 | </object> | |
386 | <object class="sizeritem"> | |
387 | <object class="wxBoxSizer"> | |
388 | <object class="sizeritem"> | |
389 | <object class="wxButton" name="wxID_OK"> | |
390 | <label>Ok</label> | |
391 | <default>1</default> | |
392 | </object> | |
393 | </object> | |
394 | <object class="sizeritem"> | |
395 | <object class="wxButton" name="wxID_CANCEL"> | |
396 | <label>Cancel</label> | |
397 | </object> | |
398 | <border>10</border> | |
399 | <flag>wxLEFT</flag> | |
400 | </object> | |
401 | </object> | |
402 | <flag>wxLEFT|wxRIGHT|wxBOTTOM|wxALIGN_RIGHT</flag> | |
403 | <border>10</border> | |
404 | </object> | |
405 | </object> | |
406 | <title>Second testing dialog</title> | |
407 | </object> | |
408 | </resource> | |
409 | \end{verbatim} | |
410 | ||
411 | \subsection{XRC file format}\label{xrcfileformat} | |
412 | ||
413 | Please see Technical Note 14 (docs/tech/tn0014.txt) in your wxWindows | |
414 | distribution. | |
415 | ||
416 | \subsection{Adding new resource handlers}\label{newresourcehandlers} | |
417 | ||
418 | Coming soon. | |
419 |