X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e2517f176b1739431be7fb21d120226e2311ded2..e87d78bb36f371d593137761158118fb09b69fa2:/docs/doxygen/overviews/xrc_format.h diff --git a/docs/doxygen/overviews/xrc_format.h b/docs/doxygen/overviews/xrc_format.h index 042b2f08bb..80f0388adf 100644 --- a/docs/doxygen/overviews/xrc_format.h +++ b/docs/doxygen/overviews/xrc_format.h @@ -3,7 +3,7 @@ // Purpose: XRC format specification // Author: Vaclav Slavik // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -18,33 +18,10 @@ @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. - - -
- - -@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, @@ -65,6 +42,7 @@ Child objects are not directly accessible via wxXmlResource, they can only be accessed using XRCCTRL(). + @section overview_xrcformat_root Resource Root Element The root element is always @c \. 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 - (""), but they may use nested subelements too (e.g. + ("\Cancel\"), but they may use nested subelements too (e.g. @ref overview_xrcformat_type_font "font property"). A property can only be listed once in an object's definition. -# Child objects. Window childs, sizers, sizer items or notebook pages @@ -213,11 +191,11 @@ For example, "my_dlg" in this snippet: My dialog 1 - + @endcode is identical to: @code - + My dialog 400,400 1 @@ -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 -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 @@ -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 - 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, @@ -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).} +@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, - 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 -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 @@ -455,6 +439,10 @@ Examples: @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 @@ -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).} +@row3col{ownfg, @ref overview_xrcformat_type_colour, + Non-inheritable foreground colour of the window, see + wxWindow::SetOwnForegroundColour() (default: none).} @row3col{bg, @ref overview_xrcformat_type_colour, Background colour of the window (default: window's default).} +@row3col{ownbg, @ref overview_xrcformat_type_colour, + Non-inheritable background colour of the window, see + wxWindow::SetOwnBackgroundColour() (default: none).} @row3col{enabled, @ref overview_xrcformat_type_bool, If set to 0, the control is disabled (default: 1).} @row3col{hidden, @ref overview_xrcformat_type_bool, @@ -492,6 +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).} +@row3col{ownfont, @ref overview_xrcformat_type_font, + Non-inheritable font to use for the control, see + wxWindow::SetOwnFont() (default: none).} @row3col{help, @ref overview_xrcformat_type_text, Context-sensitive help for the control, used by wxHelpProvider (default: not set).} @@ -516,6 +513,69 @@ controls cannot have children. @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 + + + + + bitmap.png + + ... + + + +@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 + + 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 @@ -576,14 +636,29 @@ Example: @endcode +@subsubsection xrc_wxbitmaptogglebutton wxBitmapToggleButton + +@beginTable +@hdr3col{property, type, description} +@row3col{bitmap, @ref overview_xrcformat_type_bitmap, + Label to display on the button (required).} +@row3col{checked, @ref overview_xrcformat_type_bool, + Should the button be checked/pressed initially (default: 0)?} +@endTable + + @subsubsection xrc_wxbutton wxButton @beginTable @hdr3col{property, type, description} @row3col{label, @ref overview_xrcformat_type_text, - Label to display on the button (required).} + Label to display on the button (may be empty if only bitmap is used).} +@row3col{bitmap, @ref overview_xrcformat_type_bitmap, + Bitmap to display in the button (optional).} +@row3col{bitmapposition, @c wxLEFT|wxRIGHT|wxTOP|wxBOTTOM, + Position of the bitmap in the button, see wxButton::SetBitmapPosition().} @row3col{default, @ref overview_xrcformat_type_bool, - Should this button be the default button in dialog (default: 0)?} + Should this button be the default button in dialog (default: 0)?} @endTable @@ -607,7 +682,7 @@ No additional properties. @beginTable @hdr3col{property, type, description} -@row3col{content, , +@row3col{content, items, Content of the control; this property has any number of @c \ 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).} -@row3col{content, , +@row3col{content, items, Content of the control; this property has any number of @c \ XML elements as its children, with the items text as their text values (default: empty).} @@ -660,11 +735,10 @@ Example: @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 -@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} @@ -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).} +@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 @@ -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. +@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 @@ -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).} -@row3col{content, , +@row3col{content, items, Content of the control; this property has any number of @c \ 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 +@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 @@ -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, - 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 @@ -868,13 +977,49 @@ page. @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 + + 32,32 + + + +@endcode + +In the specific case of the @ref xrc_wxlistctrl, the tag can take the name +@c \ 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).} -@row3col{content, , +@row3col{content, items, Content of the control; this property has any number of @c \ XML elements as its children, with the items text as their text values (default: empty).} @@ -898,11 +1043,10 @@ Example: @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 -@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} @@ -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).} +@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 @@ -919,7 +1066,85 @@ Each @c listbookpage has exactly one non-toplevel window as its child. @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 \ tag for the control with @c wxLC_ICON +style or using @c \ 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 @@ -1030,10 +1255,9 @@ class. @subsubsection xrc_wxnotebook wxNotebook -No additional properties. - 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} @@ -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).} +@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 @@ -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).} -@row3col{content, , +@row3col{content, items, Content of the control; this property has any number of @c \ XML elements as its children, with the items text as their text values (see below; default: empty).} @@ -1184,6 +1411,53 @@ Example: @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 + + + + + + + + open.xpm + + + + + + + + + + + + zoomin.xpm + + + zoomout.xpm + + + + + +@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 + + AddHandler(new wxRibbonXmlHandler); +@endcode +to use it. + + @subsubsection xrc_wxrichtextctrl wxRichTextCtrl @beginTable @@ -1194,6 +1468,15 @@ Example: 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 + + AddHandler(new wxRichTextCtrl); +@endcode +to use it. + @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, - 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 @@ -1297,7 +1580,12 @@ HTML markup. Note that the markup has to be escaped: @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 @@ -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).} -@row3col{minsize, @ref overview_xrcformat_type_float, +@row3col{gravity, @ref overview_xrcformat_type_float, 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 - 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 @@ -1376,7 +1665,7 @@ No additional properties. @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 @@ -1391,7 +1680,12 @@ No additional properties. @endTable -@subsubsection xrc_wxtogglebuttton wxToggleButton +@subsubsection xrc_wxtimepickerctrl wxTimePickerCtrl + +No additional properties. + + +@subsubsection xrc_wxtogglebutton wxToggleButton @beginTable @hdr3col{property, type, description} @@ -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 -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: @@ -1442,17 +1738,19 @@ properties: @row3col{toggle, @ref overview_xrcformat_type_bool, Item's kind is wxITEM_CHECK (default: 0)?} @row3col{dropdown, see below, - Item's kind is wxITEM_DROPDOWN (default: 0)? (@since 2.9.0)} + Item's kind is wxITEM_DROPDOWN (default: 0)? (only available since wxWidgets 2.9.0)} @row3col{tooltip, @ref overview_xrcformat_type_text, Tooltip to use for the tool (default: none).} @row3col{longhelp, @ref overview_xrcformat_type_text, 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 -wxITEM_DROPDOWN. It must be either empty or contain exactly one wxMenu @ref +wxITEM_DROPDOWN. It must be either empty or contain exactly one @ref xrc_wxmenu child object defining the drop-down button associated menu. Notice that @c radio, @c toggle and @c dropdown are mutually exclusive. @@ -1473,6 +1771,7 @@ Example: bar.png + view.png @@ -1487,7 +1786,7 @@ Example: - + Just @@ -1500,18 +1799,42 @@ Example: @endcode +@subsubsection xrc_wxtoolbook wxToolbook + +A toolbook can have one or more child objects of the @c toolbookpage +pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its +@c notebookpage) and one child object of the @ref xrc_wximagelist class. +@c toolbookpage objects have the following properties: + +@beginTable +@hdr3col{property, type, description} +@row3col{label, @ref overview_xrcformat_type_text, + Sheet page's title (required).} +@row3col{bitmap, @ref overview_xrcformat_type_bitmap, + Bitmap shown alongside the label (default: none).} +@row3col{image, integer, + The zero-based index of the image associated with the item + into the image list.} +@row3col{selected, @ref overview_xrcformat_type_bool, + Is the page selected initially (only one page can be selected; default: 0)?} +@endTable + +Each @c toolbookpage has exactly one non-toplevel window as its child. + + @subsubsection xrc_wxtreectrl wxTreeCtrl +A treectrl can have one child object of the @ref xrc_wximagelist class. + 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 -@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} @@ -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).} +@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{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. @@ -1598,14 +1927,14 @@ wxWizardPageSimple classes. They both support the following properties @endTable wxWizardPageSimple pages are automatically chained together; wxWizardPage pages -transitions must be handled programatically. +transitions must be handled programmatically. @section overview_xrcformat_sizers Sizers Sizers are handled slightly differently in XRC resources than they are in wxWindow hierarchy. wxWindow's sizers hierarchy is parallel to the wxWindow -children hieararchy: child windows are children of their parent window and +children hierarchy: child windows are children of their parent window and the sizer (or sizers) form separate hierarchy attached to the window with wxWindow::SetSizer(). @@ -1666,8 +1995,8 @@ Example of sizers XRC code: 0 0 0 - 0 - 0 + 0:1 + 0:1 wxALIGN_CENTRE|wxALL 5 @@ -1734,8 +2063,8 @@ class-specific properties. All classes support the following properties: @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 @@ -1744,16 +2073,26 @@ class-specific properties. All classes support the following properties: @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{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, - 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, - 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 @@ -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).} +@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, - 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, - 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 @@ -1781,7 +2130,7 @@ class-specific properties. All classes support the following properties: @subsection overview_xrcformat_wxstddialogbuttonsizer wxStdDialogButtonSizer -Unlike other sizers, wxStdDialogButtonSizer doesn't have neither @c sizeritem +Unlike other sizers, wxStdDialogButtonSizer has neither @c sizeritem nor @c spacer children. Instead, it has one or more children of the @c button pseudo-class. @c button objects have no properties and they must always have exactly one child of the @c wxButton class or a class derived from @@ -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 } -@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 @@ -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 + + + + ... + + + + ... + + +@endcode + +For the range foo, no @em size or @em start parameters were given, so the size +will be calculated from the number of range items, and IDs allocated by +wxWindow::NewControlId (so they'll be negative). Range bar asked for a size of +30, so this will be its minimum size: should it have more items, the range will +automatically expand to fit them. It specified a start ID of 10000, so +XRCID("bar[0]") will be 10000, XRCID("bar[1]") 10001 etc. Note that if you +choose to supply a start value it must be positive, and it's your +responsibility to avoid clashes. + +For every ID range, the first item can be referenced either as +rangename[0] or rangename[start]. Similarly +rangename[end] is the last item. Using [start] and [end] is more +descriptive in e.g. a Bind() event range or a @em for loop, and they don't have +to be altered whenever the number of items changes. + +Whether a range has positive or negative IDs, [start] is always a smaller +number than [end]; so code like this works as expected: + +@code +for (int n=XRCID("foo[start]"); n <= XRCID("foo[end]"); ++n) + ... +@endcode + +ID ranges can be seen in action in the objref dialog section of the +@sample{xrc}. + +@note +@li All the items in an ID range must be contained in the same XRC file. +@li You can't use an ID range in a situation where static initialisation +occurs; in particular, they won't work as expected in an event table. This is +because the event table's IDs are set to their integer values before the XRC +file is loaded, and aren't subsequently altered when the XRCID value changes. + +@since 2.9.2 + @section overview_xrcformat_extending Extending the XRC Format The XRC format is designed to be extensible and allows specifying and loading @@ -1954,7 +2361,7 @@ Child elements of @c \ are handled by the custom handler and there are no limitations on them imposed by XRC format. This is the only mechanism that works for toplevel objects -- custom controls -are accessible using type-unsafe wxXmlResource::LoadObject() method. +are accessible using the type-unsafe wxXmlResource::LoadObject() method.