X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/41e69d79eaf36c46ed33d198ad094069d10e5ade..a5e1215946b192b269d0286b050b04709fd6b980:/docs/doxygen/overviews/xrc_format.h diff --git a/docs/doxygen/overviews/xrc_format.h b/docs/doxygen/overviews/xrc_format.h index 6c84ce38ac..28845bfd4a 100644 --- a/docs/doxygen/overviews/xrc_format.h +++ b/docs/doxygen/overviews/xrc_format.h @@ -8,34 +8,35 @@ /* - NOTE: to make doxygen happy about we're forced to - escape all < and > symbols which appear inside a doxygen comment + NOTE: To make doxygen happy about 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. @@ -64,7 +65,7 @@ Child objects are not directly accessible via wxXmlResource, they can only be accessed using XRCCTRL(). -@section overview_xrcformat_root Root element: \ +@section overview_xrcformat_root Resource Root Element The root element is always @c \. It has one optional attribute, @c version. If set, it specifies version of the file. In absence of @c version @@ -97,9 +98,9 @@ set and it must be set to a value unique among root's children. -@section overview_xrcformat_objects Defining objects +@section overview_xrcformat_objects Defining Objects -@subsection overview_xrcformat_object \ +@subsection overview_xrcformat_object Object Element The @c \ element represents a single object (typically a GUI element) and it usually maps directly to a wxWidgets class instance. It has one @@ -161,7 +162,7 @@ Example: @endcode -@subsection overview_xrcformat_object_ref \ +@subsection overview_xrcformat_object_ref Object References Anywhere an @c \ element can be used, @c \ may be used instead. @c \ is a @em reference to another named (i.e. with the @@ -224,7 +225,7 @@ is identical to: @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 @@ -327,13 +328,13 @@ attribute on the property node to "0": @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. @@ -455,11 +456,11 @@ Examples: @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 @@ -499,7 +500,7 @@ from properties lists below. 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, @@ -606,7 +607,7 @@ No additional properties. @beginTable @hdr3col{property, type, description} -@row3col{content, , +@row3col{content, items, Content of the control; this property has any number of @c \ XML elements as its children, with the items text as their text values (default: empty).} @@ -636,7 +637,7 @@ Example: @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 \ XML elements as its children, with the items text as their text values (default: empty).} @@ -709,7 +710,7 @@ object. @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 \ XML elements as its children, with the items text as their text values (default: empty).} @@ -873,7 +874,7 @@ page. @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 \ XML elements as its children, with the items text as their text values (default: empty).} @@ -1142,7 +1143,7 @@ Each @c propertysheetpage has exactly one non-toplevel window as its child. 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 \ XML elements as its children, with the items text as their text values (see below; default: empty).} @@ -1440,6 +1441,8 @@ properties: 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, @@ -1448,7 +1451,11 @@ properties: 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 @@ -1466,6 +1473,20 @@ Example: bar.png + + view.png + + + + + + + + + + + + @@ -1713,8 +1734,8 @@ class-specific properties. All classes support the following properties: @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 @@ -1723,8 +1744,8 @@ class-specific properties. All classes support the following properties: @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, @@ -1784,7 +1805,7 @@ Example: -@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 @@ -1820,7 +1841,7 @@ wxIcon resources are identical to @ref overview_xrcformat_bitmap "wxBitmap ones" 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 @@ -1846,7 +1867,7 @@ Examples: -@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 @@ -1886,7 +1907,7 @@ The subclass must satisfy a number of requirements: must not be customized. -@subsection overview_xrcformat_extending_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 @@ -1911,7 +1932,7 @@ the @ref overview_xrcformat_std_props "standard window properties". 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 @@ -1937,7 +1958,7 @@ are accessible using type-unsafe wxXmlResource::LoadObject() method. -@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 @@ -1946,13 +1967,13 @@ number of XRC files and their dependencies (bitmaps, icons etc.). -@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 \). -@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 @@ -1961,7 +1982,7 @@ replaced with single "\", as one would expect. Starting with 2.5.3.0, all of 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,