X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/0d14e4f21d2aa9e7edf0cf08a352743619f41e0b..c8c77ee2af68bcea8ba157b4d5a4e2cd5b4912bd:/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 fd407a4923..dd14c10f1e 100644
--- a/docs/doxygen/overviews/xrc_format.h
+++ b/docs/doxygen/overviews/xrc_format.h
@@ -3,7 +3,7 @@
// Purpose: XRC format specification
// Author: Vaclav Slavik
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
@@ -31,6 +31,7 @@ Table of contents:
- @ref overview_xrcformat_sizers
- @ref overview_xrcformat_other_objects
- @ref overview_xrcformat_platform
+- @ref overview_xrcformat_idranges
- @ref overview_xrcformat_extending
- @ref overview_xrcformat_extending_subclass
- @ref overview_xrcformat_extending_unknown
@@ -136,7 +137,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
- ("Cancel "), 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
@@ -213,11 +214,11 @@ For example, "my_dlg" in this snippet:
My dialog
1
-
+
@endcode
is identical to:
@code
-
+
My dialog
400,400
1
@@ -482,8 +483,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,
@@ -492,6 +499,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).}
@@ -516,6 +526,27 @@ controls cannot have children.
@endTable
+@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
@@ -576,14 +607,29 @@ Example:
@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
@@ -681,6 +727,23 @@ pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its
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
@@ -904,7 +967,7 @@ The available properties are:
@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)).}
+ The size of the images in the list (default: the size of the first bitmap).}
@endTable
Example:
@@ -983,7 +1046,7 @@ 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.
-@subsubsection xrc_wxlistcol listcol
+@paragraph xrc_wxlistcol listcol
The @c listcol class can only be used for wxListCtrl children. It can have the
following properties:
@@ -997,13 +1060,15 @@ following properties:
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.
-@subsubsection xrc_wxlistitem listitem
+@paragraph xrc_wxlistitem listitem
The @c listitem is a child object for the class @ref xrc_wxlistctrl.
It can have the following properties:
@@ -1042,7 +1107,7 @@ It can have the following properties:
@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.
+ - @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,
@@ -1397,7 +1462,7 @@ HTML markup. Note that the markup has to be escaped:
@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
@@ -1524,7 +1589,12 @@ No additional properties.
@endTable
-@subsubsection xrc_wxtogglebuttton wxToggleButton
+@subsubsection xrc_wxtimepickerctrl wxTimePickerCtrl
+
+No additional properties.
+
+
+@subsubsection xrc_wxtogglebutton wxToggleButton
@beginTable
@hdr3col{property, type, description}
@@ -1557,7 +1627,9 @@ A toolbar can have one or more child objects of any wxControl-derived class or
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:
@@ -1582,6 +1654,8 @@ properties:
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
@@ -1606,6 +1680,7 @@ Example:
bar.png
Bar
+
view.png
View
@@ -1620,7 +1695,7 @@ Example:
-
+
- Just
@@ -1633,6 +1708,29 @@ Example:
@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.
@@ -1660,6 +1758,9 @@ pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its
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.
@@ -1735,14 +1836,14 @@ wxWizardPageSimple classes. They both support the following properties
@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().
@@ -1918,7 +2019,7 @@ class-specific properties. All classes support the following properties:
@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
@@ -1989,7 +2090,7 @@ should be processed on. It is filtered out and ignored on any other platforms.
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
@@ -2004,6 +2105,64 @@ Examples:
+@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
+
+
+
+ ...
+
+
+
+ ...
+
+
+@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
+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 @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 objref 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
@@ -2091,7 +2250,7 @@ Child elements of @c \ 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 type-unsafe wxXmlResource::LoadObject() method.
+are accessible using the type-unsafe wxXmlResource::LoadObject() method.