X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/0654158b184927ac997c56b312fc081515cc9c63..e87d78bb36f371d593137761158118fb09b69fa2:/docs/doxygen/overviews/xrc_format.h diff --git a/docs/doxygen/overviews/xrc_format.h b/docs/doxygen/overviews/xrc_format.h index 3d8312cd94..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 @@ -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 @@ -525,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 @@ -585,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 @@ -690,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 @@ -913,7 +996,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, - 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: @@ -1006,6 +1089,8 @@ following properties: 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 @@ -1326,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 @@ -1336,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 @@ -1406,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 @@ -1439,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 @@ -1483,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 @@ -1533,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} @@ -1566,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: @@ -1591,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)?} +@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 @@ -1615,6 +1771,7 @@ Example: bar.png + view.png @@ -1629,7 +1786,7 @@ Example: - + Just @@ -1642,6 +1799,29 @@ 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. @@ -1669,6 +1849,9 @@ pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its into the image list.} @row3col{selected, @ref overview_xrcformat_type_bool, Is the page selected initially (only one page can be selected; default: 0)?} +@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. @@ -1744,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(). @@ -1812,8 +1995,8 @@ Example of sizers XRC code: 0 0 0 - 0 - 0 + 0:1 + 0:1 wxALIGN_CENTRE|wxALL 5 @@ -1894,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{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 @@ -1908,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 @@ -1927,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 @@ -1998,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 @@ -2013,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 @@ -2100,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.