| Version: 3.2.5

XRC File Format

This document describes the format of XRC resource files, as used by wxXmlResource.

Formal description in the form of a RELAX NG schema is located in the `misc/schema` subdirectory of the wxWidgets sources.

XRC file is a XML file with all of its elements in the `http://www.wxwidgets.org/wxxrc` namespace. For backward compatibility, `http://www.wxwindows.org/wxxrc` namespace is accepted as well (and treated as identical to `http://www.wxwidgets.org/wxxrc`), but it shouldn't be used in new XRC files.

XRC file contains definitions for one or more objects – typically windows. The objects may themselves contain child objects.

Objects defined at the top level, under the root element, can be accessed using wxXmlResource::LoadDialog() and other LoadXXX methods. They must have `name` attribute that is used as LoadXXX's argument (see Object Element for details).

Child objects are not directly accessible via wxXmlResource, they can only be accessed using XRCCTRL().

# Resource Root Element

The root element is always `<resource>`. It has one optional attribute, `version` which, while optional, should always be set to the latest version. At the time of writing, it is `"2.5.3.0"`, so all XRC documents should look like the following:

<?xml version="1.0"?>
<resource xmlns="http://www.wxwidgets.org/wxxrc" version="2.5.3.0">
...
</resource>

The version consists of four integers separated by periods. The first three components are major, minor and release number of the wxWidgets release when the change was introduced, the last one is revision number and is 0 for the first incompatible change in given wxWidgets release, 1 for the second and so on. The version changes only if there was an incompatible change introduced; merely adding new kind of objects does not constitute incompatible change.

`<resource>` may have arbitrary number of object elements as its children; they are referred to as toplevel objects in the rest of this document. Unlike objects defined deeper in the hierarchy, toplevel objects must have their `name` attribute set and it must be set to a value unique among root's children.

# Defining Objects

## Object Element

The `<object>` element represents a single object (typically a GUI element) and it usually maps directly to a wxWidgets class instance. It has one mandatory attribute, `class`, and optional `name` and `subclass` attributes.

The `class` attribute must always be present, it tells XRC what wxWidgets object should be created and by which wxXmlResourceHandler.

`name` is the identifier used to identify the object. This name serves three purposes:

1. It is used by wxXmlResource's various LoadXXX() methods to find the resource by name passed as argument.
2. wxWindow's name (see wxWindow::GetName()) is set to it.
3. Numeric ID of a window or menu item is derived from the name. If the value represents an integer (in decimal notation), it is used for the numeric ID unmodified. If it is one of the wxID_XXX literals defined by wxWidgets (see Stock Items), its respective value is used. Otherwise, the name is transformed into dynamically generated ID. See wxXmlResource::GetXRCID() for more information.

Name attributes must be unique at the top level (where the name is used to load resources) and should be unique among all controls within the same toplevel window (wxDialog, wxFrame).

The `subclass` attribute optional name of class whose constructor will be called instead of the constructor for "class". See Subclassing for more details.

`<object>` element may – and almost always do – have children elements. These come in two varieties:

1. Object's properties. A property is a value describing part of object's behaviour, for example the "label" property on wxButton defines its label. In the most common form, property is a single element with text content ("\<label\>Cancel\</label\>"), but they may use nested subelements too (e.g. font property). A property can only be listed once in an object's definition.
2. Child objects. Window children, sizers, sizer items or notebook pages are all examples of child objects. They are represented using nested `<object>` elements and are can be repeated more than once. The specifics of which object classes are allowed as children are class-specific and are documented below in Supported Controls.

Example:

<object class="wxDialog" name="example_dialog">
<!-- properties: -->
<title>Non-Derived Dialog Example</title>
<centered>1</centered>
<!-- child objects: -->
<object class="wxBoxSizer">
<orient>wxVERTICAL</orient>
<cols>1</cols>
<rows>0</rows>
...
</object>
</object>
wxVERTICAL
@ wxVERTICAL
Definition: defs.h:28

## Object References

Anywhere an `<object>` element can be used, `<object_ref>` may be used instead. `<object_ref>` is a reference to another named (i.e. with the `name` attribute) `<object>` element. It has one mandatory attribute, `ref`, with value containing the name of a named `<object>` element. When an `<object_ref>` is encountered, a copy of the referenced `<object>` element is made in place of `<object_ref>` occurrence and processed as usual.

For example, the following code:

<object class="wxDialog" name="my_dlg">
...
</object>
<object_ref name="my_dlg_alias" ref="my_dlg"/>

is equivalent to

<object class="wxDialog" name="my_dlg">
...
</object>
<object class="wxDialog" name="my_dlg_alias">
... <!-- same as in my_dlg -->
</object>

Additionally, it is possible to override some parts of the referenced object in the `<object_ref>` pointing to it. This is useful for putting repetitive parts of XRC definitions into a template that can be reused and customized in several places. The two parts are merged as follows:

1. The referred object is used as the initial content.
2. All attributes set on `<object_ref>` are added to it.
3. All child elements of `<object_ref>` are scanned. If an element with the same name (and, if specified, the `name` attribute too) is found in the referred object, they are recursively merged.
4. Child elements in `<object_ref>` that do not have a match in the referred object are appended to the list of children of the resulting element by default. Optionally, they may have `insert_at` attribute with two possible values, "begin" or "end". When set to "begin", the element is prepended to the list of children instead of appended.

For example, "my_dlg" in this snippet:

<object class="wxDialog" name="template">
<title>Dummy dialog</title>
<size>400,400</size>
</object>
<object_ref ref="template" name="my_dlg">
<title>My dialog</title>
<centered>1</centered>
</object_ref>

is identical to:

<object class="wxDialog" name="my_dlg">
<title>My dialog</title>
<size>400,400</size>
<centered>1</centered>
</object>

# Data Types

There are several property data types that are frequently reused by different properties. Rather than describing their format in the documentation of every property, we list commonly used types in this section and document their format.

## Boolean

Boolean values are expressed using either "1" literal (true) or "0" (false).

## Floating-point value

Floating point values use POSIX (C locale) formatting – decimal separator is "." regardless of the locale.

## Colour

Colour specification can be either any string colour representation accepted by wxColour::Set() or any wxSYS_COLOUR_XXX symbolic name accepted by wxSystemSettings::GetColour(). In particular, the following forms are supported:

- named colours from wxColourDatabase
- HTML-like "#rrggbb" syntax (but not "#rgb")
- CSS-style "rgb(r,g,b)" and "rgba(r,g,b,a)"
- wxSYS_COLOUR_XXX symbolic names

Some examples:

<fg>red</fg>
<fg>#ff0000</fg>
<fg>rgb(255,0,0)</fg>
<fg>wxSYS_COLOUR_HIGHLIGHT</fg>
wxSYS_COLOUR_HIGHLIGHT
@ wxSYS_COLOUR_HIGHLIGHT
Colour of item(s) selected in a control.
Definition: settings.h:65

## Size

Sizes and positions can be expressed in either DPI-independent pixel values or in dialog units. The former is the default, to use the latter "d" suffix can be added. Semi-formally the format is:

size := x "," y ["d"]

where x and y are integers. Either of the components (or both) may be "-1" to signify default value. As a shortcut, empty string is equivalent to "-1,-1" (= wxDefaultSize or wxDefaultPosition).

Notice that the dialog unit suffix "d" applies to both `x` and `y` if it's specified and cannot be specified after the first component, but only at the end.

Examples:

42,-1
100,100
100,50d

## Position

Same as Size.

## Dimension

Similarly to sizes, dimensions are expressed as integers with optional "d" suffix. When "d" suffix is used, the integer preceding it is interpreted as dialog units in the parent window, otherwise it's a DPI-independent pixel value.

## Pair of integers

This is similar to Size size, but for values that are not expressed in pixels and so doesn't allow "d" suffix nor does any DPI-dependent scaling, i.e. the format is just

size := x "," y

and `x` and `y` are just integers which are not interpreted in any way.

## Text

String properties use several escape sequences that are translated according to the following table:

"_" | "&" (used for accelerators in wxWidgets)
"__" | "_"
"\n" | line break
"\r" | carriage return
"\t" | tab
"\" | backslash

By default, the text is translated using wxLocale::GetTranslation() before it is used. This can be disabled either globally by not passing wxXRC_USE_LOCALE to wxXmlResource constructor, or by setting the `translate` attribute on the property node to "0":

<!-- this is not translated: -->
<label translate="0">_Unix</label>
<!-- but this is: -->
<help>Use Unix-style newlines</help>

Note
  Even though the "_" character is used instead of "&" for accelerators, it is still possible to use "&". The latter has to be encoded as "&amp;", though, so using "_" is more convenient.

See also
  Versions Before 2.5.3.0, Versions Before 2.3.0.1

## Non-Translatable Text

Like Text, but the text is never translated and `translate` attribute cannot be used.

## String

An unformatted string. Unlike with Text, no escaping or translations are done.

## URL

