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