X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/5852e62f1fe76907832ba2c7f2b4099635e44c4b..7447d53c35249d42128d6243c90998f03882859a:/docs/doxygen/overviews/xrc_format.h diff --git a/docs/doxygen/overviews/xrc_format.h b/docs/doxygen/overviews/xrc_format.h index ab672a8882..dd14c10f1e 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 ///////////////////////////////////////////////////////////////////////////// @@ -31,6 +31,7 @@ Table of contents: - @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 @@ -213,11 +214,11 @@ For example, "my_dlg" in this snippet: My dialog 1 - + @endcode is identical to: @code - + My dialog 400,400 1 @@ -525,6 +526,27 @@ controls cannot have children. @endTable +@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,6 +607,17 @@ 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 @@ -694,6 +727,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 @@ -917,7 +967,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: @@ -1010,6 +1060,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 @@ -1410,7 +1462,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 @@ -1537,7 +1589,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} @@ -1597,6 +1654,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 @@ -1649,6 +1708,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. @@ -1676,6 +1758,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. @@ -1751,14 +1836,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(). @@ -1934,7 +2019,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 @@ -2005,7 +2090,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 @@ -2020,6 +2105,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 @@ -2107,7 +2250,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.