]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: xrc_format.h | |
3 | // Purpose: XRC format specification | |
4 | // Author: Vaclav Slavik | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | ||
10 | /* | |
11 | NOTE: To make doxygen happy about <custom-tags> we're forced to | |
12 | escape all < and > symbols which appear inside a doxygen comment. | |
13 | Also, don't use < and > symbols in section titles. | |
14 | */ | |
15 | ||
16 | ||
17 | /** | |
18 | ||
19 | @page overview_xrcformat XRC File Format | |
20 | ||
21 | Table of contents: | |
22 | - @ref overview_xrcformat_overview | |
23 | - @ref overview_xrcformat_root | |
24 | - @ref overview_xrcformat_objects | |
25 | - @ref overview_xrcformat_object | |
26 | - @ref overview_xrcformat_object_ref | |
27 | - @ref overview_xrcformat_datatypes | |
28 | - @ref overview_xrcformat_windows | |
29 | - @ref overview_xrcformat_std_props | |
30 | - @ref overview_xrcformat_controls | |
31 | - @ref overview_xrcformat_sizers | |
32 | - @ref overview_xrcformat_other_objects | |
33 | - @ref overview_xrcformat_platform | |
34 | - @ref overview_xrcformat_extending | |
35 | - @ref overview_xrcformat_extending_subclass | |
36 | - @ref overview_xrcformat_extending_unknown | |
37 | - @ref overview_xrcformat_extending_custom | |
38 | - @ref overview_xrcformat_packed | |
39 | - @ref overview_xrcformat_oldversions | |
40 | ||
41 | This document describes the format of XRC resource files, as used by wxXmlResource. | |
42 | ||
43 | ||
44 | <hr> | |
45 | ||
46 | ||
47 | @section overview_xrcformat_overview Overview | |
48 | ||
49 | XRC file is a XML file with all of its elements in the | |
50 | @c http://www.wxwidgets.org/wxxrc namespace. For backward compatibility, | |
51 | @c http://www.wxwindows.org/wxxrc namespace is accepted as well (and treated | |
52 | as identical to @c http://www.wxwidgets.org/wxxrc), but it shouldn't be used | |
53 | in new XRC files. | |
54 | ||
55 | XRC file contains definitions for one or more @em objects -- typically | |
56 | windows. The objects may themselves contain child objects. | |
57 | ||
58 | Objects defined at the top level, under the | |
59 | @ref overview_xrcformat_root "root element", can be accessed using | |
60 | wxXmlResource::LoadDialog() and other LoadXXX methods. They must have | |
61 | @c name attribute that is used as LoadXXX's argument (see | |
62 | @ref overview_xrcformat_object for details). | |
63 | ||
64 | Child objects are not directly accessible via wxXmlResource, they can only | |
65 | be accessed using XRCCTRL(). | |
66 | ||
67 | ||
68 | @section overview_xrcformat_root Resource Root Element | |
69 | ||
70 | The root element is always @c \<resource\>. It has one optional attribute, @c | |
71 | version. If set, it specifies version of the file. In absence of @c version | |
72 | attribute, the default is @c "0.0.0.0". | |
73 | ||
74 | The version consists of four integers separated by periods. The first three | |
75 | components are major, minor and release number of the wxWidgets release when | |
76 | the change was introduced, the last one is revision number and is 0 for the | |
77 | first incompatible change in given wxWidgets release, 1 for the second and so | |
78 | on. The version changes only if there was an incompatible change introduced; | |
79 | merely adding new kind of objects does not constitute incompatible change. | |
80 | ||
81 | At the time of writing, the latest version is @c "2.5.3.0". | |
82 | ||
83 | Note that even though @c version attribute is optional, it should always be | |
84 | specified to take advantage of the latest capabilities: | |
85 | ||
86 | @code | |
87 | <?xml version="1.0"?> | |
88 | <resource xmlns="http://www.wxwidgets.org/wxxrc" version="2.5.3.0"> | |
89 | ... | |
90 | </resource> | |
91 | @endcode | |
92 | ||
93 | @c \<resource\> may have arbitrary number of | |
94 | @ref overview_xrcformat_objects "object elements" as its children; they are referred | |
95 | to as @em toplevel objects in the rest of this document. Unlike objects defined | |
96 | deeper in the hierarchy, toplevel objects @em must have their @c name attribute | |
97 | set and it must be set to a value unique among root's children. | |
98 | ||
99 | ||
100 | ||
101 | @section overview_xrcformat_objects Defining Objects | |
102 | ||
103 | @subsection overview_xrcformat_object Object Element | |
104 | ||
105 | The @c \<object\> element represents a single object (typically a GUI element) | |
106 | and it usually maps directly to a wxWidgets class instance. It has one | |
107 | mandatory attribute, @c class, and optional @c name and @c subclass attributes. | |
108 | ||
109 | The @c class attribute must always be present, it tells XRC what wxWidgets | |
110 | object should be created and by which wxXmlResourceHandler. | |
111 | ||
112 | @c name is the identifier used to identify the object. This name serves three | |
113 | purposes: | |
114 | ||
115 | -# It is used by wxXmlResource's various LoadXXX() methods to find the | |
116 | resource by name passed as argument. | |
117 | -# wxWindow's name (see wxWindow::GetName()) is set to it. | |
118 | -# Numeric ID of a window or menu item is derived from the name. | |
119 | If the value represents an integer (in decimal notation), it is used for | |
120 | the numeric ID unmodified. If it is one of the wxID_XXX literals defined | |
121 | by wxWidgets (see @ref page_stockitems), its respective value is used. | |
122 | Otherwise, the name is transformed into dynamically generated ID. See | |
123 | wxXmlResource::GetXRCID() for more information. | |
124 | ||
125 | Name attributes must be unique at the top level (where the name is used to | |
126 | load resources) and should be unique among all controls within the same | |
127 | toplevel window (wxDialog, wxFrame). | |
128 | ||
129 | The @c subclass attribute optional name of class whose constructor will be | |
130 | called instead of the constructor for "class". | |
131 | See @ref overview_xrcformat_extending_subclass for more details. | |
132 | ||
133 | @c \<object\> element may -- and almost always do -- have children elements. | |
134 | These come in two varieties: | |
135 | ||
136 | -# Object's properties. A @em property is a value describing part of object's | |
137 | behaviour, for example the "label" property on wxButton defines its label. | |
138 | In the most common form, property is a single element with text content | |
139 | ("<label>Cancel</label>"), but they may use nested subelements too (e.g. | |
140 | @ref overview_xrcformat_type_font "font property"). A property can only be | |
141 | listed once in an object's definition. | |
142 | -# Child objects. Window childs, sizers, sizer items or notebook pages | |
143 | are all examples of child objects. They are represented using nested | |
144 | @c \<object\> elements and are can be repeated more than once. The specifics | |
145 | of which object classes are allowed as children are class-specific and | |
146 | are documented below in @ref overview_xrcformat_controls. | |
147 | ||
148 | Example: | |
149 | @code | |
150 | <object class="wxDialog" name="example_dialog"> | |
151 | <!-- properties: --> | |
152 | <title>Non-Derived Dialog Example</title> | |
153 | <centered>1</centered> | |
154 | <!-- child objects: --> | |
155 | <object class="wxBoxSizer"> | |
156 | <orient>wxVERTICAL</orient> | |
157 | <cols>1</cols> | |
158 | <rows>0</rows> | |
159 | ... | |
160 | </object> | |
161 | </object> | |
162 | @endcode | |
163 | ||
164 | ||
165 | @subsection overview_xrcformat_object_ref Object References | |
166 | ||
167 | Anywhere an @c \<object\> element can be used, @c \<object_ref\> may be used | |
168 | instead. @c \<object_ref\> is a @em reference to another named (i.e. with the | |
169 | @c name attribute) @c \<object\> element. It has one mandatory attribute, | |
170 | @c ref, with value containing the name of a named @c \<object\> element. When an | |
171 | @c \<object_ref\> is encountered, a copy of the referenced @c \<object\> element | |
172 | is made in place of @c \<object_ref\> occurrence and processed as usual. | |
173 | ||
174 | For example, the following code: | |
175 | @code | |
176 | <object class="wxDialog" name="my_dlg"> | |
177 | ... | |
178 | </object> | |
179 | <object_ref name="my_dlg_alias" ref="my_dlg"/> | |
180 | @endcode | |
181 | is equivalent to | |
182 | @code | |
183 | <object class="wxDialog" name="my_dlg"> | |
184 | ... | |
185 | </object> | |
186 | <object class="wxDialog" name="my_dlg_alias"> | |
187 | ... <!-- same as in my_dlg --> | |
188 | </object> | |
189 | @endcode | |
190 | ||
191 | Additionally, it is possible to override some parts of the referenced object | |
192 | in the @c \<object_ref\> pointing to it. This is useful for putting repetitive | |
193 | parts of XRC definitions into a template that can be reused and customized in | |
194 | several places. The two parts are merged as follows: | |
195 | ||
196 | -# The referred object is used as the initial content. | |
197 | -# All attributes set on @c \<object_ref\> are added to it. | |
198 | -# All child elements of @c \<object_ref\> are scanned. If an element with | |
199 | the same name (and, if specified, the @c name attribute too) is found | |
200 | in the referred object, they are recursively merged. | |
201 | -# Child elements in @c \<object_ref\> that do not have a match in the referred | |
202 | object are appended to the list of children of the resulting element by | |
203 | default. Optionally, they may have @c insert_at attribute with two possible | |
204 | values, "begin" or "end". When set to "begin", the element is prepended to | |
205 | the list of children instead of appended. | |
206 | ||
207 | For example, "my_dlg" in this snippet: | |
208 | @code | |
209 | <object class="wxDialog" name="template"> | |
210 | <title>Dummy dialog</title> | |
211 | <size>400,400</size> | |
212 | </object> | |
213 | <object_ref ref="template" name="my_dlg"> | |
214 | <title>My dialog</title> | |
215 | <centered>1</centered> | |
216 | </object> | |
217 | @endcode | |
218 | is identical to: | |
219 | @code | |
220 | <object_ref ref="template" name="my_dlg"> | |
221 | <title>My dialog</title> | |
222 | <size>400,400</size> | |
223 | <centered>1</centered> | |
224 | </object> | |
225 | @endcode | |
226 | ||
227 | ||
228 | @section overview_xrcformat_datatypes Data Types | |
229 | ||
230 | There are several property data types that are frequently reused by different | |
231 | properties. Rather than describing their format in the documentation of | |
232 | every property, we list commonly used types in this section and document | |
233 | their format. | |
234 | ||
235 | ||
236 | @subsection overview_xrcformat_type_bool Boolean | |
237 | ||
238 | Boolean values are expressed using either "1" literal (true) or "0" (false). | |
239 | ||
240 | ||
241 | @subsection overview_xrcformat_type_float Floating-point value | |
242 | ||
243 | Floating point values use POSIX (C locale) formatting -- decimal separator | |
244 | is "." regardless of the locale. | |
245 | ||
246 | ||
247 | @subsection overview_xrcformat_type_colour Colour | |
248 | ||
249 | Colour specification can be either any string colour representation accepted | |
250 | by wxColour::Set() or any wxSYS_COLOUR_XXX symbolic name accepted by | |
251 | wxSystemSettings::GetColour(). In particular, the following forms are supported: | |
252 | ||
253 | @li named colours from wxColourDatabase | |
254 | @li HTML-like "#rrggbb" syntax (but not "#rgb") | |
255 | @li CSS-style "rgb(r,g,b)" and "rgba(r,g,b,a)" | |
256 | @li wxSYS_COLOUR_XXX symbolic names | |
257 | ||
258 | Some examples: | |
259 | @code | |
260 | <fg>red</fg> | |
261 | <fg>#ff0000</fg> | |
262 | <fg>rgb(255,0,0)</fg> | |
263 | <fg>wxSYS_COLOUR_HIGHLIGHT</fg> | |
264 | @endcode | |
265 | ||
266 | ||
267 | @subsection overview_xrcformat_type_size Size | |
268 | ||
269 | Sizes and positions have the form of string with two comma-separated integer | |
270 | components, with optional "d" suffix. Semi-formally: | |
271 | ||
272 | size := x "," y ["d"] | |
273 | ||
274 | where x and y are integers. Either of the components (or both) may be "-1" to | |
275 | signify default value. As a shortcut, empty string is equivalent to "-1,-1" | |
276 | (= wxDefaultSize or wxDefaultPosition). | |
277 | ||
278 | When the "d" suffix is used, integer values are interpreted as | |
279 | @ref wxWindow::ConvertDialogToPixels() "dialog units" in the parent window. | |
280 | ||
281 | Examples: | |
282 | @code | |
283 | 42,-1 | |
284 | 100,100 | |
285 | 100,50d | |
286 | @endcode | |
287 | ||
288 | @subsection overview_xrcformat_type_pos Position | |
289 | ||
290 | Same as @ref overview_xrcformat_type_size. | |
291 | ||
292 | ||
293 | @subsection overview_xrcformat_type_dimension Dimension | |
294 | ||
295 | Similarly to @ref overview_xrcformat_type_size "sizes", dimensions are expressed | |
296 | as integers with optional "d" suffix. When "d" suffix is used, the integer | |
297 | preceding it is interpreted as dialog units in the parent window. | |
298 | ||
299 | ||
300 | @subsection overview_xrcformat_type_text Text | |
301 | ||
302 | String properties use several escape sequences that are translated according to | |
303 | the following table: | |
304 | @beginDefList | |
305 | @itemdef{ "_", "&" (used for accelerators in wxWidgets) } | |
306 | @itemdef{ "__", "_" } | |
307 | @itemdef{ "\n", line break } | |
308 | @itemdef{ "\r", carriage return } | |
309 | @itemdef{ "\t", tab } | |
310 | @itemdef{ "\\", "\" } | |
311 | @endDefList | |
312 | ||
313 | By default, the text is translated using wxLocale::GetTranslation() before | |
314 | it is used. This can be disabled either globally by not passing | |
315 | wxXRC_USE_LOCALE to wxXmlResource constructor, or by setting the @c translate | |
316 | attribute on the property node to "0": | |
317 | @code | |
318 | <!-- this is not translated: --> | |
319 | <label translate="0">_Unix</label> | |
320 | <!-- but this is: --> | |
321 | <help>Use Unix-style newlines</help> | |
322 | @endcode | |
323 | ||
324 | @note Even though the "_" character is used instead of "&" for accelerators, | |
325 | it is still possible to use "&". The latter has to be encoded as "&", | |
326 | though, so using "_" is more convenient. | |
327 | ||
328 | @see @ref overview_xrcformat_pre_v2530, @ref overview_xrcformat_pre_v2301 | |
329 | ||
330 | ||
331 | @subsection overview_xrcformat_type_text_notrans Non-Translatable Text | |
332 | ||
333 | Like @ref overview_xrcformat_type_text, but the text is never translated and | |
334 | @c translate attribute cannot be used. | |
335 | ||
336 | ||
337 | @subsection overview_xrcformat_type_string String | |
338 | ||
339 | An unformatted string. Unlike with @ref overview_xrcformat_type_text, no escaping | |
340 | or translations are done. | |
341 | ||
342 | ||
343 | @subsection overview_xrcformat_type_url URL | |
344 | ||
345 | Any URL accepted by wxFileSystem (typically relative to XRC file's location, | |
346 | but can be absolute too). Unlike with @ref overview_xrcformat_type_text, no escaping | |
347 | or translations are done. | |
348 | ||
349 | ||
350 | @subsection overview_xrcformat_type_bitmap Bitmap | |
351 | ||
352 | Bitmap properties contain specification of a single bitmap or icon. In the most | |
353 | basic form, their text value is simply a relative filename (or another | |
354 | wxFileSystem URL) of the bitmap to use. For example: | |
355 | @code | |
356 | <object class="tool" name="wxID_NEW"> | |
357 | <tooltip>New</tooltip> | |
358 | <bitmap>new.png</bitmap> | |
359 | </object> | |
360 | @endcode | |
361 | The value is interpreted as path relative to the location of XRC file where the | |
362 | reference occurs. | |
363 | ||
364 | Alternatively, it is possible to specify the bitmap using wxArtProvider IDs. | |
365 | In this case, the property element has no textual value (filename) and instead | |
366 | has the @c stock_id XML attribute that contains stock art ID as accepted by | |
367 | wxArtProvider::GetBitmap(). This can be either custom value (if the app uses | |
368 | app-specific art provider) or one of the predefined wxART_XXX constants. | |
369 | ||
370 | Optionally, @c stock_client attribute may be specified too and contain one of | |
371 | the predefined wxArtClient values. If it is not specified, the default client | |
372 | ID most appropriate in the context where the bitmap is referenced will be used. | |
373 | In most cases, specifying @c stock_client is not needed. | |
374 | ||
375 | Examples of stock bitmaps usage: | |
376 | @code | |
377 | <bitmap stock_id="fixed-width"/> <!-- custom app-specific art --> | |
378 | <bitmap stock_id="wxART_FILE_OPEN"/> <!-- standard art --> | |
379 | @endcode | |
380 | ||
381 | Specifying the bitmap directly and using @c stock_id are mutually exclusive. | |
382 | ||
383 | ||
384 | @subsection overview_xrcformat_type_style Style | |
385 | ||
386 | Style properties (such as window's style or sizer flags) use syntax similar to | |
387 | C++: the style value is OR-combination of individual flags. Symbolic names | |
388 | identical to those used in C++ code are used for the flags. Flags are separated | |
389 | with "|" (whitespace is allowed but not required around it). | |
390 | ||
391 | The flags that are allowed for a given property are context-dependent. | |
392 | ||
393 | Examples: | |
394 | @code | |
395 | <style>wxCAPTION|wxSYSTEM_MENU | wxRESIZE_BORDER</style> | |
396 | <exstyle>wxDIALOG_EX_CONTEXTHELP</exstyle> | |
397 | @endcode | |
398 | ||
399 | ||
400 | @subsection overview_xrcformat_type_font Font | |
401 | ||
402 | XRC uses similar, but more flexible, abstract description of fonts to that | |
403 | used by wxFont class. A font can be described either in terms of its elementary | |
404 | properties, or it can be derived from one of system fonts. | |
405 | ||
406 | The font property element is "composite" element: unlike majority of | |
407 | properties, it doesn't have text value but contains several child elements | |
408 | instead. These children are handled in the same way as object properties | |
409 | and can be one of the following "sub-properties": | |
410 | ||
411 | @beginTable | |
412 | @hdr3col{property, type, description} | |
413 | @row3col{size, unsigned integer, | |
414 | Pixel size of the font (default: wxNORMAL_FONT's size or @c sysfont's | |
415 | size if the @c sysfont property is used.} | |
416 | @row3col{style, enum, | |
417 | One of "normal", "italic" or "slant" (default: normal).} | |
418 | @row3col{weight, enum, | |
419 | One of "normal", "bold" or "light" (default: normal).} | |
420 | @row3col{family, enum, | |
421 | One of "roman", "script", "decorative", "swiss", "modern" or "teletype" | |
422 | (default: roman).} | |
423 | @row3col{underlined, @ref overview_xrcformat_type_bool, | |
424 | Whether the font should be underlined (default: 0).} | |
425 | @row3col{face, , | |
426 | Comma-separated list of face names; the first one available is used | |
427 | (default: unspecified).} | |
428 | @row3col{encoding, , | |
429 | Charset of the font, unused in Unicode build), as string | |
430 | (default: unspecified).} | |
431 | @row3col{sysfont, , | |
432 | Symbolic name of system standard font(one of wxSYS_*_FONT constants).} | |
433 | @row3col{relativesize, float, | |
434 | Float, font size relative to chosen system font's size; can only be | |
435 | used when 'sysfont' is used and when 'size' is not used.} | |
436 | @endTable | |
437 | ||
438 | All of them are optional, if they are missing, appropriate wxFont default is | |
439 | used. If the @c sysfont property is used, then the defaults are taken from it | |
440 | instead. | |
441 | ||
442 | Examples: | |
443 | @code | |
444 | <font> | |
445 | <!-- fixed font: Arial if available, fall back to Helvetica --> | |
446 | <face>arial,helvetica</face> | |
447 | <size>12</size> | |
448 | </font> | |
449 | ||
450 | <font> | |
451 | <!-- enlarged, enboldened standard font: --> | |
452 | <sysfont>wxSYS_DEFAULT_GUI_FONT</sysfont> | |
453 | <weight>bold</weight> | |
454 | <relativesize>1.5</relativesize> | |
455 | </font> | |
456 | @endcode | |
457 | ||
458 | ||
459 | @section overview_xrcformat_windows Controls and Windows | |
460 | ||
461 | This section describes support wxWindow-derived classes in XRC format. | |
462 | ||
463 | @subsection overview_xrcformat_std_props Standard Properties | |
464 | ||
465 | The following properties are always (unless stated otherwise in | |
466 | control-specific docs) available for @em windows objects. They are omitted | |
467 | from properties lists below. | |
468 | ||
469 | @beginTable | |
470 | @hdr3col{property, type, description} | |
471 | @row3col{pos, @ref overview_xrcformat_type_pos, | |
472 | Initial position of the window (default: wxDefaultPosition).} | |
473 | @row3col{size, @ref overview_xrcformat_type_size, | |
474 | Initial size of the window (default: wxDefaultSize).} | |
475 | @row3col{style, @ref overview_xrcformat_type_style, | |
476 | Window style for this control. The allowed values depend on what | |
477 | window is being created, consult respective class' constructor | |
478 | documentation for details (default: window-dependent default, usually | |
479 | wxFOO_DEFAULT_STYLE if defined for class wxFoo, 0 if not).} | |
480 | @row3col{exstyle, @ref overview_xrcformat_type_style, | |
481 | Extra style for the window, if any. See wxWindow::SetExtraStyle() | |
482 | (default: not set).} | |
483 | @row3col{fg, @ref overview_xrcformat_type_colour, | |
484 | Foreground colour of the window (default: window's default).} | |
485 | @row3col{bg, @ref overview_xrcformat_type_colour, | |
486 | Background colour of the window (default: window's default).} | |
487 | @row3col{enabled, @ref overview_xrcformat_type_bool, | |
488 | If set to 0, the control is disabled (default: 1).} | |
489 | @row3col{hidden, @ref overview_xrcformat_type_bool, | |
490 | If set to 1, the control is created hidden (default: 0).} | |
491 | @row3col{tooltip, @ref overview_xrcformat_type_text, | |
492 | Tooltip to use for the control (default: not set).} | |
493 | @row3col{font, @ref overview_xrcformat_type_font, | |
494 | Font to use for the control (default: window's default).} | |
495 | @row3col{help, @ref overview_xrcformat_type_text, | |
496 | Context-sensitive help for the control, used by wxHelpProvider | |
497 | (default: not set).} | |
498 | @endTable | |
499 | ||
500 | All of these properties are optional. | |
501 | ||
502 | ||
503 | @subsection overview_xrcformat_controls Supported Controls | |
504 | ||
505 | This section lists all controls supported by default. For each control, its | |
506 | control-specific properties are listed. If the control can have child objects, | |
507 | it is documented there too; unless said otherwise, XRC elements for these | |
508 | controls cannot have children. | |
509 | ||
510 | @subsubsection xrc_wxanimationctrl wxAnimationCtrl | |
511 | ||
512 | @beginTable | |
513 | @hdr3col{property, type, description} | |
514 | @row3col{animation, @ref overview_xrcformat_type_url, | |
515 | Animation file to load into the control (required).} | |
516 | @endTable | |
517 | ||
518 | ||
519 | @subsubsection xrc_wxbitmapbutton wxBitmapButton | |
520 | ||
521 | @beginTable | |
522 | @hdr3col{property, type, description} | |
523 | @row3col{default, @ref overview_xrcformat_type_bool, | |
524 | Should this button be the default button in dialog (default: 0)?} | |
525 | @row3col{bitmap, @ref overview_xrcformat_type_bitmap, | |
526 | Bitmap to show on the button (required).} | |
527 | @row3col{selected, @ref overview_xrcformat_type_bitmap, | |
528 | Bitmap to show when the button is selected (default: none, same as @c bitmap).} | |
529 | @row3col{focus, @ref overview_xrcformat_type_bitmap, | |
530 | Bitmap to show when the button has focus (default: none, same as @c bitmap).} | |
531 | @row3col{disabled, @ref overview_xrcformat_type_bitmap, | |
532 | Bitmap to show when the button is disabled (default: none, same as @c bitmap).} | |
533 | @row3col{hover, @ref overview_xrcformat_type_bitmap, | |
534 | Bitmap to show when mouse cursor hovers above the bitmap (default: none, same as @c bitmap).} | |
535 | @endTable | |
536 | ||
537 | ||
538 | @subsubsection xrc_wxbitmapcombobox wxBitmapComboBox | |
539 | ||
540 | @beginTable | |
541 | @hdr3col{property, type, description} | |
542 | @row3col{selection, integer, | |
543 | Index of the initially selected item or -1 for no selection (default: -1).} | |
544 | @row3col{value, @ref overview_xrcformat_type_string, | |
545 | Initial value in the control (doesn't have to be one of @ content values; | |
546 | default: empty).} | |
547 | @endTable | |
548 | ||
549 | If both @c value and @c selection are specified and @c selection is not -1, | |
550 | then @c selection takes precedence. | |
551 | ||
552 | A wxBitmapComboBox can have one or more child objects of the @c ownerdrawnitem | |
553 | pseudo-class. @c ownerdrawnitem objects have the following properties: | |
554 | ||
555 | @beginTable | |
556 | @hdr3col{property, type, description} | |
557 | @row3col{text, @ref overview_xrcformat_type_text, | |
558 | Item's label (required).} | |
559 | @row3col{bitmap, @ref overview_xrcformat_type_bitmap, | |
560 | Item's bitmap (default: no bitmap).} | |
561 | @endTable | |
562 | ||
563 | Example: | |
564 | @code | |
565 | <object class="wxBitmapComboBox"> | |
566 | <selection>1</selection> | |
567 | <object class="ownerdrawnitem"> | |
568 | <text>Foo</text> | |
569 | <bitmap>foo.png</bitmap> | |
570 | </object> | |
571 | <object class="ownerdrawnitem"> | |
572 | <text>Bar</text> | |
573 | <bitmap>bar.png</bitmap> | |
574 | </object> | |
575 | </object> | |
576 | @endcode | |
577 | ||
578 | ||
579 | @subsubsection xrc_wxbutton wxButton | |
580 | ||
581 | @beginTable | |
582 | @hdr3col{property, type, description} | |
583 | @row3col{label, @ref overview_xrcformat_type_text, | |
584 | Label to display on the button (required).} | |
585 | @row3col{default, @ref overview_xrcformat_type_bool, | |
586 | Should this button be the default button in dialog (default: 0)?} | |
587 | @endTable | |
588 | ||
589 | ||
590 | @subsubsection xrc_wxcalendarctrl wxCalendarCtrl | |
591 | ||
592 | No additional properties. | |
593 | ||
594 | ||
595 | @subsubsection xrc_wxcheckbox wxCheckBox | |
596 | ||
597 | @beginTable | |
598 | @hdr3col{property, type, description} | |
599 | @row3col{label, @ref overview_xrcformat_type_text, | |
600 | Label to use for the checkbox (required).} | |
601 | @row3col{checked, @ref overview_xrcformat_type_bool, | |
602 | Should the checkbox be checked initially (default: 0)?} | |
603 | @endTable | |
604 | ||
605 | ||
606 | @subsubsection xrc_wxchecklistbox wxCheckListBox | |
607 | ||
608 | @beginTable | |
609 | @hdr3col{property, type, description} | |
610 | @row3col{content, items, | |
611 | Content of the control; this property has any number of @c \<item\> XML | |
612 | elements as its children, with the items text as their text values | |
613 | (default: empty).} | |
614 | @endTable | |
615 | ||
616 | The @c \<item\> elements have listbox items' labels as their text values. They | |
617 | can also have optional @c checked XML attribute -- if set to "1", the value is | |
618 | initially checked. | |
619 | ||
620 | Example: | |
621 | @code | |
622 | <object class="wxCheckListBox"> | |
623 | <content> | |
624 | <item checked="1">Download library</item> | |
625 | <item checked="1">Compile samples</item> | |
626 | <item checked="1">Skim docs</item> | |
627 | <item checked="1">Finish project</item> | |
628 | <item>Wash car</item> | |
629 | </content> | |
630 | </object> | |
631 | @endcode | |
632 | ||
633 | ||
634 | @subsubsection xrc_wxchoice wxChoice | |
635 | ||
636 | @beginTable | |
637 | @hdr3col{property, type, description} | |
638 | @row3col{selection, integer, | |
639 | Index of the initially selected item or -1 for no selection (default: -1).} | |
640 | @row3col{content, items, | |
641 | Content of the control; this property has any number of @c \<item\> XML | |
642 | elements as its children, with the items text as their text values | |
643 | (default: empty).} | |
644 | @endTable | |
645 | ||
646 | Example: | |
647 | @code | |
648 | <object class="wxChoice" name="controls_choice"> | |
649 | <content> | |
650 | <item>See</item> | |
651 | <item>Hear</item> | |
652 | <item>Feel</item> | |
653 | <item>Smell</item> | |
654 | <item>Taste</item> | |
655 | <item>The Sixth Sense!</item> | |
656 | </content> | |
657 | </object> | |
658 | @endcode | |
659 | ||
660 | ||
661 | @subsubsection xrc_wxchoicebook wxChoicebook | |
662 | ||
663 | A choicebook can have one or more child objects of the @c choicebookpage | |
664 | pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its | |
665 | @c notebookpage) and one child object of the @ref xrc_wximagelist class. | |
666 | @c choicebookpage objects have the following properties: | |
667 | ||
668 | @beginTable | |
669 | @hdr3col{property, type, description} | |
670 | @row3col{label, @ref overview_xrcformat_type_text, | |
671 | Sheet page's title (required).} | |
672 | @row3col{bitmap, @ref overview_xrcformat_type_bitmap, | |
673 | Bitmap shown alongside the label (default: none).} | |
674 | @row3col{image, integer, | |
675 | The zero-based index of the image associated with the item | |
676 | into the image list.} | |
677 | @row3col{selected, @ref overview_xrcformat_type_bool, | |
678 | Is the page selected initially (only one page can be selected; default: 0)?} | |
679 | @endTable | |
680 | ||
681 | Each @c choicebookpage has exactly one non-toplevel window as its child. | |
682 | ||
683 | ||
684 | @subsubsection xrc_wxcollapsiblepane wxCollapsiblePane | |
685 | ||
686 | @beginTable | |
687 | @hdr3col{property, type, description} | |
688 | @row3col{label, @ref overview_xrcformat_type_text, | |
689 | Label to use for the collapsible section (required).} | |
690 | @row3col{collapsed, @ref overview_xrcformat_type_bool, | |
691 | Should the pane be collapsed initially (default: 0)?} | |
692 | @endTable | |
693 | ||
694 | wxCollapsiblePane may contain single optional child object of the @c panewindow | |
695 | pseudo-class type. @c panewindow itself must contain exactly one child that | |
696 | is a @ref overview_xrcformat_sizers "sizer" or a non-toplevel window | |
697 | object. | |
698 | ||
699 | ||
700 | @subsubsection xrc_wxcolourpickerctrl wxColourPickerCtrl | |
701 | ||
702 | @beginTable | |
703 | @hdr3col{property, type, description} | |
704 | @row3col{value, @ref overview_xrcformat_type_colour, | |
705 | Initial value of the control (default: wxBLACK).} | |
706 | @endTable | |
707 | ||
708 | ||
709 | @subsubsection xrc_wxcombobox wxComboBox | |
710 | ||
711 | @beginTable | |
712 | @hdr3col{property, type, description} | |
713 | @row3col{selection, integer, | |
714 | Index of the initially selected item or -1 for no selection (default: not used).} | |
715 | @row3col{content, items, | |
716 | Content of the control; this property has any number of @c \<item\> XML | |
717 | elements as its children, with the items text as their text values | |
718 | (default: empty).} | |
719 | @row3col{value, @ref overview_xrcformat_type_string, | |
720 | Initial value in the control (doesn't have to be one of @ content values; | |
721 | default: empty).} | |
722 | @endTable | |
723 | ||
724 | If both @c value and @c selection are specified and @c selection is not -1, | |
725 | then @c selection takes precedence. | |
726 | ||
727 | Example: | |
728 | @code | |
729 | <object class="wxComboBox" name="controls_combobox"> | |
730 | <style>wxCB_DROPDOWN</style> | |
731 | <value>nedit</value> | |
732 | <content> | |
733 | <item>vim</item> | |
734 | <item>emacs</item> | |
735 | <item>notepad.exe</item> | |
736 | <item>bbedit</item> | |
737 | </content> | |
738 | </object> | |
739 | @endcode | |
740 | ||
741 | @subsubsection xrc_wxdatepickerctrl wxDatePickerCtrl | |
742 | ||
743 | No additional properties. | |
744 | ||
745 | ||
746 | @subsubsection xrc_wxdialog wxDialog | |
747 | ||
748 | @beginTable | |
749 | @hdr3col{property, type, description} | |
750 | @row3col{title, @ref overview_xrcformat_type_text, | |
751 | Dialog's title (default: empty).} | |
752 | @row3col{icon, @ref overview_xrcformat_type_bitmap, | |
753 | Dialog's icon (default: not used).} | |
754 | @row3col{centered, @ref overview_xrcformat_type_bool, | |
755 | Whether the dialog should be centered on the screen (default: 0).} | |
756 | @endTable | |
757 | ||
758 | wxDialog may have optional children: either exactly one | |
759 | @ref overview_xrcformat_sizers "sizer" child or any number of non-toplevel window | |
760 | objects. If sizer child is used, it sets | |
761 | @ref wxSizer::SetSizeHints() "size hints" too. | |
762 | ||
763 | @subsubsection xrc_wxdirpickerctrl wxDirPickerCtrl | |
764 | ||
765 | @beginTable | |
766 | @hdr3col{property, type, description} | |
767 | @row3col{value, @ref overview_xrcformat_type_string, | |
768 | Initial value of the control (default: empty).} | |
769 | @row3col{message, @ref overview_xrcformat_type_text, | |
770 | Message shown to the user in wxDirDialog shown by the control (required).} | |
771 | @endTable | |
772 | ||
773 | ||
774 | @subsubsection xrc_wxfilepickerctrl wxFilePickerCtrl | |
775 | ||
776 | @beginTable | |
777 | @hdr3col{property, type, description} | |
778 | @row3col{value, @ref overview_xrcformat_type_string, | |
779 | Initial value of the control (default: empty).} | |
780 | @row3col{message, @ref overview_xrcformat_type_text, | |
781 | Message shown to the user in wxDirDialog shown by the control (required).} | |
782 | @row3col{wildcard, @ref overview_xrcformat_type_string, | |
783 | Message shown to the user in wxDirDialog shown by the control (required).} | |
784 | @endTable | |
785 | ||
786 | ||
787 | @subsubsection xrc_wxfontpickerctrl wxFontPickerCtrl | |
788 | ||
789 | @beginTable | |
790 | @hdr3col{property, type, description} | |
791 | @row3col{value, @ref overview_xrcformat_type_font, | |
792 | Initial value of the control (default: wxNORMAL_FONT).} | |
793 | @endTable | |
794 | ||
795 | @subsubsection xrc_wxfrane wxFrame | |
796 | ||
797 | @beginTable | |
798 | @hdr3col{property, type, description} | |
799 | @row3col{title, @ref overview_xrcformat_type_text, | |
800 | Frame's title (default: empty).} | |
801 | @row3col{icon, @ref overview_xrcformat_type_bitmap, | |
802 | Frame's icon (default: not used).} | |
803 | @row3col{centered, @ref overview_xrcformat_type_bool, | |
804 | Whether the frame should be centered on the screen (default: 0).} | |
805 | @endTable | |
806 | ||
807 | wxFrame may have optional children: either exactly one | |
808 | @ref overview_xrcformat_sizers "sizer" child or any number of non-toplevel window | |
809 | objects. If sizer child is used, it sets | |
810 | @ref wxSizer::SetSizeHints() "size hints" too. | |
811 | ||
812 | ||
813 | @subsubsection xrc_wxgauge wxGauge | |
814 | ||
815 | @beginTable | |
816 | @hdr3col{property, type, description} | |
817 | @row3col{range, integer, | |
818 | Maximum value of the gauge (default: 100).} | |
819 | @row3col{value, integer, | |
820 | Initial value of the control (default: 0).} | |
821 | @row3col{shadow, @ref overview_xrcformat_type_dimension, | |
822 | Rendered shadow size (default: none; ignored by most platforms).} | |
823 | @row3col{bezel, @ref overview_xrcformat_type_dimension, | |
824 | Rendered bezel size (default: none; ignored by most platforms).} | |
825 | @endTable | |
826 | ||
827 | @subsubsection xrc_wxgenericdirctrl wxGenericDirCtrl | |
828 | ||
829 | @beginTable | |
830 | @hdr3col{property, type, description} | |
831 | @row3col{defaultfolder, @ref overview_xrcformat_type_text, | |
832 | Initial folder (default: empty).} | |
833 | @row3col{filter, @ref overview_xrcformat_type_text, | |
834 | Filter string, using the same syntax as used by wxFileDialog, e.g. | |
835 | "All files (*.*)|*.*|JPEG files (*.jpg)|*.jpg" (default: empty).} | |
836 | @row3col{defaultfilter, integer, | |
837 | Zero-based index of default filter (default: 0).} | |
838 | @endTable | |
839 | ||
840 | @subsubsection xrc_wxgrid wxGrid | |
841 | ||
842 | No additional properties. | |
843 | ||
844 | ||
845 | @subsubsection xrc_wxhtmlwindow wxHtmlWindow | |
846 | ||
847 | @beginTable | |
848 | @hdr3col{property, type, description} | |
849 | @row3col{url, @ref overview_xrcformat_type_url, | |
850 | Page to display in the window.} | |
851 | @row3col{htmlcode, @ref overview_xrcformat_type_text, | |
852 | HTML markup to display in the window.} | |
853 | @row3col{borders, @ref overview_xrcformat_type_dimension, | |
854 | Border around HTML content (default: 0).} | |
855 | @endTable | |
856 | ||
857 | At most one of @c url and @c htmlcode properties may be specified, they are | |
858 | mutually exclusive. If neither is set, the window is initialized to show empty | |
859 | page. | |
860 | ||
861 | ||
862 | @subsubsection xrc_wxhyperlinkctrl wxHyperlinkCtrl | |
863 | ||
864 | @beginTable | |
865 | @hdr3col{property, type, description} | |
866 | @row3col{label, @ref overview_xrcformat_type_text, | |
867 | Label to display on the control (required).} | |
868 | @row3col{url, @ref overview_xrcformat_type_url, | |
869 | URL to open when the link is clicked (required).} | |
870 | @endTable | |
871 | ||
872 | ||
873 | @subsubsection xrc_wximagelist wxImageList | |
874 | ||
875 | The imagelist can be used as a child object for the following classes: | |
876 | - @ref xrc_wxchoicebook | |
877 | - @ref xrc_wxlistbook | |
878 | - @ref xrc_wxlistctrl | |
879 | - @ref xrc_wxnotebook | |
880 | - @ref xrc_wxtreebook | |
881 | - @ref xrc_wxtreectrl | |
882 | ||
883 | The available properties are: | |
884 | ||
885 | @beginTable | |
886 | @hdr3col{property, type, description} | |
887 | @row3col{bitmap, @ref overview_xrcformat_type_bitmap, | |
888 | Adds a new image by keeping its optional mask bitmap (see below).} | |
889 | @row3col{mask, @ref overview_xrcformat_type_bool, | |
890 | If masks should be created for all images (default: true).} | |
891 | @row3col{size, @ref overview_xrcformat_type_size, | |
892 | The size of the images in the list (default: system default icon size)).} | |
893 | @endTable | |
894 | ||
895 | Example: | |
896 | @code | |
897 | <imagelist> | |
898 | <size>32,32</size> | |
899 | <bitmap stock_id="wxART_QUESTION"/> | |
900 | <bitmap stock_id="wxART_INFORMATION"/> | |
901 | </imagelist> | |
902 | @endcode | |
903 | ||
904 | In the specific case of the @ref xrc_wxlistctrl, the tag can take the name | |
905 | @c \<imagelist-small\> to define the 'small' image list, related to the flag | |
906 | @c wxIMAGE_LIST_SMALL (see wxListCtrl documentation). | |
907 | ||
908 | ||
909 | @subsubsection xrc_wxlistbox wxListBox | |
910 | ||
911 | @beginTable | |
912 | @hdr3col{property, type, description} | |
913 | @row3col{selection, integer, | |
914 | Index of the initially selected item or -1 for no selection (default: -1).} | |
915 | @row3col{content, items, | |
916 | Content of the control; this property has any number of @c \<item\> XML | |
917 | elements as its children, with the items text as their text values | |
918 | (default: empty).} | |
919 | @endTable | |
920 | ||
921 | Example: | |
922 | @code | |
923 | <object class="wxListBox" name="controls_listbox"> | |
924 | <size>250,160</size> | |
925 | <style>wxLB_SINGLE</style> | |
926 | <content> | |
927 | <item>Milk</item> | |
928 | <item>Pizza</item> | |
929 | <item>Bread</item> | |
930 | <item>Orange juice</item> | |
931 | <item>Paper towels</item> | |
932 | </content> | |
933 | </object> | |
934 | @endcode | |
935 | ||
936 | ||
937 | @subsubsection xrc_wxlistbook wxListbook | |
938 | ||
939 | A listbook can have one or more child objects of the @c listbookpage | |
940 | pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its | |
941 | @c notebookpage) and one child object of the @ref xrc_wximagelist class. | |
942 | @c listbookpage objects have the following properties: | |
943 | ||
944 | @beginTable | |
945 | @hdr3col{property, type, description} | |
946 | @row3col{label, @ref overview_xrcformat_type_text, | |
947 | Sheet page's title (required).} | |
948 | @row3col{bitmap, @ref overview_xrcformat_type_bitmap, | |
949 | Bitmap shown alongside the label (default: none).} | |
950 | @row3col{image, integer, | |
951 | The zero-based index of the image associated with the item | |
952 | into the image list.} | |
953 | @row3col{selected, @ref overview_xrcformat_type_bool, | |
954 | Is the page selected initially (only one page can be selected; default: 0)?} | |
955 | @endTable | |
956 | ||
957 | Each @c listbookpage has exactly one non-toplevel window as its child. | |
958 | ||
959 | ||
960 | @subsubsection xrc_wxlistctrl wxListCtrl | |
961 | ||
962 | A list control can have one or more child objects of the class @ref xrc_wxlistitem | |
963 | and one or more objects of the @ref xrc_wximagelist class. The latter is | |
964 | defined either using @c \<imagelist\> tag for the control with @c wxLC_ICON | |
965 | style or using @c \<imagelist-small\> tag for the control with @c | |
966 | wxLC_SMALL_ICON style. | |
967 | ||
968 | Report mode list controls (i.e. created with @c wxLC_REPORT style) can in | |
969 | addition have one or more @ref xrc_wxlistcol child elements. | |
970 | ||
971 | @subsubsection xrc_wxlistcol listcol | |
972 | ||
973 | The @c listcol class can only be used for wxListCtrl children. It can have the | |
974 | following properties: | |
975 | @beginTable | |
976 | @hdr3col{property, type, description} | |
977 | @row3col{align, wxListColumnFormat, | |
978 | The alignment for the item. | |
979 | Can be one of @c wxLIST_FORMAT_LEFT, @c wxLIST_FORMAT_RIGHT or | |
980 | @c wxLIST_FORMAT_CENTRE.} | |
981 | @row3col{text, @ref overview_xrcformat_type_string, | |
982 | The title of the column. } | |
983 | @row3col{width, integer, | |
984 | The column width. } | |
985 | @endTable | |
986 | ||
987 | The columns are appended to the control in order of their appearance and may be | |
988 | referenced by 0-based index in the @c col attributes of subsequent @c listitem | |
989 | objects. | |
990 | ||
991 | @subsubsection xrc_wxlistitem listitem | |
992 | ||
993 | The @c listitem is a child object for the class @ref xrc_wxlistctrl. | |
994 | It can have the following properties: | |
995 | ||
996 | @beginTable | |
997 | @hdr3col{property, type, description} | |
998 | @row3col{align, wxListColumnFormat, | |
999 | The alignment for the item. | |
1000 | Can be one of @c wxLIST_FORMAT_LEFT, @c wxLIST_FORMAT_RIGHT or | |
1001 | @c wxLIST_FORMAT_CENTRE.} | |
1002 | @row3col{bg, @ref overview_xrcformat_type_colour, | |
1003 | The background color for the item.} | |
1004 | @row3col{bitmap, @ref overview_xrcformat_type_bitmap, | |
1005 | Add a bitmap to the (normal) @ref xrc_wximagelist associated with the | |
1006 | @ref xrc_wxlistctrl parent and associate it with this item. | |
1007 | If the imagelist is not defined it will be created implicitly.} | |
1008 | @row3col{bitmap-small, @ref overview_xrcformat_type_bitmap, | |
1009 | Add a bitmap in the 'small' @ref xrc_wximagelist associated with the | |
1010 | @ref xrc_wxlistctrl parent and associate it with this item. | |
1011 | If the 'small' imagelist is not defined it will be created implicitly.} | |
1012 | @row3col{col, integer, | |
1013 | The zero-based column index.} | |
1014 | @row3col{image, integer, | |
1015 | The zero-based index of the image associated with the item | |
1016 | in the (normal) image list.} | |
1017 | @row3col{image-small, integer, | |
1018 | The zero-based index of the image associated with the item | |
1019 | in the 'small' image list.} | |
1020 | @row3col{data, integer, | |
1021 | The client data for the item.} | |
1022 | @row3col{font, @ref overview_xrcformat_type_font, | |
1023 | The font for the item.} | |
1024 | @row3col{image, integer, | |
1025 | The zero-based index of the image associated with the item | |
1026 | into the image list.} | |
1027 | @row3col{state, @ref overview_xrcformat_type_style, | |
1028 | The item state. Can be any combination of the following values: | |
1029 | - @c wxLIST_STATE_FOCUSED: The item has the focus. | |
1030 | - @c wxLIST_STATE_SELECTED: The item is selected. | |
1031 | @row3col{text, @ref overview_xrcformat_type_string, | |
1032 | The text label for the item. } | |
1033 | @row3col{textcolour, @ref overview_xrcformat_type_colour, | |
1034 | The text colour for the item. } | |
1035 | @endTable | |
1036 | ||
1037 | Notice that the item position can't be specified here, the items are appended | |
1038 | to the list control in order of their appearance. | |
1039 | ||
1040 | ||
1041 | @subsubsection xrc_wxmdiparentframe wxMDIParentFrame | |
1042 | ||
1043 | wxMDIParentFrame supports the same properties that @ref xrc_wxfrane does. | |
1044 | ||
1045 | wxMDIParentFrame may have optional children. When used, the child objects | |
1046 | must be of wxMDIChildFrame type. | |
1047 | ||
1048 | ||
1049 | @subsubsection xrc_wxmdichildframe wxMDIChildFrame | |
1050 | ||
1051 | wxMDIChildFrame supports the same properties that @ref xrc_wxfrane and | |
1052 | @ref xrc_wxmdiparentframe do. | |
1053 | ||
1054 | wxMDIChildFrame can only be used as as immediate child of @ref | |
1055 | xrc_wxmdiparentframe. | |
1056 | ||
1057 | wxMDIChildFrame may have optional children: either exactly one | |
1058 | @ref overview_xrcformat_sizers "sizer" child or any number of non-toplevel window | |
1059 | objects. If sizer child is used, it sets | |
1060 | @ref wxSizer::SetSizeHints() "size hints" too. | |
1061 | ||
1062 | ||
1063 | @subsubsection xrc_wxmenu wxMenu | |
1064 | ||
1065 | @beginTable | |
1066 | @hdr3col{property, type, description} | |
1067 | @row3col{label, @ref overview_xrcformat_type_text, | |
1068 | Menu's label (default: empty, but required for menus other | |
1069 | than popup menus).} | |
1070 | @row3col{help, @ref overview_xrcformat_type_text, | |
1071 | Help shown in statusbar when the menu is selected (only for submenus | |
1072 | of another wxMenu, default: none).} | |
1073 | @row3col{enabled, @ref overview_xrcformat_type_bool, | |
1074 | Is the submenu item enabled (only for submenus of another wxMenu, | |
1075 | default: 1)?} | |
1076 | @endTable | |
1077 | ||
1078 | Note that unlike most controls, wxMenu does @em not have | |
1079 | @ref overview_xrcformat_std_props. | |
1080 | ||
1081 | A menu object can have one or more child objects of the wxMenuItem or wxMenu | |
1082 | classes or @c break or @c separator pseudo-classes. | |
1083 | ||
1084 | The @c separator pseudo-class is used to insert separators into the menu and | |
1085 | has neither properties nor children. Likewise, @c break inserts a break (see | |
1086 | wxMenu::Break()). | |
1087 | ||
1088 | wxMenuItem objects support the following properties: | |
1089 | ||
1090 | @beginTable | |
1091 | @hdr3col{property, type, description} | |
1092 | @row3col{label, @ref overview_xrcformat_type_text, | |
1093 | Item's label (required).} | |
1094 | @row3col{accel, @ref overview_xrcformat_type_text_notrans, | |
1095 | Item's accelerator (default: none).} | |
1096 | @row3col{radio, @ref overview_xrcformat_type_bool, | |
1097 | Item's kind is wxITEM_RADIO (default: 0)?} | |
1098 | @row3col{checkable, @ref overview_xrcformat_type_bool, | |
1099 | Item's kind is wxITEM_CHECK (default: 0)?} | |
1100 | @row3col{bitmap, @ref overview_xrcformat_type_bitmap, | |
1101 | Bitmap to show with the item (default: none).} | |
1102 | @row3col{bitmap2, @ref overview_xrcformat_type_bitmap, | |
1103 | Bitmap for the checked state (wxMSW, if checkable; default: none).} | |
1104 | @row3col{help, @ref overview_xrcformat_type_text, | |
1105 | Help shown in statusbar when the item is selected (default: none).} | |
1106 | @row3col{enabled, @ref overview_xrcformat_type_bool, | |
1107 | Is the item enabled (default: 1)?} | |
1108 | @row3col{checked, @ref overview_xrcformat_type_bool, | |
1109 | Is the item checked initially (default: 0)?} | |
1110 | @endTable | |
1111 | ||
1112 | Example: | |
1113 | @code | |
1114 | <object class="wxMenu" name="menu_edit"> | |
1115 | <style>wxMENU_TEAROFF</style> | |
1116 | <label>_Edit</label> | |
1117 | <object class="wxMenuItem" name="wxID_FIND"> | |
1118 | <label>_Find...</label> | |
1119 | <accel>Ctrl-F</accel> | |
1120 | </object> | |
1121 | <object class="separator"/> | |
1122 | <object class="wxMenuItem" name="menu_fuzzy"> | |
1123 | <label>Translation is _fuzzy</label> | |
1124 | <checkable>1</checkable> | |
1125 | </object> | |
1126 | <object class="wxMenu" name="submenu"> | |
1127 | <label>A submenu</label> | |
1128 | <object class="wxMenuItem" name="foo">...</object> | |
1129 | ... | |
1130 | </object> | |
1131 | <object class="separator" platform="unix"/> | |
1132 | <object class="wxMenuItem" name="wxID_PREFERENCES" platform="unix"> | |
1133 | <label>_Preferences</label> | |
1134 | </object> | |
1135 | </object> | |
1136 | @endcode | |
1137 | ||
1138 | @subsubsection xrc_wxmenubar wxMenuBar | |
1139 | ||
1140 | No properties. Note that unlike most controls, wxMenuBar does @em not have | |
1141 | @ref overview_xrcformat_std_props. | |
1142 | ||
1143 | A menubar can have one or more child objects of the @ref xrc_wxmenu "wxMenu" | |
1144 | class. | |
1145 | ||
1146 | ||
1147 | @subsubsection xrc_wxnotebook wxNotebook | |
1148 | ||
1149 | A notebook can have one or more child objects of the @c notebookpage | |
1150 | pseudo-class and one child object of the @ref xrc_wximagelist class. | |
1151 | @c notebookpage objects have the following properties: | |
1152 | ||
1153 | @beginTable | |
1154 | @hdr3col{property, type, description} | |
1155 | @row3col{label, @ref overview_xrcformat_type_text, | |
1156 | Page's title (required).} | |
1157 | @row3col{bitmap, @ref overview_xrcformat_type_bitmap, | |
1158 | Bitmap shown alongside the label (default: none).} | |
1159 | @row3col{image, integer, | |
1160 | The zero-based index of the image associated with the item | |
1161 | into the image list.} | |
1162 | @row3col{selected, @ref overview_xrcformat_type_bool, | |
1163 | Is the page selected initially (only one page can be selected; default: 0)?} | |
1164 | @endTable | |
1165 | ||
1166 | Each @c notebookpage has exactly one non-toplevel window as its child. | |
1167 | ||
1168 | Example: | |
1169 | @code | |
1170 | <object class="wxNotebook"> | |
1171 | <style>wxBK_BOTTOM</style> | |
1172 | <object class="notebookpage"> | |
1173 | <label>Page 1</label> | |
1174 | <object class="wxPanel" name="page_1"> | |
1175 | ... | |
1176 | </object> | |
1177 | </object> | |
1178 | <object class="notebookpage"> | |
1179 | <label>Page 2</label> | |
1180 | <object class="wxPanel" name="page_2"> | |
1181 | ... | |
1182 | </object> | |
1183 | </object> | |
1184 | </object> | |
1185 | @endcode | |
1186 | ||
1187 | ||
1188 | @subsubsection xrc_wxownerdrawncombobox wxOwnerDrawnComboBox | |
1189 | ||
1190 | wxOwnerDrawnComboBox has the same properties as | |
1191 | @ref xrc_wxcombobox "wxComboBox", plus the following additional properties: | |
1192 | ||
1193 | @beginTable | |
1194 | @hdr3col{property, type, description} | |
1195 | @row3col{buttonsize, @ref overview_xrcformat_type_size, | |
1196 | Size of the dropdown button (default: default).} | |
1197 | @endTable | |
1198 | ||
1199 | ||
1200 | @subsubsection xrc_wxpanel wxPanel | |
1201 | ||
1202 | No additional properties. | |
1203 | ||
1204 | wxPanel may have optional children: either exactly one | |
1205 | @ref overview_xrcformat_sizers "sizer" child or any number of non-toplevel window | |
1206 | objects. | |
1207 | ||
1208 | ||
1209 | @subsubsection xrc_wxpropertysheetdialog wxPropertySheetDialog | |
1210 | ||
1211 | @beginTable | |
1212 | @hdr3col{property, type, description} | |
1213 | @row3col{title, @ref overview_xrcformat_type_text, | |
1214 | Dialog's title (default: empty).} | |
1215 | @row3col{icon, @ref overview_xrcformat_type_bitmap, | |
1216 | Dialog's icon (default: not used).} | |
1217 | @row3col{centered, @ref overview_xrcformat_type_bool, | |
1218 | Whether the dialog should be centered on the screen (default: 0).} | |
1219 | @row3col{buttons, @ref overview_xrcformat_type_style, | |
1220 | Buttons to show, combination of flags accepted by | |
1221 | wxPropertySheetDialog::CreateButtons() (default: 0).} | |
1222 | @endTable | |
1223 | ||
1224 | A sheet dialog can have one or more child objects of the @c propertysheetpage | |
1225 | pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its | |
1226 | @c notebookpage). @c propertysheetpage objects have the following properties: | |
1227 | ||
1228 | @beginTable | |
1229 | @hdr3col{property, type, description} | |
1230 | @row3col{label, @ref overview_xrcformat_type_text, | |
1231 | Sheet page's title (required).} | |
1232 | @row3col{bitmap, @ref overview_xrcformat_type_bitmap, | |
1233 | Bitmap shown alongside the label (default: none).} | |
1234 | @row3col{selected, @ref overview_xrcformat_type_bool, | |
1235 | Is the page selected initially (only one page can be selected; default: 0)?} | |
1236 | @endTable | |
1237 | ||
1238 | Each @c propertysheetpage has exactly one non-toplevel window as its child. | |
1239 | ||
1240 | ||
1241 | @subsubsection xrc_wxradiobutton wxRadioButton | |
1242 | ||
1243 | @beginTable | |
1244 | @hdr3col{property, type, description} | |
1245 | @row3col{label, @ref overview_xrcformat_type_text, | |
1246 | Label shown on the radio button (required).} | |
1247 | @row3col{value, @ref overview_xrcformat_type_bool, | |
1248 | Initial value of the control (default: 0).} | |
1249 | @endTable | |
1250 | ||
1251 | ||
1252 | @subsubsection xrc_wxradiobox wxRadioBox | |
1253 | ||
1254 | @beginTable | |
1255 | @hdr3col{property, type, description} | |
1256 | @row3col{label, @ref overview_xrcformat_type_text, | |
1257 | Label for the whole box (required).} | |
1258 | @row3col{dimension, integer, | |
1259 | Specifies the maximum number of rows (if style contains | |
1260 | @c wxRA_SPECIFY_ROWS) or columns (if style contains @c wxRA_SPECIFY_COLS) | |
1261 | for a two-dimensional radiobox (default: 1).} | |
1262 | @row3col{selection, integer, | |
1263 | Index of the initially selected item or -1 for no selection (default: -1).} | |
1264 | @row3col{content, items, | |
1265 | Content of the control; this property has any number of @c \<item\> XML | |
1266 | elements as its children, with the items text as their text values | |
1267 | (see below; default: empty).} | |
1268 | @endTable | |
1269 | ||
1270 | The @c \<item\> elements have radio buttons' labels as their text values. They | |
1271 | can also have some optional XML @em attributes (not properties!): | |
1272 | ||
1273 | @beginTable | |
1274 | @hdr3col{attribute, type, description} | |
1275 | @row3col{tooltip, @ref overview_xrcformat_type_string, | |
1276 | Tooltip to show over this ratio button (default: none).} | |
1277 | @row3col{helptext, @ref overview_xrcformat_type_string, | |
1278 | Contextual help for this radio button (default: none).} | |
1279 | @row3col{enabled, @ref overview_xrcformat_type_bool, | |
1280 | Is the button enabled (default: 1)?} | |
1281 | @row3col{hidden, @ref overview_xrcformat_type_bool, | |
1282 | Is the button hidden initially (default: 0)?} | |
1283 | @endTable | |
1284 | ||
1285 | Example: | |
1286 | @code | |
1287 | <object class="wxRadioBox" name="controls_radiobox"> | |
1288 | <style>wxRA_SPECIFY_COLS</style> | |
1289 | <label>Radio stations</label> | |
1290 | <dimension>1</dimension> | |
1291 | <selection>0</selection> | |
1292 | <content> | |
1293 | <item tooltip="Powerful radio station" helptext="This station is for amateurs of hard rock and heavy metal">Power 108</item> | |
1294 | <item tooltip="Disabled radio station" enabled="0">Power 0</item> | |
1295 | <item tooltip="">WMMS 100.7</item> | |
1296 | <item tooltip="E=mc^2">Energy 98.3</item> | |
1297 | <item helptext="Favourite chukcha's radio">CHUM FM</item> | |
1298 | <item>92FM</item> | |
1299 | <item hidden="1">Very quit station</item> | |
1300 | </content> | |
1301 | </object> | |
1302 | @endcode | |
1303 | ||
1304 | ||
1305 | @subsubsection xrc_wxrichtextctrl wxRichTextCtrl | |
1306 | ||
1307 | @beginTable | |
1308 | @hdr3col{property, type, description} | |
1309 | @row3col{value, @ref overview_xrcformat_type_text, | |
1310 | Initial value of the control (default: empty).} | |
1311 | @row3col{maxlength, integer, | |
1312 | Maximum length of the text entered (default: unlimited).} | |
1313 | @endTable | |
1314 | ||
1315 | ||
1316 | @subsubsection xrc_wxscrollbar wxScrollBar | |
1317 | ||
1318 | @beginTable | |
1319 | @hdr3col{property, type, description} | |
1320 | @row3col{value, integer, | |
1321 | Initial position of the scrollbar (default: 0).} | |
1322 | @row3col{range, integer, | |
1323 | Maximum value of the gauge (default: 10).} | |
1324 | @row3col{thumbsize, integer, | |
1325 | Size of the thumb (default: 1).} | |
1326 | @row3col{pagesize, integer, | |
1327 | Page size (default: 1).} | |
1328 | @endTable | |
1329 | ||
1330 | @subsubsection xrc_wxscrolledwindow wxScrolledWindow | |
1331 | ||
1332 | @beginTable | |
1333 | @hdr3col{property, type, description} | |
1334 | @row3col{scrollrate, @ref overview_xrcformat_type_size, | |
1335 | Scroll rate in @em x and @em y directions (default: not set; | |
1336 | required if the window has a sizer child).} | |
1337 | @endTable | |
1338 | ||
1339 | wxScrolledWindow may have optional children: either exactly one | |
1340 | @ref overview_xrcformat_sizers "sizer" child or any number of non-toplevel window | |
1341 | objects. If sizer child is used, wxSizer::FitInside() is used (instead of | |
1342 | wxSizer::Fit() as usual) and so the children don't determine scrolled window's | |
1343 | minimal size, they only affect @em virtual size. Usually, both @c scrollrate | |
1344 | and either @c size or @c minsize on containing sizer item should be used | |
1345 | in this case. | |
1346 | ||
1347 | ||
1348 | @subsubsection xrc_wxsimplehtmllistbox wxSimpleHtmlListBox | |
1349 | ||
1350 | wxSimpleHtmlListBox has same properties as @ref xrc_wxlistbox "wxListBox". | |
1351 | The only difference is that the text contained in @c \<item\> elements is | |
1352 | HTML markup. Note that the markup has to be escaped: | |
1353 | ||
1354 | @code | |
1355 | <object class="wxSimpleHtmlListBox"> | |
1356 | <content> | |
1357 | <item><b>Bold</b> Milk</item> | |
1358 | </content> | |
1359 | </object> | |
1360 | @endcode | |
1361 | ||
1362 | (X)HTML markup elements cannot be included directly: | |
1363 | ||
1364 | @code | |
1365 | <object class="wxSimpleHtmlListBox"> | |
1366 | <content> | |
1367 | <!-- This is incorrect, doesn't work! --> | |
1368 | <item><b>Bold</b> Milk</item> | |
1369 | </content> | |
1370 | </object> | |
1371 | @endcode | |
1372 | ||
1373 | ||
1374 | @subsubsection xrc_wxslider wxSlider | |
1375 | ||
1376 | @beginTable | |
1377 | @hdr3col{property, type, description} | |
1378 | @row3col{value, integer, | |
1379 | Initial value of the control (default: 0).} | |
1380 | @row3col{min, integer, | |
1381 | Minimum allowed value (default: 0).} | |
1382 | @row3col{max, integer, | |
1383 | Maximum allowed value (default: 100).} | |
1384 | @row3col{pagesize, integer, | |
1385 | Line size; number of steps the slider moves when the user moves | |
1386 | pages up or down (default: unset).} | |
1387 | @row3col{linesize, integer, | |
1388 | Line size; number of steps the slider moves when the user moves it | |
1389 | up or down a line (default: unset).} | |
1390 | @row3col{tickfreq, integer, | |
1391 | Tick marks frequency (Windows only; default: unset).} | |
1392 | @row3col{tick, integer, | |
1393 | Tick position (Windows only; default: unset).} | |
1394 | @row3col{thumb, integer, | |
1395 | Thumb length (Windows only; default: unset).} | |
1396 | @row3col{selmin, integer, | |
1397 | Selection start position (Windows only; default: unset).} | |
1398 | @row3col{selmax, integer, | |
1399 | Selection end position (Windows only; default: unset).} | |
1400 | @endTable | |
1401 | ||
1402 | ||
1403 | @subsubsection xrc_wxspinbutton wxSpinButton | |
1404 | ||
1405 | @beginTable | |
1406 | @hdr3col{property, type, description} | |
1407 | @row3col{value, integer, | |
1408 | Initial value of the control (default: 0).} | |
1409 | @row3col{min, integer, | |
1410 | Minimum allowed value (default: 0).} | |
1411 | @row3col{max, integer, | |
1412 | Maximum allowed value (default: 100).} | |
1413 | @endTable | |
1414 | ||
1415 | ||
1416 | @subsubsection xrc_wxspinctrl wxSpinCtrl | |
1417 | ||
1418 | wxSpinCtrl supports the properties as @ref xrc_wxspinbutton. | |
1419 | ||
1420 | ||
1421 | @subsubsection xrc_wxsplitterwindow wxSplitterWindow | |
1422 | ||
1423 | @beginTable | |
1424 | @hdr3col{property, type, description} | |
1425 | @row3col{orientation, @ref overview_xrcformat_type_string, | |
1426 | Orientation of the splitter, either "vertical" or "horizontal" (default: horizontal).} | |
1427 | @row3col{sashpos, integer, | |
1428 | Initial position of the sash (default: 0).} | |
1429 | @row3col{minsize, integer, | |
1430 | Minimum child size (default: not set).} | |
1431 | @row3col{gravity, @ref overview_xrcformat_type_float, | |
1432 | Sash gravity, see wxSplitterWindow::SetSashGravity() (default: not set).} | |
1433 | @endTable | |
1434 | ||
1435 | wxSplitterWindow must have one or two children that are non-toplevel window | |
1436 | objects. If there's only one child, it is used as wxSplitterWindow's only | |
1437 | visible child. If there are two children, the first one is used for left/top | |
1438 | child and the second one for right/bottom child window. | |
1439 | ||
1440 | ||
1441 | @subsubsection xrc_wxsearchctrl wxSearchCtrl | |
1442 | ||
1443 | @beginTable | |
1444 | @hdr3col{property, type, description} | |
1445 | @row3col{value, @ref overview_xrcformat_type_text, | |
1446 | Initial value of the control (default: empty).} | |
1447 | @endTable | |
1448 | ||
1449 | ||
1450 | @subsubsection xrc_wxstatusbar wxStatusBar | |
1451 | ||
1452 | @beginTable | |
1453 | @hdr3col{property, type, description} | |
1454 | @row3col{fields, integer, | |
1455 | Number of status bar fields (default: 1).} | |
1456 | @row3col{widths, @ref overview_xrcformat_type_string, | |
1457 | Comma-separated list of @em fields integers. Each value specifies width | |
1458 | of one field; the values are interpreted using the same convention used | |
1459 | by wxStatusBar::SetStatusWidths().} | |
1460 | @row3col{styles, @ref overview_xrcformat_type_string, | |
1461 | Comma-separated list of @em fields flags. Each value specifies status bar | |
1462 | fieldd style and can be one of @c wxSB_NORMAL, @c wxSB_FLAT or | |
1463 | @c wxSB_RAISED. See wxStatusBar::SetStatusStyles() for their description.} | |
1464 | @endTable | |
1465 | ||
1466 | ||
1467 | ||
1468 | @subsubsection xrc_wxstaticbitmap wxStaticBitmap | |
1469 | ||
1470 | @beginTable | |
1471 | @hdr3col{property, type, description} | |
1472 | @row3col{bitmap, @ref overview_xrcformat_type_bitmap, | |
1473 | Bitmap to display (required).} | |
1474 | @endTable | |
1475 | ||
1476 | @subsubsection xrc_wxstaticbox wxStaticBox | |
1477 | ||
1478 | @beginTable | |
1479 | @hdr3col{property, type, description} | |
1480 | @row3col{label, @ref overview_xrcformat_type_text, | |
1481 | Static box's label (required).} | |
1482 | @endTable | |
1483 | ||
1484 | ||
1485 | @subsubsection xrc_wxstaticline wxStaticLine | |
1486 | ||
1487 | No additional properties. | |
1488 | ||
1489 | ||
1490 | @subsubsection xrc_wxstatictext wxStaticText | |
1491 | ||
1492 | @beginTable | |
1493 | @hdr3col{property, type, description} | |
1494 | @row3col{label, @ref overview_xrcformat_type_text, | |
1495 | Label to display (required).} | |
1496 | @row3col{wrap, integer, | |
1497 | Number of characters per line to wrap the text for, see | |
1498 | wxStaticText::Wrap() (default: no wrap).} | |
1499 | @endTable | |
1500 | ||
1501 | @subsubsection xrc_wxtextctrl wxTextCtrl | |
1502 | ||
1503 | @beginTable | |
1504 | @hdr3col{property, type, description} | |
1505 | @row3col{value, @ref overview_xrcformat_type_text, | |
1506 | Initial value of the control (default: empty).} | |
1507 | @row3col{maxlength, integer, | |
1508 | Maximum length of the text which can be entered by user (default: unlimited).} | |
1509 | @endTable | |
1510 | ||
1511 | ||
1512 | @subsubsection xrc_wxtogglebuttton wxToggleButton | |
1513 | ||
1514 | @beginTable | |
1515 | @hdr3col{property, type, description} | |
1516 | @row3col{label, @ref overview_xrcformat_type_text, | |
1517 | Label to display on the button (required).} | |
1518 | @row3col{checked, @ref overview_xrcformat_type_bool, | |
1519 | Should the button be checked/pressed initially (default: 0)?} | |
1520 | @endTable | |
1521 | ||
1522 | @subsubsection xrc_wxtoolbar wxToolBar | |
1523 | ||
1524 | @beginTable | |
1525 | @hdr3col{property, type, description} | |
1526 | @row3col{bitmapsize, @ref overview_xrcformat_type_size, | |
1527 | Size of toolbar bitmaps (default: not set).} | |
1528 | @row3col{margins, @ref overview_xrcformat_type_size, | |
1529 | Margins (default: platform default).} | |
1530 | @row3col{packing, integer, | |
1531 | Packing, see wxToolBar::SetToolPacking() (default: not set).} | |
1532 | @row3col{separation, integer, | |
1533 | Default separator size, see wxToolBar::SetToolSeparation() (default: not set).} | |
1534 | @row3col{dontattachtoframe, @ref overview_xrcformat_type_bool, | |
1535 | If set to 0 and the toolbar object is child of a wxFrame, | |
1536 | wxFrame::SetToolBar() is called; otherwise, you have to add it to a frame | |
1537 | manually. The toolbar is attached by default, you have to set this property | |
1538 | to 1 to disable this behaviour (default: 0).} | |
1539 | @endTable | |
1540 | ||
1541 | A toolbar can have one or more child objects of any wxControl-derived class or | |
1542 | one of two pseudo-classes: @c separator or @c tool. | |
1543 | ||
1544 | The @c separator pseudo-class is used to insert separators into the toolbar and | |
1545 | has neither properties nor children. | |
1546 | ||
1547 | The @c tool pseudo-class objects specify toolbar buttons and have the following | |
1548 | properties: | |
1549 | ||
1550 | @beginTable | |
1551 | @hdr3col{property, type, description} | |
1552 | @row3col{bitmap, @ref overview_xrcformat_type_bitmap, | |
1553 | Tool's bitmap (required).} | |
1554 | @row3col{bitmap2, @ref overview_xrcformat_type_bitmap, | |
1555 | Bitmap for disabled tool (default: derived from @c bitmap).} | |
1556 | @row3col{label, @ref overview_xrcformat_type_text, | |
1557 | Label to display on the tool (default: no label).} | |
1558 | @row3col{radio, @ref overview_xrcformat_type_bool, | |
1559 | Item's kind is wxITEM_RADIO (default: 0)?} | |
1560 | @row3col{toggle, @ref overview_xrcformat_type_bool, | |
1561 | Item's kind is wxITEM_CHECK (default: 0)?} | |
1562 | @row3col{dropdown, see below, | |
1563 | Item's kind is wxITEM_DROPDOWN (default: 0)? (only available since wxWidgets 2.9.0)} | |
1564 | @row3col{tooltip, @ref overview_xrcformat_type_text, | |
1565 | Tooltip to use for the tool (default: none).} | |
1566 | @row3col{longhelp, @ref overview_xrcformat_type_text, | |
1567 | Help text shown in statusbar when the mouse is on the tool (default: none).} | |
1568 | @row3col{disabled, @ref overview_xrcformat_type_bool, | |
1569 | Is the tool initially disabled (default: 0)?} | |
1570 | @endTable | |
1571 | ||
1572 | The presence of a @c dropdown property indicates that the tool is of type | |
1573 | wxITEM_DROPDOWN. It must be either empty or contain exactly one @ref | |
1574 | xrc_wxmenu child object defining the drop-down button associated menu. | |
1575 | ||
1576 | Notice that @c radio, @c toggle and @c dropdown are mutually exclusive. | |
1577 | ||
1578 | Children that are neither @c tool nor @c separator must be instances of classes | |
1579 | derived from wxControl and are added to the toolbar using | |
1580 | wxToolBar::AddControl(). | |
1581 | ||
1582 | Example: | |
1583 | @code | |
1584 | <object class="wxToolBar"> | |
1585 | <style>wxTB_FLAT|wxTB_NODIVIDER</style> | |
1586 | <object class="tool" name="foo"> | |
1587 | <bitmap>foo.png</bitmap> | |
1588 | <label>Foo</label> | |
1589 | </object> | |
1590 | <object class="tool" name="bar"> | |
1591 | <bitmap>bar.png</bitmap> | |
1592 | <label>Bar</label> | |
1593 | </object> | |
1594 | <object class="tool" name="view_auto"> | |
1595 | <bitmap>view.png</bitmap> | |
1596 | <label>View</label> | |
1597 | <dropdown> | |
1598 | <object class="wxMenu"> | |
1599 | <object class="wxMenuItem" name="view_as_text"> | |
1600 | <label>View as text</label> | |
1601 | </object> | |
1602 | <object class="wxMenuItem" name="view_as_hex"> | |
1603 | <label>View as binary</label> | |
1604 | </object> | |
1605 | </object> | |
1606 | </dropdown> | |
1607 | </object> | |
1608 | <object class="separator"/> | |
1609 | <object class="wxComboBox"> | |
1610 | <content> | |
1611 | <item>Just</item> | |
1612 | <item>a combobox</item> | |
1613 | <item>in the toolbar</item> | |
1614 | </content> | |
1615 | </object> | |
1616 | </object> | |
1617 | ||
1618 | @endcode | |
1619 | ||
1620 | ||
1621 | @subsubsection xrc_wxtreectrl wxTreeCtrl | |
1622 | ||
1623 | A treectrl can have one child object of the @ref xrc_wximagelist class. | |
1624 | ||
1625 | No additional properties. | |
1626 | ||
1627 | ||
1628 | @subsubsection xrc_wxtreebook wxTreebook | |
1629 | ||
1630 | A treebook can have one or more child objects of the @c treebookpage | |
1631 | pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its | |
1632 | @c notebookpage) and one child object of the @ref xrc_wximagelist class. | |
1633 | @c treebookpage objects have the following properties: | |
1634 | ||
1635 | @beginTable | |
1636 | @hdr3col{property, type, description} | |
1637 | @row3col{depth, integer, | |
1638 | Page's depth in the labels tree (required; see below).} | |
1639 | @row3col{label, @ref overview_xrcformat_type_text, | |
1640 | Sheet page's title (required).} | |
1641 | @row3col{bitmap, @ref overview_xrcformat_type_bitmap, | |
1642 | Bitmap shown alongside the label (default: none).} | |
1643 | @row3col{image, integer, | |
1644 | The zero-based index of the image associated with the item | |
1645 | into the image list.} | |
1646 | @row3col{selected, @ref overview_xrcformat_type_bool, | |
1647 | Is the page selected initially (only one page can be selected; default: 0)?} | |
1648 | @endTable | |
1649 | ||
1650 | Each @c treebookpage has exactly one non-toplevel window as its child. | |
1651 | ||
1652 | The tree of labels is not described using nested @c treebookpage objects, but | |
1653 | using the @em depth property. Toplevel pages have depth 0, their child pages | |
1654 | have depth 1 and so on. A @c treebookpage's label is inserted as child of | |
1655 | the latest preceding page with depth equal to @em depth-1. For example, this | |
1656 | XRC markup: | |
1657 | ||
1658 | @code | |
1659 | <object class="wxTreebook"> | |
1660 | ... | |
1661 | <object class="treebookpage"> | |
1662 | <depth>0</depth> | |
1663 | <label>Page 1</label> | |
1664 | <object class="wxPanel">...</object> | |
1665 | </object> | |
1666 | <object class="treebookpage"> | |
1667 | <depth>1</depth> | |
1668 | <label>Subpage 1A</label> | |
1669 | <object class="wxPanel">...</object> | |
1670 | </object> | |
1671 | <object class="treebookpage"> | |
1672 | <depth>2</depth> | |
1673 | <label>Subsubpage 1</label> | |
1674 | <object class="wxPanel">...</object> | |
1675 | </object> | |
1676 | <object class="treebookpage"> | |
1677 | <depth>1</depth> | |
1678 | <label>Subpage 1B</label> | |
1679 | <object class="wxPanel">...</object> | |
1680 | </object> | |
1681 | <object class="treebookpage"> | |
1682 | <depth>2</depth> | |
1683 | <label>Subsubpage 2</label> | |
1684 | <object class="wxPanel">...</object> | |
1685 | </object> | |
1686 | <object class="treebookpage"> | |
1687 | <depth>0</depth> | |
1688 | <label>Page 2</label> | |
1689 | <object class="wxPanel">...</object> | |
1690 | </object> | |
1691 | </object> | |
1692 | @endcode | |
1693 | ||
1694 | corresponds to the following tree of labels: | |
1695 | ||
1696 | - Page 1 | |
1697 | - Subpage 1A | |
1698 | - Subsubpage 1 | |
1699 | - Subpage 1B | |
1700 | - Subsubpage 2 | |
1701 | - Page 2 | |
1702 | ||
1703 | ||
1704 | @subsubsection xrc_wxwizard wxWizard | |
1705 | ||
1706 | @beginTable | |
1707 | @hdr3col{property, type, description} | |
1708 | @row3col{bitmap, @ref overview_xrcformat_type_bitmap, | |
1709 | Bitmap to display on the left side of the wizard (default: none).} | |
1710 | @endTable | |
1711 | ||
1712 | A wizard object can have one or more child objects of the wxWizardPage or | |
1713 | wxWizardPageSimple classes. They both support the following properties | |
1714 | (in addition to @ref overview_xrcformat_std_props): | |
1715 | ||
1716 | @beginTable | |
1717 | @hdr3col{property, type, description} | |
1718 | @row3col{bitmap, @ref overview_xrcformat_type_bitmap, | |
1719 | Page-specific bitmap (default: none).} | |
1720 | @endTable | |
1721 | ||
1722 | wxWizardPageSimple pages are automatically chained together; wxWizardPage pages | |
1723 | transitions must be handled programatically. | |
1724 | ||
1725 | ||
1726 | @section overview_xrcformat_sizers Sizers | |
1727 | ||
1728 | Sizers are handled slightly differently in XRC resources than they are in | |
1729 | wxWindow hierarchy. wxWindow's sizers hierarchy is parallel to the wxWindow | |
1730 | children hieararchy: child windows are children of their parent window and | |
1731 | the sizer (or sizers) form separate hierarchy attached to the window with | |
1732 | wxWindow::SetSizer(). | |
1733 | ||
1734 | In XRC, the two hierarchies are merged together: sizers are children of other | |
1735 | sizers or windows and they can contain child window objects. | |
1736 | ||
1737 | If a sizer is child of a window object in the resource, it must be the only | |
1738 | child and it will be attached to the parent with wxWindow::SetSizer(). | |
1739 | Additionally, if the window doesn't have its size explicitly set, | |
1740 | wxSizer::Fit() is used to resize the window. If the parent window is | |
1741 | toplevel window, wxSizer::SetSizeHints() is called to set its hints. | |
1742 | ||
1743 | A sizer object can have one or more child objects of one of two pseudo-classes: | |
1744 | @c sizeritem or @c spacer (see @ref overview_xrcformat_wxstddialogbuttonsizer for | |
1745 | an exception). The former specifies an element (another sizer or a window) | |
1746 | to include in the sizer, the latter adds empty space to the sizer. | |
1747 | ||
1748 | @c sizeritem objects have exactly one child object: either another sizer | |
1749 | object, or a window object. @c spacer objects don't have any children, but | |
1750 | they have one property: | |
1751 | ||
1752 | @beginTable | |
1753 | @hdr3col{property, type, description} | |
1754 | @row3col{size, @ref overview_xrcformat_type_size, Size of the empty space (required).} | |
1755 | @endTable | |
1756 | ||
1757 | Both @c sizeritem and @c spacer objects can have any of the following | |
1758 | properties: | |
1759 | ||
1760 | @beginTable | |
1761 | @hdr3col{property, type, description} | |
1762 | @row3col{option, integer, | |
1763 | The "option" value for sizers. Used by wxBoxSizer to set proportion of | |
1764 | the item in the growable direction (default: 0).} | |
1765 | @row3col{flag, @ref overview_xrcformat_type_style, | |
1766 | wxSizerItem flags (default: 0).} | |
1767 | @row3col{border, @ref overview_xrcformat_type_dimension, | |
1768 | Size of the border around the item (directions are specified in flags) | |
1769 | (default: 0).} | |
1770 | @row3col{minsize, @ref overview_xrcformat_type_size, | |
1771 | Minimal size of this item (default: no min size).} | |
1772 | @row3col{ratio, @ref overview_xrcformat_type_size, | |
1773 | Item ratio, see wxSizer::SetRatio() (default: no ratio).} | |
1774 | @row3col{cellpos, @ref overview_xrcformat_type_pos, | |
1775 | (wxGridBagSizer only) Position, see wxGBSizerItem::SetPos() (required). } | |
1776 | @row3col{cellspan, @ref overview_xrcformat_type_size, | |
1777 | (wxGridBagSizer only) Span, see wxGBSizerItem::SetSpan() (required). } | |
1778 | @endTable | |
1779 | ||
1780 | Example of sizers XRC code: | |
1781 | @code | |
1782 | <object class="wxDialog" name="derived_dialog"> | |
1783 | <title>Derived Dialog Example</title> | |
1784 | <centered>1</centered> | |
1785 | <!-- this sizer is set to be this dialog's sizer: --> | |
1786 | <object class="wxFlexGridSizer"> | |
1787 | <cols>1</cols> | |
1788 | <rows>0</rows> | |
1789 | <vgap>0</vgap> | |
1790 | <hgap>0</hgap> | |
1791 | <growablecols>0</growablecols> | |
1792 | <growablerows>0</growablerows> | |
1793 | <object class="sizeritem"> | |
1794 | <flag>wxALIGN_CENTRE|wxALL</flag> | |
1795 | <border>5</border> | |
1796 | <object class="wxButton" name="my_button"> | |
1797 | <label>My Button</label> | |
1798 | </object> | |
1799 | </object> | |
1800 | <object class="sizeritem"> | |
1801 | <flag>wxALIGN_CENTRE|wxALL</flag> | |
1802 | <border>5</border> | |
1803 | <object class="wxBoxSizer"> | |
1804 | <orient>wxHORIZONTAL</orient> | |
1805 | <object class="sizeritem"> | |
1806 | <flag>wxALIGN_CENTRE|wxALL</flag> | |
1807 | <border>5</border> | |
1808 | <object class="wxCheckBox" name="my_checkbox"> | |
1809 | <label>Enable this text control:</label> | |
1810 | </object> | |
1811 | </object> | |
1812 | <object class="sizeritem"> | |
1813 | <flag>wxALIGN_CENTRE|wxALL</flag> | |
1814 | <border>5</border> | |
1815 | <object class="wxTextCtrl" name="my_textctrl"> | |
1816 | <size>80,-1</size> | |
1817 | <value></value> | |
1818 | </object> | |
1819 | </object> | |
1820 | </object> | |
1821 | </object> | |
1822 | ... | |
1823 | </object> | |
1824 | </object> | |
1825 | @endcode | |
1826 | ||
1827 | The sizer classes that can be used are listed below, together with their | |
1828 | class-specific properties. All classes support the following properties: | |
1829 | ||
1830 | @beginTable | |
1831 | @hdr3col{property, type, description} | |
1832 | @row3col{minsize, @ref overview_xrcformat_type_size, | |
1833 | Minimal size that this sizer will have, see wxSizer::SetMinSize() | |
1834 | (default: no min size).} | |
1835 | @endTable | |
1836 | ||
1837 | @subsection overview_xrcformat_wxboxsizer wxBoxSizer | |
1838 | ||
1839 | @beginTable | |
1840 | @hdr3col{property, type, description} | |
1841 | @row3col{orient, @ref overview_xrcformat_type_style, | |
1842 | Sizer orientation, "wxHORIZONTAL" or "wxVERTICAL" (default: wxHORIZONTAL).} | |
1843 | @endTable | |
1844 | ||
1845 | @subsection overview_xrcformat_wxstaticsboxizer wxStaticBoxSizer | |
1846 | ||
1847 | @beginTable | |
1848 | @hdr3col{property, type, description} | |
1849 | @row3col{orient, @ref overview_xrcformat_type_style, | |
1850 | Sizer orientation, "wxHORIZONTAL" or "wxVERTICAL" (default: wxHORIZONTAL).} | |
1851 | @row3col{label, @ref overview_xrcformat_type_text, | |
1852 | Label to be used for the static box around the sizer (required).} | |
1853 | @endTable | |
1854 | ||
1855 | @subsection overview_xrcformat_wxgridsizer wxGridSizer | |
1856 | ||
1857 | @beginTable | |
1858 | @hdr3col{property, type, description} | |
1859 | @row3col{rows, integer, Number of rows in the grid (default: 0 - determine automatically).} | |
1860 | @row3col{cols, integer, Number of columns in the grid (default: 0 - determine automatically).} | |
1861 | @row3col{vgap, integer, Vertical gap between children (default: 0).} | |
1862 | @row3col{hgap, integer, Horizontal gap between children (default: 0).} | |
1863 | @endTable | |
1864 | ||
1865 | @subsection overview_xrcformat_wxflexgridsizer wxFlexGridSizer | |
1866 | ||
1867 | @beginTable | |
1868 | @hdr3col{property, type, description} | |
1869 | @row3col{rows, integer, Number of rows in the grid (default: 0 - determine automatically).} | |
1870 | @row3col{cols, integer, Number of columns in the grid (default: 0 - determine automatically).} | |
1871 | @row3col{vgap, integer, Vertical gap between children (default: 0).} | |
1872 | @row3col{hgap, integer, Horizontal gap between children (default: 0).} | |
1873 | @row3col{growablerows, comma-separated integers list, | |
1874 | Comma-separated list of indexes of rows that are growable | |
1875 | (default: none).} | |
1876 | @row3col{growablecols, comma-separated integers list, | |
1877 | Comma-separated list of indexes of columns that are growable | |
1878 | (default: none).} | |
1879 | @endTable | |
1880 | ||
1881 | @subsection overview_xrcformat_wxgridbagsizer wxGridBagSizer | |
1882 | ||
1883 | @beginTable | |
1884 | @hdr3col{property, type, description} | |
1885 | @row3col{vgap, integer, Vertical gap between children (default: 0).} | |
1886 | @row3col{hgap, integer, Horizontal gap between children (default: 0).} | |
1887 | @row3col{growablerows, comma-separated integers list, | |
1888 | Comma-separated list of indexes of rows that are growable | |
1889 | (default: none).} | |
1890 | @row3col{growablecols, comma-separated integers list, | |
1891 | Comma-separated list of indexes of columns that are growable | |
1892 | (default: none).} | |
1893 | @endTable | |
1894 | ||
1895 | @subsection overview_xrcformat_wxwrapsizer wxWrapSizer | |
1896 | ||
1897 | @beginTable | |
1898 | @hdr3col{property, type, description} | |
1899 | @row3col{orient, @ref overview_xrcformat_type_style, | |
1900 | Sizer orientation, "wxHORIZONTAL" or "wxVERTICAL" (required).} | |
1901 | @row3col{flag, @ref overview_xrcformat_type_style, wxWrapSizer flags (default: 0).} | |
1902 | @endTable | |
1903 | ||
1904 | @subsection overview_xrcformat_wxstddialogbuttonsizer wxStdDialogButtonSizer | |
1905 | ||
1906 | Unlike other sizers, wxStdDialogButtonSizer doesn't have neither @c sizeritem | |
1907 | nor @c spacer children. Instead, it has one or more children of the | |
1908 | @c button pseudo-class. @c button objects have no properties and they must | |
1909 | always have exactly one child of the @c wxButton class or a class derived from | |
1910 | wxButton. | |
1911 | ||
1912 | Example: | |
1913 | @code | |
1914 | <object class="wxStdDialogButtonSizer"> | |
1915 | <object class="button"> | |
1916 | <object class="wxButton" name="wxID_OK"> | |
1917 | <label>OK</label> | |
1918 | </object> | |
1919 | </object> | |
1920 | <object class="button"> | |
1921 | <object class="wxButton" name="wxID_CANCEL"> | |
1922 | <label>Cancel</label> | |
1923 | </object> | |
1924 | </object> | |
1925 | </object> | |
1926 | @endcode | |
1927 | ||
1928 | ||
1929 | ||
1930 | @section overview_xrcformat_other_objects Other Objects | |
1931 | ||
1932 | In addition to describing UI elements, XRC files can contain non-windows | |
1933 | objects such as bitmaps or icons. This is a concession to Windows developers | |
1934 | used to storing them in Win32 resources. | |
1935 | ||
1936 | Note that unlike Win32 resources, bitmaps included in XRC files are @em not | |
1937 | embedded in the XRC file itself. XRC file only contains a reference to another | |
1938 | file with bitmap data. | |
1939 | ||
1940 | @subsection overview_xrcformat_bitmap wxBitmap | |
1941 | ||
1942 | Bitmaps are stored in @c \<object\> element with class set to @c wxBitmap. Such | |
1943 | bitmaps can then be loaded using wxXmlResource::LoadBitmap(). The content of | |
1944 | the element is exactly same as in the case of | |
1945 | @ref overview_xrcformat_type_bitmap "bitmap properties", except that toplevel | |
1946 | @c \<object\> is used. | |
1947 | ||
1948 | For example, instead of: | |
1949 | @code | |
1950 | <bitmap>mybmp.png</bitmap> | |
1951 | <bitmap stock_id="wxART_NEW"/> | |
1952 | @endcode | |
1953 | toplevel wxBitmap resources would look like: | |
1954 | @code | |
1955 | <object class="wxBitmap" name="my_bitmap">mybmp.png</object> | |
1956 | <object class="wxBitmap" name="my_new_bitmap" stock_id="wxART_NEW"/> | |
1957 | @endcode | |
1958 | ||
1959 | ||
1960 | @subsection overview_xrcformat_icon wxIcon | |
1961 | ||
1962 | wxIcon resources are identical to @ref overview_xrcformat_bitmap "wxBitmap ones", | |
1963 | except that the class is @c wxIcon. | |
1964 | ||
1965 | ||
1966 | @section overview_xrcformat_platform Platform Specific Content | |
1967 | ||
1968 | It is possible to conditionally process parts of XRC files on some platforms | |
1969 | only and ignore them on other platforms. @em Any element in XRC file, be it | |
1970 | toplevel or arbitrarily nested one, can have the @c platform attribute. When | |
1971 | used, @c platform contains |-separated list of platforms that this element | |
1972 | should be processed on. It is filtered out and ignored on any other platforms. | |
1973 | ||
1974 | Possible elemental values are: | |
1975 | @beginDefList | |
1976 | @itemdef{ @c win, Windows } | |
1977 | @itemdef{ @c mac, Mac OS X (or Mac Classic in wxWidgets version supporting it } | |
1978 | @itemdef{ @c unix, Any Unix platform @em except OS X } | |
1979 | @itemdef{ @c os2, OS/2 } | |
1980 | @endDefList | |
1981 | ||
1982 | Examples: | |
1983 | @code | |
1984 | <label platform="win">Windows</label> | |
1985 | <label platform="unix">Unix</label> | |
1986 | <label platform="mac">Mac OS X</label> | |
1987 | <help platform="mac|unix">Not a Windows machine</help> | |
1988 | @endcode | |
1989 | ||
1990 | ||
1991 | ||
1992 | @section overview_xrcformat_extending Extending the XRC Format | |
1993 | ||
1994 | The XRC format is designed to be extensible and allows specifying and loading | |
1995 | custom controls. The three available mechanisms are described in the rest of | |
1996 | this section in the order of increasing complexity. | |
1997 | ||
1998 | @subsection overview_xrcformat_extending_subclass Subclassing | |
1999 | ||
2000 | The simplest way to add custom controls is to set the @c subclass attribute | |
2001 | of @c \<object\> element: | |
2002 | ||
2003 | @code | |
2004 | <object name="my_value" class="wxTextCtrl" subclass="MyTextCtrl"> | |
2005 | <style>wxTE_MULTILINE</style> | |
2006 | ...etc., setup wxTextCtrl as usual... | |
2007 | </object> | |
2008 | @endcode | |
2009 | ||
2010 | In that case, wxXmlResource will create an instance of the specified subclass | |
2011 | (@c MyTextCtrl in the example above) instead of the class (@c wxTextCtrl above) | |
2012 | when loading the resource. However, the rest of the object's loading (calling | |
2013 | its Create() method, setting its properties, loading any children etc.) | |
2014 | will proceed in @em exactly the same way as it would without @c subclass | |
2015 | attribute. In other words, this approach is only sufficient when the custom | |
2016 | class is just a small modification (e.g. overridden methods or customized | |
2017 | events handling) of an already supported classes. | |
2018 | ||
2019 | The subclass must satisfy a number of requirements: | |
2020 | ||
2021 | -# It must be derived from the class specified in @c class attribute. | |
2022 | -# It must be visible in wxWidget's pseudo-RTTI mechanism, i.e. there must be | |
2023 | a DECLARE_DYNAMIC_CLASS() entry for it. | |
2024 | -# It must support two-phase creation. In particular, this means that it has | |
2025 | to have default constructor. | |
2026 | -# It cannot provide custom Create() method and must be constructible using | |
2027 | base @c class' Create() method (this is because XRC will call Create() of | |
2028 | @c class, not @c subclass). In other words, @em creation of the control | |
2029 | must not be customized. | |
2030 | ||
2031 | ||
2032 | @subsection overview_xrcformat_extending_unknown Unknown Objects | |
2033 | ||
2034 | A more flexible solution is to put a @em placeholder in the XRC file and | |
2035 | replace it with custom control after the resource is loaded. This is done by | |
2036 | using the @c unknown pseudo-class: | |
2037 | ||
2038 | @code | |
2039 | <object class="unknown" name="my_placeholder"/> | |
2040 | @endcode | |
2041 | ||
2042 | The placeholder is inserted as dummy wxPanel that will hold custom control in | |
2043 | it. At runtime, after the resource is loaded and a window created from it | |
2044 | (using e.g. wxXmlResource::LoadDialog()), use code must call | |
2045 | wxXmlResource::AttachUnknownControl() to insert the desired control into | |
2046 | placeholder container. | |
2047 | ||
2048 | This method makes it possible to insert controls that are not known to XRC at | |
2049 | all, but it's also impossible to configure the control in XRC description in | |
2050 | any way. The only properties that can be specified are | |
2051 | the @ref overview_xrcformat_std_props "standard window properties". | |
2052 | ||
2053 | @note @c unknown class cannot be combined with @c subclass attribute, | |
2054 | they are mutually exclusive. | |
2055 | ||
2056 | ||
2057 | @subsection overview_xrcformat_extending_custom Adding Custom Classes | |
2058 | ||
2059 | Finally, XRC allows adding completely new classes in addition to the ones | |
2060 | listed in this document. A class for which wxXmlResourceHandler is implemented | |
2061 | can be used as first-class object in XRC simply by passing class name as the | |
2062 | value of @c class attribute: | |
2063 | ||
2064 | @code | |
2065 | <object name="my_ctrl" class="MyWidget"> | |
2066 | <my_prop>foo</my_prop> | |
2067 | ...etc., whatever MyWidget handler accepts... | |
2068 | </object> | |
2069 | @endcode | |
2070 | ||
2071 | The only requirements on the class are that | |
2072 | -# the class must derive from wxObject | |
2073 | -# it must support wxWidget's pseudo-RTTI mechanism | |
2074 | ||
2075 | Child elements of @c \<object\> are handled by the custom handler and there are | |
2076 | no limitations on them imposed by XRC format. | |
2077 | ||
2078 | This is the only mechanism that works for toplevel objects -- custom controls | |
2079 | are accessible using type-unsafe wxXmlResource::LoadObject() method. | |
2080 | ||
2081 | ||
2082 | ||
2083 | @section overview_xrcformat_packed Packed XRC Files | |
2084 | ||
2085 | In addition to plain XRC files, wxXmlResource supports (if wxFileSystem support | |
2086 | is compiled in) compressed XRC resources. Compressed resources have either | |
2087 | .zip or .xrs extension and are simply ZIP files that contain arbitrary | |
2088 | number of XRC files and their dependencies (bitmaps, icons etc.). | |
2089 | ||
2090 | ||
2091 | ||
2092 | @section overview_xrcformat_oldversions Older Format Versions | |
2093 | ||
2094 | This section describes differences in older revisions of XRC format (i.e. | |
2095 | files with older values of @c version attribute of @c \<resource\>). | |
2096 | ||
2097 | ||
2098 | @subsection overview_xrcformat_pre_v2530 Versions Before 2.5.3.0 | |
2099 | ||
2100 | Version 2.5.3.0 introduced C-like handling of "\\" in text. In older versions, | |
2101 | "\n", "\t" and "\r" escape sequences were replaced with respective characters | |
2102 | in the same matter it's done in C, but "\\" was left intact instead of being | |
2103 | replaced with single "\", as one would expect. Starting with 2.5.3.0, all of | |
2104 | them are handled in C-like manner. | |
2105 | ||
2106 | ||
2107 | @subsection overview_xrcformat_pre_v2301 Versions Before 2.3.0.1 | |
2108 | ||
2109 | Prior to version 2.3.0.1, "$" was used for accelerators instead of "_" | |
2110 | or "&". For example, | |
2111 | @code | |
2112 | <label>$File</label> | |
2113 | @endcode | |
2114 | was used in place of current version's | |
2115 | @code | |
2116 | <label>_File</label> | |
2117 | @endcode | |
2118 | (or "&File"). | |
2119 | ||
2120 | */ |