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