]> git.saurik.com Git - wxWidgets.git/blame - contrib/docs/latex/deprecated/tresourc.tex
test undividable words
[wxWidgets.git] / contrib / docs / latex / deprecated / tresourc.tex
CommitLineData
82e20720
JS
1\section{The wxWindows resource system}\label{resourceformats}
2
3wxWindows has an optional {\it resource file} facility,
4which allows separation of dialog, menu, bitmap and icon specifications
5from the application code.
6
7{\bf NOTE:} this format is now deprecated in favour of the XML-based \helpref{XRC resource system}{xrcoverview}.
8However it is still available if wxUSE\_RESOURCES is enabled.
9
10The format is similar in principle to the Windows resource file (whose ASCII form is
11suffixed .RC and whose binary form is suffixed .RES). The wxWindows resource
12file is currently ASCII-only, suffixed .WXR. Note that under Windows,
13the .WXR file does not {\it replace} the native Windows resource file,
14it merely supplements it. There is no existing native resource format in X
15(except for the defaults file, which has limited expressive power).
16
17For details of functions for manipulating resource files and loading
18user interface elements, see \helpref{wxWindows resource functions}{resourcefuncs}.
19
20You can use Dialog Editor to create resource files. Unfortunately neither
21Dialog Editor nor the .WXR format currently cover all wxWindows controls;
22some are missing, such as wxSpinCtrl, wxSpinButton, wxListCtrl, wxTreeCtrl and others.
23
24Note that in later versions of wxWindows, this resource format will be replaced
25by XML specifications that can also include sizers.
26
27\subsection{The format of a .WXR file}
28
29A wxWindows resource file may look a little odd at first. It is C++
30compatible, comprising mostly of static string variable declarations with
31wxExpr syntax within the string.
32
33Here's a sample .WXR file:
34
35\begin{verbatim}
36/*
37 * wxWindows Resource File
38 *
39 */
40
41#include "noname.ids"
42
43static char *my_resource = "bitmap(name = 'my_resource',\
44 bitmap = ['myproject', wxBITMAP_TYPE_BMP_RESOURCE, 'WINDOWS'],\
45 bitmap = ['myproject.xpm', wxBITMAP_TYPE_XPM, 'X']).";
46
47static char *menuBar11 = "menu(name = 'menuBar11',\
48 menu = \
49 [\
50 ['&File', 1, '', \
51 ['&Open File', 2, 'Open a file'],\
52 ['&Save File', 3, 'Save a file'],\
53 [],\
54 ['E&xit', 4, 'Exit program']\
55 ],\
56 ['&Help', 5, '', \
57 ['&About', 6, 'About this program']\
58 ]\
59 ]).";
60
61static char *project_resource = "icon(name = 'project_resource',\
62 icon = ['project', wxBITMAP_TYPE_ICO_RESOURCE, 'WINDOWS'],\
63 icon = ['project_data', wxBITMAP_TYPE_XBM, 'X']).";
64
65static char *panel3 = "dialog(name = 'panel3',\
66 style = '',\
67 title = 'untitled',\
68 button_font = [14, 'wxSWISS', 'wxNORMAL', 'wxBOLD', 0],\
69 label_font = [10, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],\
70 x = 0, y = 37, width = 292, height = 164,\
71 control = [1000, wxButton, 'OK', '', 'button5', 23, 34, -1, -1, 'my_resource'],\
72 control = [1001, wxStaticText, 'A Label', '', 'message7', 166, 61, -1, -1, 'my_resource'],\
73 control = [1002, wxTextCtrl, 'Text', 'wxTE_MULTITEXT', 'text8', 24, 110, -1, -1]).";
74\end{verbatim}
75
76As you can see, C++-style comments are allowed, and apparently include files
77are supported too: but this is a special case, where the included file
78is a file of defines shared by the C++ application code and resource file
79to relate identifiers (such as FILE\_OPEN) to integers.
80
81Each {\it resource object} is of standard \helpref{wxExpr}{wxexpr} syntax, that is,
82an object name such as {\bf dialog} or {\bf icon}, then an open
83parenthesis, a list of comma-delimited attribute/value pairs, a closing
84parenthesis, and a full stop. Backslashes are required to escape newlines,
85for the benefit of C++ syntax. If double quotation marks are used to
86delimit strings, they need to be escaped with backslash within a C++ string
87(so it is easier to use single quotation marks instead).
88
89\normalbox{{\it A note on string syntax:} A string that begins with
90an alphabetic character, and contains only alphanumeric characters,
91hyphens and underscores, need not be quoted at all. Single quotes and double
92quotes may be used to delimit more complex strings. In fact, single-quoted
93and no-quoted strings are actually called {\it words}, but are treated
94as strings for the purpose of the resource system.}
95
96A resource file like this is typically included in the application main file,
97as if it were a normal C++ file. This eliminates the need for a separate
98resource file to be distributed alongside the executable. However, the
99resource file can be dynamically loaded if desired (useful for non-C++
100languages such as Python).
101
102Once included, the resources need to be `parsed' (interpreted), because
103so far the data is just a number of static string variables. The function\rtfsp
104{\bf ::wxResourceParseData} is called early on in initialization of the application
105(usually in {\bf wxApp::OnInit}) with a variable as argument. This may need to be
106called a number of times, one for each variable. However, more than one
107resource `object' can be stored in one string variable at a time, so you can
108get all your resources into one variable if you want to.
109
110{\bf ::wxResourceParseData} parses the contents of the resource, ready for use
111by functions such as {\bf ::wxResourceCreateBitmap} and {\bf wxPanel::LoadFromResource}.
112
113If a wxWindows resource object (such as a bitmap resource) refers to a
114C++ data structure, such as static XPM data, a further call ({\bf ::wxResourceRegisterBitmapData}) needs
115to be made on initialization to tell
116wxWindows about this data. The wxWindows resource object will refer to a
117string identifier, such as `project\_data' in the example file above.
118This identifier will be looked up in a table to get the C++ static data
119to use for the bitmap or icon.
120
121In the C++ fragment below, the WXR resource file is included,
122and appropriate resource initialization is carried out in {\bf OnInit}.
123Note that at this stage, no actual wxWindows dialogs, menus, bitmaps or
124icons are created; their `templates' are merely being set up for later
125use.
126
127\begin{verbatim}
128/*
129 * File: project.cpp
130 * Purpose: main application module
131 */
132
133#include "wx/wx.h"
134#include "project.h"
135
136// Includes the dialog, menu etc. resources
137#include "project.wxr"
138
139// Includes XPM data
140#include "project.xpm"
141
142IMPLEMENT_APP(AppClass)
143
144// Called to initialize the program
145bool AppClass::OnInit()
146{
147 wxResourceRegisterBitmapData("project_data", project_bits, project_width, project_height);
148
149 wxResourceParseData(menuBar11);
150 wxResourceParseData(my_resource);
151 wxResourceParseData(project_resource);
152 wxResourceParseData(panel3);
153 ...
154
155 return true;
156}
157\end{verbatim}
158
159The following code shows a dialog:
160
161\begin{verbatim}
162 // project.wxr contains dialog1
163 MyDialog *dialog = new MyDialog;
164 if (dialog->LoadFromResource(this, "dialog1"))
165 {
166 wxTextCtrl *text = (wxTextCtrl *)wxFindWindowByName("text3", dialog);
167 if (text)
168 text->SetValue("wxWindows resource demo");
169 dialog->ShowModal();
170 }
171 dialog->Destroy();
172\end{verbatim}
173
174Please see also the resource sample.
175
176\subsection{Dialog resource format}
177
178A dialog resource object may be used for either panels or dialog boxes, and
179consists of the following attributes. In the following, a {\it font specification}\rtfsp
180is a list consisting of point size, family, style, weight, underlined, optional facename.
181
182\begin{twocollist}\itemsep=0pt
183\twocolitemruled{Attribute}{Value}
184\twocolitem{id}{The integer identifier of the resource.}
185\twocolitem{name}{The name of the resource.}
186\twocolitem{style}{Optional dialog box or panel window style.}
187\twocolitem{title}{The title of the dialog box (unused if a panel).}.
188\twocolitem{modal}{Whether modal: 1 if modal, 0 if modeless, absent if a panel resource.}
189\twocolitem{use\_dialog\_units}{If 1, use dialog units (dependent on the dialog font size) for control sizes and positions.}
190\twocolitem{use\_system\_defaults}{If 1, override colours and fonts to use system settings instead.}
191\twocolitem{button\_font}{The font used for control buttons: a list comprising point size (integer),
192family (string), font style (string), font weight (string) and underlining (0 or 1).}
193\twocolitem{label\_font}{The font used for control labels: a list comprising point size (integer),
194family (string), font style (string), font weight (string) and underlining (0 or 1). Now obsolete; use button\_font instead.}
195\twocolitem{x}{The x position of the dialog or panel.}
196\twocolitem{y}{The y position of the dialog or panel.}
197\twocolitem{width}{The width of the dialog or panel.}
198\twocolitem{height}{The height of the dialog or panel.}
199\twocolitem{background\_colour}{The background colour of the dialog or panel.}
200\twocolitem{label\_colour}{The default label colour for the children of the dialog or panel. Now obsolete; use button\_colour instead.}
201\twocolitem{button\_colour}{The default button text colour for the children of the dialog or panel.}
202\end{twocollist}
203
204Then comes zero or more attributes named `control' for each control
205(panel item) on the dialog or panel. The value is a list of further
206elements. In the table below, the names in the first column correspond to
207the first element of the value list, and the second column details the
208remaining elements of the list. Note that titles for some controls are obsolete
209(they don't have titles), but the syntax is retained for backward compatibility.
210
211\begin{twocollist}\itemsep=0pt
212\twocolitemruled{Control}{Values}
213\twocolitem{wxButton}{id (integer), title (string), window style (string), name (string), x, y, width, height, button bitmap resource (optional string), button font spec}
214\twocolitem{wxCheckBox}{id (integer), title (string), window style (string), name (string), x, y, width, height, default value (optional integer, 1 or 0), label font spec}
215\twocolitem{wxChoice}{id (integer), title (string), window style (string), name (string), x, y, width, height, values (optional list of strings), label font spec, button font spec}
216\twocolitem{wxComboBox}{id (integer), title (string), window style (string), name (string), x, y, width, height, default text value, values (optional list of strings), label font spec, button font spec}
217\twocolitem{wxGauge}{id (integer), title (string), window style (string), name (string), x, y, width, height, value (optional integer), range (optional integer), label font spec, button font spec}
218\twocolitem{wxStaticBox}{id (integer), title (string), window style (string), name (string), x, y, width, height, label font spec}
219\twocolitem{wxListBox}{id (integer), title (string), window style (string), name (string), x, y, width, height, values (optional list of strings), multiple (optional string, wxSINGLE or wxMULTIPLE),
220label font spec, button font spec}
221\twocolitem{wxStaticText}{id (integer), title (string), window style (string), name (string), x, y, width, height, message bitmap resource (optional string), label font spec}
222\twocolitem{wxRadioBox}{id (integer), title (string), window style (string), name (string), x, y, width, height, values (optional list of strings), number of rows or cols,
223label font spec, button font spec}
224\twocolitem{wxRadioButton}{id (integer), title (string), window style (string), name (string), x, y, width, height, default value (optional integer, 1 or 0), label font spec}
225\twocolitem{wxScrollBar}{id (integer), title (string), window style (string), name (string), x, y, width, height, value (optional integer),
226page length (optional integer), object length (optional integer), view length (optional integer)}
227\twocolitem{wxSlider}{id (integer), title (string), window style (string), name (string), x, y, width, height, value (optional integer), minimum (optional integer), maximum (optional integer),
228label font spec, button font spec}
229\twocolitem{wxTextCtrl}{id (integer), title (string), window style (string), name (string), x, y, width, height, default value (optional string),
230label font spec, button font spec}
231\end{twocollist}
232
233\subsection{Menubar resource format}
234
235A menubar resource object consists of the following attributes.
236
237\begin{twocollist}\itemsep=0pt
238\twocolitemruled{Attribute}{Value}
239\twocolitem{name}{The name of the menubar resource.}
240\twocolitem{menu}{A list containing all the menus, as detailed below.}
241\end{twocollist}
242
243The value of the {\bf menu} attribute is a list of menu item specifications, where each menu
244item specification is itself a list comprising:
245
246\begin{itemize}\itemsep=0pt
247\item title (a string)
248\item menu item identifier (a string or non-zero integer, see below)
249\item help string (optional)
250\item 0 or 1 for the `checkable' parameter (optional)
251\item optionally, further menu item specifications if this item is a pulldown menu.
252\end{itemize}
253
254If the menu item specification is the empty list ([]), this is interpreted as a menu separator.
255
256If further (optional) information is associated with each menu item in a future release of wxWindows,
257it will be placed after the help string and before the optional pulldown menu specifications.
258
259Note that the menu item identifier must be an integer if the resource is being
260included as C++ code and then parsed on initialisation. Unfortunately,\rtfsp
261\#define substitution is not performed inside strings, and
262therefore the program cannot know the mapping. However, if the .WXR file
263is being loaded dynamically, wxWindows will attempt to replace string
264identifiers with \#defined integers, because it is able to parse
265the included \#defines.
266
267\subsection{Bitmap resource format}
268
269A bitmap resource object consists of a name attribute, and one or more {\bf bitmap} attributes.
270There can be more than one of these to allow specification of bitmaps that are optimum for the
271platform and display.
272
273\begin{itemize}\itemsep=0pt
274\item Bitmap name or filename.
275\item Type of bitmap; for example, wxBITMAP\_TYPE\_BMP\_RESOURCE. See class reference under {\bf wxBitmap} for
276a full list).
277\item Platform this bitmap is valid for; one of WINDOWS, X, MAC and ANY.
278\item Number of colours (optional).
279\item X resolution (optional).
280\item Y resolution (optional).
281\end{itemize}
282
283\subsection{Icon resource format}
284
285An icon resource object consists of a name attribute, and one or more {\bf icon} attributes.
286There can be more than one of these to allow specification of icons that are optimum for the
287platform and display.
288
289\begin{itemize}\itemsep=0pt
290\item Icon name or filename.
291\item Type of icon; for example, wxBITMAP\_TYPE\_ICO\_RESOURCE. See class reference under {\bf wxBitmap} for
292a full list).
293\item Platform this bitmap is valid for; one of WINDOWS, X, MAC and ANY.
294\item Number of colours (optional).
295\item X resolution (optional).
296\item Y resolution (optional).
297\end{itemize}
298
299\subsection{Resource format design issues}
300
301The .WXR file format is a recent addition and subject to change.
302The use of an ASCII resource file format may seem rather inefficient, but this
303choice has a number of advantages:
304
305\begin{itemize}\itemsep=0pt
306\item Since it is C++ compatible, it can be included into an application's source code,
307eliminating the problems associated with distributing a separate resource file
308with the executable. However, it can also be loaded dynamically from a file, which will be required
309for non-C++ programs that use wxWindows.
310\item No extra binary file format and separate converter need be maintained for the wxWindows project
311(although others are welcome to add the equivalent of the Windows `rc' resource
312parser and a binary format).
313\item It would be difficult to append a binary resource component onto an executable
314in a portable way.
315\item The file format is essentially the \helpref{wxExpr}{wxexpr} object format, for which
316a parser already exists, so parsing is easy. For those programs that use wxExpr
317anyway, the size overhead of the parser is minimal.
318\end{itemize}
319
320The disadvantages of the approach include:
321
322\begin{itemize}\itemsep=0pt
323\item Parsing adds a small execution overhead to program initialization.
324\item Under 16-bit Windows especially, global data is at a premium.
325Using a .RC resource table for some wxWindows resource data may be a partial solution,
326although .RC strings are limited to 255 characters.
327\item Without a resource preprocessor, it is not possible to substitute integers
328for identifiers (so menu identifiers have to be written as integers in the resource
329object, in addition to providing \#defines for application code convenience).
330\end{itemize}
331
332\subsection{Compiling the resource system}
333
334To enable the resource system, set {\bf wxUSE\_WX\_RESOURCES} to 1 in setup.h.
335