Any URL accepted by wxFileSystem (typically relative to XRC file's location, but can be absolute too). Unlike with Text, no escaping or translations are done.

## Bitmap

Bitmap properties contain specification of a single bitmap, icon, a set of bitmaps or SVG file. In the most basic form, their text value is simply a relative URL of the bitmap to use. For example:

<object class="tool" name="wxID_NEW">
<tooltip>New</tooltip>
<bitmap>new.png</bitmap>
</object>

The value is interpreted as path relative to the location of XRC file where the reference occurs, but notice that it is still an URL and not just a filename, which means that the characters special in the URLs, such as `'#'` must be percent-encoded, e.g. here is the correct way to specify a bitmap with the path `"images/#1/tool.png"` in XRC:

<object class="tool" name="first">
<bitmap>images/%231/tool.png</bitmap>
</object>

Bitmap file paths can include environment variables that are expanded if wxXRC_USE_ENVVARS was passed to the wxXmlResource constructor.

It is possible to specify the multi-resolution bitmap by a set of bitmaps or an SVG file, which are mutually exclusive. The set of bitmaps should contain one or more relative URLs of a bitmap, separated by `'`;'. For example, to specify two bitmaps, to be used in standard and 200% DPI scaling respectively, you could write:

<bitmap>new.png;new_2x.png</bitmap>

Here the first bitmap is special, as its size determines the logical size of the bitmap. In other words, this bitmap is the one used when DPI scaling is not in effect. Any subsequent bitmaps can come in any order and will be used when the DPI scaling factor is equal, or at least close, to the ratio of their size to the size of the first bitmap. Using `_2x` naming convention here is common, but not required, the names of the bitmaps can be arbitrary, e.g.

<bitmap>new_32x32.png;new_64x64.png</bitmap>

would work just as well. When using SVG file you must also specify `default_size` attribute (even if the size is specified in SVG file, it may be different from the size needed here):

<bitmap default_size="32,32">new.svg</bitmap>

Alternatively, it is possible to specify the bitmap using wxArtProvider IDs. In this case, the property element has no textual value (filename) and instead has the `stock_id` XML attribute that contains stock art ID as accepted by wxArtProvider::GetBitmap(). This can be either custom value (if the app uses app-specific art provider) or one of the predefined wxART_XXX constants.

Optionally, `stock_client` attribute may be specified too and contain one of the predefined wxArtClient values. If it is not specified, the default client ID most appropriate in the context where the bitmap is referenced will be used. In most cases, specifying `stock_client` is not needed.

Examples of stock bitmaps usage:

<bitmap stock_id="fixed-width"/> <!-- custom app-specific art -->
<bitmap stock_id="wxART_FILE_OPEN"/> <!-- standard art -->

If both specifications are provided, then `stock_id` is used if it is recognized by wxArtProvider and the provided bitmap file is used as a fallback.

## Style

Style properties (such as window's style or sizer flags) use syntax similar to C++: the style value is OR-combination of individual flags. Symbolic names identical to those used in C++ code are used for the flags. Flags are separated with "|" (whitespace is allowed but not required around it).

The flags that are allowed for a given property are context-dependent.

Examples:

<style>wxCAPTION|wxSYSTEM_MENU | wxRESIZE_BORDER</style>
<exstyle>wxDIALOG_EX_CONTEXTHELP</exstyle>
wxSYSTEM_MENU
#define wxSYSTEM_MENU
Definition: defs.h:1345
wxRESIZE_BORDER
#define wxRESIZE_BORDER
Definition: defs.h:1350
wxCAPTION
#define wxCAPTION
Definition: defs.h:218
wxDIALOG_EX_CONTEXTHELP
#define wxDIALOG_EX_CONTEXTHELP
Definition: defs.h:327

## Show Effect

One of the wxShowEffect values.

Example:

<showeffect>wxSHOW_EFFECT_EXPAND</showeffect>
wxSHOW_EFFECT_EXPAND
@ wxSHOW_EFFECT_EXPAND
Expanding or collapsing effect.
Definition: window.h:49

## Font

XRC uses similar, but more flexible, abstract description of fonts to that used by wxFont class. A font can be described either in terms of its elementary properties, or it can be derived from one of system fonts or the parent window font.

The font property element is a "composite" element: unlike majority of properties, it doesn't have text value but contains several child elements instead. These children are handled in the same way as object properties and can be one of the following "sub-properties":

property | type | description
--- | --- | ---
size | float | Pixel size of the font (default: wxNORMAL_FONT's size or `sysfont's` size if the `sysfont` property is used or the current size of the font of the enclosing control if the `inherit` property is used. Note that versions of wxWidgets until 3.1.2 only supported integer values for the font size.
style | enum | One of "normal", "italic" or "slant" (default: normal).
weight | enum or integer | One of "thin", "extralight", "light", "normal", "medium", "semibold", "bold", "extrabold", "heavy", "extraheavy", corresponding to the similarly named elements of wxFontWeight enum, or a numeric value between 1 and 1000 (default: normal). Note that versions of wxWidgets until 3.1.2 only supported "light", "normal" and "bold" values for weight.
family | enum | One of "default", "roman", "script", "decorative", "swiss", "modern" or "teletype" (default: default).
underlined | Boolean | Whether the font should be underlined (default: 0).

strikethrough

Boolean

Whether the strikethrough font should be used (default: 0).

Since
  3.1.2

face |  | Comma-separated list of face names; the first one available is used (default: unspecified).
encoding |  | Charset of the font, unused in Unicode build), as string (default: unspecified).
sysfont |  | Symbolic name of system standard font(one of wxSYS_*_FONT constants).
inherit | Boolean | If true, the font of the enclosing control is used. If this property and the `sysfont` property are specified the `sysfont` property takes precedence.
relativesize | float | Float, font size relative to chosen system font's or inherited font's size; can only be used when 'sysfont' or 'inherit' is used and when 'size' is not used.

All of them are optional, if they are missing, appropriate wxFont default is used. If the `sysfont` or `inherit` property is used, then the defaults are taken from it instead.

Examples:

<font>
<!-- fixed font: Arial if available, fall back to Helvetica -->
<face>arial,helvetica</face>
<size>12</size>
</font>
<font>
<!-- enlarged, enboldened standard font: -->
<sysfont>wxSYS_DEFAULT_GUI_FONT</sysfont>
<weight>bold</weight>
<relativesize>1.5</relativesize>
</font>
wxSYS_DEFAULT_GUI_FONT
@ wxSYS_DEFAULT_GUI_FONT
Default font for user interface objects such as menus and dialog boxes.
Definition: settings.h:39

Note
  You cannot use `inherit` for a font that gets used before the enclosing control is created, e.g. if the control gets the font passed as parameter for its constructor, or if the control is not derived from wxWindow.

## Image List

Defines a wxImageList.

The imagelist property element is a "composite" element: unlike majority of properties, it doesn't have text value but contains several child elements instead. These children are handled similarly to object properties and can be one of the following "sub-properties":

property | type | description
--- | --- | ---
mask | Boolean | If masks should be created for all images (default: 1).
size | Size | The size of the images in the list (default: the size of the first bitmap).
bitmap | Bitmap | Adds a new image. Unlike normal object properties, `bitmap` may be used more than once to add multiple images to the list. At least one `bitmap` value is required.

Example:

<imagelist>
<size>32,32</size>
<bitmap stock_id="wxART_QUESTION"/>
<bitmap stock_id="wxART_INFORMATION"/>
</imagelist>

## Accelerators List

Defines a list of wxMenuItem's extra accelerators.

The extra-accels property element is a "composite" element: it contains one or more `<accel>` "sub-properties":

property | type | description
--- | --- | ---
accel | Non-Translatable Text | wxMenuItem's accelerator (default: none).

Example:

<extra-accels>
<accel>Ctrl-W</accel>
<accel>Shift-Ctrl-W</accel>
</extra-accels>

# Controls and Windows

This section describes support wxWindow-derived classes in XRC format.

## Standard Properties

The following properties are always (unless stated otherwise in control-specific docs) available for windows objects. They are omitted from properties lists below.

property | type | description
--- | --- | ---
pos | Position | Initial position of the window (default: wxDefaultPosition).
size | Size | Initial size of the window (default: wxDefaultSize).
style | Style | Window style for this control. The allowed values depend on what window is being created, consult respective class' constructor documentation for details (default: window-dependent default, usually wxFOO_DEFAULT_STYLE if defined for class wxFoo, 0 if not).
exstyle | Style | Extra style for the window, if any. See wxWindow::SetExtraStyle() (default: not set).
fg | Colour | Foreground colour of the window (default: window's default).
ownfg | Colour | Non-inheritable foreground colour of the window, see wxWindow::SetOwnForegroundColour() (default: none).
bg | Colour | Background colour of the window (default: window's default).
ownbg | Colour | Non-inheritable background colour of the window, see wxWindow::SetOwnBackgroundColour() (default: none).
enabled | Boolean | If set to 0, the control is disabled (default: 1).
focused | Boolean | If set to 1, the control has focus initially (default: 0).
hidden | Boolean | If set to 1, the control is created hidden (default: 0).
tooltip | Text | Tooltip to use for the control (default: not set).

variant

String

Window variant (see wxWindow::SetWindowVariant()), one of "normal", "small", "mini" or "large" (default: "normal")

Since
  3.0.2

font | Font | Font to use for the control (default: window's default).
ownfont | Font | Non-inheritable font to use for the control, see wxWindow::SetOwnFont() (default: none).
help | Text | Context-sensitive help for the control, used by wxHelpProvider (default: not set).

All of these properties are optional.

## Supported Controls

This section lists all controls supported by default. For each control, its control-specific properties are listed. If the control can have child objects, it is documented there too; unless said otherwise, XRC elements for these controls cannot have children.

### wxActivityIndicator

property | type | description
--- | --- | ---
running | Boolean | If true, start the activity indicator after creating it (default: false).

### wxAnimationCtrl

property | type | description
--- | --- | ---
animation | URL | Animation file to load into the control (default: none).
inactive-bitmap | Bitmap | Bitmap to use when not playing the animation (default: the default).

### wxAuiManager

Notice that wxAUI support in XRC is available in wxWidgets 3.1.1 and later only and you need to explicitly register its handler using

#include <wx/xrc/xh_aui.h>
AddHandler(new wxAuiXmlHandler);

to use it.

A wxAuiManager can have one or more child objects of the wxAuiPaneInfo class. wxAuiPaneInfo objects have the following properties:

property | type | description
--- | --- | ---
caption | Text | Sets the caption of the pane.
caption_visible | Boolean | Indicates that a pane caption should be visible.
close_button | Boolean | Indicates that a close button should be drawn for the pane.
maximize_button | Boolean | Indicates that a maximize button should be drawn for the pane.
minimize_button | Boolean | Indicates that a minimize button should be drawn for the pane.
pin_button | Boolean | Indicates that a pin button should be drawn for the pane.
gripper | Boolean | Indicates that a gripper should be drawn for the pane.
pane_border | Boolean | Indicates that a border should be drawn for the pane.
dock |  | Indicates that a pane should be docked.
float |  | Indicates that a pane should be floated.
top_dockable | Boolean | Indicates whether a pane can be docked at the top of the frame.
bottom_dockable | Boolean | Indicates whether a pane can be docked at the bottom of the frame.
left_dockable | Boolean | Indicates whether a pane can be docked on the left of the frame.
right_dockable | Boolean | Indicates whether a pane can be docked on the right of the frame.
dock_fixed | Boolean | Causes the containing dock to have no resize sash.
resizable | Boolean | Allows a pane to be resized if the parameter is true, and forces it to be a fixed size if the parameter is false.
movable | Boolean | Indicates whether a pane can be moved.
floatable | Boolean | Sets whether the user will be able to undock a pane and turn it into a floating window.
best_size | Size | Sets the ideal size for the pane.
floating_size | Size | Sets the size of the floating pane.
min_size | Size | Sets the minimum size of the pane.
max_size | Size | Sets the maximum size of the pane.
default_pane |  | Specifies that the pane should adopt the default pane settings.
toolbar_pane |  | Specifies that the pane should adopt the default toolbar pane settings.
layer |  | Determines the layer of the docked pane.
row |  | Determines the row of the docked pane.
center_pane |  | Specifies that the pane should adopt the default center pane settings.
centre_pane |  | Same as center_pane.
direction |  | Determines the direction of the docked pane.
top |  | Sets the pane dock position to the top of the frame.
bottom |  | Sets the pane dock position to the bottom side of the frame.
left |  | Sets the pane dock position to the left side of the frame.
right |  | Sets the pane dock position to the right side of the frame.
center |  | Sets the pane dock position to the center of the frame.
centre |  | Same as center.

### wxAuiNotebook

property | type | description
--- | --- | ---

art-provider

String

One of `default` for wxAuiDefaultTabArt or `simple` for wxAuiSimpleTabArt (default: `default`).

Since
  3.2.0

A wxAuiNotebook can have one or more child objects of the `notebookpage` pseudo-class. `notebookpage` objects have the following properties:

property | type | description
--- | --- | ---
label | Text | Page label (default: empty).
bitmap | Bitmap | Bitmap shown alongside the label (default: none).
selected | Boolean | Is the page selected initially (only one page can be selected; default: 0)?

Each `notebookpage` must have exactly one non-toplevel window as its child.

Example:

<object class="wxAuiNotebook">
<style>wxBK_BOTTOM</style>
<object class="notebookpage">
<label>Page 1</label>
<bitmap>bitmap.png</bitmap>
<object class="wxPanel" name="page_1">
...
</object>
</object>
</object>
wxBK_BOTTOM
#define wxBK_BOTTOM
Definition: bookctrl.h:40

Note
  See wxAuiManager about using wxAUI classes in XRC.

### wxAuiToolBar

Building an XRC for wxAuiToolBar is quite similar to wxToolBar. The only significant differences are:

- the use of the class name wxAuiToolBar
- the styles supported are the ones described in the wxAuiToolBar class definition
- the 'space' pseudo-class has two optional, mutually exclusive, integer properties: 'proportion' and 'width'. If 'width' is specified, a space is added using wxAuiToolBar::AddSpacer(); if 'proportion', the value is used in wxAuiToolBar::AddStretchSpacer(). If neither are provided, the default is a stretch-spacer with a proportion of 1.
- there is an additional pseudo-class, 'label', that has a string property. See wxAuiToolBar::AddLabel().

Refer to the section wxToolBar for more details.

Note
  The XML Handler should be explicitly registered:
  #include <wx/xrc/xh_auitoolb.h>
  AddHandler(new wxAuiToolBarXmlHandler);

Since
  3.1.0

### wxBannerWindow

property | type | description
--- | --- | ---
direction | `wxLEFT|wxRIGHT|wxTOP|wxBOTTOM` | The side along which the banner will be positioned (default: wxLEFT).
bitmap | Bitmap | Bitmap to use as the banner background (default: none).
title | Text | Banner title, should be single line (default: none).
message | Text | Possibly multi-line banner message (default: none).
gradient-start | Colour | Starting colour of the gradient used as banner background. (Optional. Can't be used if a valid bitmap is specified. If used, both gradient values must be set.)
gradient-end | Colour | End colour of the gradient used as banner background. (Optional. Can't be used if a valid bitmap is specified. If used, both gradient values must be set.)

### wxBitmapButton

property | type | description
--- | --- | ---
default | Boolean | Should this button be the default button in dialog (default: 0)?

close

Boolean

If set, this is a special "Close" button using system-defined appearance, see wxBitmapButton::NewCloseButton(). If this property is set, `bitmap` and `style` are ignored and shouldn't be used.

Since
  3.1.5

bitmap | Bitmap | Bitmap to show on the button (default: none).
pressed | Bitmap | Bitmap to show when the button is pressed (default: none, same as `bitmap`). This property exists since wxWidgets 3.1.6, but the equivalent (and still supported) "selected" property can be used in the older versions.
focus | Bitmap | Bitmap to show when the button has focus (default: none, same as `bitmap`).
disabled | Bitmap | Bitmap to show when the button is disabled (default: none, same as `bitmap`).
current | Bitmap | Bitmap to show when mouse cursor hovers above the bitmap (default: none, same as `bitmap`). This property exists since wxWidgets 3.1.6, but the equivalent (and still supported) "hover" property can be used in the older versions.

### wxBitmapComboBox

property | type | description
--- | --- | ---
selection | integer | Index of the initially selected item or -1 for no selection (default: -1).
value | String | Initial value in the control (doesn't have to be one of @ content values; default: empty).

If both `value` and `selection` are specified and `selection` is not -1, then `selection` takes precedence.

A wxBitmapComboBox can have one or more child objects of the `ownerdrawnitem` pseudo-class. `ownerdrawnitem` objects have the following properties:

property | type | description
--- | --- | ---
text | Text | Item's label (default: empty).
bitmap | Bitmap | Item's bitmap (default: no bitmap).

Example:

<object class="wxBitmapComboBox">
<selection>1</selection>
<object class="ownerdrawnitem">
<text>Foo</text>
<bitmap>foo.png</bitmap>
</object>
<object class="ownerdrawnitem">
<text>Bar</text>
<bitmap>bar.png</bitmap>
</object>
</object>

### wxBitmapToggleButton

property | type | description
--- | --- | ---
bitmap | Bitmap | Label to display on the button (default: none).

pressed

Bitmap

Bitmap to show when the button is pressed (default: none, same as `bitmap`).

Since
  3.1.7

focus

Bitmap

Bitmap to show when the button has focus (default: none, same as `bitmap`).

Since
  3.1.7

disabled

Bitmap

Bitmap to show when the button is disabled (default: none, same as `bitmap`).

Since
  3.1.7

current

Bitmap

Bitmap to show when the mouse cursor hovers above the bitmap (default: none, same as `bitmap`).

Since
  3.1.7

margins

Size

Set the margins between the bitmap and the text of the button. This method is currently only implemented under MSW. If it is not called, a default margin is used around the bitmap.

Since
  3.1.7

checked | Boolean | Should the button be checked/pressed initially (default: 0)?

### wxButton

property | type | description
--- | --- | ---
label | Text | Label to display on the button (may be omitted if only the bitmap or stock ID is used).
bitmap | Bitmap | Bitmap to display in the button (optional).

pressed

Bitmap

Bitmap to show when the button is pressed (default: none, same as `bitmap`).

Since
  3.1.7

focus

Bitmap

Bitmap to show when the button has focus (default: none, same as `bitmap`).

Since
  3.1.7

disabled

Bitmap

Bitmap to show when the button is disabled (default: none, same as `bitmap`).

Since
  3.1.7

current

Bitmap

Bitmap to show when the mouse cursor hovers above the bitmap (default: none, same as `bitmap`).

Since
  3.1.7

margins

Size

Set the margins between the bitmap and the text of the button. This method is currently only implemented under MSW. If it is not called, a default margin is used around the bitmap.

Since
  3.1.7

bitmapposition | `wxLEFT|wxRIGHT|wxTOP|wxBOTTOM` | Position of the bitmap in the button, see wxButton::SetBitmapPosition() (default: wxLEFT).
default | Boolean | Should this button be the default button in dialog (default: 0)?

### wxCalendarCtrl

No additional properties.

### wxCheckBox

property | type | description
--- | --- | ---
label | Text | Label to use for the checkbox (default: empty).
checked | integer | Sets the initial state of the checkbox. 0 is unchecked (default), 1 is checked, and since wxWidgets 3.1.7, 2 sets the undetermined state of a 3-state checkbox.

### wxCheckListBox

property | type | description
--- | --- | ---
content | items | Content of the control; this property has any number of `<item>` XML elements as its children, with the items text as their text values (default: empty).

The `<item>` elements have listbox items' labels as their text values. They can also have optional `checked` XML attribute – if set to "1", the value is initially checked.

Example:

<object class="wxCheckListBox">
<content>
<item checked="1">Download library</item>
<item checked="1">Compile samples</item>
<item checked="1">Skim docs</item>
<item checked="1">Finish project</item>
<item>Wash car</item>
</content>
</object>

### wxChoice

property | type | description
--- | --- | ---
selection | integer | Index of the initially selected item or -1 for no selection (default: -1).
content | items | Content of the control; this property has any number of `<item>` XML elements as its children, with the items text as their text values (default: empty).

Example:

<object class="wxChoice" name="controls_choice">
<content>
<item>See</item>
<item>Hear</item>
<item>Feel</item>
<item>Smell</item>
<item>Taste</item>
<item>The Sixth Sense!</item>
</content>
</object>

### wxChoicebook

property | type | description
--- | --- | ---
imagelist | Image List | Image list to use for the images (default: none, built implicitly).

Additionally, a choicebook can have one or more child objects of the `choicebookpage` pseudo-class (similarly to wxNotebook and its `notebookpage`).

`choicebookpage` objects have the following properties:

property | type | description
--- | --- | ---
label | Text | Sheet page's title (default: empty).
bitmap | Bitmap | Bitmap shown alongside the label (default: none, mutually exclusive with `image`).
image | integer | The zero-based index of the image associated with the item into the image list (default: none, mutually exclusive with `bitmap`, only if imagelist was set).
selected | Boolean | Is the page selected initially (only one page can be selected; default: 0)?

Each `choicebookpage` has exactly one non-toplevel window as its child.

### wxCollapsiblePane

property | type | description
--- | --- | ---
label | Text | Label to use for the collapsible section (default: empty).
collapsed | Boolean | Should the pane be collapsed initially (default: 0)?

wxCollapsiblePane may contain single optional child object of the `panewindow` pseudo-class type. `panewindow` itself must contain exactly one child that is a sizer or a non-toplevel window object.

### wxColourPickerCtrl

property | type | description
--- | --- | ---
value | Colour | Initial value of the control (default: wxBLACK).

### wxComboBox

property | type | description
--- | --- | ---
selection | integer | Index of the initially selected item or -1 for no selection (default: not used).
content | items | Content of the control; this property has any number of `<item>` XML elements as its children, with the items text as their text values (default: empty).
value | String | Initial value in the control (doesn't have to be one of @ content values; default: empty).

If both `value` and `selection` are specified and `selection` is not -1, then `selection` takes precedence.

Example:

<object class="wxComboBox" name="controls_combobox">
<style>wxCB_DROPDOWN</style>
<value>nedit</value>
<content>
<item>vim</item>
<item>emacs</item>
<item>notepad.exe</item>
<item>bbedit</item>
</content>
</object>
wxCB_DROPDOWN
#define wxCB_DROPDOWN
Definition: defs.h:378

### wxComboCtrl

property | type | description
--- | --- | ---
value | String | Initial value in the control (default: empty).

### wxCommandLinkButton

The wxCommandLinkButton contains a main title-like `label` and an optional `note` for longer description. The main `label` and the `note` can be concatenated into a single string using a new line character between them (notice that the `note` part can have more new lines in it).

property | type | description
--- | --- | ---
label | Text | First line of text on the button, typically the label of an action that will be made when the button is pressed (default: empty).
note | Text | Second line of text describing the action performed when the button is pressed (default: none).

bitmap

Bitmap

Bitmap to display in the button (optional).

Since
  3.1.5

pressed

Bitmap

Bitmap to show when the button is pressed (default: none, same as `bitmap`).

Since
  3.1.7

focus

Bitmap

Bitmap to show when the button has focus (default: none, same as `bitmap`).

Since
  3.1.7

disabled

Bitmap

Bitmap to show when the button is disabled (default: none, same as `bitmap`).

Since
  3.1.7

current

Bitmap

Bitmap to show when the mouse cursor hovers above the bitmap (default: none, same as `bitmap`).

Since
  3.1.7

default

Boolean

Should this button be the default button in dialog (default: 0)?

Since
  3.1.5

### wxDataViewCtrl

No additional properties.

### wxDataViewListCtrl

No additional properties.

### wxDataViewTreeCtrl

property | type | description
--- | --- | ---
imagelist | Image List | Image list to use for the images (default: none).

### wxDatePickerCtrl

property | type | description
--- | --- | ---

null-text

String

Set the text to show when there is no valid value (default: empty). Only used if the control has wxDP_ALLOWNONE style. Currently implemented on MSW, ignored elsewhere.

Since
  3.1.5.

### wxDialog

property | type | description
--- | --- | ---
title | Text | Dialog's title (default: empty).
icon | Bitmap | Dialog's icon (default: not used).
centered | Boolean | Whether the dialog should be centered on the screen (default: 0).

wxDialog may have optional children: either exactly one sizer child or any number of non-toplevel window objects. If sizer child is used, it sets size hints too.

### wxDirPickerCtrl

property | type | description
--- | --- | ---
value | String | Initial value of the control (default: empty).
message | Text | Message shown to the user in wxDirDialog shown by the control (default: empty).

### wxEditableListBox

property | type | description
--- | --- | ---
label | Text | Label shown above the list (default: empty).
content | items | Content of the control; this property has any number of `<item>` XML elements as its children, with the items text as their text values (default: empty).

Example:

<object class="wxEditableListBox" name="controls_listbox">
<size>250,160</size>
<label>List of things</label>
<content>
<item>Milk</item>
<item>Pizza</item>
<item>Bread</item>
<item>Orange juice</item>
<item>Paper towels</item>
</content>
</object>

### wxFileCtrl

property | type | description
--- | --- | ---
defaultdirectory | String | Sets the current directory displayed in the control (default: empty).
defaultfilename | String | Selects a certain file (default: empty).
wildcard | String | Sets the wildcard, which can contain multiple file types, for example: "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" (default: all files).

### wxFilePickerCtrl

property | type | description
--- | --- | ---
value | String | Initial value of the control (default: empty).
message | Text | Message shown to the user in wxDirDialog shown by the control (default: empty).
wildcard | String | Sets the wildcard, which can contain multiple file types, for example: "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" (default: all files).

### wxFontPickerCtrl

property | type | description
--- | --- | ---
value | Font | Initial value of the control (default: wxNORMAL_FONT).

### wxFrame

property | type | description
--- | --- | ---
title | Text | Frame's title (default: empty).
icon | Bitmap | Frame's icon (default: not used).
centered | Boolean | Whether the frame should be centered on the screen (default: 0).

wxFrame may have optional children: either exactly one sizer child or any number of non-toplevel window objects. If sizer child is used, it sets size hints too.

### wxGauge

property | type | description
--- | --- | ---
range | integer | Maximum value of the gauge (default: 100).
value | integer | Initial value of the control (default: 0).
shadow | Dimension | Ignored, preserved only for compatibility.
bezel | Dimension | Ignored, preserved only for compatibility.

### wxGenericAnimationCtrl

This handler is identical to the one for wxAnimationCtrl, please see it for more information. The only difference is that, for the platforms with a native wxAnimationCtrl implementation, using this handler creates a generic control rather than a native one.

### wxGenericDirCtrl

property | type | description
--- | --- | ---
defaultfolder | String | Initial folder (default: empty).
filter | Text | Filter string, using the same syntax as used by wxFileDialog, e.g. "All files (*.*)|*.*|JPEG files (*.jpg)|*.jpg" (default: empty).
defaultfilter | integer | Zero-based index of default filter (default: 0).

### wxGrid

No additional properties.

### wxHtmlWindow

property | type | description
--- | --- | ---
url | URL | Page to display in the window (default: none).
htmlcode | Text | HTML markup to display in the window (default: none).
borders | Dimension | Border around HTML content (default: 0).

At most one of `url` and `htmlcode` properties may be specified, they are mutually exclusive. If neither is set, the window is initialized to show empty page.

### wxHyperlinkCtrl

property | type | description
--- | --- | ---
label | Text | Label to display on the control (default: empty).
url | URL | URL to open when the link is clicked (default: empty).

### wxInfoBar

property | type | description
--- | --- | ---
showeffect | Show Effect | The effect to use when showing the bar (optional).
hideeffect | Show Effect | The effect to use when hiding the bar (optional).
effectduration | integer | The duration of the animation used when showing or hiding the bar (optional).
button | object | Add a button to be shown in the info bar (see wxInfoBar::AddButton); this property is of class "button" has name (can be one of standard button ID) and has optional label property. If no buttons are added to the info bar, the default "Close" button will be shown.

Example:

<object class="wxInfoBar">
<effectduration>1000</effectduration>
<showeffect>wxSHOW_EFFECT_EXPAND</showeffect>
<hideeffect>wxSHOW_EFFECT_SLIDE_TO_RIGHT</hideeffect>
<object class="button" name="wxID_UNDO"/>
<object class="button" name="wxID_REDO">
<label>Redo Custom Label</label>
</object>
</object>
wxSHOW_EFFECT_SLIDE_TO_RIGHT
@ wxSHOW_EFFECT_SLIDE_TO_RIGHT
Slide window to the right.
Definition: window.h:37

Since
  3.1.3

### wxListBox

property | type | description
--- | --- | ---
selection | integer | Index of the initially selected item or -1 for no selection (default: -1).
content | items | Content of the control; this property has any number of `<item>` XML elements as its children, with the items text as their text values (default: empty).

Example:

<object class="wxListBox" name="controls_listbox">
<size>250,160</size>
<style>wxLB_SINGLE</style>
<content>
<item>Milk</item>
<item>Pizza</item>
<item>Bread</item>
<item>Orange juice</item>
<item>Paper towels</item>
</content>
</object>
wxLB_SINGLE
#define wxLB_SINGLE
Definition: defs.h:360

### wxListbook

property | type | description
--- | --- | ---
imagelist | Image List | Image list to use for the images (default: none, built implicitly).

Additionally, a listbook can have one or more child objects of the `listbookpage` pseudo-class (similarly to wxNotebook and its `notebookpage`).

`listbookpage` objects have the following properties:

property | type | description
--- | --- | ---
label | Text | Sheet page's title (default: empty).
bitmap | Bitmap | Bitmap shown alongside the label (default: none, mutually exclusive with `image`).
image | integer | The zero-based index of the image associated with the item into the image list (default: none, mutually exclusive with `bitmap`, only if imagelist was set).
selected | Boolean | Is the page selected initially (only one page can be selected; default: 0)?

Each `listbookpage` has exactly one non-toplevel window as its child.

### wxListCtrl

property | type | description
--- | --- | ---
imagelist | Image List | The normal (wxIMAGE_LIST_NORMAL) image list (default: none, built implicitly).
imagelist-small | Image List | The small (wxIMAGE_LIST_SMALL) image list (default: none, built implicitly).

A list control can have optional child objects of the listitem class. Report mode list controls (i.e. created with `wxLC_REPORT` style) can in addition have optional listcol child objects.

#### listcol

The `listcol` class can only be used for wxListCtrl children. It can have the following properties (all of them optional):

property | type | description
--- | --- | ---
align | wxListColumnFormat | The alignment for the item. Can be one of `wxLIST_FORMAT_LEFT`, `wxLIST_FORMAT_RIGHT` or `wxLIST_FORMAT_CENTRE`.
text | Text | The title of the column.
width | integer | The column width. `wxLIST_DEFAULT_COL_WIDTH` is used by default.
image | integer | The zero-based index of the image associated with the item in the 'small' image list.

The columns are appended to the control in order of their appearance and may be referenced by 0-based index in the `col` attributes of subsequent `listitem` objects.

#### listitem

The `listitem` is a child object for the class wxListCtrl. It can have the following properties (all of them optional):

property | type | description
--- | --- | ---
align | wxListColumnFormat | The alignment for the item. Can be one of `wxLIST_FORMAT_LEFT`, `wxLIST_FORMAT_RIGHT` or `wxLIST_FORMAT_CENTRE`.
bg | Colour | The background color for the item.
bitmap | Bitmap | Add a bitmap to the (normal) Image List associated with the wxListCtrl parent and associate it with this item. If the imagelist is not defined it will be created implicitly (default: none, mutually exclusive with `image`).
bitmap-small | Bitmap | Add a bitmap in the 'small' Image List associated with the wxListCtrl parent and associate it with this item. If the 'small' imagelist is not defined it will be created implicitly (default: none, mutually exclusive with `image-small`).
col | integer | The zero-based column index.
image | integer | The zero-based index of the image associated with the item in the (normal) image list (default: none, mutually exclusive with `bitmap`, only if imagelist was set).
image-small | integer | The zero-based index of the image associated with the item in the 'small' image list (default: none, mutually exclusive with `bitmap-small`, only if imagelist-small was set).
data | integer | The client data for the item.
font | Font | The font for the item.

state

Style

The item state. Can be any combination of the following values:

- `wxLIST_STATE_FOCUSED:` The item has the focus.
- `wxLIST_STATE_SELECTED:` The item is selected.

text | Text | The text label for the item.
textcolour | Colour | The text colour for the item.

Notice that the item position can't be specified here, the items are appended to the list control in order of their appearance.

### wxMDIParentFrame

wxMDIParentFrame supports the same properties that wxFrame does.

wxMDIParentFrame may have optional children. When used, the child objects must be of wxMDIChildFrame type.

### wxMDIChildFrame

wxMDIChildFrame supports the same properties that wxFrame and wxMDIParentFrame do.

wxMDIChildFrame can only be used as immediate child of wxMDIParentFrame.

wxMDIChildFrame may have optional children: either exactly one sizer child or any number of non-toplevel window objects. If sizer child is used, it sets size hints too.

### wxMenu

property | type | description
--- | --- | ---
label | Text | Menu's label (default: empty, but required for menus other than popup menus).
style | Style | Window style for the menu.
help | Text | Help shown in statusbar when the menu is selected (only for submenus of another wxMenu, default: none).
enabled | Boolean | Is the submenu item enabled (only for submenus of another wxMenu, default: 1)?

Note that unlike most controls, wxMenu does not have Standard Properties, with the exception of `style`.

A menu object can have one or more child objects of the wxMenuItem or wxMenu classes or `break` or `separator` pseudo-classes.

The `separator` pseudo-class is used to insert separators into the menu and has neither properties nor children. Likewise, `break` inserts a break (see wxMenu::Break()).

wxMenuItem objects support the following properties:

property | type | description
--- | --- | ---
label | Text | Item's label (may be omitted if stock ID is used).
accel | Non-Translatable Text | Item's accelerator (default: none).

extra-accels

Accelerators List

List of item's extra accelerators. Such accelerators will not be shown in item's label, but still will work. (default: none).

Since
  3.1.6.

radio | Boolean | Item's kind is wxITEM_RADIO (default: 0)?
checkable | Boolean | Item's kind is wxITEM_CHECK (default: 0)?
bitmap | Bitmap | Bitmap to show with the item (default: none).
bitmap2 | Bitmap | Bitmap for the checked state (wxMSW, if checkable; default: none).
help | Text | Help shown in statusbar when the item is selected (default: none).
enabled | Boolean | Is the item enabled (default: 1)?
checked | Boolean | Is the item checked initially (default: 0)?

Example:

<object class="wxMenu" name="menu_edit">
<style>wxMENU_TEAROFF</style>
<label>_Edit</label>
<object class="wxMenuItem" name="wxID_FIND">
<label>_Find...</label>
<accel>Ctrl-F</accel>
<extra-accels>
<accel>Ctrl-W</accel>
<accel>Shift-Ctrl-W</accel>
</extra-accels>
</object>
<object class="separator"/>
<object class="wxMenuItem" name="menu_fuzzy">
<label>Translation is _fuzzy</label>
<checkable>1</checkable>
</object>
<object class="wxMenu" name="submenu">
<label>A submenu</label>
<object class="wxMenuItem" name="foo">...</object>
...
</object>
<object class="separator" platform="unix"/>
<object class="wxMenuItem" name="wxID_PREFERENCES" platform="unix">
<label>_Preferences</label>
</object>
</object>
wxMENU_TEAROFF
#define wxMENU_TEAROFF
Definition: defs.h:348

### wxMenuBar

property | type | description
--- | --- | ---
style | Style | Window style for the menu bar.

Note that unlike most controls, wxMenuBar does not have Standard Properties, with the exception of `style`.

A menubar can have one or more child objects of the wxMenu class.

### wxNotebook

property | type | description
--- | --- | ---
imagelist | Image List | Image list to use for the images (default: none, built implicitly).

A notebook can have one or more child objects of the `notebookpage` pseudo-class.

`notebookpage` objects have the following properties:

property | type | description
--- | --- | ---
label | Text | Page's title (default: empty).
bitmap | Bitmap | Bitmap shown alongside the label (default: none, mutually exclusive with `image`).
image | integer | The zero-based index of the image associated with the item into the image list (default: none, mutually exclusive with `bitmap`, only if imagelist was set).
selected | Boolean | Is the page selected initially (only one page can be selected; default: 0)?

Each `notebookpage` has exactly one non-toplevel window as its child.

Example:

<object class="wxNotebook">
<style>wxBK_BOTTOM</style>
<object class="notebookpage">
<label>Page 1</label>
<object class="wxPanel" name="page_1">
...
</object>
</object>
<object class="notebookpage">
<label>Page 2</label>
<object class="wxPanel" name="page_2">
...
</object>
</object>
</object>

### wxOwnerDrawnComboBox

wxOwnerDrawnComboBox has the same properties as wxComboBox, plus the following additional properties:

property | type | description
--- | --- | ---
buttonsize | Size | Size of the dropdown button (default: default).

### wxPanel

No additional properties.

wxPanel may have optional children: either exactly one sizer child or any number of non-toplevel window objects.

### wxPropertySheetDialog

property | type | description
--- | --- | ---
title | Text | Dialog's title (default: empty).
icon | Bitmap | Dialog's icon (default: not used).
centered | Boolean | Whether the dialog should be centered on the screen (default: 0).
buttons | Style | Buttons to show, combination of flags accepted by wxPropertySheetDialog::CreateButtons() (default: 0).

A sheet dialog can have one or more child objects of the `propertysheetpage` pseudo-class (similarly to wxNotebook and its `notebookpage`). `propertysheetpage` objects have the following properties:

property | type | description
--- | --- | ---
label | Text | Sheet page's title (default: empty).
bitmap | Bitmap | Bitmap shown alongside the label (default: none).
selected | Boolean | Is the page selected initially (only one page can be selected; default: 0)?

Each `propertysheetpage` has exactly one non-toplevel window as its child.

### wxRadioButton

property | type | description
--- | --- | ---
label | Text | Label shown on the radio button (default: empty).
value | Boolean | Initial value of the control (default: 0).

### wxRadioBox

property | type | description
--- | --- | ---
label | Text | Label for the whole box (default: empty).
dimension | integer | Specifies the maximum number of rows (if style contains `wxRA_SPECIFY_ROWS`) or columns (if style contains `wxRA_SPECIFY_COLS`) for a two-dimensional radiobox (default: 1).
selection | integer | Index of the initially selected item or -1 for no selection (default: -1).
content | items | Content of the control; this property has any number of `<item>` XML elements as its children, with the items text as their text values (see below; default: empty).

The `<item>` elements have radio buttons' labels as their text values. They can also have some optional XML attributes (not properties!):

attribute | type | description
--- | --- | ---
tooltip | String | Tooltip to show over this radio button (default: none).
helptext | String | Contextual help for this radio button (default: none).
enabled | Boolean | Is the button enabled (default: 1)?
hidden | Boolean | Is the button hidden initially (default: 0)?
label | Boolean | Should this item text be interpreted as a label, i.e. escaping underscores in it as done for the label properties of other controls? This attribute exists since wxWidgets 3.1.1 and was always treated as having the value of 0, which still remains its default, until then.

Example:

<object class="wxRadioBox" name="controls_radiobox">
<style>wxRA_SPECIFY_COLS</style>
<label>Radio stations</label>
<dimension>1</dimension>
<selection>0</selection>
<content>
<item tooltip="Powerful radio station" helptext="This station is for amateurs of hard rock and heavy metal">Power 108</item>
<item tooltip="Disabled radio station" enabled="0">Power 0</item>
<item tooltip="">WMMS 100.7</item>
<item tooltip="E=mc^2">Energy 98.3</item>
<item helptext="Favourite chukcha's radio">CHUM FM</item>
<item>92FM</item>
<item hidden="1">Very quiet station</item>
</content>
</object>
wxRA_SPECIFY_COLS
#define wxRA_SPECIFY_COLS
Definition: defs.h:388

### wxRibbonBar

property | type | description
--- | --- | ---
art-provider | String | One of `default`, `aui` or `msw` (default: `default`).

A wxRibbonBar may have wxRibbonPage child objects. The `page` pseudo-class may be used instead of `wxRibbonPage` when used as wxRibbonBar children.

Example:

<object class="wxRibbonBar" name="ribbonbar">
<object class="page" name="FilePage">
<label>First</label>
<object class="panel">
<label>File</label>
<object class="wxRibbonButtonBar">
<object class="button" name="Open">
<bitmap>open.xpm</bitmap>
<label>Open</label>
</object>
</object>
</object>
</object>
<object class="page" name="ViewPage">
<label>View</label>
<object class="panel">
<label>Zoom</label>
<object class="wxRibbonGallery">
<object class="item">
<bitmap>zoomin.xpm</bitmap>
</object>
<object class="item">
<bitmap>zoomout.xpm</bitmap>
</object>
</object>
</object>
</object>
</object>

Notice that wxRibbonBar support in XRC is available in wxWidgets 2.9.5 and later only and you need to explicitly register its handler using

#include <wx/xrc/xh_ribbon.h>
AddHandler(new wxRibbonXmlHandler);

to use it.

### wxRibbonButtonBar

No additional properties.

wxRibbonButtonBar can have child objects of the `button` pseudo-class. `button` objects have the following properties:

property | type | description
--- | --- | ---
hybrid | Boolean | If true, the `wxRIBBON_BUTTON_HYBRID` kind is used (default: false).
disabled | Boolean | Whether the button should be disabled (default: false).
label | Text | Item's label (default: empty).
bitmap | Bitmap | Item's bitmap (default: none).
small-bitmap | Bitmap | Small bitmap (default: none).
disabled-bitmap | Bitmap | Disabled bitmap (default: none).
small-disabled-bitmap | Bitmap | Small disabled bitmap (default: none).
help | Text | Item's help text (default: none).

### wxRibbonControl

No additional properties.

Objects of this type must be subclassed with the `subclass` attribute.

### wxRibbonGallery

No additional properties.

wxRibbonGallery can have child objects of the `item` pseudo-class. `item` objects have the following properties:

property | type | description
--- | --- | ---
bitmap | Bitmap | Item's bitmap (default: none).

### wxRibbonPage

property | type | description
--- | --- | ---
label | Text | Label (default: none).
icon | Bitmap | Icon (default: none).

A wxRibbonPage may have children of any type derived from wxRibbonControl. Most commonly, wxRibbonPanel is used. As a special case, the `panel` pseudo-class may be used instead of `wxRibbonPanel` when used as wxRibbonPage children.

### wxRibbonPanel

property | type | description
--- | --- | ---
label | Text | Label (default: none).
icon | Bitmap | Icon (default: none).

A wxRibbonPanel may have children of any type derived from wxRibbonControl or a single wxSizer child with non-ribbon windows in it.

### wxRichTextCtrl

property | type | description
--- | --- | ---
value | Text | Initial value of the control (default: empty).

Notice that you need to explicitly register the handler using

#include <wx/xrc/xh_richtext.h>
AddHandler(new wxRichTextCtrlXmlHandler);

to use it.

Since
  2.9.5

### wxScrollBar

property | type | description
--- | --- | ---
value | integer | Initial position of the scrollbar (default: 0).
range | integer | Maximum value of the gauge (default: 10).
thumbsize | integer | Size of the thumb (default: 1).
pagesize | integer | Page size (default: 1).

### wxScrolledWindow

property | type | description
--- | --- | ---
scrollrate | Size | Scroll rate in x and y directions (default: not set; required if the window has a sizer child).

wxScrolledWindow may have optional children: either exactly one sizer child or any number of non-toplevel window objects. If sizer child is used, wxSizer::FitInside() is used (instead of wxSizer::Fit() as usual) and so the children don't determine scrolled window's minimal size, they only affect virtual size. Usually, both `scrollrate` and either `size` or `minsize` on containing sizer item should be used in this case.

### wxSimpleHtmlListBox

wxSimpleHtmlListBox has same properties as wxListBox. The only difference is that the text contained in `<item>` elements is HTML markup. Note that the markup has to be escaped:

<object class="wxSimpleHtmlListBox">
<content>
<item>&lt;b&gt;Bold&lt;/b&gt; Milk</item>
</content>
</object>

(X)HTML markup elements cannot be included directly:

<object class="wxSimpleHtmlListBox">
<content>
<!-- This is incorrect, doesn't work! -->
<item><b>Bold</b> Milk</item>
</content>
</object>

### wxSimplebook

wxSimplebook is similar to wxNotebook but simpler: as it doesn't show any page headers, it uses neither image list nor individual page bitmaps and while it still accepts page labels, they are optional as they are not shown to the user either.

So `simplebookpage` child elements, that must occur inside this object, only have the following properties:

`choicebookpage` objects have the following properties:

property | type | description
--- | --- | ---
label | Text | Page's label (default: empty).
selected | Boolean | Is the page selected initially (only one page can be selected; default: 0)?

As with all the other book page elements, each `simplebookpage` must have exactly one non-toplevel window as its child.

Since
  3.0.2

### wxSlider

property | type | description
--- | --- | ---
value | integer | Initial value of the control (default: 0).
min | integer | Minimum allowed value (default: 0).
max | integer | Maximum allowed value (default: 100).
pagesize | integer | Page size; number of steps the slider moves when the user moves pages up or down (default: unset).
linesize | integer | Line size; number of steps the slider moves when the user moves it up or down a line (default: unset).
tickfreq | integer | Tick marks frequency (Windows only; default: unset).
tick | integer | Tick position (Windows only; default: unset).
thumb | integer | Thumb length (Windows only; default: unset).
selmin | integer | Selection start position (Windows only; default: unset).
selmax | integer | Selection end position (Windows only; default: unset).

### wxSpinButton

property | type | description
--- | --- | ---
value | integer | Initial value of the control (default: 0).
min | integer | Minimum allowed value (default: 0).
max | integer | Maximum allowed value (default: 100).

inc

integer

Increment (default: 1).

Since
  3.1.6.

### wxSpinCtrl

wxSpinCtrl supports the same properties as wxSpinButton and, since wxWidgets 2.9.5, another one:

base | integer | Numeric base, currently can be only 10 or 16 (default: 10).

### wxSpinCtrlDouble

wxSpinCtrlDouble supports the same properties as wxSpinButton but `value`, `min` and max are all of type float instead of int. There is one additional property:

inc | float | The amount by which the number is changed by a single arrow press.

digits

integer

Sets the precision of the value of the spin control (default: 0).

Since
  3.1.7.

Since
  3.1.1.

### wxSplitterWindow

property | type | description
--- | --- | ---
orientation | String | Orientation of the splitter, either "vertical" or "horizontal" (default: horizontal).
sashpos | Dimension | Initial position of the sash (default: 0).
minsize | Dimension | Minimum child size (default: not set).
gravity | Floating-point value | Sash gravity, see wxSplitterWindow::SetSashGravity() (default: not set).

wxSplitterWindow must have one or two children that are non-toplevel window objects. If there's only one child, it is used as wxSplitterWindow's only visible child. If there are two children, the first one is used for left/top child and the second one for right/bottom child window.

### wxSearchCtrl

property | type | description
--- | --- | ---
value | Text | Initial value of the control (default: empty).

hint

Text

Descriptive text shown in the empty control (default: "Search").

Since
  3.1.1.

### wxStatusBar

property | type | description
--- | --- | ---
fields | integer | Number of status bar fields (default: 1).
widths | String | Comma-separated list of fields integers. Each value specifies width of one field; the values are interpreted using the same convention used by wxStatusBar::SetStatusWidths() (default: not set).
styles | String | Comma-separated list of fields style values. Each value specifies style of one field and can be one of `wxSB_NORMAL`, `wxSB_FLAT`, `wxSB_RAISED` or `wxSB_SUNKEN` (default: not set).

### wxStaticBitmap

property | type | description
--- | --- | ---
bitmap | Bitmap | Bitmap to display (required).

### wxStaticBox

property | type | description
--- | --- | ---
label | Text | Static box's label (default: empty).

### wxStaticLine

No additional properties.

### wxStaticText

property | type | description
--- | --- | ---
label | Text | Label to display (default: empty).
wrap | Dimension | Wrap the text so that each line is at most the given number of pixels, see wxStaticText::Wrap() (default: no wrap).

### wxStyledTextCtrl

property | type | description
--- | --- | ---
wrapmode | Style | Set wrapmode to wxSTC_WRAP_WORD to enable wrapping on word or style boundaries, wxSTC_WRAP_CHAR to enable wrapping between any characters, wxSTC_WRAP_WHITESPACE to enable wrapping on whitespace, and wxSTC_WRAP_NONE to disable line wrapping (default: wxSTC_WRAP_NONE).

Notice that wxStyledTextCtrl support in XRC is available in wxWidgets 3.1.6 and later only and you need to explicitly register its handler using

#include <wx/xrc/xh_styledtextctrl.h>
AddHandler(new wxStyledTextCtrlXmlHandler);

to use it.

### wxTextCtrl

property | type | description
--- | --- | ---
value | Text | Initial value of the control (default: empty).
maxlength | integer | Maximum length of the text which can be entered by user (default: unlimited).
forceupper | Boolean | If true, use wxTextEntry::ForceUpper() to force the control contents to be upper case.

hint

Text

Hint shown in empty control.

Since
  3.0.1

### wxTimePickerCtrl

No additional properties.

### wxToggleButton

property | type | description
--- | --- | ---
label | Text | Label to display on the button (default: empty).
checked | Boolean | Should the button be checked/pressed initially (default: 0)?

bitmap

Bitmap

Bitmap to display in the button (optional).

Since
  3.1.1

pressed

Bitmap

Bitmap to show when the button is pressed (default: none, same as `bitmap`).

Since
  3.1.7

focus

Bitmap

Bitmap to show when the button has focus (default: none, same as `bitmap`).

Since
  3.1.7

disabled

Bitmap

Bitmap to show when the button is disabled (default: none, same as `bitmap`).

Since
  3.1.7

current

Bitmap

Bitmap to show when the mouse cursor hovers above the bitmap (default: none, same as `bitmap`).

Since
  3.1.7

margins

Size

Set the margins between the bitmap and the text of the button. This method is currently only implemented under MSW. If it is not called, a default margin is used around the bitmap.

Since
  3.1.7

bitmapposition

`wxLEFT|wxRIGHT|wxTOP|wxBOTTOM`

Position of the bitmap in the button, see wxButton::SetBitmapPosition() (default: wxLEFT).

Since
  3.1.1

### wxToolBar

property | type | description
--- | --- | ---
bitmapsize | Pair of integers | Size of toolbar bitmaps in pixels. Note that these are physical pixels, as they typically correspond to the size of available bitmaps, and not DIPs, i.e. not depending on the current DPI value. In particular, "d" suffix is invalid and cannot be used here (default: not set).
margins | Size | Margins (default: platform default).
packing | integer | Packing, see wxToolBar::SetToolPacking() (default: not set).
separation | integer | Default separator size, see wxToolBar::SetToolSeparation() (default: not set).
dontattachtoframe | Boolean | If set to 0 and the toolbar object is child of a wxFrame, wxFrame::SetToolBar() is called; otherwise, you have to add it to a frame manually. The toolbar is attached by default, you have to set this property to 1 to disable this behaviour (default: 0).

A toolbar can have one or more child objects of any wxControl-derived class or one of three pseudo-classes: `separator`, `space` or `tool`.

The `separator` pseudo-class is used to insert separators into the toolbar and has neither properties nor children. Similarly, the `space` pseudo-class is used for stretchable spaces (see wxToolBar::AddStretchableSpace(), new since wxWidgets 2.9.1).

The `tool` pseudo-class objects specify toolbar buttons and have the following properties:

property | type | description
--- | --- | ---
bitmap | Bitmap | Tool's bitmap (default: empty).
bitmap2 | Bitmap | Bitmap for disabled tool (default: derived from `bitmap`).
label | Text | Label to display on the tool (default: no label).
radio | Boolean | Item's kind is wxITEM_RADIO (default: 0)?
toggle | Boolean | Item's kind is wxITEM_CHECK (default: 0)?

dropdown

see below

Item's kind is wxITEM_DROPDOWN (default: 0)?

Since
  2.9.0

tooltip | Text | Tooltip to use for the tool (default: none).
longhelp | Text | Help text shown in statusbar when the mouse is on the tool (default: none).
disabled | Boolean | Is the tool initially disabled (default: 0)?

checked

Boolean

Is the tool initially checked (default: 0)?

Since
  2.9.3

The presence of a `dropdown` property indicates that the tool is of type wxITEM_DROPDOWN. It must be either empty or contain exactly one wxMenu child object defining the drop-down button associated menu.

Notice that `radio`, `toggle` and `dropdown` are mutually exclusive.

Children that are not `tool`, `space` or `separator` must be instances of classes derived from wxControl and are added to the toolbar using wxToolBar::AddControl().

Example:

<object class="wxToolBar">
<style>wxTB_FLAT|wxTB_NODIVIDER</style>
<object class="tool" name="foo">
<bitmap>foo.png</bitmap>
<label>Foo</label>
</object>
<object class="tool" name="bar">
<bitmap>bar.png</bitmap>
<label>Bar</label>
</object>
<object class="separator"/>
<object class="tool" name="view_auto">
<bitmap>view.png</bitmap>
<label>View</label>
<dropdown>
<object class="wxMenu">
<object class="wxMenuItem" name="view_as_text">
<label>View as text</label>
</object>
<object class="wxMenuItem" name="view_as_hex">
<label>View as binary</label>
</object>
</object>
</dropdown>
</object>
<object class="space"/>
<object class="wxComboBox">
<content>
<item>Just</item>
<item>a combobox</item>
<item>in the toolbar</item>
</content>
</object>
</object>
wxTB_FLAT
@ wxTB_FLAT
"flat" buttons (Win32/GTK only)
Definition: toolbar.h:28
wxTB_NODIVIDER
@ wxTB_NODIVIDER
don't show the divider between toolbar and the window (Win32 only)
Definition: toolbar.h:40

### wxToolbook

property | type | description
--- | --- | ---
imagelist | Image List | Image list to use for the images (default: none, built implicitly).

A toolbook can have one or more child objects of the `toolbookpage` pseudo-class (similarly to wxNotebook and its `notebookpage`).

`toolbookpage` objects have the following properties:

property | type | description
--- | --- | ---
label | Text | Sheet page's title (default: empty).
bitmap | Bitmap | Bitmap shown alongside the label (default: none, mutually exclusive with `image`).
image | integer | The zero-based index of the image associated with the item into the image list (default: none, mutually exclusive with `bitmap`, only if imagelist was set).
selected | Boolean | Is the page selected initially (only one page can be selected; default: 0)?

Each `toolbookpage` has exactly one non-toplevel window as its child.

### wxTreeCtrl

property | type | description
--- | --- | ---
imagelist | Image List | Image list to use for the images (default: none).

### wxTreebook

property | type | description
--- | --- | ---
imagelist | Image List | Image list to use for the images (default: none, built implicitly).

A treebook can have one or more child objects of the `treebookpage` pseudo-class (similarly to wxNotebook and its `notebookpage`).

`treebookpage` objects have the following properties:

property | type | description
--- | --- | ---
depth | integer | Page's depth in the labels tree (default: 0; see below).
label | Text | Sheet page's title (default: empty).
bitmap | Bitmap | Bitmap shown alongside the label (default: none, mutually exclusive with `image`).
image | integer | The zero-based index of the image associated with the item into the image list (default: none, mutually exclusive with `bitmap`, only if imagelist was set).
selected | Boolean | Is the page selected initially (only one page can be selected; default: 0)?
expanded | Boolean | If set to 1, the page is initially expanded. By default all pages are initially collapsed.

Each `treebookpage` has exactly one non-toplevel window as its child.

The tree of labels is not described using nested `treebookpage` objects, but using the depth property. Toplevel pages have depth 0, their child pages have depth 1 and so on. A `treebookpage's` label is inserted as child of the latest preceding page with depth equal to depth-1. For example, this XRC markup:

<object class="wxTreebook">
...
<object class="treebookpage">
<depth>0</depth>
<label>Page 1</label>
<object class="wxPanel">...</object>
</object>
<object class="treebookpage">
<depth>1</depth>
<label>Subpage 1A</label>
<object class="wxPanel">...</object>
</object>
<object class="treebookpage">
<depth>2</depth>
<label>Subsubpage 1</label>
<object class="wxPanel">...</object>
</object>
<object class="treebookpage">
<depth>1</depth>
<label>Subpage 1B</label>
<object class="wxPanel">...</object>
</object>
<object class="treebookpage">
<depth>2</depth>
<label>Subsubpage 2</label>
<object class="wxPanel">...</object>
</object>
<object class="treebookpage">
<depth>0</depth>
<label>Page 2</label>
<object class="wxPanel">...</object>
</object>
</object>

corresponds to the following tree of labels:

- Page 1
  - Subpage 1A
    - Subsubpage 1
  - Subpage 1B
    - Subsubpage 2
- Page 2

### wxWizard

property | type | description
--- | --- | ---
bitmap | Bitmap | Bitmap to display on the left side of the wizard (default: none).

border

integer

Sets width of border around page area. (default: 0).

Since
  3.2.0

bitmap-placement

Style

Sets the flags indicating how the wizard or page bitmap should be expanded and positioned to fit the page height. By default, placement is 0 (no expansion is done). See wxWizard::SetBitmapPlacement()

Since
  3.2.0

bitmap-minwidth

integer

Sets the minimum width for the bitmap that will be constructed to contain the actual wizard or page bitmap if a non-zero bitmap placement flag has been set.

Since
  3.2.0

bitmap-bg

Colour

Sets the colour that should be used to fill the area not taken up by the wizard or page bitmap, if a non-zero bitmap placement flag has been set.

Since
  3.2.0

A wizard object can have one or more child objects of the wxWizardPage or wxWizardPageSimple classes. They both support the following properties (in addition to Standard Properties):

property | type | description
--- | --- | ---
title | Text | Wizard window's title (default: none).
bitmap | Bitmap | Page-specific bitmap (default: none).

wxWizardPage and wxWizardPageSimple nodes may have optional children: either exactly one sizer child or any number of non-toplevel window objects.

wxWizardPageSimple pages are automatically chained together; wxWizardPage pages transitions must be handled programmatically.

# Sizers

Sizers are handled slightly differently in XRC resources than they are in wxWindow hierarchy. wxWindow's sizers hierarchy is parallel to the wxWindow children hierarchy: child windows are children of their parent window and the sizer (or sizers) form separate hierarchy attached to the window with wxWindow::SetSizer().

In XRC, the two hierarchies are merged together: sizers are children of other sizers or windows and they can contain child window objects.

If a sizer is child of a window object in the resource, it must be the only child and it will be attached to the parent with wxWindow::SetSizer(). Additionally, if the window doesn't have its size explicitly set, wxSizer::Fit() is used to resize the window. If the parent window is toplevel window, wxSizer::SetSizeHints() is called to set its hints.

A sizer object can have one or more child objects of one of two pseudo-classes: `sizeritem` or `spacer` (see wxStdDialogButtonSizer for an exception). The former specifies an element (another sizer or a window) to include in the sizer, the latter adds empty space to the sizer.

`sizeritem` objects have exactly one child object: either another sizer object, or a window object. `spacer` objects don't have any children, but they have one property:

property | type | description
--- | --- | ---
size | Size | Size of the empty space (default: `wxDefaultSize`).

Both `sizeritem` and `spacer` objects can have any of the following properties:

property | type | description
--- | --- | ---
option | integer | The "option" value for sizers. Used by wxBoxSizer to set proportion of the item in the growable direction (default: 0).
flag | Style | wxSizerItem flags (default: 0).
border | Dimension | Size of the border around the item (directions are specified in flags) (default: 0).
minsize | Size | Minimal size of this item (default: no min size).
ratio | Pair of integers | Item ratio, see wxSizerItem::SetRatio() (default: no ratio).
cellpos | Pair of integers | (wxGridBagSizer only) Position, see wxGBSizerItem::SetPos() (required).
cellspan | Pair of integers | (wxGridBagSizer only) Span, see wxGBSizerItem::SetSpan() (required).

Example of sizers XRC code:

<object class="wxDialog" name="derived_dialog">
<title>Derived Dialog Example</title>
<centered>1</centered>
<!-- this sizer is set to be this dialog's sizer: -->
<object class="wxFlexGridSizer">
<cols>1</cols>
<rows>0</rows>
<vgap>0</vgap>
<hgap>0</hgap>
<growablecols>0:1</growablecols>
<growablerows>0:1</growablerows>
<object class="sizeritem">
<flag>wxALIGN_CENTRE|wxALL</flag>
<border>5</border>
<object class="wxButton" name="my_button">
<label>My Button</label>
</object>
</object>
<object class="sizeritem">
<flag>wxALIGN_CENTRE|wxALL</flag>
<border>5</border>
<object class="wxBoxSizer">
<orient>wxHORIZONTAL</orient>
<object class="sizeritem">
<flag>wxALIGN_CENTRE|wxALL</flag>
<border>5</border>
<object class="wxCheckBox" name="my_checkbox">
<label>Enable this text control:</label>
</object>
</object>
<object class="sizeritem">
<flag>wxALIGN_CENTRE|wxALL</flag>
<border>5</border>
<object class="wxTextCtrl" name="my_textctrl">
<size>80,-1</size>
<value></value>
</object>
</object>
</object>
</object>
...
</object>
</object>

The sizer classes that can be used are listed below, together with their class-specific properties. All classes except wxStdDialogButtonSizer support the following properties:

property | type | description
--- | --- | ---
minsize | Size | Minimal size that this sizer will have, see wxSizer::SetMinSize() (default: no min size).
hideitems | Boolean | Whether the sizer will be created with all its items hidden (default: 0).

## wxBoxSizer

property | type | description
--- | --- | ---
orient | Style | Sizer orientation, "wxHORIZONTAL" or "wxVERTICAL" (default: wxHORIZONTAL).

## wxStaticBoxSizer

property | type | description
--- | --- | ---
orient | Style | Sizer orientation, "wxHORIZONTAL" or "wxVERTICAL" (default: wxHORIZONTAL).
label | Text | Label to be used for the static box around the sizer (default: empty).

windowlabel

any window

Window to be used instead of the plain text label (default: none).

Since
  3.1.1

## wxGridSizer

property | type | description
--- | --- | ---
rows | unsigned integer | Number of rows in the grid (default: 0 - determine automatically).
cols | unsigned integer | Number of columns in the grid (default: 0 - determine automatically).
vgap | Dimension | Vertical gap between children (default: 0).
hgap | Dimension | Horizontal gap between children (default: 0).

## wxFlexGridSizer

property | type | description
--- | --- | ---
rows | unsigned integer | Number of rows in the grid (default: 0 - determine automatically).
cols | unsigned integer | Number of columns in the grid (default: 0 - determine automatically).
vgap | Dimension | Vertical gap between children (default: 0).
hgap | Dimension | Horizontal gap between children (default: 0).

flexibledirection

Style

Flexible direction, `wxVERTICAL`, `wxHORIZONTAL` or `wxBOTH` (default).

Since
  2.9.5

nonflexiblegrowmode

Style

Grow mode in the non-flexible direction, `wxFLEX_GROWMODE_NONE`, `wxFLEX_GROWMODE_SPECIFIED` (default) or `wxFLEX_GROWMODE_ALL`.

Since
  2.9.5

growablerows | comma-separated integers list | Comma-separated list of indexes of rows that are growable (none by default). Since wxWidgets 2.9.5 optional proportion can be appended to each number after a colon (``:).
growablecols | comma-separated integers list | Comma-separated list of indexes of columns that are growable (none by default). Since wxWidgets 2.9.5 optional proportion can be appended to each number after a colon (``:).

## wxGridBagSizer

property | type | description
--- | --- | ---
vgap | Dimension | Vertical gap between children (default: 0).
hgap | Dimension | Horizontal gap between children (default: 0).
flexibledirection | Style | Flexible direction, `wxVERTICAL`, `wxHORIZONTAL`, `wxBOTH` (default: `wxBOTH`).
nonflexiblegrowmode | Style | Grow mode in the non-flexible direction, `wxFLEX_GROWMODE_NONE`, `wxFLEX_GROWMODE_SPECIFIED`, `wxFLEX_GROWMODE_ALL` (default: `wxFLEX_GROWMODE_SPECIFIED`).
growablerows | comma-separated integers list | Comma-separated list of indexes of rows that are growable, optionally the proportion can be appended after each number separated by a ``: (default: none).
growablecols | comma-separated integers list | Comma-separated list of indexes of columns that are growable, optionally the proportion can be appended after each number separated by a ``: (default: none).

empty_cellsize

Size

Size used for cells in the grid with no item. (default: `wxDefaultSize`).

Since
  3.2.0

## wxWrapSizer

property | type | description
--- | --- | ---
orient | Style | Sizer orientation, "wxHORIZONTAL" or "wxVERTICAL" (default: wxHORIZONTAL).
flag | Style | wxWrapSizer flags (default: 0).

## wxStdDialogButtonSizer

Unlike other sizers, wxStdDialogButtonSizer has neither `sizeritem` nor `spacer` children. Instead, it has one or more children of the `button` pseudo-class. `button` objects have no properties and they must always have exactly one child of the `wxButton` class or a class derived from wxButton.

Example:

<object class="wxStdDialogButtonSizer">
<object class="button">
<object class="wxButton" name="wxID_OK">
<label>OK</label>
</object>
</object>
<object class="button">
<object class="wxButton" name="wxID_CANCEL">
<label>Cancel</label>
</object>
</object>
</object>

# Other Objects

In addition to describing UI elements, XRC files can contain non-windows objects such as bitmaps or icons. This is a concession to Windows developers used to storing them in Win32 resources.

Note that unlike Win32 resources, bitmaps included in XRC files are not embedded in the XRC file itself. XRC file only contains a reference to another file with bitmap data.

## wxBitmap

Bitmaps are stored in `<object>` element with class set to `wxBitmap`. Such bitmaps can then be loaded using wxXmlResource::LoadBitmap(). The content of the element is exactly same as in the case of bitmap properties, except that toplevel `<object>` is used.

For example, instead of:

<bitmap>mybmp.png</bitmap>
<bitmap stock_id="wxART_NEW"/>

toplevel wxBitmap resources would look like:

<object class="wxBitmap" name="my_bitmap">mybmp.png</object>
<object class="wxBitmap" name="my_new_bitmap" stock_id="wxART_NEW"/>

## wxIcon

wxIcon resources are identical to wxBitmap ones, except that the class is `wxIcon`.

# Platform Specific Content

It is possible to conditionally process parts of XRC files on some platforms only and ignore them on other platforms. Any element in XRC file, be it toplevel or arbitrarily nested one, can have the `platform` attribute. When used, `platform` contains |-separated list of platforms that this element should be processed on. It is filtered out and ignored on any other platforms.

Possible elemental values are:

`msw` | Windows, preferred platform name
`win` | Windows, alternative synonym
`mac` | macOS or iOS
`unix` | Any Unix platform except macOS

Examples:

<label platform="msw">Windows</label>
<label platform="unix">Unix</label>
<label platform="mac">macOS</label>
<help platform="mac|unix">Not a Windows machine</help>

# ID Ranges

Usually you won't care what value the XRCID macro returns for the ID of an object. Sometimes though it is convenient to have a range of IDs that are guaranteed to be consecutive. An example of this would be connecting a group of similar controls to the same event handler.

The following XRC fragment 'declares' an ID range called foo and another called bar; each with some items.

<object class="wxButton" name="foo[start]">
<object class="wxButton" name="foo[end]">
<object class="wxButton" name="foo[2]">
...
<object class="wxButton" name="bar[0]">
<object class="wxButton" name="bar[2]">
<object class="wxButton" name="bar[1]">
...
<ids-range name="foo" />
<ids-range name="bar" size="30" start="10000" />

For the range foo, no size or start parameters were given, so the size will be calculated from the number of range items, and IDs allocated by wxWindow::NewControlId (so they'll be negative). Range bar asked for a size of 30, so this will be its minimum size: should it have more items, the range will automatically expand to fit them. It specified a start ID of 10000, so XRCID("bar[0]") will be 10000, XRCID("bar[1]") 10001 etc. Note that if you choose to supply a start value it must be positive, and it's your responsibility to avoid clashes.

For every ID range, the first item can be referenced either as rangename[0] or rangename[start]. Similarly rangename[end] is the last item. Using [start] and [end] is more descriptive in e.g. a Bind() event range or a for loop, and they don't have to be altered whenever the number of items changes.

Whether a range has positive or negative IDs, [start] is always a smaller number than [end]; so code like this works as expected:

for (int n=XRCID("foo[start]"); n <= XRCID("foo[end]"); ++n)
...

ID ranges can be seen in action in the objref dialog section of the XRC Sample.

Note
  - All the items in an ID range must be contained in the same XRC file.
  - You can't use an ID range in a situation where static initialisation occurs; in particular, they won't work as expected in an event table. This is because the event table's IDs are set to their integer values before the XRC file is loaded, and aren't subsequently altered when the XRCID value changes.

Since
  2.9.2

# Extending the XRC Format

The XRC format is designed to be extensible and allows specifying and loading custom controls. The three available mechanisms are described in the rest of this section in the order of increasing complexity.

## Subclassing

The simplest way to add custom controls is to set the `subclass` attribute of `<object>` element:

<object name="my_value" class="wxTextCtrl" subclass="MyTextCtrl">
<style>wxTE_MULTILINE</style>
...etc., setup wxTextCtrl as usual...
</object>
wxTextCtrl
A text control allows text to be displayed and edited.
Definition: textctrl.h:1436
wxTE_MULTILINE
#define wxTE_MULTILINE
Definition: textctrl.h:14

In that case, wxXmlResource will create an instance of the specified subclass (`MyTextCtrl` in the example above) instead of the class (`wxTextCtrl` above) when loading the resource. However, the rest of the object's loading (calling its Create() method, setting its properties, loading any children etc.) will proceed in exactly the same way as it would without `subclass` attribute. In other words, this approach is only sufficient when the custom class is just a small modification (e.g. overridden methods or customized events handling) of an already supported classes.

The subclass must satisfy a number of requirements:

1. It must be derived from the class specified in `class` attribute.
2. It must be visible in wxWidget's pseudo-RTTI mechanism, i.e. there must be a wxDECLARE_DYNAMIC_CLASS() entry for it.
3. It must support two-phase creation. In particular, this means that it has to have default constructor.
4. It cannot provide custom Create() method and must be constructible using base `class'` Create() method (this is because XRC will call Create() of `class`, not `subclass`). In other words, creation of the control must not be customized.

## Unknown Objects

A more flexible solution is to put a placeholder in the XRC file and replace it with custom control after the resource is loaded. This is done by using the `unknown` pseudo-class:

<object class="unknown" name="my_placeholder"/>

The placeholder is inserted as dummy wxPanel that will hold custom control in it. At runtime, after the resource is loaded and a window created from it (using e.g. wxXmlResource::LoadDialog()), use code must call wxXmlResource::AttachUnknownControl() to insert the desired control into placeholder container.

This method makes it possible to insert controls that are not known to XRC at all, but it's also impossible to configure the control in XRC description in any way. The only properties that can be specified are the standard window properties.

Note
  `unknown` class cannot be combined with `subclass` attribute, they are mutually exclusive.

## Adding Custom Classes

Finally, XRC allows adding completely new classes in addition to the ones listed in this document. A class for which wxXmlResourceHandler is implemented can be used as first-class object in XRC simply by passing class name as the value of `class` attribute:

<object name="my_ctrl" class="MyWidget">
<my_prop>foo</my_prop>
...etc., whatever MyWidget handler accepts...
</object>

The only requirements on the class are that

1. the class must derive from wxObject
2. it must support wxWidget's pseudo-RTTI mechanism

Child elements of `<object>` are handled by the custom handler and there are no limitations on them imposed by XRC format.

This is the only mechanism that works for toplevel objects – custom controls are accessible using the type-unsafe wxXmlResource::LoadObject() method.

# Packed XRC Files

In addition to plain XRC files, wxXmlResource supports (if wxFileSystem support is compiled in) compressed XRC resources. Compressed resources have either .zip or .xrs extension and are simply ZIP files that contain arbitrary number of XRC files and their dependencies (bitmaps, icons etc.).

# Older Format Versions

This section describes differences in older revisions of XRC format (i.e. files with older values of `version` attribute of `<resource>`).

## Versions Before 2.5.3.0

Version 2.5.3.0 introduced C-like handling of "\\" in text. In older versions, "\n", "\t" and "\r" escape sequences were replaced with respective characters in the same matter as it's done in C, but "\\" was left intact instead of being replaced with a single "\", as one would expect. Starting with 2.5.3.0, all of them are handled in C-like manner.

## Versions Before 2.3.0.1

Prior to version 2.3.0.1, "$" was used for accelerators instead of "_" or "&amp;". For example,

<label>$File</label>

was used in place of current version's

<label>_File</label>

(or "&amp;File").