X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/0e32e86acd2334356ab2bb7cb57e13e682ce35f7..2e18fe7139558b3cb592a04a4e4668319a966ebf:/docs/doxygen/overviews/xrc_format.h diff --git a/docs/doxygen/overviews/xrc_format.h b/docs/doxygen/overviews/xrc_format.h index 28845bfd4a..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 @@ -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 - (""), 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 +214,11 @@ For example, "my_dlg" in this snippet: My dialog 1 - + @endcode is identical to: @code - + My dialog 400,400 1 @@ -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).} +@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 +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).} +@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 +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 @@ -576,14 +607,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 @@ -660,11 +706,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 +717,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 +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 @@ -769,6 +834,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 +857,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,6 +948,42 @@ 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 @@ -898,11 +1014,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 +1025,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 +1037,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 +1226,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 +1236,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 @@ -1264,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 @@ -1310,7 +1508,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 @@ -1376,7 +1574,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 +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} @@ -1424,7 +1627,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: @@ -1449,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 @@ -1473,6 +1680,7 @@ Example: bar.png + view.png @@ -1487,7 +1695,7 @@ Example: - + Just @@ -1500,18 +1708,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 +1753,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 +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(). @@ -1781,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 @@ -1852,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 @@ -1867,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 @@ -1954,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.