Add generic wxMarkupText class implementing handling of markup.

[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 fd407a4923c3bec9b6aae9b46c9fbf538136d5b4..b21050130fbc9425b169109da5236c8d7f8c25db 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

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


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


@@ -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
  -# 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


@@ -217,7 +218,7 @@ For example, "my_dlg" in this snippet:
 @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>


@@ -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).}
     (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 +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).}
     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).}


@@ -581,9 +591,13 @@ Example:
 @beginTable
 @hdr3col{property, type, description}
 @row3col{label, @ref overview_xrcformat_type_text,
 @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
 
 


@@ -681,6 +695,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


@@ -904,7 +935,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:


@@ -983,7 +1014,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.
 
 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:
 
 The @c listcol class can only be used for wxListCtrl children. It can have the
 following properties:


@@ -1003,7 +1034,7 @@ 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.
 
 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:
 
 The @c listitem is a child object for the class @ref xrc_wxlistctrl.
 It can have the following properties:


@@ -1042,7 +1073,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.
 @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,
 @row3col{text, @ref overview_xrcformat_type_string,
     The text label for the item. }
 @row3col{textcolour, @ref overview_xrcformat_type_colour,


@@ -1557,7 +1588,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:


@@ -1606,6 +1639,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>


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


@@ -1633,6 +1667,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.


@@ -1742,7 +1799,7 @@ transitions must be handled programatically.
 
 Sizers are handled slightly differently in XRC resources than they are in
 wxWindow hierarchy. wxWindow's sizers hierarchy is parallel to the wxWindow
 
 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().
 


@@ -1918,7 +1975,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


@@ -1989,7 +2046,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


@@ -2004,6 +2061,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


@@ -2091,7 +2206,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.