/*
- NOTE: to make doxygen happy about <custom-tags> we're forced to
- escape all < and > symbols which appear inside a doxygen comment
+ NOTE: To make doxygen happy about <custom-tags> we're forced to
+ escape all < and > symbols which appear inside a doxygen comment.
+ Also, don't use < and > symbols in section titles.
*/
/**
-@page overview_xrcformat XRC file format
+@page overview_xrcformat XRC File Format
Table of contents:
-@li @ref overview_xrcformat_overview
-@li @ref overview_xrcformat_root
-@li @ref overview_xrcformat_objects
- @li @ref overview_xrcformat_object
- @li @ref overview_xrcformat_object_ref
-@li @ref overview_xrcformat_datatypes
-@li @ref overview_xrcformat_windows
- @li @ref overview_xrcformat_std_props
- @li @ref overview_xrcformat_controls
-@li @ref overview_xrcformat_sizers
-@li @ref overview_xrcformat_other_objects
-@li @ref overview_xrcformat_platform
-@li @ref overview_xrcformat_extending
- @li @ref overview_xrcformat_extending_subclass
- @li @ref overview_xrcformat_extending_unknown
- @li @ref overview_xrcformat_extending_custom
-@li @ref overview_xrcformat_packed
-@li @ref overview_xrcformat_oldversions
+- @ref overview_xrcformat_overview
+- @ref overview_xrcformat_root
+- @ref overview_xrcformat_objects
+ - @ref overview_xrcformat_object
+ - @ref overview_xrcformat_object_ref
+- @ref overview_xrcformat_datatypes
+- @ref overview_xrcformat_windows
+ - @ref overview_xrcformat_std_props
+ - @ref overview_xrcformat_controls
+- @ref overview_xrcformat_sizers
+- @ref overview_xrcformat_other_objects
+- @ref overview_xrcformat_platform
+- @ref overview_xrcformat_extending
+ - @ref overview_xrcformat_extending_subclass
+ - @ref overview_xrcformat_extending_unknown
+ - @ref overview_xrcformat_extending_custom
+- @ref overview_xrcformat_packed
+- @ref overview_xrcformat_oldversions
This document describes the format of XRC resource files, as used by wxXmlResource.
be accessed using XRCCTRL().
-@section overview_xrcformat_root Root element: \<resource\>
+@section overview_xrcformat_root Resource Root Element
The root element is always @c \<resource\>. It has one optional attribute, @c
version. If set, it specifies version of the file. In absence of @c version
-@section overview_xrcformat_objects Defining objects
+@section overview_xrcformat_objects Defining Objects
-@subsection overview_xrcformat_object \<object\>
+@subsection overview_xrcformat_object Object Element
The @c \<object\> element represents a single object (typically a GUI element)
and it usually maps directly to a wxWidgets class instance. It has one
@endcode
-@subsection overview_xrcformat_object_ref \<object_ref\>
+@subsection overview_xrcformat_object_ref Object References
Anywhere an @c \<object\> element can be used, @c \<object_ref\> may be used
instead. @c \<object_ref\> is a @em reference to another named (i.e. with the
@endcode
-@section overview_xrcformat_datatypes Data types
+@section overview_xrcformat_datatypes Data Types
There are several property data types that are frequently reused by different
properties. Rather than describing their format in the documentation of
@see @ref overview_xrcformat_pre_v2530, @ref overview_xrcformat_pre_v2301
-@subsection overview_xrcformat_type_text_notrans Non-translatable text
+@subsection overview_xrcformat_type_text_notrans Non-Translatable Text
Like @ref overview_xrcformat_type_text, but the text is never translated and
@c translate attribute cannot be used.
-@subsection overview_xrcformat_type_string URL
+@subsection overview_xrcformat_type_string String
An unformatted string. Unlike with @ref overview_xrcformat_type_text, no escaping
or translations are done.
@endcode
-@section overview_xrcformat_windows Controls and windows
+@section overview_xrcformat_windows Controls and Windows
This section describes support wxWindow-derived classes in XRC format.
-@subsection overview_xrcformat_std_props Standard properties
+@subsection overview_xrcformat_std_props Standard Properties
The following properties are always (unless stated otherwise in
control-specific docs) available for @em windows objects. They are omitted
All of these properties are optional.
-@subsection overview_xrcformat_controls Supported controls
+@subsection overview_xrcformat_controls 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,
@beginTable
@hdr3col{property, type, description}
-@row3col{content, ,
+@row3col{content, items,
Content of the control; this property has any number of @c \<item\> XML
elements as its children, with the items text as their text values
(default: empty).}
@hdr3col{property, type, description}
@row3col{selection, integer,
Index of the initially selected item or -1 for no selection (default: -1).}
-@row3col{content, ,
+@row3col{content, items,
Content of the control; this property has any number of @c \<item\> XML
elements as its children, with the items text as their text values
(default: empty).}
@hdr3col{property, type, description}
@row3col{selection, integer,
Index of the initially selected item or -1 for no selection (default: not used).}
-@row3col{content, ,
+@row3col{content, items,
Content of the control; this property has any number of @c \<item\> XML
elements as its children, with the items text as their text values
(default: empty).}
@hdr3col{property, type, description}
@row3col{selection, integer,
Index of the initially selected item or -1 for no selection (default: -1).}
-@row3col{content, ,
+@row3col{content, items,
Content of the control; this property has any number of @c \<item\> XML
elements as its children, with the items text as their text values
(default: empty).}
for a two-dimensional radiobox (default: 1).}
@row3col{selection, integer,
Index of the initially selected item or -1 for no selection (default: -1).}
-@row3col{content, ,
+@row3col{content, items,
Content of the control; this property has any number of @c \<item\> XML
elements as its children, with the items text as their text values
(see below; default: empty).}
Item's kind is wxITEM_RADIO (default: 0)?}
@row3col{toggle, @ref overview_xrcformat_type_bool,
Item's kind is wxITEM_CHECK (default: 0)?}
+@row3col{dropdown, see below,
+ Item's kind is wxITEM_DROPDOWN (default: 0)? (only available since wxWidgets 2.9.0)}
@row3col{tooltip, @ref overview_xrcformat_type_text,
Tooltip to use for the tool (default: none).}
@row3col{longhelp, @ref overview_xrcformat_type_text,
Is the tool initially disabled (default: 0)?}
@endTable
-@c radio and @c toggle are mutually exclusive.
+The presence of a @c dropdown property indicates that the tool is of type
+wxITEM_DROPDOWN. It must be either empty or contain exactly one @ref
+xrc_wxmenu child object defining the drop-down button associated menu.
+
+Notice that @c radio, @c toggle and @c dropdown are mutually exclusive.
Children that are neither @c tool nor @c separator must be instances of classes
derived from wxControl and are added to the toolbar using
<bitmap>bar.png</bitmap>
<label>Bar</label>
</object>
+ <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="separator"/>
<object class="wxComboBox">
<content>
@beginTable
@hdr3col{property, type, description}
-@row3col{rows, integer, Number of rows in the grid (required).}
-@row3col{cols, integer, Number of columns in the grid (required).}
+@row3col{rows, integer, Number of rows in the grid (default: 0 - determine automatically).}
+@row3col{cols, integer, Number of columns in the grid (default: 0 - determine automatically).}
@row3col{vgap, integer, Vertical gap between children (default: 0).}
@row3col{hgap, integer, Horizontal gap between children (default: 0).}
@endTable
@beginTable
@hdr3col{property, type, description}
-@row3col{rows, integer, Number of rows in the grid (required).}
-@row3col{cols, integer, Number of columns in the grid (required).}
+@row3col{rows, integer, Number of rows in the grid (default: 0 - determine automatically).}
+@row3col{cols, integer, Number of columns in the grid (default: 0 - determine automatically).}
@row3col{vgap, integer, Vertical gap between children (default: 0).}
@row3col{hgap, integer, Horizontal gap between children (default: 0).}
@row3col{growablerows, comma-separated integers list,
-@section overview_xrcformat_other_objects Other objects
+@section overview_xrcformat_other_objects 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
except that the class is @c wxIcon.
-@section overview_xrcformat_platform Platform specific content
+@section overview_xrcformat_platform Platform Specific Content
It is possible to conditionally process parts of XRC files on some platforms
only and ignore them on other platforms. @em Any element in XRC file, be it
-@section overview_xrcformat_extending Extending XRC format
+@section overview_xrcformat_extending 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
must not be customized.
-@subsection overview_xrcformat_extending_unknown \<object class="unknown"\>
+@subsection overview_xrcformat_extending_unknown Unknown Objects
A more flexible solution is to put a @em placeholder in the XRC file and
replace it with custom control after the resource is loaded. This is done by
they are mutually exclusive.
-@subsection overview_xrcformat_extending_custom Adding custom classes
+@subsection overview_xrcformat_extending_custom 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
-@section overview_xrcformat_packed Packed XRC files
+@section overview_xrcformat_packed Packed XRC Files
In addition to plain XRC files, wxXmlResource supports (if wxFileSystem support
is compiled in) compressed XRC resources. Compressed resources have either
-@section overview_xrcformat_oldversions Older format versions
+@section overview_xrcformat_oldversions Older Format Versions
This section describes differences in older revisions of XRC format (i.e.
files with older values of @c version attribute of @c \<resource\>).
-@subsection overview_xrcformat_pre_v2530 Versions before 2.5.3.0
+@subsection overview_xrcformat_pre_v2530 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
them are handled in C-like manner.
-@subsection overview_xrcformat_pre_v2301 Versions before 2.3.0.1
+@subsection overview_xrcformat_pre_v2301 Versions Before 2.3.0.1
Prior to version 2.3.0.1, "$" was used for accelerators instead of "_"
or "&". For example,
projects / wxWidgets.git / blobdiff