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 71325a6ebb096bf07d0beb2dadee37cdd831a3d2..80f0388adf6182933b5e116f6b34e4ceb97aaaef 100644 (file)
--- a/docs/doxygen/overviews/xrc_format.h
+++ b/docs/doxygen/overviews/xrc_format.h
@@ -18,34 +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_idranges
-- @ref overview_xrcformat_extending
-    - @ref overview_xrcformat_extending_subclass
-    - @ref overview_xrcformat_extending_unknown
-    - @ref overview_xrcformat_extending_custom
-- @ref overview_xrcformat_packed
-- @ref overview_xrcformat_oldversions
-
-This document describes the format of XRC resource files, as used by wxXmlResource.
-
-
-<hr>
-
-
-@section overview_xrcformat_overview Overview
+@tableofcontents
+
+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,


@@ -66,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


@@ -214,7 +191,7 @@ 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


@@ -402,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


@@ -413,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,


@@ -431,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


@@ -456,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
 


@@ -526,7 +513,49 @@ controls cannot have children.
 @endTable
 
 
 @endTable
 
 

-@subsubsection xrc_wxanimationctrl wxBannerWindow
+@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}
 
 @beginTable
 @hdr3col{property, type, description}


@@ -607,7 +636,7 @@ Example:
 @endcode
 
 
 @endcode
 
 

-@subsubsection xrc_wxtogglebuttton wxBitmapToggleButton
+@subsubsection xrc_wxbitmaptogglebutton wxBitmapToggleButton

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


@@ -1382,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


@@ -1392,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
 


@@ -1462,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


@@ -1495,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


@@ -1539,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
 
 


@@ -1594,7 +1685,7 @@ No additional properties.
 No additional properties.
 
 
 No additional properties.
 
 

-@subsubsection xrc_wxtogglebuttton wxToggleButton
+@subsubsection xrc_wxtogglebutton wxToggleButton

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


@@ -1654,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


@@ -1902,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>


@@ -1984,12 +2077,22 @@ class-specific properties. All classes support the following properties:
 @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{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,
 @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


@@ -1998,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
 


@@ -2145,7 +2258,7 @@ Whether a range has positive or negative IDs, [start] is always a smaller
 number than [end]; so code like this works as expected:
 
 @code
 number than [end]; so code like this works as expected:
 
 @code

-for (int n=XRCID("foo[start]"); n < XRCID("foo[end]"); ++n)
+for (int n=XRCID("foo[start]"); n <= XRCID("foo[end]"); ++n)

     ...
 @endcode
 
     ...
 @endcode