1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: XRC format specification
4 // Author: Vaclav Slavik
5 // Licence: wxWindows licence
6 /////////////////////////////////////////////////////////////////////////////
10 NOTE: To make doxygen happy about <custom-tags> we're forced to
11 escape all < and > symbols which appear inside a doxygen comment.
12 Also, don't use < and > symbols in section titles.
18 @page overview_xrcformat XRC File Format
22 This document describes the format of XRC resource files, as used by
25 XRC file is a XML file with all of its elements in the
26 @c http://www.wxwidgets.org/wxxrc namespace. For backward compatibility,
27 @c http://www.wxwindows.org/wxxrc namespace is accepted as well (and treated
28 as identical to @c http://www.wxwidgets.org/wxxrc), but it shouldn't be used
31 XRC file contains definitions for one or more @em objects -- typically
32 windows. The objects may themselves contain child objects.
34 Objects defined at the top level, under the
35 @ref overview_xrcformat_root "root element", can be accessed using
36 wxXmlResource::LoadDialog() and other LoadXXX methods. They must have
37 @c name attribute that is used as LoadXXX's argument (see
38 @ref overview_xrcformat_object for details).
40 Child objects are not directly accessible via wxXmlResource, they can only
41 be accessed using XRCCTRL().
45 @section overview_xrcformat_root Resource Root Element
47 The root element is always @c \<resource\>. It has one optional attribute, @c
48 version. If set, it specifies version of the file. In absence of @c version
49 attribute, the default is @c "0.0.0.0".
51 The version consists of four integers separated by periods. The first three
52 components are major, minor and release number of the wxWidgets release when
53 the change was introduced, the last one is revision number and is 0 for the
54 first incompatible change in given wxWidgets release, 1 for the second and so
55 on. The version changes only if there was an incompatible change introduced;
56 merely adding new kind of objects does not constitute incompatible change.
58 At the time of writing, the latest version is @c "2.5.3.0".
60 Note that even though @c version attribute is optional, it should always be
61 specified to take advantage of the latest capabilities:
65 <resource xmlns="http://www.wxwidgets.org/wxxrc" version="2.5.3.0">
70 @c \<resource\> may have arbitrary number of
71 @ref overview_xrcformat_objects "object elements" as its children; they are referred
72 to as @em toplevel objects in the rest of this document. Unlike objects defined
73 deeper in the hierarchy, toplevel objects @em must have their @c name attribute
74 set and it must be set to a value unique among root's children.
78 @section overview_xrcformat_objects Defining Objects
80 @subsection overview_xrcformat_object Object Element
82 The @c \<object\> element represents a single object (typically a GUI element)
83 and it usually maps directly to a wxWidgets class instance. It has one
84 mandatory attribute, @c class, and optional @c name and @c subclass attributes.
86 The @c class attribute must always be present, it tells XRC what wxWidgets
87 object should be created and by which wxXmlResourceHandler.
89 @c name is the identifier used to identify the object. This name serves three
92 -# It is used by wxXmlResource's various LoadXXX() methods to find the
93 resource by name passed as argument.
94 -# wxWindow's name (see wxWindow::GetName()) is set to it.
95 -# Numeric ID of a window or menu item is derived from the name.
96 If the value represents an integer (in decimal notation), it is used for
97 the numeric ID unmodified. If it is one of the wxID_XXX literals defined
98 by wxWidgets (see @ref page_stockitems), its respective value is used.
99 Otherwise, the name is transformed into dynamically generated ID. See
100 wxXmlResource::GetXRCID() for more information.
102 Name attributes must be unique at the top level (where the name is used to
103 load resources) and should be unique among all controls within the same
104 toplevel window (wxDialog, wxFrame).
106 The @c subclass attribute optional name of class whose constructor will be
107 called instead of the constructor for "class".
108 See @ref overview_xrcformat_extending_subclass for more details.
110 @c \<object\> element may -- and almost always do -- have children elements.
111 These come in two varieties:
113 -# Object's properties. A @em property is a value describing part of object's
114 behaviour, for example the "label" property on wxButton defines its label.
115 In the most common form, property is a single element with text content
116 ("\<label\>Cancel\</label\>"), but they may use nested subelements too (e.g.
117 @ref overview_xrcformat_type_font "font property"). A property can only be
118 listed once in an object's definition.
119 -# Child objects. Window childs, sizers, sizer items or notebook pages
120 are all examples of child objects. They are represented using nested
121 @c \<object\> elements and are can be repeated more than once. The specifics
122 of which object classes are allowed as children are class-specific and
123 are documented below in @ref overview_xrcformat_controls.
127 <object class="wxDialog" name="example_dialog">
129 <title>Non-Derived Dialog Example</title>
130 <centered>1</centered>
131 <!-- child objects: -->
132 <object class="wxBoxSizer">
133 <orient>wxVERTICAL</orient>
142 @subsection overview_xrcformat_object_ref Object References
144 Anywhere an @c \<object\> element can be used, @c \<object_ref\> may be used
145 instead. @c \<object_ref\> is a @em reference to another named (i.e. with the
146 @c name attribute) @c \<object\> element. It has one mandatory attribute,
147 @c ref, with value containing the name of a named @c \<object\> element. When an
148 @c \<object_ref\> is encountered, a copy of the referenced @c \<object\> element
149 is made in place of @c \<object_ref\> occurrence and processed as usual.
151 For example, the following code:
153 <object class="wxDialog" name="my_dlg">
156 <object_ref name="my_dlg_alias" ref="my_dlg"/>
160 <object class="wxDialog" name="my_dlg">
163 <object class="wxDialog" name="my_dlg_alias">
164 ... <!-- same as in my_dlg -->
168 Additionally, it is possible to override some parts of the referenced object
169 in the @c \<object_ref\> pointing to it. This is useful for putting repetitive
170 parts of XRC definitions into a template that can be reused and customized in
171 several places. The two parts are merged as follows:
173 -# The referred object is used as the initial content.
174 -# All attributes set on @c \<object_ref\> are added to it.
175 -# All child elements of @c \<object_ref\> are scanned. If an element with
176 the same name (and, if specified, the @c name attribute too) is found
177 in the referred object, they are recursively merged.
178 -# Child elements in @c \<object_ref\> that do not have a match in the referred
179 object are appended to the list of children of the resulting element by
180 default. Optionally, they may have @c insert_at attribute with two possible
181 values, "begin" or "end". When set to "begin", the element is prepended to
182 the list of children instead of appended.
184 For example, "my_dlg" in this snippet:
186 <object class="wxDialog" name="template">
187 <title>Dummy dialog</title>
190 <object_ref ref="template" name="my_dlg">
191 <title>My dialog</title>
192 <centered>1</centered>
197 <object class="wxDialog" name="my_dlg">
198 <title>My dialog</title>
200 <centered>1</centered>
205 @section overview_xrcformat_datatypes Data Types
207 There are several property data types that are frequently reused by different
208 properties. Rather than describing their format in the documentation of
209 every property, we list commonly used types in this section and document
213 @subsection overview_xrcformat_type_bool Boolean
215 Boolean values are expressed using either "1" literal (true) or "0" (false).
218 @subsection overview_xrcformat_type_float Floating-point value
220 Floating point values use POSIX (C locale) formatting -- decimal separator
221 is "." regardless of the locale.
224 @subsection overview_xrcformat_type_colour Colour
226 Colour specification can be either any string colour representation accepted
227 by wxColour::Set() or any wxSYS_COLOUR_XXX symbolic name accepted by
228 wxSystemSettings::GetColour(). In particular, the following forms are supported:
230 @li named colours from wxColourDatabase
231 @li HTML-like "#rrggbb" syntax (but not "#rgb")
232 @li CSS-style "rgb(r,g,b)" and "rgba(r,g,b,a)"
233 @li wxSYS_COLOUR_XXX symbolic names
239 <fg>rgb(255,0,0)</fg>
240 <fg>wxSYS_COLOUR_HIGHLIGHT</fg>
244 @subsection overview_xrcformat_type_size Size
246 Sizes and positions have the form of string with two comma-separated integer
247 components, with optional "d" suffix. Semi-formally:
249 size := x "," y ["d"]
251 where x and y are integers. Either of the components (or both) may be "-1" to
252 signify default value. As a shortcut, empty string is equivalent to "-1,-1"
253 (= wxDefaultSize or wxDefaultPosition).
255 When the "d" suffix is used, integer values are interpreted as
256 @ref wxWindow::ConvertDialogToPixels() "dialog units" in the parent window.
265 @subsection overview_xrcformat_type_pos Position
267 Same as @ref overview_xrcformat_type_size.
270 @subsection overview_xrcformat_type_dimension Dimension
272 Similarly to @ref overview_xrcformat_type_size "sizes", dimensions are expressed
273 as integers with optional "d" suffix. When "d" suffix is used, the integer
274 preceding it is interpreted as dialog units in the parent window.
277 @subsection overview_xrcformat_type_text Text
279 String properties use several escape sequences that are translated according to
282 @itemdef{ "_", "&" (used for accelerators in wxWidgets) }
283 @itemdef{ "__", "_" }
284 @itemdef{ "\n", line break }
285 @itemdef{ "\r", carriage return }
286 @itemdef{ "\t", tab }
287 @itemdef{ "\\", "\" }
290 By default, the text is translated using wxLocale::GetTranslation() before
291 it is used. This can be disabled either globally by not passing
292 wxXRC_USE_LOCALE to wxXmlResource constructor, or by setting the @c translate
293 attribute on the property node to "0":
295 <!-- this is not translated: -->
296 <label translate="0">_Unix</label>
297 <!-- but this is: -->
298 <help>Use Unix-style newlines</help>
301 @note Even though the "_" character is used instead of "&" for accelerators,
302 it is still possible to use "&". The latter has to be encoded as "&",
303 though, so using "_" is more convenient.
305 @see @ref overview_xrcformat_pre_v2530, @ref overview_xrcformat_pre_v2301
308 @subsection overview_xrcformat_type_text_notrans Non-Translatable Text
310 Like @ref overview_xrcformat_type_text, but the text is never translated and
311 @c translate attribute cannot be used.
314 @subsection overview_xrcformat_type_string String
316 An unformatted string. Unlike with @ref overview_xrcformat_type_text, no escaping
317 or translations are done.
320 @subsection overview_xrcformat_type_url URL
322 Any URL accepted by wxFileSystem (typically relative to XRC file's location,
323 but can be absolute too). Unlike with @ref overview_xrcformat_type_text, no escaping
324 or translations are done.
327 @subsection overview_xrcformat_type_bitmap Bitmap
329 Bitmap properties contain specification of a single bitmap or icon. In the most
330 basic form, their text value is simply a relative filename (or another
331 wxFileSystem URL) of the bitmap to use. For example:
333 <object class="tool" name="wxID_NEW">
334 <tooltip>New</tooltip>
335 <bitmap>new.png</bitmap>
338 The value is interpreted as path relative to the location of XRC file where the
341 Alternatively, it is possible to specify the bitmap using wxArtProvider IDs.
342 In this case, the property element has no textual value (filename) and instead
343 has the @c stock_id XML attribute that contains stock art ID as accepted by
344 wxArtProvider::GetBitmap(). This can be either custom value (if the app uses
345 app-specific art provider) or one of the predefined wxART_XXX constants.
347 Optionally, @c stock_client attribute may be specified too and contain one of
348 the predefined wxArtClient values. If it is not specified, the default client
349 ID most appropriate in the context where the bitmap is referenced will be used.
350 In most cases, specifying @c stock_client is not needed.
352 Examples of stock bitmaps usage:
354 <bitmap stock_id="fixed-width"/> <!-- custom app-specific art -->
355 <bitmap stock_id="wxART_FILE_OPEN"/> <!-- standard art -->
358 Specifying the bitmap directly and using @c stock_id are mutually exclusive.
361 @subsection overview_xrcformat_type_style Style
363 Style properties (such as window's style or sizer flags) use syntax similar to
364 C++: the style value is OR-combination of individual flags. Symbolic names
365 identical to those used in C++ code are used for the flags. Flags are separated
366 with "|" (whitespace is allowed but not required around it).
368 The flags that are allowed for a given property are context-dependent.
372 <style>wxCAPTION|wxSYSTEM_MENU | wxRESIZE_BORDER</style>
373 <exstyle>wxDIALOG_EX_CONTEXTHELP</exstyle>
377 @subsection overview_xrcformat_type_font Font
379 XRC uses similar, but more flexible, abstract description of fonts to that
380 used by wxFont class. A font can be described either in terms of its elementary
381 properties, or it can be derived from one of system fonts or the parent window
384 The font property element is "composite" element: unlike majority of
385 properties, it doesn't have text value but contains several child elements
386 instead. These children are handled in the same way as object properties
387 and can be one of the following "sub-properties":
390 @hdr3col{property, type, description}
391 @row3col{size, unsigned integer,
392 Pixel size of the font (default: wxNORMAL_FONT's size or @c sysfont's
393 size if the @c sysfont property is used or the current size of the font
394 of the enclosing control if the @c inherit property is used.}
395 @row3col{style, enum,
396 One of "normal", "italic" or "slant" (default: normal).}
397 @row3col{weight, enum,
398 One of "normal", "bold" or "light" (default: normal).}
399 @row3col{family, enum,
400 One of "roman", "script", "decorative", "swiss", "modern" or "teletype"
402 @row3col{underlined, @ref overview_xrcformat_type_bool,
403 Whether the font should be underlined (default: 0).}
405 Comma-separated list of face names; the first one available is used
406 (default: unspecified).}
408 Charset of the font, unused in Unicode build), as string
409 (default: unspecified).}
411 Symbolic name of system standard font(one of wxSYS_*_FONT constants).}
412 @row3col{inherit, @ref overview_xrcformat_type_bool,
413 If true, the font of the enclosing control is used. If this property and the
414 @c sysfont property are specified the @c sysfont property takes precedence.}
415 @row3col{relativesize, float,
416 Float, font size relative to chosen system font's or inherited font's size;
417 can only be used when 'sysfont' or 'inherit' is used and when 'size' is not
421 All of them are optional, if they are missing, appropriate wxFont default is
422 used. If the @c sysfont or @c inherit property is used, then the defaults are
423 taken from it instead.
428 <!-- fixed font: Arial if available, fall back to Helvetica -->
429 <face>arial,helvetica</face>
434 <!-- enlarged, enboldened standard font: -->
435 <sysfont>wxSYS_DEFAULT_GUI_FONT</sysfont>
436 <weight>bold</weight>
437 <relativesize>1.5</relativesize>
441 @note You cannot use @c inherit for a font that gets used before the enclosing
442 control is created, e.g. if the control gets the font passed as parameter
443 for its constructor, or if the control is not derived from wxWindow.
446 @section overview_xrcformat_windows Controls and Windows
448 This section describes support wxWindow-derived classes in XRC format.
450 @subsection overview_xrcformat_std_props Standard Properties
452 The following properties are always (unless stated otherwise in
453 control-specific docs) available for @em windows objects. They are omitted
454 from properties lists below.
457 @hdr3col{property, type, description}
458 @row3col{pos, @ref overview_xrcformat_type_pos,
459 Initial position of the window (default: wxDefaultPosition).}
460 @row3col{size, @ref overview_xrcformat_type_size,
461 Initial size of the window (default: wxDefaultSize).}
462 @row3col{style, @ref overview_xrcformat_type_style,
463 Window style for this control. The allowed values depend on what
464 window is being created, consult respective class' constructor
465 documentation for details (default: window-dependent default, usually
466 wxFOO_DEFAULT_STYLE if defined for class wxFoo, 0 if not).}
467 @row3col{exstyle, @ref overview_xrcformat_type_style,
468 Extra style for the window, if any. See wxWindow::SetExtraStyle()
470 @row3col{fg, @ref overview_xrcformat_type_colour,
471 Foreground colour of the window (default: window's default).}
472 @row3col{ownfg, @ref overview_xrcformat_type_colour,
473 Non-inheritable foreground colour of the window, see
474 wxWindow::SetOwnForegroundColour() (default: none).}
475 @row3col{bg, @ref overview_xrcformat_type_colour,
476 Background colour of the window (default: window's default).}
477 @row3col{ownbg, @ref overview_xrcformat_type_colour,
478 Non-inheritable background colour of the window, see
479 wxWindow::SetOwnBackgroundColour() (default: none).}
480 @row3col{enabled, @ref overview_xrcformat_type_bool,
481 If set to 0, the control is disabled (default: 1).}
482 @row3col{hidden, @ref overview_xrcformat_type_bool,
483 If set to 1, the control is created hidden (default: 0).}
484 @row3col{tooltip, @ref overview_xrcformat_type_text,
485 Tooltip to use for the control (default: not set).}
486 @row3col{font, @ref overview_xrcformat_type_font,
487 Font to use for the control (default: window's default).}
488 @row3col{ownfont, @ref overview_xrcformat_type_font,
489 Non-inheritable font to use for the control, see
490 wxWindow::SetOwnFont() (default: none).}
491 @row3col{help, @ref overview_xrcformat_type_text,
492 Context-sensitive help for the control, used by wxHelpProvider
496 All of these properties are optional.
499 @subsection overview_xrcformat_controls Supported Controls
501 This section lists all controls supported by default. For each control, its
502 control-specific properties are listed. If the control can have child objects,
503 it is documented there too; unless said otherwise, XRC elements for these
504 controls cannot have children.
506 @subsubsection xrc_wxanimationctrl wxAnimationCtrl
509 @hdr3col{property, type, description}
510 @row3col{animation, @ref overview_xrcformat_type_url,
511 Animation file to load into the control (required).}
515 @subsubsection xrc_wxauinotebook wxAuiNotebook
517 A wxAuiNotebook can have one or more child objects of the @c notebookpage
519 @c notebookpage objects have the following properties:
522 @hdr3col{property, type, description}
523 @row3col{label, @ref overview_xrcformat_type_text,
524 Page label (required).}
525 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
526 Bitmap shown alongside the label (default: none).}
527 @row3col{selected, @ref overview_xrcformat_type_bool,
528 Is the page selected initially (only one page can be selected; default: 0)?}
531 Each @c notebookpage must have exactly one non-toplevel window as its child.
535 <object class="wxAuiNotebook">
536 <style>wxBK_BOTTOM</style>
537 <object class="notebookpage">
538 <label>Page 1</label>
539 <bitmap>bitmap.png</bitmap>
540 <object class="wxPanel" name="page_1">
547 Notice that wxAuiNotebook support in XRC is available in wxWidgets 2.9.5 and
548 later only and you need to explicitly register its handler using
550 #include <wx/xrc/xh_auinotbk.h>
552 AddHandler(new wxAuiNotebookXmlHandler);
557 @subsubsection xrc_wxbannerwindow wxBannerWindow
560 @hdr3col{property, type, description}
561 @row3col{direction, @c wxLEFT|wxRIGHT|wxTOP|wxBOTTOM,
562 The side along which the banner will be positioned (default: wxLEFT).}
563 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
564 Bitmap to use as the banner background (default: none).}
565 @row3col{title, @ref overview_xrcformat_type_text,
566 Banner title, should be single line (default: none).}
567 @row3col{message, @ref overview_xrcformat_type_text,
568 Possibly multi-line banner message (default: none).}
569 @row3col{gradient-start, @ref overview_xrcformat_type_colour,
570 Starting colour of the gradient used as banner background.
571 (Optional. Can't be used if a valid bitmap is specified. If used, both gradient values must be set.)}
572 @row3col{gradient-end, @ref overview_xrcformat_type_colour,
573 End colour of the gradient used as banner background.
574 (Optional. Can't be used if a valid bitmap is specified. If used, both gradient values must be set.)}
578 @subsubsection xrc_wxbitmapbutton wxBitmapButton
581 @hdr3col{property, type, description}
582 @row3col{default, @ref overview_xrcformat_type_bool,
583 Should this button be the default button in dialog (default: 0)?}
584 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
585 Bitmap to show on the button (required).}
586 @row3col{selected, @ref overview_xrcformat_type_bitmap,
587 Bitmap to show when the button is selected (default: none, same as @c bitmap).}
588 @row3col{focus, @ref overview_xrcformat_type_bitmap,
589 Bitmap to show when the button has focus (default: none, same as @c bitmap).}
590 @row3col{disabled, @ref overview_xrcformat_type_bitmap,
591 Bitmap to show when the button is disabled (default: none, same as @c bitmap).}
592 @row3col{hover, @ref overview_xrcformat_type_bitmap,
593 Bitmap to show when mouse cursor hovers above the bitmap (default: none, same as @c bitmap).}
597 @subsubsection xrc_wxbitmapcombobox wxBitmapComboBox
600 @hdr3col{property, type, description}
601 @row3col{selection, integer,
602 Index of the initially selected item or -1 for no selection (default: -1).}
603 @row3col{value, @ref overview_xrcformat_type_string,
604 Initial value in the control (doesn't have to be one of @ content values;
608 If both @c value and @c selection are specified and @c selection is not -1,
609 then @c selection takes precedence.
611 A wxBitmapComboBox can have one or more child objects of the @c ownerdrawnitem
612 pseudo-class. @c ownerdrawnitem objects have the following properties:
615 @hdr3col{property, type, description}
616 @row3col{text, @ref overview_xrcformat_type_text,
617 Item's label (required).}
618 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
619 Item's bitmap (default: no bitmap).}
624 <object class="wxBitmapComboBox">
625 <selection>1</selection>
626 <object class="ownerdrawnitem">
628 <bitmap>foo.png</bitmap>
630 <object class="ownerdrawnitem">
632 <bitmap>bar.png</bitmap>
638 @subsubsection xrc_wxbitmaptogglebutton wxBitmapToggleButton
641 @hdr3col{property, type, description}
642 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
643 Label to display on the button (required).}
644 @row3col{checked, @ref overview_xrcformat_type_bool,
645 Should the button be checked/pressed initially (default: 0)?}
649 @subsubsection xrc_wxbutton wxButton
652 @hdr3col{property, type, description}
653 @row3col{label, @ref overview_xrcformat_type_text,
654 Label to display on the button (may be empty if only bitmap is used).}
655 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
656 Bitmap to display in the button (optional).}
657 @row3col{bitmapposition, @c wxLEFT|wxRIGHT|wxTOP|wxBOTTOM,
658 Position of the bitmap in the button, see wxButton::SetBitmapPosition() (default: wxLEFT).}
659 @row3col{default, @ref overview_xrcformat_type_bool,
660 Should this button be the default button in dialog (default: 0)?}
664 @subsubsection xrc_wxcalendarctrl wxCalendarCtrl
666 No additional properties.
669 @subsubsection xrc_wxcheckbox wxCheckBox
672 @hdr3col{property, type, description}
673 @row3col{label, @ref overview_xrcformat_type_text,
674 Label to use for the checkbox (required).}
675 @row3col{checked, @ref overview_xrcformat_type_bool,
676 Should the checkbox be checked initially (default: 0)?}
680 @subsubsection xrc_wxchecklistbox wxCheckListBox
683 @hdr3col{property, type, description}
684 @row3col{content, items,
685 Content of the control; this property has any number of @c \<item\> XML
686 elements as its children, with the items text as their text values
690 The @c \<item\> elements have listbox items' labels as their text values. They
691 can also have optional @c checked XML attribute -- if set to "1", the value is
696 <object class="wxCheckListBox">
698 <item checked="1">Download library</item>
699 <item checked="1">Compile samples</item>
700 <item checked="1">Skim docs</item>
701 <item checked="1">Finish project</item>
702 <item>Wash car</item>
708 @subsubsection xrc_wxchoice wxChoice
711 @hdr3col{property, type, description}
712 @row3col{selection, integer,
713 Index of the initially selected item or -1 for no selection (default: -1).}
714 @row3col{content, items,
715 Content of the control; this property has any number of @c \<item\> XML
716 elements as its children, with the items text as their text values
722 <object class="wxChoice" name="controls_choice">
729 <item>The Sixth Sense!</item>
735 @subsubsection xrc_wxchoicebook wxChoicebook
737 A choicebook can have one or more child objects of the @c choicebookpage
738 pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its
739 @c notebookpage) and one child object of the @ref xrc_wximagelist class.
741 @c choicebookpage objects have the following properties:
744 @hdr3col{property, type, description}
745 @row3col{label, @ref overview_xrcformat_type_text,
746 Sheet page's title (required).}
747 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
748 Bitmap shown alongside the label (default: none, mutually exclusive with @c image).}
749 @row3col{image, integer,
750 The zero-based index of the image associated with the item
751 into the image list (default: none, mutually exclusive with @c bitmap, parent must have @ref xrc_wximagelist).}
752 @row3col{selected, @ref overview_xrcformat_type_bool,
753 Is the page selected initially (only one page can be selected; default: 0)?}
756 Each @c choicebookpage has exactly one non-toplevel window as its child.
759 @subsubsection xrc_wxcommandlinkbutton wxCommandLinkButton
761 The wxCommandLinkButton contains a main title-like @c label and an optional
762 @c note for longer description. The main @c label and the @c note can be
763 concatenated into a single string using a new line character between them
764 (notice that the @c note part can have more new lines in it).
767 @hdr3col{property, type, description}
768 @row3col{label, @ref overview_xrcformat_type_text,
769 First line of text on the button, typically the label of an action that
770 will be made when the button is pressed (required). }
771 @row3col{note, @ref overview_xrcformat_type_text,
772 Second line of text describing the action performed when the button is pressed (default: none). }
776 @subsubsection xrc_wxcollapsiblepane wxCollapsiblePane
779 @hdr3col{property, type, description}
780 @row3col{label, @ref overview_xrcformat_type_text,
781 Label to use for the collapsible section (required).}
782 @row3col{collapsed, @ref overview_xrcformat_type_bool,
783 Should the pane be collapsed initially (default: 0)?}
786 wxCollapsiblePane may contain single optional child object of the @c panewindow
787 pseudo-class type. @c panewindow itself must contain exactly one child that
788 is a @ref overview_xrcformat_sizers "sizer" or a non-toplevel window
792 @subsubsection xrc_wxcolourpickerctrl wxColourPickerCtrl
795 @hdr3col{property, type, description}
796 @row3col{value, @ref overview_xrcformat_type_colour,
797 Initial value of the control (default: wxBLACK).}
801 @subsubsection xrc_wxcombobox wxComboBox
804 @hdr3col{property, type, description}
805 @row3col{selection, integer,
806 Index of the initially selected item or -1 for no selection (default: not used).}
807 @row3col{content, items,
808 Content of the control; this property has any number of @c \<item\> XML
809 elements as its children, with the items text as their text values
811 @row3col{value, @ref overview_xrcformat_type_string,
812 Initial value in the control (doesn't have to be one of @ content values;
816 If both @c value and @c selection are specified and @c selection is not -1,
817 then @c selection takes precedence.
821 <object class="wxComboBox" name="controls_combobox">
822 <style>wxCB_DROPDOWN</style>
827 <item>notepad.exe</item>
834 @subsubsection xrc_wxcomboctrl wxComboCtrl
837 @hdr3col{property, type, description}
838 @row3col{value, @ref overview_xrcformat_type_string,
839 Initial value in the control (default: empty).}
843 @subsubsection xrc_wxdatepickerctrl wxDatePickerCtrl
845 No additional properties.
848 @subsubsection xrc_wxdialog wxDialog
851 @hdr3col{property, type, description}
852 @row3col{title, @ref overview_xrcformat_type_text,
853 Dialog's title (default: empty).}
854 @row3col{icon, @ref overview_xrcformat_type_bitmap,
855 Dialog's icon (default: not used).}
856 @row3col{centered, @ref overview_xrcformat_type_bool,
857 Whether the dialog should be centered on the screen (default: 0).}
860 wxDialog may have optional children: either exactly one
861 @ref overview_xrcformat_sizers "sizer" child or any number of non-toplevel window
862 objects. If sizer child is used, it sets
863 @ref wxSizer::SetSizeHints() "size hints" too.
866 @subsubsection xrc_wxdirpickerctrl wxDirPickerCtrl
869 @hdr3col{property, type, description}
870 @row3col{value, @ref overview_xrcformat_type_string,
871 Initial value of the control (default: empty).}
872 @row3col{message, @ref overview_xrcformat_type_text,
873 Message shown to the user in wxDirDialog shown by the control (required).}
877 @subsubsection xrc_wxeditablelistbox wxEditableListBox
880 @hdr3col{property, type, description}
881 @row3col{label, @ref overview_xrcformat_type_text,
882 Label shown above the list (default: empty).}
883 @row3col{content, items,
884 Content of the control; this property has any number of @c \<item\> XML
885 elements as its children, with the items text as their text values
891 <object class="wxEditableListBox" name="controls_listbox">
893 <label>List of things</label>
898 <item>Orange juice</item>
899 <item>Paper towels</item>
905 @subsubsection xrc_wxfilectrl wxFileCtrl
908 @hdr3col{property, type, description}
909 @row3col{defaultdirectory, @ref overview_xrcformat_type_string,
910 Sets the current directory displayed in the control. }
911 @row3col{defaultfilename, @ref overview_xrcformat_type_string,
912 Selects a certain file.}
913 @row3col{wildcard, @ref overview_xrcformat_type_string,
914 Sets the wildcard, which can contain multiple file types, for example:
915 "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
916 (default: all files).}
920 @subsubsection xrc_wxfilepickerctrl wxFilePickerCtrl
923 @hdr3col{property, type, description}
924 @row3col{value, @ref overview_xrcformat_type_string,
925 Initial value of the control (default: empty).}
926 @row3col{message, @ref overview_xrcformat_type_text,
927 Message shown to the user in wxDirDialog shown by the control (required).}
928 @row3col{wildcard, @ref overview_xrcformat_type_string,
929 Sets the wildcard, which can contain multiple file types, for example:
930 "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
931 (default: all files).}
935 @subsubsection xrc_wxfontpickerctrl wxFontPickerCtrl
938 @hdr3col{property, type, description}
939 @row3col{value, @ref overview_xrcformat_type_font,
940 Initial value of the control (default: wxNORMAL_FONT).}
943 @subsubsection xrc_wxfrane wxFrame
946 @hdr3col{property, type, description}
947 @row3col{title, @ref overview_xrcformat_type_text,
948 Frame's title (default: empty).}
949 @row3col{icon, @ref overview_xrcformat_type_bitmap,
950 Frame's icon (default: not used).}
951 @row3col{centered, @ref overview_xrcformat_type_bool,
952 Whether the frame should be centered on the screen (default: 0).}
955 wxFrame may have optional children: either exactly one
956 @ref overview_xrcformat_sizers "sizer" child or any number of non-toplevel window
957 objects. If sizer child is used, it sets
958 @ref wxSizer::SetSizeHints() "size hints" too.
961 @subsubsection xrc_wxgauge wxGauge
964 @hdr3col{property, type, description}
965 @row3col{range, integer,
966 Maximum value of the gauge (default: 100).}
967 @row3col{value, integer,
968 Initial value of the control (default: 0).}
969 @row3col{shadow, @ref overview_xrcformat_type_dimension,
970 Rendered shadow size (default: none; ignored by most platforms).}
971 @row3col{bezel, @ref overview_xrcformat_type_dimension,
972 Rendered bezel size (default: none; ignored by most platforms).}
975 @subsubsection xrc_wxgenericdirctrl wxGenericDirCtrl
978 @hdr3col{property, type, description}
979 @row3col{defaultfolder, @ref overview_xrcformat_type_text,
980 Initial folder (default: empty).}
981 @row3col{filter, @ref overview_xrcformat_type_text,
982 Filter string, using the same syntax as used by wxFileDialog, e.g.
983 "All files (*.*)|*.*|JPEG files (*.jpg)|*.jpg" (default: empty).}
984 @row3col{defaultfilter, integer,
985 Zero-based index of default filter (default: 0).}
988 @subsubsection xrc_wxgrid wxGrid
990 No additional properties.
993 @subsubsection xrc_wxhtmlwindow wxHtmlWindow
996 @hdr3col{property, type, description}
997 @row3col{url, @ref overview_xrcformat_type_url,
998 Page to display in the window.}
999 @row3col{htmlcode, @ref overview_xrcformat_type_text,
1000 HTML markup to display in the window.}
1001 @row3col{borders, @ref overview_xrcformat_type_dimension,
1002 Border around HTML content (default: 0).}
1005 At most one of @c url and @c htmlcode properties may be specified, they are
1006 mutually exclusive. If neither is set, the window is initialized to show empty
1010 @subsubsection xrc_wxhyperlinkctrl wxHyperlinkCtrl
1013 @hdr3col{property, type, description}
1014 @row3col{label, @ref overview_xrcformat_type_text,
1015 Label to display on the control (required).}
1016 @row3col{url, @ref overview_xrcformat_type_url,
1017 URL to open when the link is clicked (required).}
1021 @subsubsection xrc_wximagelist wxImageList
1023 The imagelist can be used as a child object for the following classes:
1024 - @ref xrc_wxchoicebook
1025 - @ref xrc_wxlistbook
1026 - @ref xrc_wxlistctrl
1027 - @ref xrc_wxnotebook
1028 - @ref xrc_wxtreebook
1029 - @ref xrc_wxtreectrl
1031 The available properties are:
1034 @hdr3col{property, type, description}
1035 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1036 Adds a new image by keeping its optional mask bitmap (see below).}
1037 @row3col{mask, @ref overview_xrcformat_type_bool,
1038 If masks should be created for all images (default: true).}
1039 @row3col{size, @ref overview_xrcformat_type_size,
1040 The size of the images in the list (default: the size of the first bitmap).}
1047 <bitmap stock_id="wxART_QUESTION"/>
1048 <bitmap stock_id="wxART_INFORMATION"/>
1052 In the specific case of the @ref xrc_wxlistctrl, the tag can take the name
1053 @c \<imagelist-small\> to define the 'small' image list, related to the flag
1054 @c wxIMAGE_LIST_SMALL (see wxListCtrl documentation).
1057 @subsubsection xrc_wxlistbox wxListBox
1060 @hdr3col{property, type, description}
1061 @row3col{selection, integer,
1062 Index of the initially selected item or -1 for no selection (default: -1).}
1063 @row3col{content, items,
1064 Content of the control; this property has any number of @c \<item\> XML
1065 elements as its children, with the items text as their text values
1071 <object class="wxListBox" name="controls_listbox">
1072 <size>250,160</size>
1073 <style>wxLB_SINGLE</style>
1078 <item>Orange juice</item>
1079 <item>Paper towels</item>
1085 @subsubsection xrc_wxlistbook wxListbook
1087 A listbook can have one or more child objects of the @c listbookpage
1088 pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its
1089 @c notebookpage) and one child object of the @ref xrc_wximagelist class.
1090 @c listbookpage objects have the following properties:
1093 @hdr3col{property, type, description}
1094 @row3col{label, @ref overview_xrcformat_type_text,
1095 Sheet page's title (required).}
1096 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1097 Bitmap shown alongside the label (default: none).}
1098 @row3col{image, integer,
1099 The zero-based index of the image associated with the item
1100 into the image list.}
1101 @row3col{selected, @ref overview_xrcformat_type_bool,
1102 Is the page selected initially (only one page can be selected; default: 0)?}
1105 Each @c listbookpage has exactly one non-toplevel window as its child.
1108 @subsubsection xrc_wxlistctrl wxListCtrl
1110 A list control can have one or more child objects of the class @ref xrc_wxlistitem
1111 and one or more objects of the @ref xrc_wximagelist class. The latter is
1112 defined either using @c \<imagelist\> tag for the control with @c wxLC_ICON
1113 style or using @c \<imagelist-small\> tag for the control with @c
1114 wxLC_SMALL_ICON style.
1116 Report mode list controls (i.e. created with @c wxLC_REPORT style) can in
1117 addition have one or more @ref xrc_wxlistcol child elements.
1119 @paragraph xrc_wxlistcol listcol
1121 The @c listcol class can only be used for wxListCtrl children. It can have the
1122 following properties:
1124 @hdr3col{property, type, description}
1125 @row3col{align, wxListColumnFormat,
1126 The alignment for the item.
1127 Can be one of @c wxLIST_FORMAT_LEFT, @c wxLIST_FORMAT_RIGHT or
1128 @c wxLIST_FORMAT_CENTRE.}
1129 @row3col{text, @ref overview_xrcformat_type_string,
1130 The title of the column. }
1131 @row3col{width, integer,
1133 @row3col{image, integer,
1134 The zero-based index of the image associated with the item in the 'small' image list. }
1137 The columns are appended to the control in order of their appearance and may be
1138 referenced by 0-based index in the @c col attributes of subsequent @c listitem
1141 @paragraph xrc_wxlistitem listitem
1143 The @c listitem is a child object for the class @ref xrc_wxlistctrl.
1144 It can have the following properties:
1147 @hdr3col{property, type, description}
1148 @row3col{align, wxListColumnFormat,
1149 The alignment for the item.
1150 Can be one of @c wxLIST_FORMAT_LEFT, @c wxLIST_FORMAT_RIGHT or
1151 @c wxLIST_FORMAT_CENTRE.}
1152 @row3col{bg, @ref overview_xrcformat_type_colour,
1153 The background color for the item.}
1154 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1155 Add a bitmap to the (normal) @ref xrc_wximagelist associated with the
1156 @ref xrc_wxlistctrl parent and associate it with this item.
1157 If the imagelist is not defined it will be created implicitly.}
1158 @row3col{bitmap-small, @ref overview_xrcformat_type_bitmap,
1159 Add a bitmap in the 'small' @ref xrc_wximagelist associated with the
1160 @ref xrc_wxlistctrl parent and associate it with this item.
1161 If the 'small' imagelist is not defined it will be created implicitly.}
1162 @row3col{col, integer,
1163 The zero-based column index.}
1164 @row3col{image, integer,
1165 The zero-based index of the image associated with the item
1166 in the (normal) image list.}
1167 @row3col{image-small, integer,
1168 The zero-based index of the image associated with the item
1169 in the 'small' image list.}
1170 @row3col{data, integer,
1171 The client data for the item.}
1172 @row3col{font, @ref overview_xrcformat_type_font,
1173 The font for the item.}
1174 @row3col{image, integer,
1175 The zero-based index of the image associated with the item
1176 into the image list.}
1177 @row3col{state, @ref overview_xrcformat_type_style,
1178 The item state. Can be any combination of the following values:
1179 - @c wxLIST_STATE_FOCUSED: The item has the focus.
1180 - @c wxLIST_STATE_SELECTED: The item is selected.}
1181 @row3col{text, @ref overview_xrcformat_type_string,
1182 The text label for the item. }
1183 @row3col{textcolour, @ref overview_xrcformat_type_colour,
1184 The text colour for the item. }
1187 Notice that the item position can't be specified here, the items are appended
1188 to the list control in order of their appearance.
1191 @subsubsection xrc_wxmdiparentframe wxMDIParentFrame
1193 wxMDIParentFrame supports the same properties that @ref xrc_wxfrane does.
1195 wxMDIParentFrame may have optional children. When used, the child objects
1196 must be of wxMDIChildFrame type.
1199 @subsubsection xrc_wxmdichildframe wxMDIChildFrame
1201 wxMDIChildFrame supports the same properties that @ref xrc_wxfrane and
1202 @ref xrc_wxmdiparentframe do.
1204 wxMDIChildFrame can only be used as as immediate child of @ref
1205 xrc_wxmdiparentframe.
1207 wxMDIChildFrame may have optional children: either exactly one
1208 @ref overview_xrcformat_sizers "sizer" child or any number of non-toplevel window
1209 objects. If sizer child is used, it sets
1210 @ref wxSizer::SetSizeHints() "size hints" too.
1213 @subsubsection xrc_wxmenu wxMenu
1216 @hdr3col{property, type, description}
1217 @row3col{label, @ref overview_xrcformat_type_text,
1218 Menu's label (default: empty, but required for menus other
1220 @row3col{style, @ref overview_xrcformat_type_style,
1221 Window style for the menu.}
1222 @row3col{help, @ref overview_xrcformat_type_text,
1223 Help shown in statusbar when the menu is selected (only for submenus
1224 of another wxMenu, default: none).}
1225 @row3col{enabled, @ref overview_xrcformat_type_bool,
1226 Is the submenu item enabled (only for submenus of another wxMenu,
1230 Note that unlike most controls, wxMenu does @em not have
1231 @ref overview_xrcformat_std_props, with the exception of @c style.
1233 A menu object can have one or more child objects of the wxMenuItem or wxMenu
1234 classes or @c break or @c separator pseudo-classes.
1236 The @c separator pseudo-class is used to insert separators into the menu and
1237 has neither properties nor children. Likewise, @c break inserts a break (see
1240 wxMenuItem objects support the following properties:
1243 @hdr3col{property, type, description}
1244 @row3col{label, @ref overview_xrcformat_type_text,
1245 Item's label (required).}
1246 @row3col{accel, @ref overview_xrcformat_type_text_notrans,
1247 Item's accelerator (default: none).}
1248 @row3col{radio, @ref overview_xrcformat_type_bool,
1249 Item's kind is wxITEM_RADIO (default: 0)?}
1250 @row3col{checkable, @ref overview_xrcformat_type_bool,
1251 Item's kind is wxITEM_CHECK (default: 0)?}
1252 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1253 Bitmap to show with the item (default: none).}
1254 @row3col{bitmap2, @ref overview_xrcformat_type_bitmap,
1255 Bitmap for the checked state (wxMSW, if checkable; default: none).}
1256 @row3col{help, @ref overview_xrcformat_type_text,
1257 Help shown in statusbar when the item is selected (default: none).}
1258 @row3col{enabled, @ref overview_xrcformat_type_bool,
1259 Is the item enabled (default: 1)?}
1260 @row3col{checked, @ref overview_xrcformat_type_bool,
1261 Is the item checked initially (default: 0)?}
1266 <object class="wxMenu" name="menu_edit">
1267 <style>wxMENU_TEAROFF</style>
1268 <label>_Edit</label>
1269 <object class="wxMenuItem" name="wxID_FIND">
1270 <label>_Find...</label>
1271 <accel>Ctrl-F</accel>
1273 <object class="separator"/>
1274 <object class="wxMenuItem" name="menu_fuzzy">
1275 <label>Translation is _fuzzy</label>
1276 <checkable>1</checkable>
1278 <object class="wxMenu" name="submenu">
1279 <label>A submenu</label>
1280 <object class="wxMenuItem" name="foo">...</object>
1283 <object class="separator" platform="unix"/>
1284 <object class="wxMenuItem" name="wxID_PREFERENCES" platform="unix">
1285 <label>_Preferences</label>
1290 @subsubsection xrc_wxmenubar wxMenuBar
1293 @hdr3col{property, type, description}
1294 @row3col{style, @ref overview_xrcformat_type_style,
1295 Window style for the menu bar.}
1298 Note that unlike most controls, wxMenuBar does @em not have
1299 @ref overview_xrcformat_std_props, with the exception of @c style.
1301 A menubar can have one or more child objects of the @ref xrc_wxmenu "wxMenu"
1305 @subsubsection xrc_wxnotebook wxNotebook
1307 A notebook can have one or more child objects of the @c notebookpage
1308 pseudo-class and one child object of the @ref xrc_wximagelist class.
1309 @c notebookpage objects have the following properties:
1312 @hdr3col{property, type, description}
1313 @row3col{label, @ref overview_xrcformat_type_text,
1314 Page's title (required).}
1315 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1316 Bitmap shown alongside the label (default: none).}
1317 @row3col{image, integer,
1318 The zero-based index of the image associated with the item
1319 into the image list.}
1320 @row3col{selected, @ref overview_xrcformat_type_bool,
1321 Is the page selected initially (only one page can be selected; default: 0)?}
1324 Each @c notebookpage has exactly one non-toplevel window as its child.
1328 <object class="wxNotebook">
1329 <style>wxBK_BOTTOM</style>
1330 <object class="notebookpage">
1331 <label>Page 1</label>
1332 <object class="wxPanel" name="page_1">
1336 <object class="notebookpage">
1337 <label>Page 2</label>
1338 <object class="wxPanel" name="page_2">
1346 @subsubsection xrc_wxownerdrawncombobox wxOwnerDrawnComboBox
1348 wxOwnerDrawnComboBox has the same properties as
1349 @ref xrc_wxcombobox "wxComboBox", plus the following additional properties:
1352 @hdr3col{property, type, description}
1353 @row3col{buttonsize, @ref overview_xrcformat_type_size,
1354 Size of the dropdown button (default: default).}
1358 @subsubsection xrc_wxpanel wxPanel
1360 No additional properties.
1362 wxPanel may have optional children: either exactly one
1363 @ref overview_xrcformat_sizers "sizer" child or any number of non-toplevel window
1367 @subsubsection xrc_wxpropertysheetdialog wxPropertySheetDialog
1370 @hdr3col{property, type, description}
1371 @row3col{title, @ref overview_xrcformat_type_text,
1372 Dialog's title (default: empty).}
1373 @row3col{icon, @ref overview_xrcformat_type_bitmap,
1374 Dialog's icon (default: not used).}
1375 @row3col{centered, @ref overview_xrcformat_type_bool,
1376 Whether the dialog should be centered on the screen (default: 0).}
1377 @row3col{buttons, @ref overview_xrcformat_type_style,
1378 Buttons to show, combination of flags accepted by
1379 wxPropertySheetDialog::CreateButtons() (default: 0).}
1382 A sheet dialog can have one or more child objects of the @c propertysheetpage
1383 pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its
1384 @c notebookpage). @c propertysheetpage objects have the following properties:
1387 @hdr3col{property, type, description}
1388 @row3col{label, @ref overview_xrcformat_type_text,
1389 Sheet page's title (required).}
1390 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1391 Bitmap shown alongside the label (default: none).}
1392 @row3col{selected, @ref overview_xrcformat_type_bool,
1393 Is the page selected initially (only one page can be selected; default: 0)?}
1396 Each @c propertysheetpage has exactly one non-toplevel window as its child.
1399 @subsubsection xrc_wxradiobutton wxRadioButton
1402 @hdr3col{property, type, description}
1403 @row3col{label, @ref overview_xrcformat_type_text,
1404 Label shown on the radio button (required).}
1405 @row3col{value, @ref overview_xrcformat_type_bool,
1406 Initial value of the control (default: 0).}
1410 @subsubsection xrc_wxradiobox wxRadioBox
1413 @hdr3col{property, type, description}
1414 @row3col{label, @ref overview_xrcformat_type_text,
1415 Label for the whole box (required).}
1416 @row3col{dimension, integer,
1417 Specifies the maximum number of rows (if style contains
1418 @c wxRA_SPECIFY_ROWS) or columns (if style contains @c wxRA_SPECIFY_COLS)
1419 for a two-dimensional radiobox (default: 1).}
1420 @row3col{selection, integer,
1421 Index of the initially selected item or -1 for no selection (default: -1).}
1422 @row3col{content, items,
1423 Content of the control; this property has any number of @c \<item\> XML
1424 elements as its children, with the items text as their text values
1425 (see below; default: empty).}
1428 The @c \<item\> elements have radio buttons' labels as their text values. They
1429 can also have some optional XML @em attributes (not properties!):
1432 @hdr3col{attribute, type, description}
1433 @row3col{tooltip, @ref overview_xrcformat_type_string,
1434 Tooltip to show over this ratio button (default: none).}
1435 @row3col{helptext, @ref overview_xrcformat_type_string,
1436 Contextual help for this radio button (default: none).}
1437 @row3col{enabled, @ref overview_xrcformat_type_bool,
1438 Is the button enabled (default: 1)?}
1439 @row3col{hidden, @ref overview_xrcformat_type_bool,
1440 Is the button hidden initially (default: 0)?}
1445 <object class="wxRadioBox" name="controls_radiobox">
1446 <style>wxRA_SPECIFY_COLS</style>
1447 <label>Radio stations</label>
1448 <dimension>1</dimension>
1449 <selection>0</selection>
1451 <item tooltip="Powerful radio station" helptext="This station is for amateurs of hard rock and heavy metal">Power 108</item>
1452 <item tooltip="Disabled radio station" enabled="0">Power 0</item>
1453 <item tooltip="">WMMS 100.7</item>
1454 <item tooltip="E=mc^2">Energy 98.3</item>
1455 <item helptext="Favourite chukcha's radio">CHUM FM</item>
1457 <item hidden="1">Very quit station</item>
1463 @subsubsection xrc_wxribbon wxRibbon
1465 A wxRibbonBar is a container of ribbon pages which, in turn, contain elements
1466 that can be wxRibbonControl or wxRibbonGallery.
1470 <object class="wxRibbonBar" name="ribbonbar">
1471 <object class="page" name="FilePage">
1472 <label>First</label>
1473 <object class="panel">
1475 <object class="wxRibbonButtonBar">
1476 <object class="button" name="Open">
1477 <bitmap>open.xpm</bitmap>
1483 <object class="page" name="ViewPage">
1485 <object class="panel">
1487 <object class="wxRibbonGallery">
1488 <object class="item">
1489 <bitmap>zoomin.xpm</bitmap>
1491 <object class="item">
1492 <bitmap>zoomout.xpm</bitmap>
1500 Notice that wxRibbon support in XRC is available in wxWidgets 2.9.5 and
1501 later only and you need to explicitly register its handler using
1503 #include <wx/xrc/xh_ribbon.h>
1505 AddHandler(new wxRibbonXmlHandler);
1510 @subsubsection xrc_wxrichtextctrl wxRichTextCtrl
1513 @hdr3col{property, type, description}
1514 @row3col{value, @ref overview_xrcformat_type_text,
1515 Initial value of the control (default: empty).}
1516 @row3col{maxlength, integer,
1517 Maximum length of the text entered (default: unlimited).}
1520 Notice that wxRichTextCtrl support in XRC is available in wxWidgets 2.9.5 and
1521 later only and you need to explicitly register its handler using
1523 #include <wx/xrc/xh_richtext.h>
1525 AddHandler(new wxRichTextCtrl);
1530 @subsubsection xrc_wxscrollbar wxScrollBar
1533 @hdr3col{property, type, description}
1534 @row3col{value, integer,
1535 Initial position of the scrollbar (default: 0).}
1536 @row3col{range, integer,
1537 Maximum value of the gauge (default: 10).}
1538 @row3col{thumbsize, integer,
1539 Size of the thumb (default: 1).}
1540 @row3col{pagesize, integer,
1541 Page size (default: 1).}
1544 @subsubsection xrc_wxscrolledwindow wxScrolledWindow
1547 @hdr3col{property, type, description}
1548 @row3col{scrollrate, @ref overview_xrcformat_type_size,
1549 Scroll rate in @em x and @em y directions (default: not set;
1550 required if the window has a sizer child).}
1553 wxScrolledWindow may have optional children: either exactly one
1554 @ref overview_xrcformat_sizers "sizer" child or any number of non-toplevel window
1555 objects. If sizer child is used, wxSizer::FitInside() is used (instead of
1556 wxSizer::Fit() as usual) and so the children don't determine scrolled window's
1557 minimal size, they only affect @em virtual size. Usually, both @c scrollrate
1558 and either @c size or @c minsize on containing sizer item should be used
1562 @subsubsection xrc_wxsimplehtmllistbox wxSimpleHtmlListBox
1564 wxSimpleHtmlListBox has same properties as @ref xrc_wxlistbox "wxListBox".
1565 The only difference is that the text contained in @c \<item\> elements is
1566 HTML markup. Note that the markup has to be escaped:
1569 <object class="wxSimpleHtmlListBox">
1571 <item><b>Bold</b> Milk</item>
1576 (X)HTML markup elements cannot be included directly:
1579 <object class="wxSimpleHtmlListBox">
1581 <!-- This is incorrect, doesn't work! -->
1582 <item><b>Bold</b> Milk</item>
1588 @subsubsection xrc_wxslider wxSlider
1591 @hdr3col{property, type, description}
1592 @row3col{value, integer,
1593 Initial value of the control (default: 0).}
1594 @row3col{min, integer,
1595 Minimum allowed value (default: 0).}
1596 @row3col{max, integer,
1597 Maximum allowed value (default: 100).}
1598 @row3col{pagesize, integer,
1599 Page size; number of steps the slider moves when the user moves
1600 pages up or down (default: unset).}
1601 @row3col{linesize, integer,
1602 Line size; number of steps the slider moves when the user moves it
1603 up or down a line (default: unset).}
1604 @row3col{tickfreq, integer,
1605 Tick marks frequency (Windows only; default: unset).}
1606 @row3col{tick, integer,
1607 Tick position (Windows only; default: unset).}
1608 @row3col{thumb, integer,
1609 Thumb length (Windows only; default: unset).}
1610 @row3col{selmin, integer,
1611 Selection start position (Windows only; default: unset).}
1612 @row3col{selmax, integer,
1613 Selection end position (Windows only; default: unset).}
1617 @subsubsection xrc_wxspinbutton wxSpinButton
1620 @hdr3col{property, type, description}
1621 @row3col{value, integer,
1622 Initial value of the control (default: 0).}
1623 @row3col{min, integer,
1624 Minimum allowed value (default: 0).}
1625 @row3col{max, integer,
1626 Maximum allowed value (default: 100).}
1630 @subsubsection xrc_wxspinctrl wxSpinCtrl
1632 wxSpinCtrl supports the same properties as @ref xrc_wxspinbutton and, since
1633 wxWidgets 2.9.5, another one:
1635 @row3col{base, integer,
1636 Numeric base, currently can be only 10 or 16 (default: 10).}
1640 @subsubsection xrc_wxsplitterwindow wxSplitterWindow
1643 @hdr3col{property, type, description}
1644 @row3col{orientation, @ref overview_xrcformat_type_string,
1645 Orientation of the splitter, either "vertical" or "horizontal" (default: horizontal).}
1646 @row3col{sashpos, integer,
1647 Initial position of the sash (default: 0).}
1648 @row3col{minsize, integer,
1649 Minimum child size (default: not set).}
1650 @row3col{gravity, @ref overview_xrcformat_type_float,
1651 Sash gravity, see wxSplitterWindow::SetSashGravity() (default: not set).}
1654 wxSplitterWindow must have one or two children that are non-toplevel window
1655 objects. If there's only one child, it is used as wxSplitterWindow's only
1656 visible child. If there are two children, the first one is used for left/top
1657 child and the second one for right/bottom child window.
1660 @subsubsection xrc_wxsearchctrl wxSearchCtrl
1663 @hdr3col{property, type, description}
1664 @row3col{value, @ref overview_xrcformat_type_text,
1665 Initial value of the control (default: empty).}
1669 @subsubsection xrc_wxstatusbar wxStatusBar
1672 @hdr3col{property, type, description}
1673 @row3col{fields, integer,
1674 Number of status bar fields (default: 1).}
1675 @row3col{widths, @ref overview_xrcformat_type_string,
1676 Comma-separated list of @em fields integers. Each value specifies width
1677 of one field; the values are interpreted using the same convention used
1678 by wxStatusBar::SetStatusWidths().}
1683 @subsubsection xrc_wxstaticbitmap wxStaticBitmap
1686 @hdr3col{property, type, description}
1687 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1688 Bitmap to display (required).}
1691 @subsubsection xrc_wxstaticbox wxStaticBox
1694 @hdr3col{property, type, description}
1695 @row3col{label, @ref overview_xrcformat_type_text,
1696 Static box's label (required).}
1700 @subsubsection xrc_wxstaticline wxStaticLine
1702 No additional properties.
1705 @subsubsection xrc_wxstatictext wxStaticText
1708 @hdr3col{property, type, description}
1709 @row3col{label, @ref overview_xrcformat_type_text,
1710 Label to display (required).}
1711 @row3col{wrap, integer,
1712 Wrap the text so that each line is at most the given number of pixels, see
1713 wxStaticText::Wrap() (default: no wrap).}
1716 @subsubsection xrc_wxtextctrl wxTextCtrl
1719 @hdr3col{property, type, description}
1720 @row3col{value, @ref overview_xrcformat_type_text,
1721 Initial value of the control (default: empty).}
1722 @row3col{maxlength, integer,
1723 Maximum length of the text which can be entered by user (default: unlimited).}
1727 @subsubsection xrc_wxtimepickerctrl wxTimePickerCtrl
1729 No additional properties.
1732 @subsubsection xrc_wxtogglebutton wxToggleButton
1735 @hdr3col{property, type, description}
1736 @row3col{label, @ref overview_xrcformat_type_text,
1737 Label to display on the button (required).}
1738 @row3col{checked, @ref overview_xrcformat_type_bool,
1739 Should the button be checked/pressed initially (default: 0)?}
1742 @subsubsection xrc_wxtoolbar wxToolBar
1745 @hdr3col{property, type, description}
1746 @row3col{bitmapsize, @ref overview_xrcformat_type_size,
1747 Size of toolbar bitmaps (default: not set).}
1748 @row3col{margins, @ref overview_xrcformat_type_size,
1749 Margins (default: platform default).}
1750 @row3col{packing, integer,
1751 Packing, see wxToolBar::SetToolPacking() (default: not set).}
1752 @row3col{separation, integer,
1753 Default separator size, see wxToolBar::SetToolSeparation() (default: not set).}
1754 @row3col{dontattachtoframe, @ref overview_xrcformat_type_bool,
1755 If set to 0 and the toolbar object is child of a wxFrame,
1756 wxFrame::SetToolBar() is called; otherwise, you have to add it to a frame
1757 manually. The toolbar is attached by default, you have to set this property
1758 to 1 to disable this behaviour (default: 0).}
1761 A toolbar can have one or more child objects of any wxControl-derived class or
1762 one of two pseudo-classes: @c separator or @c tool.
1764 The @c separator pseudo-class is used to insert separators into the toolbar and
1765 has neither properties nor children. Similarly, the @c space pseudo-class is
1766 used for stretchable spaces (see wxToolBar::AddStretchableSpace(), new since
1769 The @c tool pseudo-class objects specify toolbar buttons and have the following
1773 @hdr3col{property, type, description}
1774 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1775 Tool's bitmap (required).}
1776 @row3col{bitmap2, @ref overview_xrcformat_type_bitmap,
1777 Bitmap for disabled tool (default: derived from @c bitmap).}
1778 @row3col{label, @ref overview_xrcformat_type_text,
1779 Label to display on the tool (default: no label).}
1780 @row3col{radio, @ref overview_xrcformat_type_bool,
1781 Item's kind is wxITEM_RADIO (default: 0)?}
1782 @row3col{toggle, @ref overview_xrcformat_type_bool,
1783 Item's kind is wxITEM_CHECK (default: 0)?}
1784 @row3col{dropdown, see below,
1785 Item's kind is wxITEM_DROPDOWN (default: 0)? (only available since wxWidgets 2.9.0)}
1786 @row3col{tooltip, @ref overview_xrcformat_type_text,
1787 Tooltip to use for the tool (default: none).}
1788 @row3col{longhelp, @ref overview_xrcformat_type_text,
1789 Help text shown in statusbar when the mouse is on the tool (default: none).}
1790 @row3col{disabled, @ref overview_xrcformat_type_bool,
1791 Is the tool initially disabled (default: 0)?}
1792 @row3col{checked, @ref overview_xrcformat_type_bool,
1793 Is the tool initially checked (default: 0)? (only available since wxWidgets 2.9.3)}
1796 The presence of a @c dropdown property indicates that the tool is of type
1797 wxITEM_DROPDOWN. It must be either empty or contain exactly one @ref
1798 xrc_wxmenu child object defining the drop-down button associated menu.
1800 Notice that @c radio, @c toggle and @c dropdown are mutually exclusive.
1802 Children that are neither @c tool nor @c separator must be instances of classes
1803 derived from wxControl and are added to the toolbar using
1804 wxToolBar::AddControl().
1808 <object class="wxToolBar">
1809 <style>wxTB_FLAT|wxTB_NODIVIDER</style>
1810 <object class="tool" name="foo">
1811 <bitmap>foo.png</bitmap>
1814 <object class="tool" name="bar">
1815 <bitmap>bar.png</bitmap>
1818 <object class="separator"/>
1819 <object class="tool" name="view_auto">
1820 <bitmap>view.png</bitmap>
1823 <object class="wxMenu">
1824 <object class="wxMenuItem" name="view_as_text">
1825 <label>View as text</label>
1827 <object class="wxMenuItem" name="view_as_hex">
1828 <label>View as binary</label>
1833 <object class="space"/>
1834 <object class="wxComboBox">
1837 <item>a combobox</item>
1838 <item>in the toolbar</item>
1846 @subsubsection xrc_wxtoolbook wxToolbook
1848 A toolbook can have one or more child objects of the @c toolbookpage
1849 pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its
1850 @c notebookpage) and one child object of the @ref xrc_wximagelist class.
1851 @c toolbookpage objects have the following properties:
1854 @hdr3col{property, type, description}
1855 @row3col{label, @ref overview_xrcformat_type_text,
1856 Sheet page's title (required).}
1857 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1858 Bitmap shown alongside the label (default: none).}
1859 @row3col{image, integer,
1860 The zero-based index of the image associated with the item
1861 into the image list.}
1862 @row3col{selected, @ref overview_xrcformat_type_bool,
1863 Is the page selected initially (only one page can be selected; default: 0)?}
1866 Each @c toolbookpage has exactly one non-toplevel window as its child.
1869 @subsubsection xrc_wxtreectrl wxTreeCtrl
1871 A treectrl can have one child object of the @ref xrc_wximagelist class.
1873 No additional properties.
1876 @subsubsection xrc_wxtreebook wxTreebook
1878 A treebook can have one or more child objects of the @c treebookpage
1879 pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its
1880 @c notebookpage) and one child object of the @ref xrc_wximagelist class.
1881 @c treebookpage objects have the following properties:
1884 @hdr3col{property, type, description}
1885 @row3col{depth, integer,
1886 Page's depth in the labels tree (required; see below).}
1887 @row3col{label, @ref overview_xrcformat_type_text,
1888 Sheet page's title (required).}
1889 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1890 Bitmap shown alongside the label (default: none).}
1891 @row3col{image, integer,
1892 The zero-based index of the image associated with the item
1893 into the image list.}
1894 @row3col{selected, @ref overview_xrcformat_type_bool,
1895 Is the page selected initially (only one page can be selected; default: 0)?}
1896 @row3col{expanded, @ref overview_xrcformat_type_bool,
1897 If set to 1, the page is initially expanded. By default all pages are
1898 initially collapsed.}
1901 Each @c treebookpage has exactly one non-toplevel window as its child.
1903 The tree of labels is not described using nested @c treebookpage objects, but
1904 using the @em depth property. Toplevel pages have depth 0, their child pages
1905 have depth 1 and so on. A @c treebookpage's label is inserted as child of
1906 the latest preceding page with depth equal to @em depth-1. For example, this
1910 <object class="wxTreebook">
1912 <object class="treebookpage">
1914 <label>Page 1</label>
1915 <object class="wxPanel">...</object>
1917 <object class="treebookpage">
1919 <label>Subpage 1A</label>
1920 <object class="wxPanel">...</object>
1922 <object class="treebookpage">
1924 <label>Subsubpage 1</label>
1925 <object class="wxPanel">...</object>
1927 <object class="treebookpage">
1929 <label>Subpage 1B</label>
1930 <object class="wxPanel">...</object>
1932 <object class="treebookpage">
1934 <label>Subsubpage 2</label>
1935 <object class="wxPanel">...</object>
1937 <object class="treebookpage">
1939 <label>Page 2</label>
1940 <object class="wxPanel">...</object>
1945 corresponds to the following tree of labels:
1955 @subsubsection xrc_wxwizard wxWizard
1958 @hdr3col{property, type, description}
1959 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1960 Bitmap to display on the left side of the wizard (default: none).}
1963 A wizard object can have one or more child objects of the wxWizardPage or
1964 wxWizardPageSimple classes. They both support the following properties
1965 (in addition to @ref overview_xrcformat_std_props):
1968 @hdr3col{property, type, description}
1969 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1970 Page-specific bitmap (default: none).}
1973 wxWizardPageSimple pages are automatically chained together; wxWizardPage pages
1974 transitions must be handled programmatically.
1977 @section overview_xrcformat_sizers Sizers
1979 Sizers are handled slightly differently in XRC resources than they are in
1980 wxWindow hierarchy. wxWindow's sizers hierarchy is parallel to the wxWindow
1981 children hierarchy: child windows are children of their parent window and
1982 the sizer (or sizers) form separate hierarchy attached to the window with
1983 wxWindow::SetSizer().
1985 In XRC, the two hierarchies are merged together: sizers are children of other
1986 sizers or windows and they can contain child window objects.
1988 If a sizer is child of a window object in the resource, it must be the only
1989 child and it will be attached to the parent with wxWindow::SetSizer().
1990 Additionally, if the window doesn't have its size explicitly set,
1991 wxSizer::Fit() is used to resize the window. If the parent window is
1992 toplevel window, wxSizer::SetSizeHints() is called to set its hints.
1994 A sizer object can have one or more child objects of one of two pseudo-classes:
1995 @c sizeritem or @c spacer (see @ref overview_xrcformat_wxstddialogbuttonsizer for
1996 an exception). The former specifies an element (another sizer or a window)
1997 to include in the sizer, the latter adds empty space to the sizer.
1999 @c sizeritem objects have exactly one child object: either another sizer
2000 object, or a window object. @c spacer objects don't have any children, but
2001 they have one property:
2004 @hdr3col{property, type, description}
2005 @row3col{size, @ref overview_xrcformat_type_size, Size of the empty space (required).}
2008 Both @c sizeritem and @c spacer objects can have any of the following
2012 @hdr3col{property, type, description}
2013 @row3col{option, integer,
2014 The "option" value for sizers. Used by wxBoxSizer to set proportion of
2015 the item in the growable direction (default: 0).}
2016 @row3col{flag, @ref overview_xrcformat_type_style,
2017 wxSizerItem flags (default: 0).}
2018 @row3col{border, @ref overview_xrcformat_type_dimension,
2019 Size of the border around the item (directions are specified in flags)
2021 @row3col{minsize, @ref overview_xrcformat_type_size,
2022 Minimal size of this item (default: no min size).}
2023 @row3col{ratio, @ref overview_xrcformat_type_size,
2024 Item ratio, see wxSizer::SetRatio() (default: no ratio).}
2025 @row3col{cellpos, @ref overview_xrcformat_type_pos,
2026 (wxGridBagSizer only) Position, see wxGBSizerItem::SetPos() (required). }
2027 @row3col{cellspan, @ref overview_xrcformat_type_size,
2028 (wxGridBagSizer only) Span, see wxGBSizerItem::SetSpan() (required). }
2031 Example of sizers XRC code:
2033 <object class="wxDialog" name="derived_dialog">
2034 <title>Derived Dialog Example</title>
2035 <centered>1</centered>
2036 <!-- this sizer is set to be this dialog's sizer: -->
2037 <object class="wxFlexGridSizer">
2042 <growablecols>0:1</growablecols>
2043 <growablerows>0:1</growablerows>
2044 <object class="sizeritem">
2045 <flag>wxALIGN_CENTRE|wxALL</flag>
2047 <object class="wxButton" name="my_button">
2048 <label>My Button</label>
2051 <object class="sizeritem">
2052 <flag>wxALIGN_CENTRE|wxALL</flag>
2054 <object class="wxBoxSizer">
2055 <orient>wxHORIZONTAL</orient>
2056 <object class="sizeritem">
2057 <flag>wxALIGN_CENTRE|wxALL</flag>
2059 <object class="wxCheckBox" name="my_checkbox">
2060 <label>Enable this text control:</label>
2063 <object class="sizeritem">
2064 <flag>wxALIGN_CENTRE|wxALL</flag>
2066 <object class="wxTextCtrl" name="my_textctrl">
2078 The sizer classes that can be used are listed below, together with their
2079 class-specific properties. All classes support the following properties:
2082 @hdr3col{property, type, description}
2083 @row3col{minsize, @ref overview_xrcformat_type_size,
2084 Minimal size that this sizer will have, see wxSizer::SetMinSize()
2085 (default: no min size).}
2088 @subsection overview_xrcformat_wxboxsizer wxBoxSizer
2091 @hdr3col{property, type, description}
2092 @row3col{orient, @ref overview_xrcformat_type_style,
2093 Sizer orientation, "wxHORIZONTAL" or "wxVERTICAL" (default: wxHORIZONTAL).}
2096 @subsection overview_xrcformat_wxstaticsboxizer wxStaticBoxSizer
2099 @hdr3col{property, type, description}
2100 @row3col{orient, @ref overview_xrcformat_type_style,
2101 Sizer orientation, "wxHORIZONTAL" or "wxVERTICAL" (default: wxHORIZONTAL).}
2102 @row3col{label, @ref overview_xrcformat_type_text,
2103 Label to be used for the static box around the sizer (required).}
2106 @subsection overview_xrcformat_wxgridsizer wxGridSizer
2109 @hdr3col{property, type, description}
2110 @row3col{rows, integer, Number of rows in the grid (default: 0 - determine automatically).}
2111 @row3col{cols, integer, Number of columns in the grid (default: 0 - determine automatically).}
2112 @row3col{vgap, integer, Vertical gap between children (default: 0).}
2113 @row3col{hgap, integer, Horizontal gap between children (default: 0).}
2116 @subsection overview_xrcformat_wxflexgridsizer wxFlexGridSizer
2119 @hdr3col{property, type, description}
2120 @row3col{rows, integer, Number of rows in the grid (default: 0 - determine automatically).}
2121 @row3col{cols, integer, Number of columns in the grid (default: 0 - determine automatically).}
2122 @row3col{vgap, integer, Vertical gap between children (default: 0).}
2123 @row3col{hgap, integer, Horizontal gap between children (default: 0).}
2124 @row3col{flexibledirection, @ref overview_xrcformat_type_style,
2125 Flexible direction, @c wxVERTICAL, @c wxHORIZONTAL or @c wxBOTH (default).
2126 This property is only available since wxWidgets 2.9.5.}
2127 @row3col{nonflexiblegrowmode, @ref overview_xrcformat_type_style,
2128 Grow mode in the non-flexible direction,
2129 @c wxFLEX_GROWMODE_NONE, @c wxFLEX_GROWMODE_SPECIFIED (default) or
2130 @c wxFLEX_GROWMODE_ALL.
2131 This property is only available since wxWidgets 2.9.5.}
2132 @row3col{growablerows, comma-separated integers list,
2133 Comma-separated list of indexes of rows that are growable (none by default).
2134 Since wxWidgets 2.9.5 optional proportion can be appended to each number
2135 after a colon (@c :).}
2136 @row3col{growablecols, comma-separated integers list,
2137 Comma-separated list of indexes of columns that are growable (none by default).
2138 Since wxWidgets 2.9.5 optional proportion can be appended to each number
2139 after a colon (@c :).}
2142 @subsection overview_xrcformat_wxgridbagsizer wxGridBagSizer
2145 @hdr3col{property, type, description}
2146 @row3col{vgap, integer, Vertical gap between children (default: 0).}
2147 @row3col{hgap, integer, Horizontal gap between children (default: 0).}
2148 @row3col{flexibledirection, @ref overview_xrcformat_type_style,
2149 Flexible direction, @c wxVERTICAL, @c wxHORIZONTAL, @c wxBOTH (default: @c wxBOTH).}
2150 @row3col{nonflexiblegrowmode, @ref overview_xrcformat_type_style,
2151 Grow mode in the non-flexible direction,
2152 @c wxFLEX_GROWMODE_NONE, @c wxFLEX_GROWMODE_SPECIFIED, @c wxFLEX_GROWMODE_ALL
2153 (default: @c wxFLEX_GROWMODE_SPECIFIED).}
2154 @row3col{growablerows, comma-separated integers list,
2155 Comma-separated list of indexes of rows that are growable,
2156 optionally the proportion can be appended after each number
2159 @row3col{growablecols, comma-separated integers list,
2160 Comma-separated list of indexes of columns that are growable,
2161 optionally the proportion can be appended after each number
2166 @subsection overview_xrcformat_wxwrapsizer wxWrapSizer
2169 @hdr3col{property, type, description}
2170 @row3col{orient, @ref overview_xrcformat_type_style,
2171 Sizer orientation, "wxHORIZONTAL" or "wxVERTICAL" (required).}
2172 @row3col{flag, @ref overview_xrcformat_type_style, wxWrapSizer flags (default: 0).}
2175 @subsection overview_xrcformat_wxstddialogbuttonsizer wxStdDialogButtonSizer
2177 Unlike other sizers, wxStdDialogButtonSizer has neither @c sizeritem
2178 nor @c spacer children. Instead, it has one or more children of the
2179 @c button pseudo-class. @c button objects have no properties and they must
2180 always have exactly one child of the @c wxButton class or a class derived from
2185 <object class="wxStdDialogButtonSizer">
2186 <object class="button">
2187 <object class="wxButton" name="wxID_OK">
2191 <object class="button">
2192 <object class="wxButton" name="wxID_CANCEL">
2193 <label>Cancel</label>
2201 @section overview_xrcformat_other_objects Other Objects
2203 In addition to describing UI elements, XRC files can contain non-windows
2204 objects such as bitmaps or icons. This is a concession to Windows developers
2205 used to storing them in Win32 resources.
2207 Note that unlike Win32 resources, bitmaps included in XRC files are @em not
2208 embedded in the XRC file itself. XRC file only contains a reference to another
2209 file with bitmap data.
2211 @subsection overview_xrcformat_bitmap wxBitmap
2213 Bitmaps are stored in @c \<object\> element with class set to @c wxBitmap. Such
2214 bitmaps can then be loaded using wxXmlResource::LoadBitmap(). The content of
2215 the element is exactly same as in the case of
2216 @ref overview_xrcformat_type_bitmap "bitmap properties", except that toplevel
2217 @c \<object\> is used.
2219 For example, instead of:
2221 <bitmap>mybmp.png</bitmap>
2222 <bitmap stock_id="wxART_NEW"/>
2224 toplevel wxBitmap resources would look like:
2226 <object class="wxBitmap" name="my_bitmap">mybmp.png</object>
2227 <object class="wxBitmap" name="my_new_bitmap" stock_id="wxART_NEW"/>
2231 @subsection overview_xrcformat_icon wxIcon
2233 wxIcon resources are identical to @ref overview_xrcformat_bitmap "wxBitmap ones",
2234 except that the class is @c wxIcon.
2237 @section overview_xrcformat_platform Platform Specific Content
2239 It is possible to conditionally process parts of XRC files on some platforms
2240 only and ignore them on other platforms. @em Any element in XRC file, be it
2241 toplevel or arbitrarily nested one, can have the @c platform attribute. When
2242 used, @c platform contains |-separated list of platforms that this element
2243 should be processed on. It is filtered out and ignored on any other platforms.
2245 Possible elemental values are:
2247 @itemdef{ @c win, Windows }
2248 @itemdef{ @c mac, Mac OS X (or Mac Classic in wxWidgets version supporting it) }
2249 @itemdef{ @c unix, Any Unix platform @em except OS X }
2250 @itemdef{ @c os2, OS/2 }
2255 <label platform="win">Windows</label>
2256 <label platform="unix">Unix</label>
2257 <label platform="mac">Mac OS X</label>
2258 <help platform="mac|unix">Not a Windows machine</help>
2263 @section overview_xrcformat_idranges ID Ranges
2265 Usually you won't care what value the XRCID macro returns for the ID of an
2266 object. Sometimes though it is convenient to have a range of IDs that are
2267 guaranteed to be consecutive. An example of this would be connecting a group of
2268 similar controls to the same event handler.
2270 The following XRC fragment 'declares' an ID range called @em foo and another
2271 called @em bar; each with some items.
2274 <object class="wxButton" name="foo[start]">
2275 <object class="wxButton" name="foo[end]">
2276 <object class="wxButton" name="foo[2]">
2278 <object class="wxButton" name="bar[0]">
2279 <object class="wxButton" name="bar[2]">
2280 <object class="wxButton" name="bar[1]">
2282 <ids-range name="foo" />
2283 <ids-range name="bar" size="30" start="10000" />
2286 For the range foo, no @em size or @em start parameters were given, so the size
2287 will be calculated from the number of range items, and IDs allocated by
2288 wxWindow::NewControlId (so they'll be negative). Range bar asked for a size of
2289 30, so this will be its minimum size: should it have more items, the range will
2290 automatically expand to fit them. It specified a start ID of 10000, so
2291 XRCID("bar[0]") will be 10000, XRCID("bar[1]") 10001 etc. Note that if you
2292 choose to supply a start value it must be positive, and it's your
2293 responsibility to avoid clashes.
2295 For every ID range, the first item can be referenced either as
2296 <em>rangename</em>[0] or <em>rangename</em>[start]. Similarly
2297 <em>rangename</em>[end] is the last item. Using [start] and [end] is more
2298 descriptive in e.g. a Bind() event range or a @em for loop, and they don't have
2299 to be altered whenever the number of items changes.
2301 Whether a range has positive or negative IDs, [start] is always a smaller
2302 number than [end]; so code like this works as expected:
2305 for (int n=XRCID("foo[start]"); n <= XRCID("foo[end]"); ++n)
2309 ID ranges can be seen in action in the <em>objref</em> dialog section of the
2313 @li All the items in an ID range must be contained in the same XRC file.
2314 @li You can't use an ID range in a situation where static initialisation
2315 occurs; in particular, they won't work as expected in an event table. This is
2316 because the event table's IDs are set to their integer values before the XRC
2317 file is loaded, and aren't subsequently altered when the XRCID value changes.
2321 @section overview_xrcformat_extending Extending the XRC Format
2323 The XRC format is designed to be extensible and allows specifying and loading
2324 custom controls. The three available mechanisms are described in the rest of
2325 this section in the order of increasing complexity.
2327 @subsection overview_xrcformat_extending_subclass Subclassing
2329 The simplest way to add custom controls is to set the @c subclass attribute
2330 of @c \<object\> element:
2333 <object name="my_value" class="wxTextCtrl" subclass="MyTextCtrl">
2334 <style>wxTE_MULTILINE</style>
2335 ...etc., setup wxTextCtrl as usual...
2339 In that case, wxXmlResource will create an instance of the specified subclass
2340 (@c MyTextCtrl in the example above) instead of the class (@c wxTextCtrl above)
2341 when loading the resource. However, the rest of the object's loading (calling
2342 its Create() method, setting its properties, loading any children etc.)
2343 will proceed in @em exactly the same way as it would without @c subclass
2344 attribute. In other words, this approach is only sufficient when the custom
2345 class is just a small modification (e.g. overridden methods or customized
2346 events handling) of an already supported classes.
2348 The subclass must satisfy a number of requirements:
2350 -# It must be derived from the class specified in @c class attribute.
2351 -# It must be visible in wxWidget's pseudo-RTTI mechanism, i.e. there must be
2352 a DECLARE_DYNAMIC_CLASS() entry for it.
2353 -# It must support two-phase creation. In particular, this means that it has
2354 to have default constructor.
2355 -# It cannot provide custom Create() method and must be constructible using
2356 base @c class' Create() method (this is because XRC will call Create() of
2357 @c class, not @c subclass). In other words, @em creation of the control
2358 must not be customized.
2361 @subsection overview_xrcformat_extending_unknown Unknown Objects
2363 A more flexible solution is to put a @em placeholder in the XRC file and
2364 replace it with custom control after the resource is loaded. This is done by
2365 using the @c unknown pseudo-class:
2368 <object class="unknown" name="my_placeholder"/>
2371 The placeholder is inserted as dummy wxPanel that will hold custom control in
2372 it. At runtime, after the resource is loaded and a window created from it
2373 (using e.g. wxXmlResource::LoadDialog()), use code must call
2374 wxXmlResource::AttachUnknownControl() to insert the desired control into
2375 placeholder container.
2377 This method makes it possible to insert controls that are not known to XRC at
2378 all, but it's also impossible to configure the control in XRC description in
2379 any way. The only properties that can be specified are
2380 the @ref overview_xrcformat_std_props "standard window properties".
2382 @note @c unknown class cannot be combined with @c subclass attribute,
2383 they are mutually exclusive.
2386 @subsection overview_xrcformat_extending_custom Adding Custom Classes
2388 Finally, XRC allows adding completely new classes in addition to the ones
2389 listed in this document. A class for which wxXmlResourceHandler is implemented
2390 can be used as first-class object in XRC simply by passing class name as the
2391 value of @c class attribute:
2394 <object name="my_ctrl" class="MyWidget">
2395 <my_prop>foo</my_prop>
2396 ...etc., whatever MyWidget handler accepts...
2400 The only requirements on the class are that
2401 -# the class must derive from wxObject
2402 -# it must support wxWidget's pseudo-RTTI mechanism
2404 Child elements of @c \<object\> are handled by the custom handler and there are
2405 no limitations on them imposed by XRC format.
2407 This is the only mechanism that works for toplevel objects -- custom controls
2408 are accessible using the type-unsafe wxXmlResource::LoadObject() method.
2412 @section overview_xrcformat_packed Packed XRC Files
2414 In addition to plain XRC files, wxXmlResource supports (if wxFileSystem support
2415 is compiled in) compressed XRC resources. Compressed resources have either
2416 .zip or .xrs extension and are simply ZIP files that contain arbitrary
2417 number of XRC files and their dependencies (bitmaps, icons etc.).
2421 @section overview_xrcformat_oldversions Older Format Versions
2423 This section describes differences in older revisions of XRC format (i.e.
2424 files with older values of @c version attribute of @c \<resource\>).
2427 @subsection overview_xrcformat_pre_v2530 Versions Before 2.5.3.0
2429 Version 2.5.3.0 introduced C-like handling of "\\" in text. In older versions,
2430 "\n", "\t" and "\r" escape sequences were replaced with respective characters
2431 in the same matter it's done in C, but "\\" was left intact instead of being
2432 replaced with single "\", as one would expect. Starting with 2.5.3.0, all of
2433 them are handled in C-like manner.
2436 @subsection overview_xrcformat_pre_v2301 Versions Before 2.3.0.1
2438 Prior to version 2.3.0.1, "$" was used for accelerators instead of "_"
2439 or "&". For example,
2441 <label>$File</label>
2443 was used in place of current version's
2445 <label>_File</label>