// Purpose: XRC format specification
// Author: Vaclav Slavik
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
@page overview_xrcformat XRC File Format
-Table of contents:
-- @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
+@tableofcontents
-This document describes the format of XRC resource files, as used by wxXmlResource.
-
-
-<hr>
-
-
-@section overview_xrcformat_overview Overview
+This document describes the format of XRC resource files, as used by
+wxXmlResource.
XRC file is a XML file with all of its elements in the
@c http://www.wxwidgets.org/wxxrc namespace. For backward compatibility,
be accessed using XRCCTRL().
+
@section overview_xrcformat_root Resource Root Element
The root element is always @c \<resource\>. It has one optional attribute, @c
-# 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
- ("<label>Cancel</label>"), but they may use nested subelements too (e.g.
+ ("\<label\>Cancel\</label\>"), 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
<object_ref ref="template" name="my_dlg">
<title>My dialog</title>
<centered>1</centered>
-</object>
+</object_ref>
@endcode
is identical to:
@code
-<object_ref ref="template" name="my_dlg">
+<object class="wxDialog" name="my_dlg">
<title>My dialog</title>
<size>400,400</size>
<centered>1</centered>
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.
+properties, or it can be derived from one of system fonts or the parent window
+font.
The font property element is "composite" element: unlike majority of
properties, it doesn't have text value but contains several child elements
@hdr3col{property, type, description}
@row3col{size, unsigned integer,
Pixel size of the font (default: wxNORMAL_FONT's size or @c sysfont's
- size if the @c sysfont property is used.}
+ size if the @c sysfont property is used or the current size of the font
+ of the enclosing control if the @c inherit property is used.}
@row3col{style, enum,
One of "normal", "italic" or "slant" (default: normal).}
@row3col{weight, enum,
(default: unspecified).}
@row3col{sysfont, ,
Symbolic name of system standard font(one of wxSYS_*_FONT constants).}
+@row3col{inherit, @ref overview_xrcformat_type_bool,
+ If true, the font of the enclosing control is used. If this property and the
+ @c sysfont property are specified the @c sysfont property takes precedence.}
@row3col{relativesize, float,
- Float, font size relative to chosen system font's size; can only be
- used when 'sysfont' is used and when 'size' is not used.}
+ 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.}
@endTable
All of them are optional, if they are missing, appropriate wxFont default is
-used. If the @c sysfont property is used, then the defaults are taken from it
-instead.
+used. If the @c sysfont or @c inherit property is used, then the defaults are
+taken from it instead.
Examples:
@code
</font>
@endcode
+@note You cannot use @c 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.
+
@section overview_xrcformat_windows Controls and Windows
(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,
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).}
@endTable
+@subsubsection xrc_wxauinotebook wxAuiNotebook
+
+A wxAuiNotebook can have one or more child objects of the @c notebookpage
+pseudo-class.
+@c notebookpage objects have the following properties:
+
+@beginTable
+@hdr3col{property, type, description}
+@row3col{label, @ref overview_xrcformat_type_text,
+ Page label (required).}
+@row3col{bitmap, @ref overview_xrcformat_type_bitmap,
+ Bitmap shown alongside the label (default: none).}
+@row3col{selected, @ref overview_xrcformat_type_bool,
+ Is the page selected initially (only one page can be selected; default: 0)?}
+@endTable
+
+Each @c notebookpage must have exactly one non-toplevel window as its child.
+
+Example:
+@code
+<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>
+@endcode
+
+Notice that wxAuiNotebook support in XRC is available in wxWidgets 2.9.5 and
+later only and you need to explicitly register its handler using
+@code
+ #include <wx/xrc/xh_auinotbk.h>
+
+ AddHandler(new wxAuiNotebookXmlHandler);
+@endcode
+to use it.
+
+
+@subsubsection xrc_wxbannerwindow wxBannerWindow
+
+@beginTable
+@hdr3col{property, type, description}
+@row3col{direction, @c wxLEFT|wxRIGHT|wxTOP|wxBOTTOM,
+ The side along which the banner will be positioned.}
+@row3col{bitmap, @ref overview_xrcformat_type_bitmap,
+ Bitmap to use as the banner background.}
+@row3col{title, @ref overview_xrcformat_type_text,
+ Banner title, should be single line.}
+@row3col{message, @ref overview_xrcformat_type_text,
+ Possibly multi-line banner message.}
+@row3col{gradient-start, @ref overview_xrcformat_type_colour,
+ Starting colour of the gradient used as banner background. Can't be used if
+ a valid bitmap is specified.}
+@row3col{gradient-end, @ref overview_xrcformat_type_colour,
+ End colour of the gradient used as banner background. Can't be used if
+ a valid bitmap is specified.}
+@endTable
+
+
@subsubsection xrc_wxbitmapbutton wxBitmapButton
@beginTable
@endcode
+@subsubsection xrc_wxbitmaptogglebutton wxBitmapToggleButton
+
+@beginTable
+@hdr3col{property, type, description}
+@row3col{bitmap, @ref overview_xrcformat_type_bitmap,
+ Label to display on the button (required).}
+@row3col{checked, @ref overview_xrcformat_type_bool,
+ Should the button be checked/pressed initially (default: 0)?}
+@endTable
+
+
@subsubsection xrc_wxbutton wxButton
@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
@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).}
@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}
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
Each @c choicebookpage has exactly one non-toplevel window as its child.
+@subsubsection xrc_wxcommandlinkbutton wxCommandLinkButton
+
+The wxCommandLinkButton contains a main title-like @c label and an optional
+@c note for longer description. The main @c label and the @c note can be
+concatenated into a single string using a new line character between them
+(notice that the @c note part can have more new lines in it).
+
+@beginTable
+@hdr3col{property, type, description}
+@row3col{label, @ref overview_xrcformat_type_text,
+ First line of text on the button, typically the label of an action that
+ will be made when the button is pressed. }
+@row3col{note, @ref overview_xrcformat_type_text,
+ Second line of text describing the action performed when the button is pressed. }
+@endTable
+
+
@subsubsection xrc_wxcollapsiblepane wxCollapsiblePane
@beginTable
@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).}
@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
@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
@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: the size of the first bitmap).}
+@endTable
+
+Example:
+@code
+<imagelist>
+ <size>32,32</size>
+ <bitmap stock_id="wxART_QUESTION"/>
+ <bitmap stock_id="wxART_INFORMATION"/>
+</imagelist>
+@endcode
+
+In the specific case of the @ref xrc_wxlistctrl, the tag can take the name
+@c \<imagelist-small\> 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 \<item\> XML
elements as its children, with the items text as their text values
(default: empty).}
@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}
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
@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 \<imagelist\> tag for the control with @c wxLC_ICON
+style or using @c \<imagelist-small\> 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. }
+@row3col{image, integer,
+ The zero-based index of the image associated with the item in the 'small' image list. }
+@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
@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}
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
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).}
@endcode
+@subsubsection xrc_wxribbon wxRibbon
+
+A wxRibbonBar is a container of ribbon pages which, in turn, contain elements
+that can be wxRibbonControl or wxRibbonGallery.
+
+Example:
+@code
+<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>
+@endcode
+
+Notice that wxRibbon support in XRC is available in wxWidgets 2.9.5 and
+later only and you need to explicitly register its handler using
+@code
+ #include <wx/xrc/xh_ribbon.h>
+
+ AddHandler(new wxRibbonXmlHandler);
+@endcode
+to use it.
+
+
@subsubsection xrc_wxrichtextctrl wxRichTextCtrl
@beginTable
Maximum length of the text entered (default: unlimited).}
@endTable
+Notice that wxRichTextCtrl support in XRC is available in wxWidgets 2.9.5 and
+later only and you need to explicitly register its handler using
+@code
+ #include <wx/xrc/xh_richtext.h>
+
+ AddHandler(new wxRichTextCtrl);
+@endcode
+to use it.
+
@subsubsection xrc_wxscrollbar wxScrollBar
@row3col{max, integer,
Maximum allowed value (default: 100).}
@row3col{pagesize, integer,
- Line size; number of steps the slider moves when the user moves
+ Page size; number of steps the slider moves when the user moves
pages up or down (default: unset).}
@row3col{linesize, integer,
Line size; number of steps the slider moves when the user moves it
@subsubsection xrc_wxspinctrl wxSpinCtrl
-wxSpinCtrl supports the properties as @ref xrc_wxspinbutton.
+wxSpinCtrl supports the same properties as @ref xrc_wxspinbutton and, since
+wxWidgets 2.9.5, another one:
+@beginTable
+@row3col{base, integer,
+ Numeric base, currently can be only 10 or 16 (default: 10).}
+@endTable
@subsubsection xrc_wxsplitterwindow wxSplitterWindow
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
by wxStatusBar::SetStatusWidths().}
@row3col{styles, @ref overview_xrcformat_type_string,
Comma-separated list of @em fields flags. Each value specifies status bar
- fieldd style and can be one of @c wxSB_NORMAL, @c wxSB_FLAT or
- @c wxSB_RAISED. See wxStatusBar::SetStatusStyles() for their description.}
+ fieldd style and can be one of @c wxSB_NORMAL, @c wxSB_FLAT,
+ @c wxSB_RAISED or, since wxWidgets 2.9.5, @c wxSB_SUNKEN. See
+ wxStatusBar::SetStatusStyles() for their description.}
@endTable
@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
@endTable
-@subsubsection xrc_wxtogglebuttton wxToggleButton
+@subsubsection xrc_wxtimepickerctrl wxTimePickerCtrl
+
+No additional properties.
+
+
+@subsubsection xrc_wxtogglebutton wxToggleButton
@beginTable
@hdr3col{property, type, description}
one of two pseudo-classes: @c separator or @c tool.
The @c separator pseudo-class is used to insert separators into the toolbar and
-has neither properties nor children.
+has neither properties nor children. Similarly, the @c space pseudo-class is
+used for stretchable spaces (see wxToolBar::AddStretchableSpace(), new since
+wxWidgets 2.9.1).
The @c tool pseudo-class objects specify toolbar buttons and have the following
properties:
@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)? (@since 2.9.0)}
+ 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,
Help text shown in statusbar when the mouse is on the tool (default: none).}
@row3col{disabled, @ref overview_xrcformat_type_bool,
Is the tool initially disabled (default: 0)?}
+@row3col{checked, @ref overview_xrcformat_type_bool,
+ Is the tool initially checked (default: 0)? (only available since wxWidgets 2.9.3)}
@endTable
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 wxMenu @ref
+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.
<bitmap>bar.png</bitmap>
<label>Bar</label>
</object>
+ <object class="separator"/>
<object class="tool" name="view_auto">
<bitmap>view.png</bitmap>
<label>View</label>
</object>
</dropdown>
</object>
- <object class="separator"/>
+ <object class="space"/>
<object class="wxComboBox">
<content>
<item>Just</item>
@endcode
+@subsubsection xrc_wxtoolbook wxToolbook
+
+A toolbook can have one or more child objects of the @c toolbookpage
+pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its
+@c notebookpage) and one child object of the @ref xrc_wximagelist class.
+@c toolbookpage objects have the following properties:
+
+@beginTable
+@hdr3col{property, type, description}
+@row3col{label, @ref overview_xrcformat_type_text,
+ 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
+
+Each @c toolbookpage has exactly one non-toplevel window as its child.
+
+
@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}
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)?}
+@row3col{expanded, @ref overview_xrcformat_type_bool,
+ If set to 1, the page is initially expanded. By default all pages are
+ initially collapsed.}
@endTable
Each @c treebookpage has exactly one non-toplevel window as its child.
@endTable
wxWizardPageSimple pages are automatically chained together; wxWizardPage pages
-transitions must be handled programatically.
+transitions must be handled programmatically.
@section overview_xrcformat_sizers 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 hieararchy: child windows are children of their parent window and
+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().
<rows>0</rows>
<vgap>0</vgap>
<hgap>0</hgap>
- <growablecols>0</growablecols>
- <growablerows>0</growablerows>
+ <growablecols>0:1</growablecols>
+ <growablerows>0:1</growablerows>
<object class="sizeritem">
<flag>wxALIGN_CENTRE|wxALL</flag>
<border>5</border>
@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{flexibledirection, @ref overview_xrcformat_type_style,
+ Flexible direction, @c wxVERTICAL, @c wxHORIZONTAL or @c wxBOTH (default).
+ This property is only available since wxWidgets 2.9.5.}
+@row3col{nonflexiblegrowmode, @ref overview_xrcformat_type_style,
+ Grow mode in the non-flexible direction,
+ @c wxFLEX_GROWMODE_NONE, @c wxFLEX_GROWMODE_SPECIFIED (default) or
+ @c wxFLEX_GROWMODE_ALL.
+ This property is only available since wxWidgets 2.9.5.}
@row3col{growablerows, comma-separated integers list,
- Comma-separated list of indexes of rows that are growable
- (default: none).}
+ 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 (@c :).}
@row3col{growablecols, comma-separated integers list,
- Comma-separated list of indexes of columns that are growable
- (default: none).}
+ 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 (@c :).}
@endTable
@subsection overview_xrcformat_wxgridbagsizer wxGridBagSizer
@hdr3col{property, type, description}
@row3col{vgap, integer, Vertical gap between children (default: 0).}
@row3col{hgap, integer, Horizontal gap between children (default: 0).}
+@row3col{flexibledirection, @ref overview_xrcformat_type_style,
+ Flexible direction, @c wxVERTICAL, @c wxHORIZONTAL, @c wxBOTH (default: @c wxBOTH).}
+@row3col{nonflexiblegrowmode, @ref overview_xrcformat_type_style,
+ Grow mode in the non-flexible direction,
+ @c wxFLEX_GROWMODE_NONE, @c wxFLEX_GROWMODE_SPECIFIED, @c wxFLEX_GROWMODE_ALL
+ (default: @c wxFLEX_GROWMODE_SPECIFIED).}
@row3col{growablerows, comma-separated integers list,
- Comma-separated list of indexes of rows that are growable
+ Comma-separated list of indexes of rows that are growable,
+ optionally the proportion can be appended after each number
+ separated by a @c :
(default: none).}
@row3col{growablecols, comma-separated integers list,
- Comma-separated list of indexes of columns that are growable
+ Comma-separated list of indexes of columns that are growable,
+ optionally the proportion can be appended after each number
+ separated by a @c :
(default: none).}
@endTable
@subsection overview_xrcformat_wxstddialogbuttonsizer wxStdDialogButtonSizer
-Unlike other sizers, wxStdDialogButtonSizer doesn't have neither @c sizeritem
+Unlike other sizers, wxStdDialogButtonSizer has neither @c sizeritem
nor @c spacer children. Instead, it has one or more children of the
@c button pseudo-class. @c button objects have no properties and they must
always have exactly one child of the @c wxButton class or a class derived from
Possible elemental values are:
@beginDefList
@itemdef{ @c win, Windows }
-@itemdef{ @c mac, Mac OS X (or Mac Classic in wxWidgets version supporting it }
+@itemdef{ @c mac, Mac OS X (or Mac Classic in wxWidgets version supporting it) }
@itemdef{ @c unix, Any Unix platform @em except OS X }
@itemdef{ @c os2, OS/2 }
@endDefList
+@section overview_xrcformat_idranges 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 @em foo and another
+called @em bar; each with some items.
+
+@code
+ <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" />
+@endcode
+
+For the range foo, no @em size or @em 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
+<em>rangename</em>[0] or <em>rangename</em>[start]. Similarly
+<em>rangename</em>[end] is the last item. Using [start] and [end] is more
+descriptive in e.g. a Bind() event range or a @em 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:
+
+@code
+for (int n=XRCID("foo[start]"); n <= XRCID("foo[end]"); ++n)
+ ...
+@endcode
+
+ID ranges can be seen in action in the <em>objref</em> dialog section of the
+@sample{xrc}.
+
+@note
+@li All the items in an ID range must be contained in the same XRC file.
+@li 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
+
@section overview_xrcformat_extending Extending the XRC Format
The XRC format is designed to be extensible and allows specifying and loading
no limitations on them imposed by XRC format.
This is the only mechanism that works for toplevel objects -- custom controls
-are accessible using type-unsafe wxXmlResource::LoadObject() method.
+are accessible using the type-unsafe wxXmlResource::LoadObject() method.
projects / wxWidgets.git / blobdiff