1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: XRC format specification
4 // Author: Vaclav Slavik
5 // Licence: wxWindows licence
6 /////////////////////////////////////////////////////////////////////////////
10 NOTE: To make doxygen happy about <custom-tags> we're forced to
11 escape all < and > symbols which appear inside a doxygen comment.
12 Also, don't use < and > symbols in section titles.
18 @page overview_xrcformat XRC File Format
22 This document describes the format of XRC resource files, as used by
25 Formal description in the form of a RELAX NG schema is located in the
26 @c misc/schema subdirectory of the wxWidgets sources.
28 XRC file is a XML file with all of its elements in the
29 @c http://www.wxwidgets.org/wxxrc namespace. For backward compatibility,
30 @c http://www.wxwindows.org/wxxrc namespace is accepted as well (and treated
31 as identical to @c http://www.wxwidgets.org/wxxrc), but it shouldn't be used
34 XRC file contains definitions for one or more @em objects -- typically
35 windows. The objects may themselves contain child objects.
37 Objects defined at the top level, under the
38 @ref overview_xrcformat_root "root element", can be accessed using
39 wxXmlResource::LoadDialog() and other LoadXXX methods. They must have
40 @c name attribute that is used as LoadXXX's argument (see
41 @ref overview_xrcformat_object for details).
43 Child objects are not directly accessible via wxXmlResource, they can only
44 be accessed using XRCCTRL().
48 @section overview_xrcformat_root Resource Root Element
50 The root element is always @c \<resource\>. It has one optional attribute, @c
51 version. If set, it specifies version of the file. In absence of @c version
52 attribute, the default is @c "0.0.0.0".
54 The version consists of four integers separated by periods. The first three
55 components are major, minor and release number of the wxWidgets release when
56 the change was introduced, the last one is revision number and is 0 for the
57 first incompatible change in given wxWidgets release, 1 for the second and so
58 on. The version changes only if there was an incompatible change introduced;
59 merely adding new kind of objects does not constitute incompatible change.
61 At the time of writing, the latest version is @c "2.5.3.0".
63 Note that even though @c version attribute is optional, it should always be
64 specified to take advantage of the latest capabilities:
68 <resource xmlns="http://www.wxwidgets.org/wxxrc" version="2.5.3.0">
73 @c \<resource\> may have arbitrary number of
74 @ref overview_xrcformat_objects "object elements" as its children; they are referred
75 to as @em toplevel objects in the rest of this document. Unlike objects defined
76 deeper in the hierarchy, toplevel objects @em must have their @c name attribute
77 set and it must be set to a value unique among root's children.
81 @section overview_xrcformat_objects Defining Objects
83 @subsection overview_xrcformat_object Object Element
85 The @c \<object\> element represents a single object (typically a GUI element)
86 and it usually maps directly to a wxWidgets class instance. It has one
87 mandatory attribute, @c class, and optional @c name and @c subclass attributes.
89 The @c class attribute must always be present, it tells XRC what wxWidgets
90 object should be created and by which wxXmlResourceHandler.
92 @c name is the identifier used to identify the object. This name serves three
95 -# It is used by wxXmlResource's various LoadXXX() methods to find the
96 resource by name passed as argument.
97 -# wxWindow's name (see wxWindow::GetName()) is set to it.
98 -# Numeric ID of a window or menu item is derived from the name.
99 If the value represents an integer (in decimal notation), it is used for
100 the numeric ID unmodified. If it is one of the wxID_XXX literals defined
101 by wxWidgets (see @ref page_stockitems), its respective value is used.
102 Otherwise, the name is transformed into dynamically generated ID. See
103 wxXmlResource::GetXRCID() for more information.
105 Name attributes must be unique at the top level (where the name is used to
106 load resources) and should be unique among all controls within the same
107 toplevel window (wxDialog, wxFrame).
109 The @c subclass attribute optional name of class whose constructor will be
110 called instead of the constructor for "class".
111 See @ref overview_xrcformat_extending_subclass for more details.
113 @c \<object\> element may -- and almost always do -- have children elements.
114 These come in two varieties:
116 -# Object's properties. A @em property is a value describing part of object's
117 behaviour, for example the "label" property on wxButton defines its label.
118 In the most common form, property is a single element with text content
119 ("\<label\>Cancel\</label\>"), but they may use nested subelements too (e.g.
120 @ref overview_xrcformat_type_font "font property"). A property can only be
121 listed once in an object's definition.
122 -# Child objects. Window childs, sizers, sizer items or notebook pages
123 are all examples of child objects. They are represented using nested
124 @c \<object\> elements and are can be repeated more than once. The specifics
125 of which object classes are allowed as children are class-specific and
126 are documented below in @ref overview_xrcformat_controls.
130 <object class="wxDialog" name="example_dialog">
132 <title>Non-Derived Dialog Example</title>
133 <centered>1</centered>
134 <!-- child objects: -->
135 <object class="wxBoxSizer">
136 <orient>wxVERTICAL</orient>
145 @subsection overview_xrcformat_object_ref Object References
147 Anywhere an @c \<object\> element can be used, @c \<object_ref\> may be used
148 instead. @c \<object_ref\> is a @em reference to another named (i.e. with the
149 @c name attribute) @c \<object\> element. It has one mandatory attribute,
150 @c ref, with value containing the name of a named @c \<object\> element. When an
151 @c \<object_ref\> is encountered, a copy of the referenced @c \<object\> element
152 is made in place of @c \<object_ref\> occurrence and processed as usual.
154 For example, the following code:
156 <object class="wxDialog" name="my_dlg">
159 <object_ref name="my_dlg_alias" ref="my_dlg"/>
163 <object class="wxDialog" name="my_dlg">
166 <object class="wxDialog" name="my_dlg_alias">
167 ... <!-- same as in my_dlg -->
171 Additionally, it is possible to override some parts of the referenced object
172 in the @c \<object_ref\> pointing to it. This is useful for putting repetitive
173 parts of XRC definitions into a template that can be reused and customized in
174 several places. The two parts are merged as follows:
176 -# The referred object is used as the initial content.
177 -# All attributes set on @c \<object_ref\> are added to it.
178 -# All child elements of @c \<object_ref\> are scanned. If an element with
179 the same name (and, if specified, the @c name attribute too) is found
180 in the referred object, they are recursively merged.
181 -# Child elements in @c \<object_ref\> that do not have a match in the referred
182 object are appended to the list of children of the resulting element by
183 default. Optionally, they may have @c insert_at attribute with two possible
184 values, "begin" or "end". When set to "begin", the element is prepended to
185 the list of children instead of appended.
187 For example, "my_dlg" in this snippet:
189 <object class="wxDialog" name="template">
190 <title>Dummy dialog</title>
193 <object_ref ref="template" name="my_dlg">
194 <title>My dialog</title>
195 <centered>1</centered>
200 <object class="wxDialog" name="my_dlg">
201 <title>My dialog</title>
203 <centered>1</centered>
208 @section overview_xrcformat_datatypes Data Types
210 There are several property data types that are frequently reused by different
211 properties. Rather than describing their format in the documentation of
212 every property, we list commonly used types in this section and document
216 @subsection overview_xrcformat_type_bool Boolean
218 Boolean values are expressed using either "1" literal (true) or "0" (false).
221 @subsection overview_xrcformat_type_float Floating-point value
223 Floating point values use POSIX (C locale) formatting -- decimal separator
224 is "." regardless of the locale.
227 @subsection overview_xrcformat_type_colour Colour
229 Colour specification can be either any string colour representation accepted
230 by wxColour::Set() or any wxSYS_COLOUR_XXX symbolic name accepted by
231 wxSystemSettings::GetColour(). In particular, the following forms are supported:
233 @li named colours from wxColourDatabase
234 @li HTML-like "#rrggbb" syntax (but not "#rgb")
235 @li CSS-style "rgb(r,g,b)" and "rgba(r,g,b,a)"
236 @li wxSYS_COLOUR_XXX symbolic names
242 <fg>rgb(255,0,0)</fg>
243 <fg>wxSYS_COLOUR_HIGHLIGHT</fg>
247 @subsection overview_xrcformat_type_size Size
249 Sizes and positions have the form of string with two comma-separated integer
250 components, with optional "d" suffix. Semi-formally:
252 size := x "," y ["d"]
254 where x and y are integers. Either of the components (or both) may be "-1" to
255 signify default value. As a shortcut, empty string is equivalent to "-1,-1"
256 (= wxDefaultSize or wxDefaultPosition).
258 When the "d" suffix is used, integer values are interpreted as
259 @ref wxWindow::ConvertDialogToPixels() "dialog units" in the parent window.
268 @subsection overview_xrcformat_type_pos Position
270 Same as @ref overview_xrcformat_type_size.
273 @subsection overview_xrcformat_type_dimension Dimension
275 Similarly to @ref overview_xrcformat_type_size "sizes", dimensions are expressed
276 as integers with optional "d" suffix. When "d" suffix is used, the integer
277 preceding it is interpreted as dialog units in the parent window.
280 @subsection overview_xrcformat_type_text Text
282 String properties use several escape sequences that are translated according to
285 @itemdef{ "_", "&" (used for accelerators in wxWidgets) }
286 @itemdef{ "__", "_" }
287 @itemdef{ "\n", line break }
288 @itemdef{ "\r", carriage return }
289 @itemdef{ "\t", tab }
290 @itemdef{ "\\", "\" }
293 By default, the text is translated using wxLocale::GetTranslation() before
294 it is used. This can be disabled either globally by not passing
295 wxXRC_USE_LOCALE to wxXmlResource constructor, or by setting the @c translate
296 attribute on the property node to "0":
298 <!-- this is not translated: -->
299 <label translate="0">_Unix</label>
300 <!-- but this is: -->
301 <help>Use Unix-style newlines</help>
304 @note Even though the "_" character is used instead of "&" for accelerators,
305 it is still possible to use "&". The latter has to be encoded as "&",
306 though, so using "_" is more convenient.
308 @see @ref overview_xrcformat_pre_v2530, @ref overview_xrcformat_pre_v2301
311 @subsection overview_xrcformat_type_text_notrans Non-Translatable Text
313 Like @ref overview_xrcformat_type_text, but the text is never translated and
314 @c translate attribute cannot be used.
317 @subsection overview_xrcformat_type_string String
319 An unformatted string. Unlike with @ref overview_xrcformat_type_text, no escaping
320 or translations are done.
323 @subsection overview_xrcformat_type_url URL
325 Any URL accepted by wxFileSystem (typically relative to XRC file's location,
326 but can be absolute too). Unlike with @ref overview_xrcformat_type_text, no escaping
327 or translations are done.
330 @subsection overview_xrcformat_type_bitmap Bitmap
332 Bitmap properties contain specification of a single bitmap or icon. In the most
333 basic form, their text value is simply a relative filename (or another
334 wxFileSystem URL) of the bitmap to use. For example:
336 <object class="tool" name="wxID_NEW">
337 <tooltip>New</tooltip>
338 <bitmap>new.png</bitmap>
341 The value is interpreted as path relative to the location of XRC file where the
344 Alternatively, it is possible to specify the bitmap using wxArtProvider IDs.
345 In this case, the property element has no textual value (filename) and instead
346 has the @c stock_id XML attribute that contains stock art ID as accepted by
347 wxArtProvider::GetBitmap(). This can be either custom value (if the app uses
348 app-specific art provider) or one of the predefined wxART_XXX constants.
350 Optionally, @c stock_client attribute may be specified too and contain one of
351 the predefined wxArtClient values. If it is not specified, the default client
352 ID most appropriate in the context where the bitmap is referenced will be used.
353 In most cases, specifying @c stock_client is not needed.
355 Examples of stock bitmaps usage:
357 <bitmap stock_id="fixed-width"/> <!-- custom app-specific art -->
358 <bitmap stock_id="wxART_FILE_OPEN"/> <!-- standard art -->
361 If both specifications are provided, then @c stock_id is used if it is
362 recognized by wxArtProvider and the provided bitmap file is used as a fallback.
365 @subsection overview_xrcformat_type_style Style
367 Style properties (such as window's style or sizer flags) use syntax similar to
368 C++: the style value is OR-combination of individual flags. Symbolic names
369 identical to those used in C++ code are used for the flags. Flags are separated
370 with "|" (whitespace is allowed but not required around it).
372 The flags that are allowed for a given property are context-dependent.
376 <style>wxCAPTION|wxSYSTEM_MENU | wxRESIZE_BORDER</style>
377 <exstyle>wxDIALOG_EX_CONTEXTHELP</exstyle>
381 @subsection overview_xrcformat_type_font Font
383 XRC uses similar, but more flexible, abstract description of fonts to that
384 used by wxFont class. A font can be described either in terms of its elementary
385 properties, or it can be derived from one of system fonts or the parent window
388 The font property element is a "composite" element: unlike majority of
389 properties, it doesn't have text value but contains several child elements
390 instead. These children are handled in the same way as object properties
391 and can be one of the following "sub-properties":
394 @hdr3col{property, type, description}
395 @row3col{size, unsigned integer,
396 Pixel size of the font (default: wxNORMAL_FONT's size or @c sysfont's
397 size if the @c sysfont property is used or the current size of the font
398 of the enclosing control if the @c inherit property is used.}
399 @row3col{style, enum,
400 One of "normal", "italic" or "slant" (default: normal).}
401 @row3col{weight, enum,
402 One of "normal", "bold" or "light" (default: normal).}
403 @row3col{family, enum,
404 One of "roman", "script", "decorative", "swiss", "modern" or "teletype"
406 @row3col{underlined, @ref overview_xrcformat_type_bool,
407 Whether the font should be underlined (default: 0).}
409 Comma-separated list of face names; the first one available is used
410 (default: unspecified).}
412 Charset of the font, unused in Unicode build), as string
413 (default: unspecified).}
415 Symbolic name of system standard font(one of wxSYS_*_FONT constants).}
416 @row3col{inherit, @ref overview_xrcformat_type_bool,
417 If true, the font of the enclosing control is used. If this property and the
418 @c sysfont property are specified the @c sysfont property takes precedence.}
419 @row3col{relativesize, float,
420 Float, font size relative to chosen system font's or inherited font's size;
421 can only be used when 'sysfont' or 'inherit' is used and when 'size' is not
425 All of them are optional, if they are missing, appropriate wxFont default is
426 used. If the @c sysfont or @c inherit property is used, then the defaults are
427 taken from it instead.
432 <!-- fixed font: Arial if available, fall back to Helvetica -->
433 <face>arial,helvetica</face>
438 <!-- enlarged, enboldened standard font: -->
439 <sysfont>wxSYS_DEFAULT_GUI_FONT</sysfont>
440 <weight>bold</weight>
441 <relativesize>1.5</relativesize>
445 @note You cannot use @c inherit for a font that gets used before the enclosing
446 control is created, e.g. if the control gets the font passed as parameter
447 for its constructor, or if the control is not derived from wxWindow.
450 @subsection overview_xrcformat_type_imagelist Image List
452 Defines a wxImageList.
454 The imagelist property element is a "composite" element: unlike majority of
455 properties, it doesn't have text value but contains several child elements
456 instead. These children are handled similarly to object properties
457 and can be one of the following "sub-properties":
460 @hdr3col{property, type, description}
461 @row3col{mask, @ref overview_xrcformat_type_bool,
462 If masks should be created for all images (default: 1).}
463 @row3col{size, @ref overview_xrcformat_type_size,
464 The size of the images in the list (default: the size of the first bitmap).}
465 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
466 Adds a new image. Unlike normal object properties, @c bitmap may be used more than once
467 to add multiple images to the list. At least one @c bitmap value is required.}
474 <bitmap stock_id="wxART_QUESTION"/>
475 <bitmap stock_id="wxART_INFORMATION"/>
480 @section overview_xrcformat_windows Controls and Windows
482 This section describes support wxWindow-derived classes in XRC format.
484 @subsection overview_xrcformat_std_props Standard Properties
486 The following properties are always (unless stated otherwise in
487 control-specific docs) available for @em windows objects. They are omitted
488 from properties lists below.
491 @hdr3col{property, type, description}
492 @row3col{pos, @ref overview_xrcformat_type_pos,
493 Initial position of the window (default: wxDefaultPosition).}
494 @row3col{size, @ref overview_xrcformat_type_size,
495 Initial size of the window (default: wxDefaultSize).}
496 @row3col{style, @ref overview_xrcformat_type_style,
497 Window style for this control. The allowed values depend on what
498 window is being created, consult respective class' constructor
499 documentation for details (default: window-dependent default, usually
500 wxFOO_DEFAULT_STYLE if defined for class wxFoo, 0 if not).}
501 @row3col{exstyle, @ref overview_xrcformat_type_style,
502 Extra style for the window, if any. See wxWindow::SetExtraStyle()
504 @row3col{fg, @ref overview_xrcformat_type_colour,
505 Foreground colour of the window (default: window's default).}
506 @row3col{ownfg, @ref overview_xrcformat_type_colour,
507 Non-inheritable foreground colour of the window, see
508 wxWindow::SetOwnForegroundColour() (default: none).}
509 @row3col{bg, @ref overview_xrcformat_type_colour,
510 Background colour of the window (default: window's default).}
511 @row3col{ownbg, @ref overview_xrcformat_type_colour,
512 Non-inheritable background colour of the window, see
513 wxWindow::SetOwnBackgroundColour() (default: none).}
514 @row3col{enabled, @ref overview_xrcformat_type_bool,
515 If set to 0, the control is disabled (default: 1).}
516 @row3col{focused, @ref overview_xrcformat_type_bool,
517 If set to 1, the control has focus initially (default: 0).}
518 @row3col{hidden, @ref overview_xrcformat_type_bool,
519 If set to 1, the control is created hidden (default: 0).}
520 @row3col{tooltip, @ref overview_xrcformat_type_text,
521 Tooltip to use for the control (default: not set).}
522 @row3col{font, @ref overview_xrcformat_type_font,
523 Font to use for the control (default: window's default).}
524 @row3col{ownfont, @ref overview_xrcformat_type_font,
525 Non-inheritable font to use for the control, see
526 wxWindow::SetOwnFont() (default: none).}
527 @row3col{help, @ref overview_xrcformat_type_text,
528 Context-sensitive help for the control, used by wxHelpProvider
532 All of these properties are optional.
535 @subsection overview_xrcformat_controls Supported Controls
537 This section lists all controls supported by default. For each control, its
538 control-specific properties are listed. If the control can have child objects,
539 it is documented there too; unless said otherwise, XRC elements for these
540 controls cannot have children.
542 @subsubsection xrc_wxanimationctrl wxAnimationCtrl
545 @hdr3col{property, type, description}
546 @row3col{animation, @ref overview_xrcformat_type_url,
547 Animation file to load into the control (default: none).}
548 @row3col{inactive-bitmap, @ref overview_xrcformat_type_bitmap,
549 Bitmap to use when not playing the animation (default: the default).}
553 @subsubsection xrc_wxauinotebook wxAuiNotebook
555 A wxAuiNotebook can have one or more child objects of the @c notebookpage
557 @c notebookpage objects have the following properties:
560 @hdr3col{property, type, description}
561 @row3col{label, @ref overview_xrcformat_type_text,
562 Page label (required).}
563 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
564 Bitmap shown alongside the label (default: none).}
565 @row3col{selected, @ref overview_xrcformat_type_bool,
566 Is the page selected initially (only one page can be selected; default: 0)?}
569 Each @c notebookpage must have exactly one non-toplevel window as its child.
573 <object class="wxAuiNotebook">
574 <style>wxBK_BOTTOM</style>
575 <object class="notebookpage">
576 <label>Page 1</label>
577 <bitmap>bitmap.png</bitmap>
578 <object class="wxPanel" name="page_1">
585 Notice that wxAuiNotebook support in XRC is available in wxWidgets 2.9.5 and
586 later only and you need to explicitly register its handler using
588 #include <wx/xrc/xh_auinotbk.h>
590 AddHandler(new wxAuiNotebookXmlHandler);
595 @subsubsection xrc_wxbannerwindow wxBannerWindow
598 @hdr3col{property, type, description}
599 @row3col{direction, @c wxLEFT|wxRIGHT|wxTOP|wxBOTTOM,
600 The side along which the banner will be positioned (default: wxLEFT).}
601 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
602 Bitmap to use as the banner background (default: none).}
603 @row3col{title, @ref overview_xrcformat_type_text,
604 Banner title, should be single line (default: none).}
605 @row3col{message, @ref overview_xrcformat_type_text,
606 Possibly multi-line banner message (default: none).}
607 @row3col{gradient-start, @ref overview_xrcformat_type_colour,
608 Starting colour of the gradient used as banner background.
609 (Optional. Can't be used if a valid bitmap is specified. If used, both gradient values must be set.)}
610 @row3col{gradient-end, @ref overview_xrcformat_type_colour,
611 End colour of the gradient used as banner background.
612 (Optional. Can't be used if a valid bitmap is specified. If used, both gradient values must be set.)}
616 @subsubsection xrc_wxbitmapbutton wxBitmapButton
619 @hdr3col{property, type, description}
620 @row3col{default, @ref overview_xrcformat_type_bool,
621 Should this button be the default button in dialog (default: 0)?}
622 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
623 Bitmap to show on the button (required).}
624 @row3col{selected, @ref overview_xrcformat_type_bitmap,
625 Bitmap to show when the button is selected (default: none, same as @c bitmap).}
626 @row3col{focus, @ref overview_xrcformat_type_bitmap,
627 Bitmap to show when the button has focus (default: none, same as @c bitmap).}
628 @row3col{disabled, @ref overview_xrcformat_type_bitmap,
629 Bitmap to show when the button is disabled (default: none, same as @c bitmap).}
630 @row3col{hover, @ref overview_xrcformat_type_bitmap,
631 Bitmap to show when mouse cursor hovers above the bitmap (default: none, same as @c bitmap).}
635 @subsubsection xrc_wxbitmapcombobox wxBitmapComboBox
638 @hdr3col{property, type, description}
639 @row3col{selection, integer,
640 Index of the initially selected item or -1 for no selection (default: -1).}
641 @row3col{value, @ref overview_xrcformat_type_string,
642 Initial value in the control (doesn't have to be one of @ content values;
646 If both @c value and @c selection are specified and @c selection is not -1,
647 then @c selection takes precedence.
649 A wxBitmapComboBox can have one or more child objects of the @c ownerdrawnitem
650 pseudo-class. @c ownerdrawnitem objects have the following properties:
653 @hdr3col{property, type, description}
654 @row3col{text, @ref overview_xrcformat_type_text,
655 Item's label (required).}
656 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
657 Item's bitmap (default: no bitmap).}
662 <object class="wxBitmapComboBox">
663 <selection>1</selection>
664 <object class="ownerdrawnitem">
666 <bitmap>foo.png</bitmap>
668 <object class="ownerdrawnitem">
670 <bitmap>bar.png</bitmap>
676 @subsubsection xrc_wxbitmaptogglebutton wxBitmapToggleButton
679 @hdr3col{property, type, description}
680 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
681 Label to display on the button (required).}
682 @row3col{checked, @ref overview_xrcformat_type_bool,
683 Should the button be checked/pressed initially (default: 0)?}
687 @subsubsection xrc_wxbutton wxButton
690 @hdr3col{property, type, description}
691 @row3col{label, @ref overview_xrcformat_type_text,
692 Label to display on the button (may be omitted if only the bitmap or stock ID is used).}
693 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
694 Bitmap to display in the button (optional).}
695 @row3col{bitmapposition, @c wxLEFT|wxRIGHT|wxTOP|wxBOTTOM,
696 Position of the bitmap in the button, see wxButton::SetBitmapPosition() (default: wxLEFT).}
697 @row3col{default, @ref overview_xrcformat_type_bool,
698 Should this button be the default button in dialog (default: 0)?}
702 @subsubsection xrc_wxcalendarctrl wxCalendarCtrl
704 No additional properties.
707 @subsubsection xrc_wxcheckbox wxCheckBox
710 @hdr3col{property, type, description}
711 @row3col{label, @ref overview_xrcformat_type_text,
712 Label to use for the checkbox (default: empty).}
713 @row3col{checked, @ref overview_xrcformat_type_bool,
714 Should the checkbox be checked initially (default: 0)?}
718 @subsubsection xrc_wxchecklistbox wxCheckListBox
721 @hdr3col{property, type, description}
722 @row3col{content, items,
723 Content of the control; this property has any number of @c \<item\> XML
724 elements as its children, with the items text as their text values
728 The @c \<item\> elements have listbox items' labels as their text values. They
729 can also have optional @c checked XML attribute -- if set to "1", the value is
734 <object class="wxCheckListBox">
736 <item checked="1">Download library</item>
737 <item checked="1">Compile samples</item>
738 <item checked="1">Skim docs</item>
739 <item checked="1">Finish project</item>
740 <item>Wash car</item>
746 @subsubsection xrc_wxchoice wxChoice
749 @hdr3col{property, type, description}
750 @row3col{selection, integer,
751 Index of the initially selected item or -1 for no selection (default: -1).}
752 @row3col{content, items,
753 Content of the control; this property has any number of @c \<item\> XML
754 elements as its children, with the items text as their text values
760 <object class="wxChoice" name="controls_choice">
767 <item>The Sixth Sense!</item>
773 @subsubsection xrc_wxchoicebook wxChoicebook
776 @hdr3col{property, type, description}
777 @row3col{imagelist, @ref overview_xrcformat_type_imagelist,
778 Image list to use for the images (default: none, built implicitly).}
781 Additionally, a choicebook can have one or more child objects of the @c
782 choicebookpage pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and
783 its @c notebookpage).
785 @c choicebookpage objects have the following properties:
788 @hdr3col{property, type, description}
789 @row3col{label, @ref overview_xrcformat_type_text,
790 Sheet page's title (required).}
791 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
792 Bitmap shown alongside the label (default: none, mutually exclusive with @c image).}
793 @row3col{image, integer,
794 The zero-based index of the image associated with the item
795 into the image list (default: none, mutually exclusive with @c bitmap, only if imagelist was set).}
796 @row3col{selected, @ref overview_xrcformat_type_bool,
797 Is the page selected initially (only one page can be selected; default: 0)?}
800 Each @c choicebookpage has exactly one non-toplevel window as its child.
803 @subsubsection xrc_wxcommandlinkbutton wxCommandLinkButton
805 The wxCommandLinkButton contains a main title-like @c label and an optional
806 @c note for longer description. The main @c label and the @c note can be
807 concatenated into a single string using a new line character between them
808 (notice that the @c note part can have more new lines in it).
811 @hdr3col{property, type, description}
812 @row3col{label, @ref overview_xrcformat_type_text,
813 First line of text on the button, typically the label of an action that
814 will be made when the button is pressed (required). }
815 @row3col{note, @ref overview_xrcformat_type_text,
816 Second line of text describing the action performed when the button is pressed (default: none). }
820 @subsubsection xrc_wxcollapsiblepane wxCollapsiblePane
823 @hdr3col{property, type, description}
824 @row3col{label, @ref overview_xrcformat_type_text,
825 Label to use for the collapsible section (required).}
826 @row3col{collapsed, @ref overview_xrcformat_type_bool,
827 Should the pane be collapsed initially (default: 0)?}
830 wxCollapsiblePane may contain single optional child object of the @c panewindow
831 pseudo-class type. @c panewindow itself must contain exactly one child that
832 is a @ref overview_xrcformat_sizers "sizer" or a non-toplevel window
836 @subsubsection xrc_wxcolourpickerctrl wxColourPickerCtrl
839 @hdr3col{property, type, description}
840 @row3col{value, @ref overview_xrcformat_type_colour,
841 Initial value of the control (default: wxBLACK).}
845 @subsubsection xrc_wxcombobox wxComboBox
848 @hdr3col{property, type, description}
849 @row3col{selection, integer,
850 Index of the initially selected item or -1 for no selection (default: not used).}
851 @row3col{content, items,
852 Content of the control; this property has any number of @c \<item\> XML
853 elements as its children, with the items text as their text values
855 @row3col{value, @ref overview_xrcformat_type_string,
856 Initial value in the control (doesn't have to be one of @ content values;
860 If both @c value and @c selection are specified and @c selection is not -1,
861 then @c selection takes precedence.
865 <object class="wxComboBox" name="controls_combobox">
866 <style>wxCB_DROPDOWN</style>
871 <item>notepad.exe</item>
878 @subsubsection xrc_wxcomboctrl wxComboCtrl
881 @hdr3col{property, type, description}
882 @row3col{value, @ref overview_xrcformat_type_string,
883 Initial value in the control (default: empty).}
887 @subsubsection xrc_wxdatepickerctrl wxDatePickerCtrl
889 No additional properties.
892 @subsubsection xrc_wxdialog wxDialog
895 @hdr3col{property, type, description}
896 @row3col{title, @ref overview_xrcformat_type_text,
897 Dialog's title (default: empty).}
898 @row3col{icon, @ref overview_xrcformat_type_bitmap,
899 Dialog's icon (default: not used).}
900 @row3col{centered, @ref overview_xrcformat_type_bool,
901 Whether the dialog should be centered on the screen (default: 0).}
904 wxDialog may have optional children: either exactly one
905 @ref overview_xrcformat_sizers "sizer" child or any number of non-toplevel window
906 objects. If sizer child is used, it sets
907 @ref wxSizer::SetSizeHints() "size hints" too.
910 @subsubsection xrc_wxdirpickerctrl wxDirPickerCtrl
913 @hdr3col{property, type, description}
914 @row3col{value, @ref overview_xrcformat_type_string,
915 Initial value of the control (default: empty).}
916 @row3col{message, @ref overview_xrcformat_type_text,
917 Message shown to the user in wxDirDialog shown by the control (required).}
921 @subsubsection xrc_wxeditablelistbox wxEditableListBox
924 @hdr3col{property, type, description}
925 @row3col{label, @ref overview_xrcformat_type_text,
926 Label shown above the list (default: empty).}
927 @row3col{content, items,
928 Content of the control; this property has any number of @c \<item\> XML
929 elements as its children, with the items text as their text values
935 <object class="wxEditableListBox" name="controls_listbox">
937 <label>List of things</label>
942 <item>Orange juice</item>
943 <item>Paper towels</item>
949 @subsubsection xrc_wxfilectrl wxFileCtrl
952 @hdr3col{property, type, description}
953 @row3col{defaultdirectory, @ref overview_xrcformat_type_string,
954 Sets the current directory displayed in the control. }
955 @row3col{defaultfilename, @ref overview_xrcformat_type_string,
956 Selects a certain file.}
957 @row3col{wildcard, @ref overview_xrcformat_type_string,
958 Sets the wildcard, which can contain multiple file types, for example:
959 "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
960 (default: all files).}
964 @subsubsection xrc_wxfilepickerctrl wxFilePickerCtrl
967 @hdr3col{property, type, description}
968 @row3col{value, @ref overview_xrcformat_type_string,
969 Initial value of the control (default: empty).}
970 @row3col{message, @ref overview_xrcformat_type_text,
971 Message shown to the user in wxDirDialog shown by the control (required).}
972 @row3col{wildcard, @ref overview_xrcformat_type_string,
973 Sets the wildcard, which can contain multiple file types, for example:
974 "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
975 (default: all files).}
979 @subsubsection xrc_wxfontpickerctrl wxFontPickerCtrl
982 @hdr3col{property, type, description}
983 @row3col{value, @ref overview_xrcformat_type_font,
984 Initial value of the control (default: wxNORMAL_FONT).}
987 @subsubsection xrc_wxfrane wxFrame
990 @hdr3col{property, type, description}
991 @row3col{title, @ref overview_xrcformat_type_text,
992 Frame's title (default: empty).}
993 @row3col{icon, @ref overview_xrcformat_type_bitmap,
994 Frame's icon (default: not used).}
995 @row3col{centered, @ref overview_xrcformat_type_bool,
996 Whether the frame should be centered on the screen (default: 0).}
999 wxFrame may have optional children: either exactly one
1000 @ref overview_xrcformat_sizers "sizer" child or any number of non-toplevel window
1001 objects. If sizer child is used, it sets
1002 @ref wxSizer::SetSizeHints() "size hints" too.
1005 @subsubsection xrc_wxgauge wxGauge
1008 @hdr3col{property, type, description}
1009 @row3col{range, integer,
1010 Maximum value of the gauge (default: 100).}
1011 @row3col{value, integer,
1012 Initial value of the control (default: 0).}
1013 @row3col{shadow, @ref overview_xrcformat_type_dimension,
1014 Rendered shadow size (default: none; ignored by most platforms).}
1015 @row3col{bezel, @ref overview_xrcformat_type_dimension,
1016 Rendered bezel size (default: none; ignored by most platforms).}
1019 @subsubsection xrc_wxgenericdirctrl wxGenericDirCtrl
1022 @hdr3col{property, type, description}
1023 @row3col{defaultfolder, @ref overview_xrcformat_type_string,
1024 Initial folder (default: empty).}
1025 @row3col{filter, @ref overview_xrcformat_type_text,
1026 Filter string, using the same syntax as used by wxFileDialog, e.g.
1027 "All files (*.*)|*.*|JPEG files (*.jpg)|*.jpg" (default: empty).}
1028 @row3col{defaultfilter, integer,
1029 Zero-based index of default filter (default: 0).}
1032 @subsubsection xrc_wxgrid wxGrid
1034 No additional properties.
1037 @subsubsection xrc_wxhtmlwindow wxHtmlWindow
1040 @hdr3col{property, type, description}
1041 @row3col{url, @ref overview_xrcformat_type_url,
1042 Page to display in the window (default: none).}
1043 @row3col{htmlcode, @ref overview_xrcformat_type_text,
1044 HTML markup to display in the window (default: none).}
1045 @row3col{borders, @ref overview_xrcformat_type_dimension,
1046 Border around HTML content (default: 0).}
1049 At most one of @c url and @c htmlcode properties may be specified, they are
1050 mutually exclusive. If neither is set, the window is initialized to show empty
1054 @subsubsection xrc_wxhyperlinkctrl wxHyperlinkCtrl
1057 @hdr3col{property, type, description}
1058 @row3col{label, @ref overview_xrcformat_type_text,
1059 Label to display on the control (required).}
1060 @row3col{url, @ref overview_xrcformat_type_url,
1061 URL to open when the link is clicked (required).}
1065 @subsubsection xrc_wxlistbox wxListBox
1068 @hdr3col{property, type, description}
1069 @row3col{selection, integer,
1070 Index of the initially selected item or -1 for no selection (default: -1).}
1071 @row3col{content, items,
1072 Content of the control; this property has any number of @c \<item\> XML
1073 elements as its children, with the items text as their text values
1079 <object class="wxListBox" name="controls_listbox">
1080 <size>250,160</size>
1081 <style>wxLB_SINGLE</style>
1086 <item>Orange juice</item>
1087 <item>Paper towels</item>
1093 @subsubsection xrc_wxlistbook wxListbook
1096 @hdr3col{property, type, description}
1097 @row3col{imagelist, @ref overview_xrcformat_type_imagelist,
1098 Image list to use for the images (default: none, built implicitly).}
1101 Additionally, a listbook can have one or more child objects of the @c
1102 listbookpage pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and
1103 its @c notebookpage).
1105 @c listbookpage objects have the following properties:
1108 @hdr3col{property, type, description}
1109 @row3col{label, @ref overview_xrcformat_type_text,
1110 Sheet page's title (required).}
1111 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1112 Bitmap shown alongside the label (default: none, mutually exclusive with @c image).}
1113 @row3col{image, integer,
1114 The zero-based index of the image associated with the item
1115 into the image list (default: none, mutually exclusive with @c bitmap, only if imagelist was set).}
1116 @row3col{selected, @ref overview_xrcformat_type_bool,
1117 Is the page selected initially (only one page can be selected; default: 0)?}
1120 Each @c listbookpage has exactly one non-toplevel window as its child.
1123 @subsubsection xrc_wxlistctrl wxListCtrl
1126 @hdr3col{property, type, description}
1127 @row3col{imagelist, @ref overview_xrcformat_type_imagelist,
1128 The normal (wxIMAGE_LIST_NORMAL) image list (default: none, built implicitly).}
1129 @row3col{imagelist-small, @ref overview_xrcformat_type_imagelist,
1130 The small (wxIMAGE_LIST_SMALL) image list (default: none, built implicitly).}
1133 A list control can have optional child objects of the @ref xrc_wxlistitem
1134 class. Report mode list controls (i.e. created with @c wxLC_REPORT style) can
1135 in addition have optional @ref xrc_wxlistcol child objects.
1137 @paragraph xrc_wxlistcol listcol
1139 The @c listcol class can only be used for wxListCtrl children. It can have the
1140 following properties (all of them optional):
1143 @hdr3col{property, type, description}
1144 @row3col{align, wxListColumnFormat,
1145 The alignment for the item.
1146 Can be one of @c wxLIST_FORMAT_LEFT, @c wxLIST_FORMAT_RIGHT or
1147 @c wxLIST_FORMAT_CENTRE.}
1148 @row3col{text, @ref overview_xrcformat_type_text,
1149 The title of the column. }
1150 @row3col{width, integer,
1152 @row3col{image, integer,
1153 The zero-based index of the image associated with the item in the 'small' image list. }
1156 The columns are appended to the control in order of their appearance and may be
1157 referenced by 0-based index in the @c col attributes of subsequent @c listitem
1160 @paragraph xrc_wxlistitem listitem
1162 The @c listitem is a child object for the class @ref xrc_wxlistctrl.
1163 It can have the following properties (all of them optional):
1166 @hdr3col{property, type, description}
1167 @row3col{align, wxListColumnFormat,
1168 The alignment for the item.
1169 Can be one of @c wxLIST_FORMAT_LEFT, @c wxLIST_FORMAT_RIGHT or
1170 @c wxLIST_FORMAT_CENTRE.}
1171 @row3col{bg, @ref overview_xrcformat_type_colour,
1172 The background color for the item.}
1173 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1174 Add a bitmap to the (normal) @ref overview_xrcformat_type_imagelist associated with the
1175 @ref xrc_wxlistctrl parent and associate it with this item.
1176 If the imagelist is not defined it will be created implicitly
1177 (default: none, mutually exclusive with @c image).}
1178 @row3col{bitmap-small, @ref overview_xrcformat_type_bitmap,
1179 Add a bitmap in the 'small' @ref overview_xrcformat_type_imagelist associated with the
1180 @ref xrc_wxlistctrl parent and associate it with this item.
1181 If the 'small' imagelist is not defined it will be created implicitly
1182 (default: none, mutually exclusive with @c image-small).}
1183 @row3col{col, integer,
1184 The zero-based column index.}
1185 @row3col{image, integer,
1186 The zero-based index of the image associated with the item
1187 in the (normal) image list
1188 (default: none, mutually exclusive with @c bitmap, only if imagelist was set).}
1189 @row3col{image-small, integer,
1190 The zero-based index of the image associated with the item
1191 in the 'small' image list
1192 (default: none, mutually exclusive with @c bitmap-small, only if imagelist-small was set).}
1193 @row3col{data, integer,
1194 The client data for the item.}
1195 @row3col{font, @ref overview_xrcformat_type_font,
1196 The font for the item.}
1197 @row3col{state, @ref overview_xrcformat_type_style,
1198 The item state. Can be any combination of the following values:
1199 - @c wxLIST_STATE_FOCUSED: The item has the focus.
1200 - @c wxLIST_STATE_SELECTED: The item is selected.}
1201 @row3col{text, @ref overview_xrcformat_type_text,
1202 The text label for the item. }
1203 @row3col{textcolour, @ref overview_xrcformat_type_colour,
1204 The text colour for the item. }
1207 Notice that the item position can't be specified here, the items are appended
1208 to the list control in order of their appearance.
1211 @subsubsection xrc_wxmdiparentframe wxMDIParentFrame
1213 wxMDIParentFrame supports the same properties that @ref xrc_wxfrane does.
1215 wxMDIParentFrame may have optional children. When used, the child objects
1216 must be of wxMDIChildFrame type.
1219 @subsubsection xrc_wxmdichildframe wxMDIChildFrame
1221 wxMDIChildFrame supports the same properties that @ref xrc_wxfrane and
1222 @ref xrc_wxmdiparentframe do.
1224 wxMDIChildFrame can only be used as as immediate child of @ref
1225 xrc_wxmdiparentframe.
1227 wxMDIChildFrame may have optional children: either exactly one
1228 @ref overview_xrcformat_sizers "sizer" child or any number of non-toplevel window
1229 objects. If sizer child is used, it sets
1230 @ref wxSizer::SetSizeHints() "size hints" too.
1233 @subsubsection xrc_wxmenu wxMenu
1236 @hdr3col{property, type, description}
1237 @row3col{label, @ref overview_xrcformat_type_text,
1238 Menu's label (default: empty, but required for menus other
1240 @row3col{style, @ref overview_xrcformat_type_style,
1241 Window style for the menu.}
1242 @row3col{help, @ref overview_xrcformat_type_text,
1243 Help shown in statusbar when the menu is selected (only for submenus
1244 of another wxMenu, default: none).}
1245 @row3col{enabled, @ref overview_xrcformat_type_bool,
1246 Is the submenu item enabled (only for submenus of another wxMenu,
1250 Note that unlike most controls, wxMenu does @em not have
1251 @ref overview_xrcformat_std_props, with the exception of @c style.
1253 A menu object can have one or more child objects of the wxMenuItem or wxMenu
1254 classes or @c break or @c separator pseudo-classes.
1256 The @c separator pseudo-class is used to insert separators into the menu and
1257 has neither properties nor children. Likewise, @c break inserts a break (see
1260 wxMenuItem objects support the following properties:
1263 @hdr3col{property, type, description}
1264 @row3col{label, @ref overview_xrcformat_type_text,
1265 Item's label (may be omitted if stock ID is used).}
1266 @row3col{accel, @ref overview_xrcformat_type_text_notrans,
1267 Item's accelerator (default: none).}
1268 @row3col{radio, @ref overview_xrcformat_type_bool,
1269 Item's kind is wxITEM_RADIO (default: 0)?}
1270 @row3col{checkable, @ref overview_xrcformat_type_bool,
1271 Item's kind is wxITEM_CHECK (default: 0)?}
1272 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1273 Bitmap to show with the item (default: none).}
1274 @row3col{bitmap2, @ref overview_xrcformat_type_bitmap,
1275 Bitmap for the checked state (wxMSW, if checkable; default: none).}
1276 @row3col{help, @ref overview_xrcformat_type_text,
1277 Help shown in statusbar when the item is selected (default: none).}
1278 @row3col{enabled, @ref overview_xrcformat_type_bool,
1279 Is the item enabled (default: 1)?}
1280 @row3col{checked, @ref overview_xrcformat_type_bool,
1281 Is the item checked initially (default: 0)?}
1286 <object class="wxMenu" name="menu_edit">
1287 <style>wxMENU_TEAROFF</style>
1288 <label>_Edit</label>
1289 <object class="wxMenuItem" name="wxID_FIND">
1290 <label>_Find...</label>
1291 <accel>Ctrl-F</accel>
1293 <object class="separator"/>
1294 <object class="wxMenuItem" name="menu_fuzzy">
1295 <label>Translation is _fuzzy</label>
1296 <checkable>1</checkable>
1298 <object class="wxMenu" name="submenu">
1299 <label>A submenu</label>
1300 <object class="wxMenuItem" name="foo">...</object>
1303 <object class="separator" platform="unix"/>
1304 <object class="wxMenuItem" name="wxID_PREFERENCES" platform="unix">
1305 <label>_Preferences</label>
1310 @subsubsection xrc_wxmenubar wxMenuBar
1313 @hdr3col{property, type, description}
1314 @row3col{style, @ref overview_xrcformat_type_style,
1315 Window style for the menu bar.}
1318 Note that unlike most controls, wxMenuBar does @em not have
1319 @ref overview_xrcformat_std_props, with the exception of @c style.
1321 A menubar can have one or more child objects of the @ref xrc_wxmenu "wxMenu"
1325 @subsubsection xrc_wxnotebook wxNotebook
1328 @hdr3col{property, type, description}
1329 @row3col{imagelist, @ref overview_xrcformat_type_imagelist,
1330 Image list to use for the images (default: none, built implicitly).}
1333 A notebook can have one or more child objects of the @c notebookpage
1336 @c notebookpage objects have the following properties:
1339 @hdr3col{property, type, description}
1340 @row3col{label, @ref overview_xrcformat_type_text,
1341 Page's title (required).}
1342 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1343 Bitmap shown alongside the label
1344 (default: none, mutually exclusive with @c image).}
1345 @row3col{image, integer,
1346 The zero-based index of the image associated with the item
1348 (default: none, mutually exclusive with @c bitmap, only if imagelist was set).}
1349 @row3col{selected, @ref overview_xrcformat_type_bool,
1350 Is the page selected initially (only one page can be selected; default: 0)?}
1353 Each @c notebookpage has exactly one non-toplevel window as its child.
1357 <object class="wxNotebook">
1358 <style>wxBK_BOTTOM</style>
1359 <object class="notebookpage">
1360 <label>Page 1</label>
1361 <object class="wxPanel" name="page_1">
1365 <object class="notebookpage">
1366 <label>Page 2</label>
1367 <object class="wxPanel" name="page_2">
1375 @subsubsection xrc_wxownerdrawncombobox wxOwnerDrawnComboBox
1377 wxOwnerDrawnComboBox has the same properties as
1378 @ref xrc_wxcombobox "wxComboBox", plus the following additional properties:
1381 @hdr3col{property, type, description}
1382 @row3col{buttonsize, @ref overview_xrcformat_type_size,
1383 Size of the dropdown button (default: default).}
1387 @subsubsection xrc_wxpanel wxPanel
1389 No additional properties.
1391 wxPanel may have optional children: either exactly one
1392 @ref overview_xrcformat_sizers "sizer" child or any number of non-toplevel window
1396 @subsubsection xrc_wxpropertysheetdialog wxPropertySheetDialog
1399 @hdr3col{property, type, description}
1400 @row3col{title, @ref overview_xrcformat_type_text,
1401 Dialog's title (default: empty).}
1402 @row3col{icon, @ref overview_xrcformat_type_bitmap,
1403 Dialog's icon (default: not used).}
1404 @row3col{centered, @ref overview_xrcformat_type_bool,
1405 Whether the dialog should be centered on the screen (default: 0).}
1406 @row3col{buttons, @ref overview_xrcformat_type_style,
1407 Buttons to show, combination of flags accepted by
1408 wxPropertySheetDialog::CreateButtons() (default: 0).}
1411 A sheet dialog can have one or more child objects of the @c propertysheetpage
1412 pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its
1413 @c notebookpage). @c propertysheetpage objects have the following properties:
1416 @hdr3col{property, type, description}
1417 @row3col{label, @ref overview_xrcformat_type_text,
1418 Sheet page's title (required).}
1419 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1420 Bitmap shown alongside the label (default: none).}
1421 @row3col{selected, @ref overview_xrcformat_type_bool,
1422 Is the page selected initially (only one page can be selected; default: 0)?}
1425 Each @c propertysheetpage has exactly one non-toplevel window as its child.
1428 @subsubsection xrc_wxradiobutton wxRadioButton
1431 @hdr3col{property, type, description}
1432 @row3col{label, @ref overview_xrcformat_type_text,
1433 Label shown on the radio button (required).}
1434 @row3col{value, @ref overview_xrcformat_type_bool,
1435 Initial value of the control (default: 0).}
1439 @subsubsection xrc_wxradiobox wxRadioBox
1442 @hdr3col{property, type, description}
1443 @row3col{label, @ref overview_xrcformat_type_text,
1444 Label for the whole box (default: empty).}
1445 @row3col{dimension, integer,
1446 Specifies the maximum number of rows (if style contains
1447 @c wxRA_SPECIFY_ROWS) or columns (if style contains @c wxRA_SPECIFY_COLS)
1448 for a two-dimensional radiobox (default: 1).}
1449 @row3col{selection, integer,
1450 Index of the initially selected item or -1 for no selection (default: -1).}
1451 @row3col{content, items,
1452 Content of the control; this property has any number of @c \<item\> XML
1453 elements as its children, with the items text as their text values
1454 (see below; default: empty).}
1457 The @c \<item\> elements have radio buttons' labels as their text values. They
1458 can also have some optional XML @em attributes (not properties!):
1461 @hdr3col{attribute, type, description}
1462 @row3col{tooltip, @ref overview_xrcformat_type_string,
1463 Tooltip to show over this ratio button (default: none).}
1464 @row3col{helptext, @ref overview_xrcformat_type_string,
1465 Contextual help for this radio button (default: none).}
1466 @row3col{enabled, @ref overview_xrcformat_type_bool,
1467 Is the button enabled (default: 1)?}
1468 @row3col{hidden, @ref overview_xrcformat_type_bool,
1469 Is the button hidden initially (default: 0)?}
1474 <object class="wxRadioBox" name="controls_radiobox">
1475 <style>wxRA_SPECIFY_COLS</style>
1476 <label>Radio stations</label>
1477 <dimension>1</dimension>
1478 <selection>0</selection>
1480 <item tooltip="Powerful radio station" helptext="This station is for amateurs of hard rock and heavy metal">Power 108</item>
1481 <item tooltip="Disabled radio station" enabled="0">Power 0</item>
1482 <item tooltip="">WMMS 100.7</item>
1483 <item tooltip="E=mc^2">Energy 98.3</item>
1484 <item helptext="Favourite chukcha's radio">CHUM FM</item>
1486 <item hidden="1">Very quit station</item>
1492 @subsubsection xrc_wxribbonbar wxRibbonBar
1495 @hdr3col{property, type, description}
1496 @row3col{art-provider, @ref overview_xrcformat_type_string,
1497 One of @c default, @c aui or @c msw (default: @c default).}
1500 A wxRibbonBar may have @ref xrc_wxribbonpage child objects. The @c page
1501 pseudo-class may be used instead of @c wxRibbonPage when used as wxRibbonBar
1506 <object class="wxRibbonBar" name="ribbonbar">
1507 <object class="page" name="FilePage">
1508 <label>First</label>
1509 <object class="panel">
1511 <object class="wxRibbonButtonBar">
1512 <object class="button" name="Open">
1513 <bitmap>open.xpm</bitmap>
1519 <object class="page" name="ViewPage">
1521 <object class="panel">
1523 <object class="wxRibbonGallery">
1524 <object class="item">
1525 <bitmap>zoomin.xpm</bitmap>
1527 <object class="item">
1528 <bitmap>zoomout.xpm</bitmap>
1536 Notice that wxRibbonBar support in XRC is available in wxWidgets 2.9.5 and
1537 later only and you need to explicitly register its handler using
1539 #include <wx/xrc/xh_ribbon.h>
1541 AddHandler(new wxRibbonXmlHandler);
1546 @subsubsection xrc_wxribbonbuttonbar wxRibbonButtonBar
1548 No additional properties.
1550 wxRibbonButtonBar can have child objects of the @c button pseudo-class. @c button
1551 objects have the following properties:
1554 @hdr3col{property, type, description}
1555 @row3col{hybrid, @ref overview_xrcformat_type_bool,
1556 If true, the @c wxRIBBON_BUTTON_HYBRID kind is used (default: false).}
1557 @row3col{disabled, @ref overview_xrcformat_type_bool,
1558 Whether the button should be disabled (default: false).}
1559 @row3col{label, @ref overview_xrcformat_type_text,
1560 Item's label (required).}
1561 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1562 Item's bitmap (required).}
1563 @row3col{small-bitmap, @ref overview_xrcformat_type_bitmap,
1564 Small bitmap (default: none).}
1565 @row3col{disabled-bitmap, @ref overview_xrcformat_type_bitmap,
1566 Disabled bitmap (default: none).}
1567 @row3col{small-disabled-bitmap, @ref overview_xrcformat_type_bitmap,
1568 Small disabled bitmap (default: none).}
1569 @row3col{help, @ref overview_xrcformat_type_text,
1570 Item's help text (default: none).}
1574 @subsubsection xrc_wxribboncontrol wxRibbonControl
1576 No additional properties.
1578 Objects of this type *must* be subclassed with the @c subclass attribute.
1581 @subsubsection xrc_wxribbongallery wxRibbonGallery
1583 No additional properties.
1585 wxRibbonGallery can have child objects of the @c item pseudo-class. @c item
1586 objects have the following properties:
1589 @hdr3col{property, type, description}
1590 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1591 Item's bitmap (default: none).}
1595 @subsubsection xrc_wxribbonpage wxRibbonPage
1598 @hdr3col{property, type, description}
1599 @row3col{label, @ref overview_xrcformat_type_text,
1600 Label (default: none).}
1601 @row3col{icon, @ref overview_xrcformat_type_bitmap,
1602 Icon (default: none).}
1605 A wxRibbonPage may have children of any type derived from wxRibbonControl.
1606 Most commontly, wxRibbonPanel is used. As a special case, the @c panel
1607 pseudo-class may be used instead of @c wxRibbonPanel when used as wxRibbonPage
1611 @subsubsection xrc_wxribbonpanel wxRibbonPanel
1614 @hdr3col{property, type, description}
1615 @row3col{label, @ref overview_xrcformat_type_text,
1616 Label (default: none).}
1617 @row3col{icon, @ref overview_xrcformat_type_bitmap,
1618 Icon (default: none).}
1621 A wxRibbonPanel may have children of any type derived from wxRibbonControl or
1622 a single wxSizer child with non-ribbon windows in it.
1625 @subsubsection xrc_wxrichtextctrl wxRichTextCtrl
1628 @hdr3col{property, type, description}
1629 @row3col{value, @ref overview_xrcformat_type_text,
1630 Initial value of the control (default: empty).}
1631 @row3col{maxlength, integer,
1632 Maximum length of the text entered (default: unlimited).}
1635 Notice that wxRichTextCtrl support in XRC is available in wxWidgets 2.9.5 and
1636 later only and you need to explicitly register its handler using
1638 #include <wx/xrc/xh_richtext.h>
1640 AddHandler(new wxRichTextCtrl);
1645 @subsubsection xrc_wxscrollbar wxScrollBar
1648 @hdr3col{property, type, description}
1649 @row3col{value, integer,
1650 Initial position of the scrollbar (default: 0).}
1651 @row3col{range, integer,
1652 Maximum value of the gauge (default: 10).}
1653 @row3col{thumbsize, integer,
1654 Size of the thumb (default: 1).}
1655 @row3col{pagesize, integer,
1656 Page size (default: 1).}
1659 @subsubsection xrc_wxscrolledwindow wxScrolledWindow
1662 @hdr3col{property, type, description}
1663 @row3col{scrollrate, @ref overview_xrcformat_type_size,
1664 Scroll rate in @em x and @em y directions (default: not set;
1665 required if the window has a sizer child).}
1668 wxScrolledWindow may have optional children: either exactly one
1669 @ref overview_xrcformat_sizers "sizer" child or any number of non-toplevel window
1670 objects. If sizer child is used, wxSizer::FitInside() is used (instead of
1671 wxSizer::Fit() as usual) and so the children don't determine scrolled window's
1672 minimal size, they only affect @em virtual size. Usually, both @c scrollrate
1673 and either @c size or @c minsize on containing sizer item should be used
1677 @subsubsection xrc_wxsimplehtmllistbox wxSimpleHtmlListBox
1679 wxSimpleHtmlListBox has same properties as @ref xrc_wxlistbox "wxListBox".
1680 The only difference is that the text contained in @c \<item\> elements is
1681 HTML markup. Note that the markup has to be escaped:
1684 <object class="wxSimpleHtmlListBox">
1686 <item><b>Bold</b> Milk</item>
1691 (X)HTML markup elements cannot be included directly:
1694 <object class="wxSimpleHtmlListBox">
1696 <!-- This is incorrect, doesn't work! -->
1697 <item><b>Bold</b> Milk</item>
1703 @subsubsection xrc_wxslider wxSlider
1706 @hdr3col{property, type, description}
1707 @row3col{value, integer,
1708 Initial value of the control (default: 0).}
1709 @row3col{min, integer,
1710 Minimum allowed value (default: 0).}
1711 @row3col{max, integer,
1712 Maximum allowed value (default: 100).}
1713 @row3col{pagesize, integer,
1714 Page size; number of steps the slider moves when the user moves
1715 pages up or down (default: unset).}
1716 @row3col{linesize, integer,
1717 Line size; number of steps the slider moves when the user moves it
1718 up or down a line (default: unset).}
1719 @row3col{tickfreq, integer,
1720 Tick marks frequency (Windows only; default: unset).}
1721 @row3col{tick, integer,
1722 Tick position (Windows only; default: unset).}
1723 @row3col{thumb, integer,
1724 Thumb length (Windows only; default: unset).}
1725 @row3col{selmin, integer,
1726 Selection start position (Windows only; default: unset).}
1727 @row3col{selmax, integer,
1728 Selection end position (Windows only; default: unset).}
1732 @subsubsection xrc_wxspinbutton wxSpinButton
1735 @hdr3col{property, type, description}
1736 @row3col{value, integer,
1737 Initial value of the control (default: 0).}
1738 @row3col{min, integer,
1739 Minimum allowed value (default: 0).}
1740 @row3col{max, integer,
1741 Maximum allowed value (default: 100).}
1745 @subsubsection xrc_wxspinctrl wxSpinCtrl
1747 wxSpinCtrl supports the same properties as @ref xrc_wxspinbutton and, since
1748 wxWidgets 2.9.5, another one:
1750 @row3col{base, integer,
1751 Numeric base, currently can be only 10 or 16 (default: 10).}
1755 @subsubsection xrc_wxsplitterwindow wxSplitterWindow
1758 @hdr3col{property, type, description}
1759 @row3col{orientation, @ref overview_xrcformat_type_string,
1760 Orientation of the splitter, either "vertical" or "horizontal" (default: horizontal).}
1761 @row3col{sashpos, @ref overview_xrcformat_type_dimension,
1762 Initial position of the sash (default: 0).}
1763 @row3col{minsize, @ref overview_xrcformat_type_dimension,
1764 Minimum child size (default: not set).}
1765 @row3col{gravity, @ref overview_xrcformat_type_float,
1766 Sash gravity, see wxSplitterWindow::SetSashGravity() (default: not set).}
1769 wxSplitterWindow must have one or two children that are non-toplevel window
1770 objects. If there's only one child, it is used as wxSplitterWindow's only
1771 visible child. If there are two children, the first one is used for left/top
1772 child and the second one for right/bottom child window.
1775 @subsubsection xrc_wxsearchctrl wxSearchCtrl
1778 @hdr3col{property, type, description}
1779 @row3col{value, @ref overview_xrcformat_type_text,
1780 Initial value of the control (default: empty).}
1784 @subsubsection xrc_wxstatusbar wxStatusBar
1787 @hdr3col{property, type, description}
1788 @row3col{fields, integer,
1789 Number of status bar fields (default: 1).}
1790 @row3col{widths, @ref overview_xrcformat_type_string,
1791 Comma-separated list of @em fields integers. Each value specifies width
1792 of one field; the values are interpreted using the same convention used
1793 by wxStatusBar::SetStatusWidths() (default: not set).}
1794 @row3col{styles, @ref overview_xrcformat_type_string,
1795 Comma-separated list of @em fields style values. Each value specifies style
1796 of one field and can be one of @c wxSB_NORMAL, @c wxSB_FLAT, @c wxSB_RAISED or
1797 @c wxSB_SUNKEN (default: not set).}
1802 @subsubsection xrc_wxstaticbitmap wxStaticBitmap
1805 @hdr3col{property, type, description}
1806 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1807 Bitmap to display (required).}
1810 @subsubsection xrc_wxstaticbox wxStaticBox
1813 @hdr3col{property, type, description}
1814 @row3col{label, @ref overview_xrcformat_type_text,
1815 Static box's label (default: empty).}
1819 @subsubsection xrc_wxstaticline wxStaticLine
1821 No additional properties.
1824 @subsubsection xrc_wxstatictext wxStaticText
1827 @hdr3col{property, type, description}
1828 @row3col{label, @ref overview_xrcformat_type_text,
1829 Label to display (default: empty).}
1830 @row3col{wrap, @ref overview_xrcformat_type_dimension,
1831 Wrap the text so that each line is at most the given number of pixels, see
1832 wxStaticText::Wrap() (default: no wrap).}
1835 @subsubsection xrc_wxtextctrl wxTextCtrl
1838 @hdr3col{property, type, description}
1839 @row3col{value, @ref overview_xrcformat_type_text,
1840 Initial value of the control (default: empty).}
1841 @row3col{maxlength, integer,
1842 Maximum length of the text which can be entered by user (default: unlimited).}
1846 @subsubsection xrc_wxtimepickerctrl wxTimePickerCtrl
1848 No additional properties.
1851 @subsubsection xrc_wxtogglebutton wxToggleButton
1854 @hdr3col{property, type, description}
1855 @row3col{label, @ref overview_xrcformat_type_text,
1856 Label to display on the button (required).}
1857 @row3col{checked, @ref overview_xrcformat_type_bool,
1858 Should the button be checked/pressed initially (default: 0)?}
1861 @subsubsection xrc_wxtoolbar wxToolBar
1864 @hdr3col{property, type, description}
1865 @row3col{bitmapsize, @ref overview_xrcformat_type_size,
1866 Size of toolbar bitmaps (default: not set).}
1867 @row3col{margins, @ref overview_xrcformat_type_size,
1868 Margins (default: platform default).}
1869 @row3col{packing, integer,
1870 Packing, see wxToolBar::SetToolPacking() (default: not set).}
1871 @row3col{separation, integer,
1872 Default separator size, see wxToolBar::SetToolSeparation() (default: not set).}
1873 @row3col{dontattachtoframe, @ref overview_xrcformat_type_bool,
1874 If set to 0 and the toolbar object is child of a wxFrame,
1875 wxFrame::SetToolBar() is called; otherwise, you have to add it to a frame
1876 manually. The toolbar is attached by default, you have to set this property
1877 to 1 to disable this behaviour (default: 0).}
1880 A toolbar can have one or more child objects of any wxControl-derived class or
1881 one of three pseudo-classes: @c separator, @c space or @c tool.
1883 The @c separator pseudo-class is used to insert separators into the toolbar and
1884 has neither properties nor children. Similarly, the @c space pseudo-class is
1885 used for stretchable spaces (see wxToolBar::AddStretchableSpace(), new since
1888 The @c tool pseudo-class objects specify toolbar buttons and have the following
1892 @hdr3col{property, type, description}
1893 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1894 Tool's bitmap (required).}
1895 @row3col{bitmap2, @ref overview_xrcformat_type_bitmap,
1896 Bitmap for disabled tool (default: derived from @c bitmap).}
1897 @row3col{label, @ref overview_xrcformat_type_text,
1898 Label to display on the tool (default: no label).}
1899 @row3col{radio, @ref overview_xrcformat_type_bool,
1900 Item's kind is wxITEM_RADIO (default: 0)?}
1901 @row3col{toggle, @ref overview_xrcformat_type_bool,
1902 Item's kind is wxITEM_CHECK (default: 0)?}
1903 @row3col{dropdown, see below,
1904 Item's kind is wxITEM_DROPDOWN (default: 0)? (only available since wxWidgets 2.9.0)}
1905 @row3col{tooltip, @ref overview_xrcformat_type_text,
1906 Tooltip to use for the tool (default: none).}
1907 @row3col{longhelp, @ref overview_xrcformat_type_text,
1908 Help text shown in statusbar when the mouse is on the tool (default: none).}
1909 @row3col{disabled, @ref overview_xrcformat_type_bool,
1910 Is the tool initially disabled (default: 0)?}
1911 @row3col{checked, @ref overview_xrcformat_type_bool,
1912 Is the tool initially checked (default: 0)? (only available since wxWidgets 2.9.3)}
1915 The presence of a @c dropdown property indicates that the tool is of type
1916 wxITEM_DROPDOWN. It must be either empty or contain exactly one @ref
1917 xrc_wxmenu child object defining the drop-down button associated menu.
1919 Notice that @c radio, @c toggle and @c dropdown are mutually exclusive.
1921 Children that are not @c tool, @c space or @c separator must be instances of classes
1922 derived from wxControl and are added to the toolbar using
1923 wxToolBar::AddControl().
1927 <object class="wxToolBar">
1928 <style>wxTB_FLAT|wxTB_NODIVIDER</style>
1929 <object class="tool" name="foo">
1930 <bitmap>foo.png</bitmap>
1933 <object class="tool" name="bar">
1934 <bitmap>bar.png</bitmap>
1937 <object class="separator"/>
1938 <object class="tool" name="view_auto">
1939 <bitmap>view.png</bitmap>
1942 <object class="wxMenu">
1943 <object class="wxMenuItem" name="view_as_text">
1944 <label>View as text</label>
1946 <object class="wxMenuItem" name="view_as_hex">
1947 <label>View as binary</label>
1952 <object class="space"/>
1953 <object class="wxComboBox">
1956 <item>a combobox</item>
1957 <item>in the toolbar</item>
1965 @subsubsection xrc_wxtoolbook wxToolbook
1968 @hdr3col{property, type, description}
1969 @row3col{imagelist, @ref overview_xrcformat_type_imagelist,
1970 Image list to use for the images (default: none, built implicitly).}
1973 A toolbook can have one or more child objects of the @c toolbookpage
1974 pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its
1977 @c toolbookpage objects have the following properties:
1980 @hdr3col{property, type, description}
1981 @row3col{label, @ref overview_xrcformat_type_text,
1982 Sheet page's title (required).}
1983 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1984 Bitmap shown alongside the label
1985 (default: none, mutually exclusive with @c image).}
1986 @row3col{image, integer,
1987 The zero-based index of the image associated with the item
1989 (default: none, mutually exclusive with @c bitmap, only if imagelist was set).}
1990 @row3col{selected, @ref overview_xrcformat_type_bool,
1991 Is the page selected initially (only one page can be selected; default: 0)?}
1994 Each @c toolbookpage has exactly one non-toplevel window as its child.
1997 @subsubsection xrc_wxtreectrl wxTreeCtrl
2000 @hdr3col{property, type, description}
2001 @row3col{imagelist, @ref overview_xrcformat_type_imagelist,
2002 Image list to use for the images (default: none).}
2006 @subsubsection xrc_wxtreebook wxTreebook
2009 @hdr3col{property, type, description}
2010 @row3col{imagelist, @ref overview_xrcformat_type_imagelist,
2011 Image list to use for the images (default: none, built implicitly).}
2014 A treebook can have one or more child objects of the @c treebookpage
2015 pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its
2018 @c treebookpage objects have the following properties:
2021 @hdr3col{property, type, description}
2022 @row3col{depth, integer,
2023 Page's depth in the labels tree (required; see below).}
2024 @row3col{label, @ref overview_xrcformat_type_text,
2025 Sheet page's title (required).}
2026 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
2027 Bitmap shown alongside the label (default: none, mutually exclusive with @c image).}
2028 @row3col{image, integer,
2029 The zero-based index of the image associated with the item
2031 (default: none, mutually exclusive with @c bitmap, only if imagelist was set).}
2032 @row3col{selected, @ref overview_xrcformat_type_bool,
2033 Is the page selected initially (only one page can be selected; default: 0)?}
2034 @row3col{expanded, @ref overview_xrcformat_type_bool,
2035 If set to 1, the page is initially expanded. By default all pages are
2036 initially collapsed.}
2039 Each @c treebookpage has exactly one non-toplevel window as its child.
2041 The tree of labels is not described using nested @c treebookpage objects, but
2042 using the @em depth property. Toplevel pages have depth 0, their child pages
2043 have depth 1 and so on. A @c treebookpage's label is inserted as child of
2044 the latest preceding page with depth equal to @em depth-1. For example, this
2048 <object class="wxTreebook">
2050 <object class="treebookpage">
2052 <label>Page 1</label>
2053 <object class="wxPanel">...</object>
2055 <object class="treebookpage">
2057 <label>Subpage 1A</label>
2058 <object class="wxPanel">...</object>
2060 <object class="treebookpage">
2062 <label>Subsubpage 1</label>
2063 <object class="wxPanel">...</object>
2065 <object class="treebookpage">
2067 <label>Subpage 1B</label>
2068 <object class="wxPanel">...</object>
2070 <object class="treebookpage">
2072 <label>Subsubpage 2</label>
2073 <object class="wxPanel">...</object>
2075 <object class="treebookpage">
2077 <label>Page 2</label>
2078 <object class="wxPanel">...</object>
2083 corresponds to the following tree of labels:
2093 @subsubsection xrc_wxwizard wxWizard
2096 @hdr3col{property, type, description}
2097 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
2098 Bitmap to display on the left side of the wizard (default: none).}
2101 A wizard object can have one or more child objects of the wxWizardPage or
2102 wxWizardPageSimple classes. They both support the following properties
2103 (in addition to @ref overview_xrcformat_std_props):
2106 @hdr3col{property, type, description}
2107 @row3col{title, @ref overview_xrcformat_type_text,
2108 Wizard window's title (default: none).}
2109 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
2110 Page-specific bitmap (default: none).}
2113 wxWizardPage and wxWizardPageSimple nodes may have optional children: either
2114 exactly one @ref overview_xrcformat_sizers "sizer" child or any number of
2115 non-toplevel window objects.
2117 wxWizardPageSimple pages are automatically chained together; wxWizardPage pages
2118 transitions must be handled programmatically.
2121 @section overview_xrcformat_sizers Sizers
2123 Sizers are handled slightly differently in XRC resources than they are in
2124 wxWindow hierarchy. wxWindow's sizers hierarchy is parallel to the wxWindow
2125 children hierarchy: child windows are children of their parent window and
2126 the sizer (or sizers) form separate hierarchy attached to the window with
2127 wxWindow::SetSizer().
2129 In XRC, the two hierarchies are merged together: sizers are children of other
2130 sizers or windows and they can contain child window objects.
2132 If a sizer is child of a window object in the resource, it must be the only
2133 child and it will be attached to the parent with wxWindow::SetSizer().
2134 Additionally, if the window doesn't have its size explicitly set,
2135 wxSizer::Fit() is used to resize the window. If the parent window is
2136 toplevel window, wxSizer::SetSizeHints() is called to set its hints.
2138 A sizer object can have one or more child objects of one of two pseudo-classes:
2139 @c sizeritem or @c spacer (see @ref overview_xrcformat_wxstddialogbuttonsizer for
2140 an exception). The former specifies an element (another sizer or a window)
2141 to include in the sizer, the latter adds empty space to the sizer.
2143 @c sizeritem objects have exactly one child object: either another sizer
2144 object, or a window object. @c spacer objects don't have any children, but
2145 they have one property:
2148 @hdr3col{property, type, description}
2149 @row3col{size, @ref overview_xrcformat_type_size, Size of the empty space (default: @c wxDefaultSize).}
2152 Both @c sizeritem and @c spacer objects can have any of the following
2156 @hdr3col{property, type, description}
2157 @row3col{option, integer,
2158 The "option" value for sizers. Used by wxBoxSizer to set proportion of
2159 the item in the growable direction (default: 0).}
2160 @row3col{flag, @ref overview_xrcformat_type_style,
2161 wxSizerItem flags (default: 0).}
2162 @row3col{border, @ref overview_xrcformat_type_dimension,
2163 Size of the border around the item (directions are specified in flags)
2165 @row3col{minsize, @ref overview_xrcformat_type_size,
2166 Minimal size of this item (default: no min size).}
2167 @row3col{ratio, @ref overview_xrcformat_type_size,
2168 Item ratio, see wxSizer::SetRatio() (default: no ratio).}
2169 @row3col{cellpos, @ref overview_xrcformat_type_pos,
2170 (wxGridBagSizer only) Position, see wxGBSizerItem::SetPos() (required). }
2171 @row3col{cellspan, @ref overview_xrcformat_type_size,
2172 (wxGridBagSizer only) Span, see wxGBSizerItem::SetSpan() (required). }
2175 Example of sizers XRC code:
2177 <object class="wxDialog" name="derived_dialog">
2178 <title>Derived Dialog Example</title>
2179 <centered>1</centered>
2180 <!-- this sizer is set to be this dialog's sizer: -->
2181 <object class="wxFlexGridSizer">
2186 <growablecols>0:1</growablecols>
2187 <growablerows>0:1</growablerows>
2188 <object class="sizeritem">
2189 <flag>wxALIGN_CENTRE|wxALL</flag>
2191 <object class="wxButton" name="my_button">
2192 <label>My Button</label>
2195 <object class="sizeritem">
2196 <flag>wxALIGN_CENTRE|wxALL</flag>
2198 <object class="wxBoxSizer">
2199 <orient>wxHORIZONTAL</orient>
2200 <object class="sizeritem">
2201 <flag>wxALIGN_CENTRE|wxALL</flag>
2203 <object class="wxCheckBox" name="my_checkbox">
2204 <label>Enable this text control:</label>
2207 <object class="sizeritem">
2208 <flag>wxALIGN_CENTRE|wxALL</flag>
2210 <object class="wxTextCtrl" name="my_textctrl">
2222 The sizer classes that can be used are listed below, together with their
2223 class-specific properties. All classes support the following properties:
2226 @hdr3col{property, type, description}
2227 @row3col{minsize, @ref overview_xrcformat_type_size,
2228 Minimal size that this sizer will have, see wxSizer::SetMinSize()
2229 (default: no min size).}
2232 @subsection overview_xrcformat_wxboxsizer wxBoxSizer
2235 @hdr3col{property, type, description}
2236 @row3col{orient, @ref overview_xrcformat_type_style,
2237 Sizer orientation, "wxHORIZONTAL" or "wxVERTICAL" (default: wxHORIZONTAL).}
2240 @subsection overview_xrcformat_wxstaticsboxizer wxStaticBoxSizer
2243 @hdr3col{property, type, description}
2244 @row3col{orient, @ref overview_xrcformat_type_style,
2245 Sizer orientation, "wxHORIZONTAL" or "wxVERTICAL" (default: wxHORIZONTAL).}
2246 @row3col{label, @ref overview_xrcformat_type_text,
2247 Label to be used for the static box around the sizer (default: empty).}
2250 @subsection overview_xrcformat_wxgridsizer wxGridSizer
2253 @hdr3col{property, type, description}
2254 @row3col{rows, integer, Number of rows in the grid (default: 0 - determine automatically).}
2255 @row3col{cols, integer, Number of columns in the grid (default: 0 - determine automatically).}
2256 @row3col{vgap, @ref overview_xrcformat_type_dimension, Vertical gap between children (default: 0).}
2257 @row3col{hgap, @ref overview_xrcformat_type_dimension, Horizontal gap between children (default: 0).}
2260 @subsection overview_xrcformat_wxflexgridsizer wxFlexGridSizer
2263 @hdr3col{property, type, description}
2264 @row3col{rows, integer, Number of rows in the grid (default: 0 - determine automatically).}
2265 @row3col{cols, integer, Number of columns in the grid (default: 0 - determine automatically).}
2266 @row3col{vgap, @ref overview_xrcformat_type_dimension, Vertical gap between children (default: 0).}
2267 @row3col{hgap, @ref overview_xrcformat_type_dimension, Horizontal gap between children (default: 0).}
2268 @row3col{flexibledirection, @ref overview_xrcformat_type_style,
2269 Flexible direction, @c wxVERTICAL, @c wxHORIZONTAL or @c wxBOTH (default).
2270 This property is only available since wxWidgets 2.9.5.}
2271 @row3col{nonflexiblegrowmode, @ref overview_xrcformat_type_style,
2272 Grow mode in the non-flexible direction,
2273 @c wxFLEX_GROWMODE_NONE, @c wxFLEX_GROWMODE_SPECIFIED (default) or
2274 @c wxFLEX_GROWMODE_ALL.
2275 This property is only available since wxWidgets 2.9.5.}
2276 @row3col{growablerows, comma-separated integers list,
2277 Comma-separated list of indexes of rows that are growable (none by default).
2278 Since wxWidgets 2.9.5 optional proportion can be appended to each number
2279 after a colon (@c :).}
2280 @row3col{growablecols, comma-separated integers list,
2281 Comma-separated list of indexes of columns that are growable (none by default).
2282 Since wxWidgets 2.9.5 optional proportion can be appended to each number
2283 after a colon (@c :).}
2286 @subsection overview_xrcformat_wxgridbagsizer wxGridBagSizer
2289 @hdr3col{property, type, description}
2290 @row3col{vgap, @ref overview_xrcformat_type_dimension, Vertical gap between children (default: 0).}
2291 @row3col{hgap, @ref overview_xrcformat_type_dimension, Horizontal gap between children (default: 0).}
2292 @row3col{flexibledirection, @ref overview_xrcformat_type_style,
2293 Flexible direction, @c wxVERTICAL, @c wxHORIZONTAL, @c wxBOTH (default: @c wxBOTH).}
2294 @row3col{nonflexiblegrowmode, @ref overview_xrcformat_type_style,
2295 Grow mode in the non-flexible direction,
2296 @c wxFLEX_GROWMODE_NONE, @c wxFLEX_GROWMODE_SPECIFIED, @c wxFLEX_GROWMODE_ALL
2297 (default: @c wxFLEX_GROWMODE_SPECIFIED).}
2298 @row3col{growablerows, comma-separated integers list,
2299 Comma-separated list of indexes of rows that are growable,
2300 optionally the proportion can be appended after each number
2303 @row3col{growablecols, comma-separated integers list,
2304 Comma-separated list of indexes of columns that are growable,
2305 optionally the proportion can be appended after each number
2310 @subsection overview_xrcformat_wxwrapsizer wxWrapSizer
2313 @hdr3col{property, type, description}
2314 @row3col{orient, @ref overview_xrcformat_type_style,
2315 Sizer orientation, "wxHORIZONTAL" or "wxVERTICAL" (required).}
2316 @row3col{flag, @ref overview_xrcformat_type_style, wxWrapSizer flags (default: 0).}
2319 @subsection overview_xrcformat_wxstddialogbuttonsizer wxStdDialogButtonSizer
2321 Unlike other sizers, wxStdDialogButtonSizer has neither @c sizeritem
2322 nor @c spacer children. Instead, it has one or more children of the
2323 @c button pseudo-class. @c button objects have no properties and they must
2324 always have exactly one child of the @c wxButton class or a class derived from
2329 <object class="wxStdDialogButtonSizer">
2330 <object class="button">
2331 <object class="wxButton" name="wxID_OK">
2335 <object class="button">
2336 <object class="wxButton" name="wxID_CANCEL">
2337 <label>Cancel</label>
2345 @section overview_xrcformat_other_objects Other Objects
2347 In addition to describing UI elements, XRC files can contain non-windows
2348 objects such as bitmaps or icons. This is a concession to Windows developers
2349 used to storing them in Win32 resources.
2351 Note that unlike Win32 resources, bitmaps included in XRC files are @em not
2352 embedded in the XRC file itself. XRC file only contains a reference to another
2353 file with bitmap data.
2355 @subsection overview_xrcformat_bitmap wxBitmap
2357 Bitmaps are stored in @c \<object\> element with class set to @c wxBitmap. Such
2358 bitmaps can then be loaded using wxXmlResource::LoadBitmap(). The content of
2359 the element is exactly same as in the case of
2360 @ref overview_xrcformat_type_bitmap "bitmap properties", except that toplevel
2361 @c \<object\> is used.
2363 For example, instead of:
2365 <bitmap>mybmp.png</bitmap>
2366 <bitmap stock_id="wxART_NEW"/>
2368 toplevel wxBitmap resources would look like:
2370 <object class="wxBitmap" name="my_bitmap">mybmp.png</object>
2371 <object class="wxBitmap" name="my_new_bitmap" stock_id="wxART_NEW"/>
2375 @subsection overview_xrcformat_icon wxIcon
2377 wxIcon resources are identical to @ref overview_xrcformat_bitmap "wxBitmap ones",
2378 except that the class is @c wxIcon.
2381 @section overview_xrcformat_platform Platform Specific Content
2383 It is possible to conditionally process parts of XRC files on some platforms
2384 only and ignore them on other platforms. @em Any element in XRC file, be it
2385 toplevel or arbitrarily nested one, can have the @c platform attribute. When
2386 used, @c platform contains |-separated list of platforms that this element
2387 should be processed on. It is filtered out and ignored on any other platforms.
2389 Possible elemental values are:
2391 @itemdef{ @c win, Windows }
2392 @itemdef{ @c mac, Mac OS X (or Mac Classic in wxWidgets version supporting it) }
2393 @itemdef{ @c unix, Any Unix platform @em except OS X }
2394 @itemdef{ @c os2, OS/2 }
2399 <label platform="win">Windows</label>
2400 <label platform="unix">Unix</label>
2401 <label platform="mac">Mac OS X</label>
2402 <help platform="mac|unix">Not a Windows machine</help>
2407 @section overview_xrcformat_idranges ID Ranges
2409 Usually you won't care what value the XRCID macro returns for the ID of an
2410 object. Sometimes though it is convenient to have a range of IDs that are
2411 guaranteed to be consecutive. An example of this would be connecting a group of
2412 similar controls to the same event handler.
2414 The following XRC fragment 'declares' an ID range called @em foo and another
2415 called @em bar; each with some items.
2418 <object class="wxButton" name="foo[start]">
2419 <object class="wxButton" name="foo[end]">
2420 <object class="wxButton" name="foo[2]">
2422 <object class="wxButton" name="bar[0]">
2423 <object class="wxButton" name="bar[2]">
2424 <object class="wxButton" name="bar[1]">
2426 <ids-range name="foo" />
2427 <ids-range name="bar" size="30" start="10000" />
2430 For the range foo, no @em size or @em start parameters were given, so the size
2431 will be calculated from the number of range items, and IDs allocated by
2432 wxWindow::NewControlId (so they'll be negative). Range bar asked for a size of
2433 30, so this will be its minimum size: should it have more items, the range will
2434 automatically expand to fit them. It specified a start ID of 10000, so
2435 XRCID("bar[0]") will be 10000, XRCID("bar[1]") 10001 etc. Note that if you
2436 choose to supply a start value it must be positive, and it's your
2437 responsibility to avoid clashes.
2439 For every ID range, the first item can be referenced either as
2440 <em>rangename</em>[0] or <em>rangename</em>[start]. Similarly
2441 <em>rangename</em>[end] is the last item. Using [start] and [end] is more
2442 descriptive in e.g. a Bind() event range or a @em for loop, and they don't have
2443 to be altered whenever the number of items changes.
2445 Whether a range has positive or negative IDs, [start] is always a smaller
2446 number than [end]; so code like this works as expected:
2449 for (int n=XRCID("foo[start]"); n <= XRCID("foo[end]"); ++n)
2453 ID ranges can be seen in action in the <em>objref</em> dialog section of the
2457 @li All the items in an ID range must be contained in the same XRC file.
2458 @li You can't use an ID range in a situation where static initialisation
2459 occurs; in particular, they won't work as expected in an event table. This is
2460 because the event table's IDs are set to their integer values before the XRC
2461 file is loaded, and aren't subsequently altered when the XRCID value changes.
2465 @section overview_xrcformat_extending Extending the XRC Format
2467 The XRC format is designed to be extensible and allows specifying and loading
2468 custom controls. The three available mechanisms are described in the rest of
2469 this section in the order of increasing complexity.
2471 @subsection overview_xrcformat_extending_subclass Subclassing
2473 The simplest way to add custom controls is to set the @c subclass attribute
2474 of @c \<object\> element:
2477 <object name="my_value" class="wxTextCtrl" subclass="MyTextCtrl">
2478 <style>wxTE_MULTILINE</style>
2479 ...etc., setup wxTextCtrl as usual...
2483 In that case, wxXmlResource will create an instance of the specified subclass
2484 (@c MyTextCtrl in the example above) instead of the class (@c wxTextCtrl above)
2485 when loading the resource. However, the rest of the object's loading (calling
2486 its Create() method, setting its properties, loading any children etc.)
2487 will proceed in @em exactly the same way as it would without @c subclass
2488 attribute. In other words, this approach is only sufficient when the custom
2489 class is just a small modification (e.g. overridden methods or customized
2490 events handling) of an already supported classes.
2492 The subclass must satisfy a number of requirements:
2494 -# It must be derived from the class specified in @c class attribute.
2495 -# It must be visible in wxWidget's pseudo-RTTI mechanism, i.e. there must be
2496 a DECLARE_DYNAMIC_CLASS() entry for it.
2497 -# It must support two-phase creation. In particular, this means that it has
2498 to have default constructor.
2499 -# It cannot provide custom Create() method and must be constructible using
2500 base @c class' Create() method (this is because XRC will call Create() of
2501 @c class, not @c subclass). In other words, @em creation of the control
2502 must not be customized.
2505 @subsection overview_xrcformat_extending_unknown Unknown Objects
2507 A more flexible solution is to put a @em placeholder in the XRC file and
2508 replace it with custom control after the resource is loaded. This is done by
2509 using the @c unknown pseudo-class:
2512 <object class="unknown" name="my_placeholder"/>
2515 The placeholder is inserted as dummy wxPanel that will hold custom control in
2516 it. At runtime, after the resource is loaded and a window created from it
2517 (using e.g. wxXmlResource::LoadDialog()), use code must call
2518 wxXmlResource::AttachUnknownControl() to insert the desired control into
2519 placeholder container.
2521 This method makes it possible to insert controls that are not known to XRC at
2522 all, but it's also impossible to configure the control in XRC description in
2523 any way. The only properties that can be specified are
2524 the @ref overview_xrcformat_std_props "standard window properties".
2526 @note @c unknown class cannot be combined with @c subclass attribute,
2527 they are mutually exclusive.
2530 @subsection overview_xrcformat_extending_custom Adding Custom Classes
2532 Finally, XRC allows adding completely new classes in addition to the ones
2533 listed in this document. A class for which wxXmlResourceHandler is implemented
2534 can be used as first-class object in XRC simply by passing class name as the
2535 value of @c class attribute:
2538 <object name="my_ctrl" class="MyWidget">
2539 <my_prop>foo</my_prop>
2540 ...etc., whatever MyWidget handler accepts...
2544 The only requirements on the class are that
2545 -# the class must derive from wxObject
2546 -# it must support wxWidget's pseudo-RTTI mechanism
2548 Child elements of @c \<object\> are handled by the custom handler and there are
2549 no limitations on them imposed by XRC format.
2551 This is the only mechanism that works for toplevel objects -- custom controls
2552 are accessible using the type-unsafe wxXmlResource::LoadObject() method.
2556 @section overview_xrcformat_packed Packed XRC Files
2558 In addition to plain XRC files, wxXmlResource supports (if wxFileSystem support
2559 is compiled in) compressed XRC resources. Compressed resources have either
2560 .zip or .xrs extension and are simply ZIP files that contain arbitrary
2561 number of XRC files and their dependencies (bitmaps, icons etc.).
2565 @section overview_xrcformat_oldversions Older Format Versions
2567 This section describes differences in older revisions of XRC format (i.e.
2568 files with older values of @c version attribute of @c \<resource\>).
2571 @subsection overview_xrcformat_pre_v2530 Versions Before 2.5.3.0
2573 Version 2.5.3.0 introduced C-like handling of "\\" in text. In older versions,
2574 "\n", "\t" and "\r" escape sequences were replaced with respective characters
2575 in the same matter it's done in C, but "\\" was left intact instead of being
2576 replaced with single "\", as one would expect. Starting with 2.5.3.0, all of
2577 them are handled in C-like manner.
2580 @subsection overview_xrcformat_pre_v2301 Versions Before 2.3.0.1
2582 Prior to version 2.3.0.1, "$" was used for accelerators instead of "_"
2583 or "&". For example,
2585 <label>$File</label>
2587 was used in place of current version's
2589 <label>_File</label>