Undid accidental modification of wxTaskBarIcon in the last commit.

[wxWidgets.git] / docs / doxygen / overviews / xrc_format.h

diff --git a/docs/doxygen/overviews/xrc_format.h b/docs/doxygen/overviews/xrc_format.h
index 75ec8c814badd516e54adb493a03803135b3563d..eb9f73e49b6400aa0c29ad0862e7bfaad759d03e 100644 (file)
--- a/docs/doxygen/overviews/xrc_format.h
+++ b/docs/doxygen/overviews/xrc_format.h
@@ -31,6 +31,7 @@ Table of contents:
 - @ref overview_xrcformat_sizers
 - @ref overview_xrcformat_other_objects
 - @ref overview_xrcformat_platform
 - @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
 - @ref overview_xrcformat_extending
     - @ref overview_xrcformat_extending_subclass
     - @ref overview_xrcformat_extending_unknown


@@ -213,11 +214,11 @@ For example, "my_dlg" in this snippet:
 <object_ref ref="template" name="my_dlg">
     <title>My dialog</title>
     <centered>1</centered>
 <object_ref ref="template" name="my_dlg">
     <title>My dialog</title>
     <centered>1</centered>

-</object>
+</object_ref>

 @endcode
 is identical to:
 @code
 @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>
     <title>My dialog</title>
     <size>400,400</size>
     <centered>1</centered>


@@ -525,6 +526,27 @@ controls cannot have children.
 @endTable
 
 
 @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
 @subsubsection xrc_wxbitmapbutton wxBitmapButton
 
 @beginTable


@@ -585,6 +607,17 @@ Example:
 @endcode
 
 
 @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
 @subsubsection xrc_wxbutton wxButton
 
 @beginTable


@@ -934,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,
 @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:
 @endTable
 
 Example:


@@ -1027,6 +1060,8 @@ following properties:
     The title of the column. }
 @row3col{width, integer,
     The column width. }
     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
 @endTable
 
 The columns are appended to the control in order of their appearance and may be


@@ -1427,7 +1462,7 @@ HTML markup. Note that the markup has to be escaped:
 @row3col{max, integer,
     Maximum allowed value (default: 100).}
 @row3col{pagesize, integer,
 @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
     pages up or down (default: unset).}
 @row3col{linesize, integer,
     Line size; number of steps the slider moves when the user moves it


@@ -1460,7 +1495,12 @@ HTML markup. Note that the markup has to be escaped:
 
 @subsubsection xrc_wxspinctrl wxSpinCtrl
 
 
 @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
 
 
 @subsubsection xrc_wxsplitterwindow wxSplitterWindow


@@ -1554,7 +1594,12 @@ No additional properties.
 @endTable
 
 
 @endTable
 
 

-@subsubsection xrc_wxtogglebuttton wxToggleButton
+@subsubsection xrc_wxtimepickerctrl wxTimePickerCtrl
+
+No additional properties.
+
+
+@subsubsection xrc_wxtogglebutton wxToggleButton

 
 @beginTable
 @hdr3col{property, type, description}
 
 @beginTable
 @hdr3col{property, type, description}


@@ -1614,6 +1659,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)?}
     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
 @endTable
 
 The presence of a @c dropdown property indicates that the tool is of type


@@ -1666,6 +1713,29 @@ Example:
 @endcode
 
 
 @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.
 @subsubsection xrc_wxtreectrl wxTreeCtrl
 
 A treectrl can have one child object of the @ref xrc_wximagelist class.


@@ -1693,6 +1763,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)?}
     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
 
 Each @c treebookpage has exactly one non-toplevel window as its child.


@@ -1768,14 +1841,14 @@ wxWizardPageSimple classes. They both support the following properties
 @endTable
 
 wxWizardPageSimple pages are automatically chained together; wxWizardPage pages
 @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
 
 
 @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().
 
 the sizer (or sizers) form separate hierarchy attached to the window with
 wxWindow::SetSizer().
 


@@ -1951,7 +2024,7 @@ class-specific properties. All classes support the following properties:
 
 @subsection overview_xrcformat_wxstddialogbuttonsizer wxStdDialogButtonSizer
 
 
 @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
 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


@@ -2022,7 +2095,7 @@ should be processed on. It is filtered out and ignored on any other platforms.
 Possible elemental values are:
 @beginDefList
 @itemdef{ @c win, Windows }
 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
 @itemdef{ @c unix, Any Unix platform @em except OS X }
 @itemdef{ @c os2, OS/2 }
 @endDefList


@@ -2037,6 +2110,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
+    <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
 @section overview_xrcformat_extending Extending the XRC Format
 
 The XRC format is designed to be extensible and allows specifying and loading


@@ -2124,7 +2255,7 @@ Child elements of @c \<object\> 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
 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.