Move wx/msw/gccpriv.h inclusion back to wx/platform.h from wx/compiler.h.

[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 c8f710afd2983e4731b9e0f9a702ed7e426a981c..80f0388adf6182933b5e116f6b34e4ceb97aaaef 100644 (file)
--- 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$
 // Purpose:     XRC format specification
 // Author:      Vaclav Slavik
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 
 /////////////////////////////////////////////////////////////////////////////
 
 


@@ -18,33 +18,10 @@
 
 @page overview_xrcformat XRC File Format
 
 
 @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,
 
 XRC file is a XML file with all of its elements in the
 @c http://www.wxwidgets.org/wxxrc namespace. For backward compatibility,


@@ -65,6 +42,7 @@ Child objects are not directly accessible via wxXmlResource, they can only
 be accessed using XRCCTRL().
 
 
 be accessed using XRCCTRL().
 
 

+

 @section overview_xrcformat_root Resource Root Element
 
 The root element is always @c \<resource\>. It has one optional attribute, @c
 @section overview_xrcformat_root Resource Root Element
 
 The root element is always @c \<resource\>. It has one optional attribute, @c


@@ -136,7 +114,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
  -# 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
     @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 +191,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>


@@ -401,7 +379,8 @@ Examples:
 
 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
 
 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
 
 The font property element is "composite" element: unlike majority of
 properties, it doesn't have text value but contains several child elements


@@ -412,7 +391,8 @@ and can be one of the following "sub-properties":
 @hdr3col{property, type, description}
 @row3col{size, unsigned integer,
     Pixel size of the font (default: wxNORMAL_FONT's size or @c sysfont's
 @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,
 @row3col{style, enum,
     One of "normal", "italic" or "slant" (default: normal).}
 @row3col{weight, enum,


@@ -430,14 +410,18 @@ and can be one of the following "sub-properties":
     (default: unspecified).}
 @row3col{sysfont, ,
     Symbolic name of system standard font(one of wxSYS_*_FONT constants).}
     (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,
 @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
 @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
 
 Examples:
 @code


@@ -455,6 +439,10 @@ Examples:
 </font>
 @endcode
 
 </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
 
 
 @section overview_xrcformat_windows Controls and Windows
 


@@ -482,8 +470,14 @@ from properties lists below.
     (default: not set).}
 @row3col{fg, @ref overview_xrcformat_type_colour,
     Foreground colour of the window (default: window's default).}
     (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{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,
 @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 +486,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).}
     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).}
 @row3col{help, @ref overview_xrcformat_type_text,
     Context-sensitive help for the control, used by wxHelpProvider
     (default: not set).}


@@ -516,6 +513,69 @@ controls cannot have children.
 @endTable
 
 
 @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
 @subsubsection xrc_wxbitmapbutton wxBitmapButton
 
 @beginTable


@@ -576,14 +636,29 @@ 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
 @hdr3col{property, type, description}
 @row3col{label, @ref overview_xrcformat_type_text,
 @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,
 @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
 
 
 @endTable
 
 


@@ -607,7 +682,7 @@ No additional properties.
 
 @beginTable
 @hdr3col{property, type, description}
 
 @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).}
      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).}


@@ -637,7 +712,7 @@ Example:
 @hdr3col{property, type, description}
 @row3col{selection, integer,
      Index of the initially selected item or -1 for no selection (default: -1).}
 @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).}
      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).}


@@ -660,11 +735,10 @@ Example:
 
 @subsubsection xrc_wxchoicebook wxChoicebook
 
 
 @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
 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}
 
 @beginTable
 @hdr3col{property, type, description}


@@ -672,6 +746,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).}
      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
 @row3col{selected, @ref overview_xrcformat_type_bool,
      Is the page selected initially (only one page can be selected; default: 0)?}
 @endTable


@@ -679,6 +756,23 @@ pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its
 Each @c choicebookpage has exactly one non-toplevel window as its child.
 
 
 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
 @subsubsection xrc_wxcollapsiblepane wxCollapsiblePane
 
 @beginTable


@@ -710,7 +804,7 @@ object.
 @hdr3col{property, type, description}
 @row3col{selection, integer,
      Index of the initially selected item or -1 for no selection (default: not used).}
 @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).}
      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).}


@@ -769,6 +863,20 @@ objects. If sizer child is used, it sets
 @endTable
 
 
 @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
 @subsubsection xrc_wxfilepickerctrl wxFilePickerCtrl
 
 @beginTable


@@ -778,7 +886,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,
 @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
 
 


@@ -868,13 +977,49 @@ page.
 @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).}
 @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).}
      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).}


@@ -898,11 +1043,10 @@ Example:
 
 @subsubsection xrc_wxlistbook wxListbook
 
 
 @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
 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}
 
 @beginTable
 @hdr3col{property, type, description}


