X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/41e69d79eaf36c46ed33d198ad094069d10e5ade..c602c59b6e623d7775c16ce6412b64b34dc5dd94:/docs/doxygen/overviews/xrc_format.h?ds=sidebyside diff --git a/docs/doxygen/overviews/xrc_format.h b/docs/doxygen/overviews/xrc_format.h index 6c84ce38ac..00adb8849b 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 @@ -135,7 +136,7 @@ These come in two varieties: -# Object's properties. A @em 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 - (""), but they may use nested subelements too (e.g. + ("\Cancel\"), but they may use nested subelements too (e.g. @ref overview_xrcformat_type_font "font property"). A property can only be listed once in an object's definition. -# Child objects. Window childs, sizers, sizer items or notebook pages @@ -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 @@ -481,8 +482,14 @@ from properties lists below. (default: not set).} @row3col{fg, @ref overview_xrcformat_type_colour, Foreground colour of the window (default: window's default).} +@row3col{ownfg, @ref overview_xrcformat_type_colour, + Non-inheritable foreground colour of the window, see + wxWindow::SetOwnForegroundColour() (default: none).} @row3col{bg, @ref overview_xrcformat_type_colour, Background colour of the window (default: window's default).} +@row3col{ownbg, @ref overview_xrcformat_type_colour, + Non-inheritable background colour of the window, see + wxWindow::SetOwnBackgroundColour() (default: none).} @row3col{enabled, @ref overview_xrcformat_type_bool, If set to 0, the control is disabled (default: 1).} @row3col{hidden, @ref overview_xrcformat_type_bool, @@ -491,6 +498,9 @@ from properties lists below. Tooltip to use for the control (default: not set).} @row3col{font, @ref overview_xrcformat_type_font, Font to use for the control (default: window's default).} +@row3col{ownfont, @ref overview_xrcformat_type_font, + Non-inheritable font to use for the control, see + wxWindow::SetOwnFont() (default: none).} @row3col{help, @ref overview_xrcformat_type_text, Context-sensitive help for the control, used by wxHelpProvider (default: not set).} @@ -499,7 +509,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, @@ -580,9 +590,13 @@ Example: @beginTable @hdr3col{property, type, description} @row3col{label, @ref overview_xrcformat_type_text, - Label to display on the button (required).} + Label to display on the button (may be empty if only bitmap is used).} +@row3col{bitmap, @ref overview_xrcformat_type_bitmap, + Bitmap to display in the button (optional).} +@row3col{bitmapposition, @c wxLEFT|wxRIGHT|wxTOP|wxBOTTOM, + Position of the bitmap in the button, see wxButton::SetBitmapPosition().} @row3col{default, @ref overview_xrcformat_type_bool, - Should this button be the default button in dialog (default: 0)?} + Should this button be the default button in dialog (default: 0)?} @endTable @@ -606,7 +620,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 +650,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).} @@ -659,11 +673,10 @@ Example: @subsubsection xrc_wxchoicebook wxChoicebook -No additional properties. - A choicebook can have one or more child objects of the @c choicebookpage pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its -@c notebookpage). @c choicebookpage objects have the following properties: +@c notebookpage) and one child object of the @ref xrc_wximagelist class. +@c choicebookpage objects have the following properties: @beginTable @hdr3col{property, type, description} @@ -671,6 +684,9 @@ pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its Sheet page's title (required).} @row3col{bitmap, @ref overview_xrcformat_type_bitmap, Bitmap shown alongside the label (default: none).} +@row3col{image, integer, + The zero-based index of the image associated with the item + into the image list.} @row3col{selected, @ref overview_xrcformat_type_bool, Is the page selected initially (only one page can be selected; default: 0)?} @endTable @@ -709,7 +725,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).} @@ -768,6 +784,20 @@ objects. If sizer child is used, it sets @endTable +@subsubsection xrc_wxfilectrl wxFileCtrl + +@beginTable +@hdr3col{property, type, description} +@row3col{defaultdirectory, @ref overview_xrcformat_type_string, + Sets the current directory displayed in the control. } +@row3col{defaultfilename, @ref overview_xrcformat_type_string, + Selects a certain file.} +@row3col{wildcard, @ref overview_xrcformat_type_string, + Sets the wildcard, which can contain multiple file types, for example: + "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif".} +@endTable + + @subsubsection xrc_wxfilepickerctrl wxFilePickerCtrl @beginTable @@ -777,7 +807,8 @@ objects. If sizer child is used, it sets @row3col{message, @ref overview_xrcformat_type_text, Message shown to the user in wxDirDialog shown by the control (required).} @row3col{wildcard, @ref overview_xrcformat_type_string, - Message shown to the user in wxDirDialog shown by the control (required).} + Sets the wildcard, which can contain multiple file types, for example: + "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif".} @endTable @@ -867,13 +898,49 @@ page. @endTable +@subsubsection xrc_wximagelist wxImageList + +The imagelist can be used as a child object for the following classes: + - @ref xrc_wxchoicebook + - @ref xrc_wxlistbook + - @ref xrc_wxlistctrl + - @ref xrc_wxnotebook + - @ref xrc_wxtreebook + - @ref xrc_wxtreectrl + +The available properties are: + +@beginTable +@hdr3col{property, type, description} +@row3col{bitmap, @ref overview_xrcformat_type_bitmap, + Adds a new image by keeping its optional mask bitmap (see below).} +@row3col{mask, @ref overview_xrcformat_type_bool, + If masks should be created for all images (default: true).} +@row3col{size, @ref overview_xrcformat_type_size, + The size of the images in the list (default: system default icon size)).} +@endTable + +Example: +@code + + 32,32 + + + +@endcode + +In the specific case of the @ref xrc_wxlistctrl, the tag can take the name +@c \ to define the 'small' image list, related to the flag +@c wxIMAGE_LIST_SMALL (see wxListCtrl documentation). + + @subsubsection xrc_wxlistbox wxListBox @beginTable @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).} @@ -897,11 +964,10 @@ Example: @subsubsection xrc_wxlistbook wxListbook -No additional properties. - A listbook can have one or more child objects of the @c listbookpage pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its -@c notebookpage). @c listbookpage objects have the following properties: +@c notebookpage) and one child object of the @ref xrc_wximagelist class. +@c listbookpage objects have the following properties: @beginTable @hdr3col{property, type, description} @@ -909,6 +975,9 @@ pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its Sheet page's title (required).} @row3col{bitmap, @ref overview_xrcformat_type_bitmap, Bitmap shown alongside the label (default: none).} +@row3col{image, integer, + The zero-based index of the image associated with the item + into the image list.} @row3col{selected, @ref overview_xrcformat_type_bool, Is the page selected initially (only one page can be selected; default: 0)?} @endTable @@ -918,7 +987,83 @@ Each @c listbookpage has exactly one non-toplevel window as its child. @subsubsection xrc_wxlistctrl wxListCtrl -No additional properties. +A list control can have one or more child objects of the class @ref xrc_wxlistitem +and one or more objects of the @ref xrc_wximagelist class. The latter is +defined either using @c \ tag for the control with @c wxLC_ICON +style or using @c \ tag for the control with @c +wxLC_SMALL_ICON style. + +Report mode list controls (i.e. created with @c wxLC_REPORT style) can in +addition have one or more @ref xrc_wxlistcol child elements. + +@paragraph xrc_wxlistcol listcol + +The @c listcol class can only be used for wxListCtrl children. It can have the +following properties: +@beginTable +@hdr3col{property, type, description} +@row3col{align, wxListColumnFormat, + The alignment for the item. + Can be one of @c wxLIST_FORMAT_LEFT, @c wxLIST_FORMAT_RIGHT or + @c wxLIST_FORMAT_CENTRE.} +@row3col{text, @ref overview_xrcformat_type_string, + The title of the column. } +@row3col{width, integer, + The column width. } +@endTable + +The columns are appended to the control in order of their appearance and may be +referenced by 0-based index in the @c col attributes of subsequent @c listitem +objects. + +@paragraph xrc_wxlistitem listitem + +The @c listitem is a child object for the class @ref xrc_wxlistctrl. +It can have the following properties: + +@beginTable +@hdr3col{property, type, description} +@row3col{align, wxListColumnFormat, + The alignment for the item. + Can be one of @c wxLIST_FORMAT_LEFT, @c wxLIST_FORMAT_RIGHT or + @c wxLIST_FORMAT_CENTRE.} +@row3col{bg, @ref overview_xrcformat_type_colour, + The background color for the item.} +@row3col{bitmap, @ref overview_xrcformat_type_bitmap, + Add a bitmap to the (normal) @ref xrc_wximagelist associated with the + @ref xrc_wxlistctrl parent and associate it with this item. + If the imagelist is not defined it will be created implicitly.} +@row3col{bitmap-small, @ref overview_xrcformat_type_bitmap, + Add a bitmap in the 'small' @ref xrc_wximagelist associated with the + @ref xrc_wxlistctrl parent and associate it with this item. + If the 'small' imagelist is not defined it will be created implicitly.} +@row3col{col, integer, + The zero-based column index.} +@row3col{image, integer, + The zero-based index of the image associated with the item + in the (normal) image list.} +@row3col{image-small, integer, + The zero-based index of the image associated with the item + in the 'small' image list.} +@row3col{data, integer, + The client data for the item.} +@row3col{font, @ref overview_xrcformat_type_font, + The font for the item.} +@row3col{image, integer, + The zero-based index of the image associated with the item + into the image list.} +@row3col{state, @ref overview_xrcformat_type_style, + The item state. Can be any combination of the following values: + - @c wxLIST_STATE_FOCUSED: The item has the focus. + - @c wxLIST_STATE_SELECTED: The item is selected.} +@row3col{text, @ref overview_xrcformat_type_string, + The text label for the item. } +@row3col{textcolour, @ref overview_xrcformat_type_colour, + The text colour for the item. } +@endTable + +Notice that the item position can't be specified here, the items are appended +to the list control in order of their appearance. @subsubsection xrc_wxmdiparentframe wxMDIParentFrame @@ -1029,10 +1174,9 @@ class. @subsubsection xrc_wxnotebook wxNotebook -No additional properties. - A notebook can have one or more child objects of the @c notebookpage -pseudo-class. @c notebookpage objects have the following properties: +pseudo-class and one child object of the @ref xrc_wximagelist class. +@c notebookpage objects have the following properties: @beginTable @hdr3col{property, type, description} @@ -1040,6 +1184,9 @@ pseudo-class. @c notebookpage objects have the following properties: Page's title (required).} @row3col{bitmap, @ref overview_xrcformat_type_bitmap, Bitmap shown alongside the label (default: none).} +@row3col{image, integer, + The zero-based index of the image associated with the item + into the image list.} @row3col{selected, @ref overview_xrcformat_type_bool, Is the page selected initially (only one page can be selected; default: 0)?} @endTable @@ -1142,7 +1289,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).} @@ -1309,7 +1456,7 @@ wxSpinCtrl supports the properties as @ref xrc_wxspinbutton. Initial position of the sash (default: 0).} @row3col{minsize, integer, Minimum child size (default: not set).} -@row3col{minsize, @ref overview_xrcformat_type_float, +@row3col{gravity, @ref overview_xrcformat_type_float, Sash gravity, see wxSplitterWindow::SetSashGravity() (default: not set).} @endTable @@ -1375,7 +1522,7 @@ No additional properties. @row3col{label, @ref overview_xrcformat_type_text, Label to display (required).} @row3col{wrap, integer, - Number of characters per line to wrap the text for, see + Wrap the text so that each line is at most the given number of pixels, see wxStaticText::Wrap() (default: no wrap).} @endTable @@ -1440,6 +1587,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 +1597,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 +1619,20 @@ Example: bar.png + + view.png + + + + + + + + + + + + @@ -1481,16 +1648,17 @@ Example: @subsubsection xrc_wxtreectrl wxTreeCtrl +A treectrl can have one child object of the @ref xrc_wximagelist class. + No additional properties. @subsubsection xrc_wxtreebook wxTreebook -No additional properties. - A treebook can have one or more child objects of the @c treebookpage pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its -@c notebookpage). @c treebookpage objects have the following properties: +@c notebookpage) and one child object of the @ref xrc_wximagelist class. +@c treebookpage objects have the following properties: @beginTable @hdr3col{property, type, description} @@ -1500,6 +1668,9 @@ pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its Sheet page's title (required).} @row3col{bitmap, @ref overview_xrcformat_type_bitmap, Bitmap shown alongside the label (default: none).} +@row3col{image, integer, + The zero-based index of the image associated with the item + into the image list.} @row3col{selected, @ref overview_xrcformat_type_bool, Is the page selected initially (only one page can be selected; default: 0)?} @endTable @@ -1713,8 +1884,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 +1894,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 +1955,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 +1991,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 +2017,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 +2057,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 +2082,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 +2108,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 +2117,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 +2132,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,