@@ -910,6 +1054,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).}
      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
 @row3col{selected, @ref overview_xrcformat_type_bool,
      Is the page selected initially (only one page can be selected; default: 0)?}
 @endTable


@@ -919,7 +1066,85 @@ Each @c listbookpage has exactly one non-toplevel window as its child.
 
 @subsubsection xrc_wxlistctrl wxListCtrl
 
 
 @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_wxmdiparentframe wxMDIParentFrame


@@ -1030,10 +1255,9 @@ class.
 
 @subsubsection xrc_wxnotebook wxNotebook
 
 
 @subsubsection xrc_wxnotebook wxNotebook
 

-No additional properties.
-

 A notebook can have one or more child objects of the @c notebookpage
 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}
 
 @beginTable
 @hdr3col{property, type, description}


@@ -1041,6 +1265,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).}
      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
 @row3col{selected, @ref overview_xrcformat_type_bool,
      Is the page selected initially (only one page can be selected; default: 0)?}
 @endTable


@@ -1143,7 +1370,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).}
      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).}
      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).}


@@ -1184,6 +1411,53 @@ Example:
 @endcode
 
 
 @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
 @subsubsection xrc_wxrichtextctrl wxRichTextCtrl
 
 @beginTable


@@ -1194,6 +1468,15 @@ Example:
     Maximum length of the text entered (default: unlimited).}
 @endTable
 
     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
 
 
 @subsubsection xrc_wxscrollbar wxScrollBar
 


@@ -1264,7 +1547,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


@@ -1297,7 +1580,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


@@ -1310,7 +1598,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).}
     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
 
     Sash gravity, see wxSplitterWindow::SetSashGravity() (default: not set).}
 @endTable
 


@@ -1341,8 +1629,9 @@ child and the second one for right/bottom child window.
     by wxStatusBar::SetStatusWidths().}
 @row3col{styles, @ref overview_xrcformat_type_string,
     Comma-separated list of @em fields flags. Each value specifies status bar
     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
 
 
 @endTable
 
 


@@ -1376,7 +1665,7 @@ No additional properties.
 @row3col{label, @ref overview_xrcformat_type_text,
      Label to display (required).}
 @row3col{wrap, integer,
 @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
 
      wxStaticText::Wrap() (default: no wrap).}
 @endTable
 


@@ -1391,7 +1680,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}


@@ -1424,7 +1718,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
 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:
 
 The @c tool pseudo-class objects specify toolbar buttons and have the following
 properties:


@@ -1449,6 +1745,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


@@ -1473,6 +1771,7 @@ Example:
         <bitmap>bar.png</bitmap>
         <label>Bar</label>
     </object>
         <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 class="tool" name="view_auto">
         <bitmap>view.png</bitmap>
         <label>View</label>


@@ -1487,7 +1786,7 @@ Example:
             </object>
         </dropdown>
     </object>
             </object>
         </dropdown>
     </object>

-    <object class="separator"/>
+    <object class="space"/>

     <object class="wxComboBox">
         <content>
             <item>Just</item>
     <object class="wxComboBox">
         <content>
             <item>Just</item>


@@ -1500,18 +1799,42 @@ 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
 
 @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.
 
 
 @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
 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}
 
 @beginTable
 @hdr3col{property, type, description}


@@ -1521,8 +1844,14 @@ 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).}
      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{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.


@@ -1598,14 +1927,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().
 


@@ -1666,8 +1995,8 @@ Example of sizers XRC code:
         <rows>0</rows>
         <vgap>0</vgap>
         <hgap>0</hgap>
         <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>
         <object class="sizeritem">
             <flag>wxALIGN_CENTRE|wxALL</flag>
             <border>5</border>


@@ -1734,8 +2063,8 @@ class-specific properties. All classes support the following properties:
 
 @beginTable
 @hdr3col{property, type, description}
 
 @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
 @row3col{vgap, integer, Vertical gap between children (default: 0).}
 @row3col{hgap, integer, Horizontal gap between children (default: 0).}
 @endTable


@@ -1744,16 +2073,26 @@ class-specific properties. All classes support the following properties:
 
 @beginTable
 @hdr3col{property, type, description}
 
 @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{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,
 @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,
 @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
 @endTable
 
 @subsection overview_xrcformat_wxgridbagsizer wxGridBagSizer


@@ -1762,11 +2101,21 @@ class-specific properties. All classes support the following properties:
 @hdr3col{property, type, description}
 @row3col{vgap, integer, Vertical gap between children (default: 0).}
 @row3col{hgap, integer, Horizontal gap between children (default: 0).}
 @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,
 @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,
     (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
 
     (default: none).}
 @endTable
 


@@ -1781,7 +2130,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


@@ -1852,7 +2201,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


@@ -1867,6 +2216,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


@@ -1954,7 +2361,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.