]>
git.saurik.com Git - wxWidgets.git/blob - docs/doxygen/overviews/xrc_format.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: XRC format specification
4 // Author: Vaclav Slavik
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
11 NOTE: To make doxygen happy about <custom-tags> we're forced to
12 escape all < and > symbols which appear inside a doxygen comment.
13 Also, don't use < and > symbols in section titles.
19 @page overview_xrcformat XRC File Format
22 - @ref overview_xrcformat_overview
23 - @ref overview_xrcformat_root
24 - @ref overview_xrcformat_objects
25 - @ref overview_xrcformat_object
26 - @ref overview_xrcformat_object_ref
27 - @ref overview_xrcformat_datatypes
28 - @ref overview_xrcformat_windows
29 - @ref overview_xrcformat_std_props
30 - @ref overview_xrcformat_controls
31 - @ref overview_xrcformat_sizers
32 - @ref overview_xrcformat_other_objects
33 - @ref overview_xrcformat_platform
34 - @ref overview_xrcformat_idranges
35 - @ref overview_xrcformat_extending
36 - @ref overview_xrcformat_extending_subclass
37 - @ref overview_xrcformat_extending_unknown
38 - @ref overview_xrcformat_extending_custom
39 - @ref overview_xrcformat_packed
40 - @ref overview_xrcformat_oldversions
42 This document describes the format of XRC resource files, as used by wxXmlResource.
48 @section overview_xrcformat_overview Overview
50 XRC file is a XML file with all of its elements in the
51 @c http://www.wxwidgets.org/wxxrc namespace. For backward compatibility,
52 @c http://www.wxwindows.org/wxxrc namespace is accepted as well (and treated
53 as identical to @c http://www.wxwidgets.org/wxxrc), but it shouldn't be used
56 XRC file contains definitions for one or more @em objects -- typically
57 windows. The objects may themselves contain child objects.
59 Objects defined at the top level, under the
60 @ref overview_xrcformat_root "root element", can be accessed using
61 wxXmlResource::LoadDialog() and other LoadXXX methods. They must have
62 @c name attribute that is used as LoadXXX's argument (see
63 @ref overview_xrcformat_object for details).
65 Child objects are not directly accessible via wxXmlResource, they can only
66 be accessed using XRCCTRL().
69 @section overview_xrcformat_root Resource Root Element
71 The root element is always @c \<resource\>. It has one optional attribute, @c
72 version. If set, it specifies version of the file. In absence of @c version
73 attribute, the default is @c "0.0.0.0".
75 The version consists of four integers separated by periods. The first three
76 components are major, minor and release number of the wxWidgets release when
77 the change was introduced, the last one is revision number and is 0 for the
78 first incompatible change in given wxWidgets release, 1 for the second and so
79 on. The version changes only if there was an incompatible change introduced;
80 merely adding new kind of objects does not constitute incompatible change.
82 At the time of writing, the latest version is @c "2.5.3.0".
84 Note that even though @c version attribute is optional, it should always be
85 specified to take advantage of the latest capabilities:
89 <resource xmlns="http://www.wxwidgets.org/wxxrc" version="2.5.3.0">
94 @c \<resource\> may have arbitrary number of
95 @ref overview_xrcformat_objects "object elements" as its children; they are referred
96 to as @em toplevel objects in the rest of this document. Unlike objects defined
97 deeper in the hierarchy, toplevel objects @em must have their @c name attribute
98 set and it must be set to a value unique among root's children.
102 @section overview_xrcformat_objects Defining Objects
104 @subsection overview_xrcformat_object Object Element
106 The @c \<object\> element represents a single object (typically a GUI element)
107 and it usually maps directly to a wxWidgets class instance. It has one
108 mandatory attribute, @c class, and optional @c name and @c subclass attributes.
110 The @c class attribute must always be present, it tells XRC what wxWidgets
111 object should be created and by which wxXmlResourceHandler.
113 @c name is the identifier used to identify the object. This name serves three
116 -# It is used by wxXmlResource's various LoadXXX() methods to find the
117 resource by name passed as argument.
118 -# wxWindow's name (see wxWindow::GetName()) is set to it.
119 -# Numeric ID of a window or menu item is derived from the name.
120 If the value represents an integer (in decimal notation), it is used for
121 the numeric ID unmodified. If it is one of the wxID_XXX literals defined
122 by wxWidgets (see @ref page_stockitems), its respective value is used.
123 Otherwise, the name is transformed into dynamically generated ID. See
124 wxXmlResource::GetXRCID() for more information.
126 Name attributes must be unique at the top level (where the name is used to
127 load resources) and should be unique among all controls within the same
128 toplevel window (wxDialog, wxFrame).
130 The @c subclass attribute optional name of class whose constructor will be
131 called instead of the constructor for "class".
132 See @ref overview_xrcformat_extending_subclass for more details.
134 @c \<object\> element may -- and almost always do -- have children elements.
135 These come in two varieties:
137 -# Object's properties. A @em property is a value describing part of object's
138 behaviour, for example the "label" property on wxButton defines its label.
139 In the most common form, property is a single element with text content
140 ("\<label\>Cancel\</label\>"), but they may use nested subelements too (e.g.
141 @ref overview_xrcformat_type_font "font property"). A property can only be
142 listed once in an object's definition.
143 -# Child objects. Window childs, sizers, sizer items or notebook pages
144 are all examples of child objects. They are represented using nested
145 @c \<object\> elements and are can be repeated more than once. The specifics
146 of which object classes are allowed as children are class-specific and
147 are documented below in @ref overview_xrcformat_controls.
151 <object class="wxDialog" name="example_dialog">
153 <title>Non-Derived Dialog Example</title>
154 <centered>1</centered>
155 <!-- child objects: -->
156 <object class="wxBoxSizer">
157 <orient>wxVERTICAL</orient>
166 @subsection overview_xrcformat_object_ref Object References
168 Anywhere an @c \<object\> element can be used, @c \<object_ref\> may be used
169 instead. @c \<object_ref\> is a @em reference to another named (i.e. with the
170 @c name attribute) @c \<object\> element. It has one mandatory attribute,
171 @c ref, with value containing the name of a named @c \<object\> element. When an
172 @c \<object_ref\> is encountered, a copy of the referenced @c \<object\> element
173 is made in place of @c \<object_ref\> occurrence and processed as usual.
175 For example, the following code:
177 <object class="wxDialog" name="my_dlg">
180 <object_ref name="my_dlg_alias" ref="my_dlg"/>
184 <object class="wxDialog" name="my_dlg">
187 <object class="wxDialog" name="my_dlg_alias">
188 ... <!-- same as in my_dlg -->
192 Additionally, it is possible to override some parts of the referenced object
193 in the @c \<object_ref\> pointing to it. This is useful for putting repetitive
194 parts of XRC definitions into a template that can be reused and customized in
195 several places. The two parts are merged as follows:
197 -# The referred object is used as the initial content.
198 -# All attributes set on @c \<object_ref\> are added to it.
199 -# All child elements of @c \<object_ref\> are scanned. If an element with
200 the same name (and, if specified, the @c name attribute too) is found
201 in the referred object, they are recursively merged.
202 -# Child elements in @c \<object_ref\> that do not have a match in the referred
203 object are appended to the list of children of the resulting element by
204 default. Optionally, they may have @c insert_at attribute with two possible
205 values, "begin" or "end". When set to "begin", the element is prepended to
206 the list of children instead of appended.
208 For example, "my_dlg" in this snippet:
210 <object class="wxDialog" name="template">
211 <title>Dummy dialog</title>
214 <object_ref ref="template" name="my_dlg">
215 <title>My dialog</title>
216 <centered>1</centered>
221 <object class="wxDialog" name="my_dlg">
222 <title>My dialog</title>
224 <centered>1</centered>
229 @section overview_xrcformat_datatypes Data Types
231 There are several property data types that are frequently reused by different
232 properties. Rather than describing their format in the documentation of
233 every property, we list commonly used types in this section and document
237 @subsection overview_xrcformat_type_bool Boolean
239 Boolean values are expressed using either "1" literal (true) or "0" (false).
242 @subsection overview_xrcformat_type_float Floating-point value
244 Floating point values use POSIX (C locale) formatting -- decimal separator
245 is "." regardless of the locale.
248 @subsection overview_xrcformat_type_colour Colour
250 Colour specification can be either any string colour representation accepted
251 by wxColour::Set() or any wxSYS_COLOUR_XXX symbolic name accepted by
252 wxSystemSettings::GetColour(). In particular, the following forms are supported:
254 @li named colours from wxColourDatabase
255 @li HTML-like "#rrggbb" syntax (but not "#rgb")
256 @li CSS-style "rgb(r,g,b)" and "rgba(r,g,b,a)"
257 @li wxSYS_COLOUR_XXX symbolic names
263 <fg>rgb(255,0,0)</fg>
264 <fg>wxSYS_COLOUR_HIGHLIGHT</fg>
268 @subsection overview_xrcformat_type_size Size
270 Sizes and positions have the form of string with two comma-separated integer
271 components, with optional "d" suffix. Semi-formally:
273 size := x "," y ["d"]
275 where x and y are integers. Either of the components (or both) may be "-1" to
276 signify default value. As a shortcut, empty string is equivalent to "-1,-1"
277 (= wxDefaultSize or wxDefaultPosition).
279 When the "d" suffix is used, integer values are interpreted as
280 @ref wxWindow::ConvertDialogToPixels() "dialog units" in the parent window.
289 @subsection overview_xrcformat_type_pos Position
291 Same as @ref overview_xrcformat_type_size.
294 @subsection overview_xrcformat_type_dimension Dimension
296 Similarly to @ref overview_xrcformat_type_size "sizes", dimensions are expressed
297 as integers with optional "d" suffix. When "d" suffix is used, the integer
298 preceding it is interpreted as dialog units in the parent window.
301 @subsection overview_xrcformat_type_text Text
303 String properties use several escape sequences that are translated according to
306 @itemdef{ "_", "&" (used for accelerators in wxWidgets) }
307 @itemdef{ "__", "_" }
308 @itemdef{ "\n", line break }
309 @itemdef{ "\r", carriage return }
310 @itemdef{ "\t", tab }
311 @itemdef{ "\\", "\" }
314 By default, the text is translated using wxLocale::GetTranslation() before
315 it is used. This can be disabled either globally by not passing
316 wxXRC_USE_LOCALE to wxXmlResource constructor, or by setting the @c translate
317 attribute on the property node to "0":
319 <!-- this is not translated: -->
320 <label translate="0">_Unix</label>
321 <!-- but this is: -->
322 <help>Use Unix-style newlines</help>
325 @note Even though the "_" character is used instead of "&" for accelerators,
326 it is still possible to use "&". The latter has to be encoded as "&",
327 though, so using "_" is more convenient.
329 @see @ref overview_xrcformat_pre_v2530, @ref overview_xrcformat_pre_v2301
332 @subsection overview_xrcformat_type_text_notrans Non-Translatable Text
334 Like @ref overview_xrcformat_type_text, but the text is never translated and
335 @c translate attribute cannot be used.
338 @subsection overview_xrcformat_type_string String
340 An unformatted string. Unlike with @ref overview_xrcformat_type_text, no escaping
341 or translations are done.
344 @subsection overview_xrcformat_type_url URL
346 Any URL accepted by wxFileSystem (typically relative to XRC file's location,
347 but can be absolute too). Unlike with @ref overview_xrcformat_type_text, no escaping
348 or translations are done.
351 @subsection overview_xrcformat_type_bitmap Bitmap
353 Bitmap properties contain specification of a single bitmap or icon. In the most
354 basic form, their text value is simply a relative filename (or another
355 wxFileSystem URL) of the bitmap to use. For example:
357 <object class="tool" name="wxID_NEW">
358 <tooltip>New</tooltip>
359 <bitmap>new.png</bitmap>
362 The value is interpreted as path relative to the location of XRC file where the
365 Alternatively, it is possible to specify the bitmap using wxArtProvider IDs.
366 In this case, the property element has no textual value (filename) and instead
367 has the @c stock_id XML attribute that contains stock art ID as accepted by
368 wxArtProvider::GetBitmap(). This can be either custom value (if the app uses
369 app-specific art provider) or one of the predefined wxART_XXX constants.
371 Optionally, @c stock_client attribute may be specified too and contain one of
372 the predefined wxArtClient values. If it is not specified, the default client
373 ID most appropriate in the context where the bitmap is referenced will be used.
374 In most cases, specifying @c stock_client is not needed.
376 Examples of stock bitmaps usage:
378 <bitmap stock_id="fixed-width"/> <!-- custom app-specific art -->
379 <bitmap stock_id="wxART_FILE_OPEN"/> <!-- standard art -->
382 Specifying the bitmap directly and using @c stock_id are mutually exclusive.
385 @subsection overview_xrcformat_type_style Style
387 Style properties (such as window's style or sizer flags) use syntax similar to
388 C++: the style value is OR-combination of individual flags. Symbolic names
389 identical to those used in C++ code are used for the flags. Flags are separated
390 with "|" (whitespace is allowed but not required around it).
392 The flags that are allowed for a given property are context-dependent.
396 <style>wxCAPTION|wxSYSTEM_MENU | wxRESIZE_BORDER</style>
397 <exstyle>wxDIALOG_EX_CONTEXTHELP</exstyle>
401 @subsection overview_xrcformat_type_font Font
403 XRC uses similar, but more flexible, abstract description of fonts to that
404 used by wxFont class. A font can be described either in terms of its elementary
405 properties, or it can be derived from one of system fonts or the parent window
408 The font property element is "composite" element: unlike majority of
409 properties, it doesn't have text value but contains several child elements
410 instead. These children are handled in the same way as object properties
411 and can be one of the following "sub-properties":
414 @hdr3col{property, type, description}
415 @row3col{size, unsigned integer,
416 Pixel size of the font (default: wxNORMAL_FONT's size or @c sysfont's
417 size if the @c sysfont property is used or the current size of the font
418 of the enclosing control if the @c inherit property is used.}
419 @row3col{style, enum,
420 One of "normal", "italic" or "slant" (default: normal).}
421 @row3col{weight, enum,
422 One of "normal", "bold" or "light" (default: normal).}
423 @row3col{family, enum,
424 One of "roman", "script", "decorative", "swiss", "modern" or "teletype"
426 @row3col{underlined, @ref overview_xrcformat_type_bool,
427 Whether the font should be underlined (default: 0).}
429 Comma-separated list of face names; the first one available is used
430 (default: unspecified).}
432 Charset of the font, unused in Unicode build), as string
433 (default: unspecified).}
435 Symbolic name of system standard font(one of wxSYS_*_FONT constants).}
436 @row3col{inherit, @ref overview_xrcformat_type_bool,
437 If true, the font of the enclosing control is used. If this property and the
438 @c sysfont property are specified the @c sysfont property takes precedence.}
439 @row3col{relativesize, float,
440 Float, font size relative to chosen system font's or inherited font's size;
441 can only be used when 'sysfont' or 'inherit' is used and when 'size' is not
445 All of them are optional, if they are missing, appropriate wxFont default is
446 used. If the @c sysfont or @c inherit property is used, then the defaults are
447 taken from it instead.
452 <!-- fixed font: Arial if available, fall back to Helvetica -->
453 <face>arial,helvetica</face>
458 <!-- enlarged, enboldened standard font: -->
459 <sysfont>wxSYS_DEFAULT_GUI_FONT</sysfont>
460 <weight>bold</weight>
461 <relativesize>1.5</relativesize>
465 @note You cannot use @c inherit for a font that gets used before the enclosing
466 control is created, e.g. if the control gets the font passed as parameter
467 for its constructor, or if the control is not derived from wxWindow.
470 @section overview_xrcformat_windows Controls and Windows
472 This section describes support wxWindow-derived classes in XRC format.
474 @subsection overview_xrcformat_std_props Standard Properties
476 The following properties are always (unless stated otherwise in
477 control-specific docs) available for @em windows objects. They are omitted
478 from properties lists below.
481 @hdr3col{property, type, description}
482 @row3col{pos, @ref overview_xrcformat_type_pos,
483 Initial position of the window (default: wxDefaultPosition).}
484 @row3col{size, @ref overview_xrcformat_type_size,
485 Initial size of the window (default: wxDefaultSize).}
486 @row3col{style, @ref overview_xrcformat_type_style,
487 Window style for this control. The allowed values depend on what
488 window is being created, consult respective class' constructor
489 documentation for details (default: window-dependent default, usually
490 wxFOO_DEFAULT_STYLE if defined for class wxFoo, 0 if not).}
491 @row3col{exstyle, @ref overview_xrcformat_type_style,
492 Extra style for the window, if any. See wxWindow::SetExtraStyle()
494 @row3col{fg, @ref overview_xrcformat_type_colour,
495 Foreground colour of the window (default: window's default).}
496 @row3col{ownfg, @ref overview_xrcformat_type_colour,
497 Non-inheritable foreground colour of the window, see
498 wxWindow::SetOwnForegroundColour() (default: none).}
499 @row3col{bg, @ref overview_xrcformat_type_colour,
500 Background colour of the window (default: window's default).}
501 @row3col{ownbg, @ref overview_xrcformat_type_colour,
502 Non-inheritable background colour of the window, see
503 wxWindow::SetOwnBackgroundColour() (default: none).}
504 @row3col{enabled, @ref overview_xrcformat_type_bool,
505 If set to 0, the control is disabled (default: 1).}
506 @row3col{hidden, @ref overview_xrcformat_type_bool,
507 If set to 1, the control is created hidden (default: 0).}
508 @row3col{tooltip, @ref overview_xrcformat_type_text,
509 Tooltip to use for the control (default: not set).}
510 @row3col{font, @ref overview_xrcformat_type_font,
511 Font to use for the control (default: window's default).}
512 @row3col{ownfont, @ref overview_xrcformat_type_font,
513 Non-inheritable font to use for the control, see
514 wxWindow::SetOwnFont() (default: none).}
515 @row3col{help, @ref overview_xrcformat_type_text,
516 Context-sensitive help for the control, used by wxHelpProvider
520 All of these properties are optional.
523 @subsection overview_xrcformat_controls Supported Controls
525 This section lists all controls supported by default. For each control, its
526 control-specific properties are listed. If the control can have child objects,
527 it is documented there too; unless said otherwise, XRC elements for these
528 controls cannot have children.
530 @subsubsection xrc_wxanimationctrl wxAnimationCtrl
533 @hdr3col{property, type, description}
534 @row3col{animation, @ref overview_xrcformat_type_url,
535 Animation file to load into the control (required).}
539 @subsubsection xrc_wxbannerwindow wxBannerWindow
542 @hdr3col{property, type, description}
543 @row3col{direction, @c wxLEFT|wxRIGHT|wxTOP|wxBOTTOM,
544 The side along which the banner will be positioned.}
545 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
546 Bitmap to use as the banner background.}
547 @row3col{title, @ref overview_xrcformat_type_text,
548 Banner title, should be single line.}
549 @row3col{message, @ref overview_xrcformat_type_text,
550 Possibly multi-line banner message.}
551 @row3col{gradient-start, @ref overview_xrcformat_type_colour,
552 Starting colour of the gradient used as banner background. Can't be used if
553 a valid bitmap is specified.}
554 @row3col{gradient-end, @ref overview_xrcformat_type_colour,
555 End colour of the gradient used as banner background. Can't be used if
556 a valid bitmap is specified.}
560 @subsubsection xrc_wxbitmapbutton wxBitmapButton
563 @hdr3col{property, type, description}
564 @row3col{default, @ref overview_xrcformat_type_bool,
565 Should this button be the default button in dialog (default: 0)?}
566 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
567 Bitmap to show on the button (required).}
568 @row3col{selected, @ref overview_xrcformat_type_bitmap,
569 Bitmap to show when the button is selected (default: none, same as @c bitmap).}
570 @row3col{focus, @ref overview_xrcformat_type_bitmap,
571 Bitmap to show when the button has focus (default: none, same as @c bitmap).}
572 @row3col{disabled, @ref overview_xrcformat_type_bitmap,
573 Bitmap to show when the button is disabled (default: none, same as @c bitmap).}
574 @row3col{hover, @ref overview_xrcformat_type_bitmap,
575 Bitmap to show when mouse cursor hovers above the bitmap (default: none, same as @c bitmap).}
579 @subsubsection xrc_wxbitmapcombobox wxBitmapComboBox
582 @hdr3col{property, type, description}
583 @row3col{selection, integer,
584 Index of the initially selected item or -1 for no selection (default: -1).}
585 @row3col{value, @ref overview_xrcformat_type_string,
586 Initial value in the control (doesn't have to be one of @ content values;
590 If both @c value and @c selection are specified and @c selection is not -1,
591 then @c selection takes precedence.
593 A wxBitmapComboBox can have one or more child objects of the @c ownerdrawnitem
594 pseudo-class. @c ownerdrawnitem objects have the following properties:
597 @hdr3col{property, type, description}
598 @row3col{text, @ref overview_xrcformat_type_text,
599 Item's label (required).}
600 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
601 Item's bitmap (default: no bitmap).}
606 <object class="wxBitmapComboBox">
607 <selection>1</selection>
608 <object class="ownerdrawnitem">
610 <bitmap>foo.png</bitmap>
612 <object class="ownerdrawnitem">
614 <bitmap>bar.png</bitmap>
620 @subsubsection xrc_wxbitmaptogglebutton wxBitmapToggleButton
623 @hdr3col{property, type, description}
624 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
625 Label to display on the button (required).}
626 @row3col{checked, @ref overview_xrcformat_type_bool,
627 Should the button be checked/pressed initially (default: 0)?}
631 @subsubsection xrc_wxbutton wxButton
634 @hdr3col{property, type, description}
635 @row3col{label, @ref overview_xrcformat_type_text,
636 Label to display on the button (may be empty if only bitmap is used).}
637 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
638 Bitmap to display in the button (optional).}
639 @row3col{bitmapposition, @c wxLEFT|wxRIGHT|wxTOP|wxBOTTOM,
640 Position of the bitmap in the button, see wxButton::SetBitmapPosition().}
641 @row3col{default, @ref overview_xrcformat_type_bool,
642 Should this button be the default button in dialog (default: 0)?}
646 @subsubsection xrc_wxcalendarctrl wxCalendarCtrl
648 No additional properties.
651 @subsubsection xrc_wxcheckbox wxCheckBox
654 @hdr3col{property, type, description}
655 @row3col{label, @ref overview_xrcformat_type_text,
656 Label to use for the checkbox (required).}
657 @row3col{checked, @ref overview_xrcformat_type_bool,
658 Should the checkbox be checked initially (default: 0)?}
662 @subsubsection xrc_wxchecklistbox wxCheckListBox
665 @hdr3col{property, type, description}
666 @row3col{content, items,
667 Content of the control; this property has any number of @c \<item\> XML
668 elements as its children, with the items text as their text values
672 The @c \<item\> elements have listbox items' labels as their text values. They
673 can also have optional @c checked XML attribute -- if set to "1", the value is
678 <object class="wxCheckListBox">
680 <item checked="1">Download library</item>
681 <item checked="1">Compile samples</item>
682 <item checked="1">Skim docs</item>
683 <item checked="1">Finish project</item>
684 <item>Wash car</item>
690 @subsubsection xrc_wxchoice wxChoice
693 @hdr3col{property, type, description}
694 @row3col{selection, integer,
695 Index of the initially selected item or -1 for no selection (default: -1).}
696 @row3col{content, items,
697 Content of the control; this property has any number of @c \<item\> XML
698 elements as its children, with the items text as their text values
704 <object class="wxChoice" name="controls_choice">
711 <item>The Sixth Sense!</item>
717 @subsubsection xrc_wxchoicebook wxChoicebook
719 A choicebook can have one or more child objects of the @c choicebookpage
720 pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its
721 @c notebookpage) and one child object of the @ref xrc_wximagelist class.
722 @c choicebookpage objects have the following properties:
725 @hdr3col{property, type, description}
726 @row3col{label, @ref overview_xrcformat_type_text,
727 Sheet page's title (required).}
728 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
729 Bitmap shown alongside the label (default: none).}
730 @row3col{image, integer,
731 The zero-based index of the image associated with the item
732 into the image list.}
733 @row3col{selected, @ref overview_xrcformat_type_bool,
734 Is the page selected initially (only one page can be selected; default: 0)?}
737 Each @c choicebookpage has exactly one non-toplevel window as its child.
740 @subsubsection xrc_wxcommandlinkbutton wxCommandLinkButton
742 The wxCommandLinkButton contains a main title-like @c label and an optional
743 @c note for longer description. The main @c label and the @c note can be
744 concatenated into a single string using a new line character between them
745 (notice that the @c note part can have more new lines in it).
748 @hdr3col{property, type, description}
749 @row3col{label, @ref overview_xrcformat_type_text,
750 First line of text on the button, typically the label of an action that
751 will be made when the button is pressed. }
752 @row3col{note, @ref overview_xrcformat_type_text,
753 Second line of text describing the action performed when the button is pressed. }
757 @subsubsection xrc_wxcollapsiblepane wxCollapsiblePane
760 @hdr3col{property, type, description}
761 @row3col{label, @ref overview_xrcformat_type_text,
762 Label to use for the collapsible section (required).}
763 @row3col{collapsed, @ref overview_xrcformat_type_bool,
764 Should the pane be collapsed initially (default: 0)?}
767 wxCollapsiblePane may contain single optional child object of the @c panewindow
768 pseudo-class type. @c panewindow itself must contain exactly one child that
769 is a @ref overview_xrcformat_sizers "sizer" or a non-toplevel window
773 @subsubsection xrc_wxcolourpickerctrl wxColourPickerCtrl
776 @hdr3col{property, type, description}
777 @row3col{value, @ref overview_xrcformat_type_colour,
778 Initial value of the control (default: wxBLACK).}
782 @subsubsection xrc_wxcombobox wxComboBox
785 @hdr3col{property, type, description}
786 @row3col{selection, integer,
787 Index of the initially selected item or -1 for no selection (default: not used).}
788 @row3col{content, items,
789 Content of the control; this property has any number of @c \<item\> XML
790 elements as its children, with the items text as their text values
792 @row3col{value, @ref overview_xrcformat_type_string,
793 Initial value in the control (doesn't have to be one of @ content values;
797 If both @c value and @c selection are specified and @c selection is not -1,
798 then @c selection takes precedence.
802 <object class="wxComboBox" name="controls_combobox">
803 <style>wxCB_DROPDOWN</style>
808 <item>notepad.exe</item>
814 @subsubsection xrc_wxdatepickerctrl wxDatePickerCtrl
816 No additional properties.
819 @subsubsection xrc_wxdialog wxDialog
822 @hdr3col{property, type, description}
823 @row3col{title, @ref overview_xrcformat_type_text,
824 Dialog's title (default: empty).}
825 @row3col{icon, @ref overview_xrcformat_type_bitmap,
826 Dialog's icon (default: not used).}
827 @row3col{centered, @ref overview_xrcformat_type_bool,
828 Whether the dialog should be centered on the screen (default: 0).}
831 wxDialog may have optional children: either exactly one
832 @ref overview_xrcformat_sizers "sizer" child or any number of non-toplevel window
833 objects. If sizer child is used, it sets
834 @ref wxSizer::SetSizeHints() "size hints" too.
836 @subsubsection xrc_wxdirpickerctrl wxDirPickerCtrl
839 @hdr3col{property, type, description}
840 @row3col{value, @ref overview_xrcformat_type_string,
841 Initial value of the control (default: empty).}
842 @row3col{message, @ref overview_xrcformat_type_text,
843 Message shown to the user in wxDirDialog shown by the control (required).}
847 @subsubsection xrc_wxfilectrl wxFileCtrl
850 @hdr3col{property, type, description}
851 @row3col{defaultdirectory, @ref overview_xrcformat_type_string,
852 Sets the current directory displayed in the control. }
853 @row3col{defaultfilename, @ref overview_xrcformat_type_string,
854 Selects a certain file.}
855 @row3col{wildcard, @ref overview_xrcformat_type_string,
856 Sets the wildcard, which can contain multiple file types, for example:
857 "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif".}
861 @subsubsection xrc_wxfilepickerctrl wxFilePickerCtrl
864 @hdr3col{property, type, description}
865 @row3col{value, @ref overview_xrcformat_type_string,
866 Initial value of the control (default: empty).}
867 @row3col{message, @ref overview_xrcformat_type_text,
868 Message shown to the user in wxDirDialog shown by the control (required).}
869 @row3col{wildcard, @ref overview_xrcformat_type_string,
870 Sets the wildcard, which can contain multiple file types, for example:
871 "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif".}
875 @subsubsection xrc_wxfontpickerctrl wxFontPickerCtrl
878 @hdr3col{property, type, description}
879 @row3col{value, @ref overview_xrcformat_type_font,
880 Initial value of the control (default: wxNORMAL_FONT).}
883 @subsubsection xrc_wxfrane wxFrame
886 @hdr3col{property, type, description}
887 @row3col{title, @ref overview_xrcformat_type_text,
888 Frame's title (default: empty).}
889 @row3col{icon, @ref overview_xrcformat_type_bitmap,
890 Frame's icon (default: not used).}
891 @row3col{centered, @ref overview_xrcformat_type_bool,
892 Whether the frame should be centered on the screen (default: 0).}
895 wxFrame may have optional children: either exactly one
896 @ref overview_xrcformat_sizers "sizer" child or any number of non-toplevel window
897 objects. If sizer child is used, it sets
898 @ref wxSizer::SetSizeHints() "size hints" too.
901 @subsubsection xrc_wxgauge wxGauge
904 @hdr3col{property, type, description}
905 @row3col{range, integer,
906 Maximum value of the gauge (default: 100).}
907 @row3col{value, integer,
908 Initial value of the control (default: 0).}
909 @row3col{shadow, @ref overview_xrcformat_type_dimension,
910 Rendered shadow size (default: none; ignored by most platforms).}
911 @row3col{bezel, @ref overview_xrcformat_type_dimension,
912 Rendered bezel size (default: none; ignored by most platforms).}
915 @subsubsection xrc_wxgenericdirctrl wxGenericDirCtrl
918 @hdr3col{property, type, description}
919 @row3col{defaultfolder, @ref overview_xrcformat_type_text,
920 Initial folder (default: empty).}
921 @row3col{filter, @ref overview_xrcformat_type_text,
922 Filter string, using the same syntax as used by wxFileDialog, e.g.
923 "All files (*.*)|*.*|JPEG files (*.jpg)|*.jpg" (default: empty).}
924 @row3col{defaultfilter, integer,
925 Zero-based index of default filter (default: 0).}
928 @subsubsection xrc_wxgrid wxGrid
930 No additional properties.
933 @subsubsection xrc_wxhtmlwindow wxHtmlWindow
936 @hdr3col{property, type, description}
937 @row3col{url, @ref overview_xrcformat_type_url,
938 Page to display in the window.}
939 @row3col{htmlcode, @ref overview_xrcformat_type_text,
940 HTML markup to display in the window.}
941 @row3col{borders, @ref overview_xrcformat_type_dimension,
942 Border around HTML content (default: 0).}
945 At most one of @c url and @c htmlcode properties may be specified, they are
946 mutually exclusive. If neither is set, the window is initialized to show empty
950 @subsubsection xrc_wxhyperlinkctrl wxHyperlinkCtrl
953 @hdr3col{property, type, description}
954 @row3col{label, @ref overview_xrcformat_type_text,
955 Label to display on the control (required).}
956 @row3col{url, @ref overview_xrcformat_type_url,
957 URL to open when the link is clicked (required).}
961 @subsubsection xrc_wximagelist wxImageList
963 The imagelist can be used as a child object for the following classes:
964 - @ref xrc_wxchoicebook
965 - @ref xrc_wxlistbook
966 - @ref xrc_wxlistctrl
967 - @ref xrc_wxnotebook
968 - @ref xrc_wxtreebook
969 - @ref xrc_wxtreectrl
971 The available properties are:
974 @hdr3col{property, type, description}
975 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
976 Adds a new image by keeping its optional mask bitmap (see below).}
977 @row3col{mask, @ref overview_xrcformat_type_bool,
978 If masks should be created for all images (default: true).}
979 @row3col{size, @ref overview_xrcformat_type_size,
980 The size of the images in the list (default: the size of the first bitmap).}
987 <bitmap stock_id="wxART_QUESTION"/>
988 <bitmap stock_id="wxART_INFORMATION"/>
992 In the specific case of the @ref xrc_wxlistctrl, the tag can take the name
993 @c \<imagelist-small\> to define the 'small' image list, related to the flag
994 @c wxIMAGE_LIST_SMALL (see wxListCtrl documentation).
997 @subsubsection xrc_wxlistbox wxListBox
1000 @hdr3col{property, type, description}
1001 @row3col{selection, integer,
1002 Index of the initially selected item or -1 for no selection (default: -1).}
1003 @row3col{content, items,
1004 Content of the control; this property has any number of @c \<item\> XML
1005 elements as its children, with the items text as their text values
1011 <object class="wxListBox" name="controls_listbox">
1012 <size>250,160</size>
1013 <style>wxLB_SINGLE</style>
1018 <item>Orange juice</item>
1019 <item>Paper towels</item>
1025 @subsubsection xrc_wxlistbook wxListbook
1027 A listbook can have one or more child objects of the @c listbookpage
1028 pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its
1029 @c notebookpage) and one child object of the @ref xrc_wximagelist class.
1030 @c listbookpage objects have the following properties:
1033 @hdr3col{property, type, description}
1034 @row3col{label, @ref overview_xrcformat_type_text,
1035 Sheet page's title (required).}
1036 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1037 Bitmap shown alongside the label (default: none).}
1038 @row3col{image, integer,
1039 The zero-based index of the image associated with the item
1040 into the image list.}
1041 @row3col{selected, @ref overview_xrcformat_type_bool,
1042 Is the page selected initially (only one page can be selected; default: 0)?}
1045 Each @c listbookpage has exactly one non-toplevel window as its child.
1048 @subsubsection xrc_wxlistctrl wxListCtrl
1050 A list control can have one or more child objects of the class @ref xrc_wxlistitem
1051 and one or more objects of the @ref xrc_wximagelist class. The latter is
1052 defined either using @c \<imagelist\> tag for the control with @c wxLC_ICON
1053 style or using @c \<imagelist-small\> tag for the control with @c
1054 wxLC_SMALL_ICON style.
1056 Report mode list controls (i.e. created with @c wxLC_REPORT style) can in
1057 addition have one or more @ref xrc_wxlistcol child elements.
1059 @paragraph xrc_wxlistcol listcol
1061 The @c listcol class can only be used for wxListCtrl children. It can have the
1062 following properties:
1064 @hdr3col{property, type, description}
1065 @row3col{align, wxListColumnFormat,
1066 The alignment for the item.
1067 Can be one of @c wxLIST_FORMAT_LEFT, @c wxLIST_FORMAT_RIGHT or
1068 @c wxLIST_FORMAT_CENTRE.}
1069 @row3col{text, @ref overview_xrcformat_type_string,
1070 The title of the column. }
1071 @row3col{width, integer,
1073 @row3col{image, integer,
1074 The zero-based index of the image associated with the item in the 'small' image list. }
1077 The columns are appended to the control in order of their appearance and may be
1078 referenced by 0-based index in the @c col attributes of subsequent @c listitem
1081 @paragraph xrc_wxlistitem listitem
1083 The @c listitem is a child object for the class @ref xrc_wxlistctrl.
1084 It can have the following properties:
1087 @hdr3col{property, type, description}
1088 @row3col{align, wxListColumnFormat,
1089 The alignment for the item.
1090 Can be one of @c wxLIST_FORMAT_LEFT, @c wxLIST_FORMAT_RIGHT or
1091 @c wxLIST_FORMAT_CENTRE.}
1092 @row3col{bg, @ref overview_xrcformat_type_colour,
1093 The background color for the item.}
1094 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1095 Add a bitmap to the (normal) @ref xrc_wximagelist associated with the
1096 @ref xrc_wxlistctrl parent and associate it with this item.
1097 If the imagelist is not defined it will be created implicitly.}
1098 @row3col{bitmap-small, @ref overview_xrcformat_type_bitmap,
1099 Add a bitmap in the 'small' @ref xrc_wximagelist associated with the
1100 @ref xrc_wxlistctrl parent and associate it with this item.
1101 If the 'small' imagelist is not defined it will be created implicitly.}
1102 @row3col{col, integer,
1103 The zero-based column index.}
1104 @row3col{image, integer,
1105 The zero-based index of the image associated with the item
1106 in the (normal) image list.}
1107 @row3col{image-small, integer,
1108 The zero-based index of the image associated with the item
1109 in the 'small' image list.}
1110 @row3col{data, integer,
1111 The client data for the item.}
1112 @row3col{font, @ref overview_xrcformat_type_font,
1113 The font for the item.}
1114 @row3col{image, integer,
1115 The zero-based index of the image associated with the item
1116 into the image list.}
1117 @row3col{state, @ref overview_xrcformat_type_style,
1118 The item state. Can be any combination of the following values:
1119 - @c wxLIST_STATE_FOCUSED: The item has the focus.
1120 - @c wxLIST_STATE_SELECTED: The item is selected.}
1121 @row3col{text, @ref overview_xrcformat_type_string,
1122 The text label for the item. }
1123 @row3col{textcolour, @ref overview_xrcformat_type_colour,
1124 The text colour for the item. }
1127 Notice that the item position can't be specified here, the items are appended
1128 to the list control in order of their appearance.
1131 @subsubsection xrc_wxmdiparentframe wxMDIParentFrame
1133 wxMDIParentFrame supports the same properties that @ref xrc_wxfrane does.
1135 wxMDIParentFrame may have optional children. When used, the child objects
1136 must be of wxMDIChildFrame type.
1139 @subsubsection xrc_wxmdichildframe wxMDIChildFrame
1141 wxMDIChildFrame supports the same properties that @ref xrc_wxfrane and
1142 @ref xrc_wxmdiparentframe do.
1144 wxMDIChildFrame can only be used as as immediate child of @ref
1145 xrc_wxmdiparentframe.
1147 wxMDIChildFrame may have optional children: either exactly one
1148 @ref overview_xrcformat_sizers "sizer" child or any number of non-toplevel window
1149 objects. If sizer child is used, it sets
1150 @ref wxSizer::SetSizeHints() "size hints" too.
1153 @subsubsection xrc_wxmenu wxMenu
1156 @hdr3col{property, type, description}
1157 @row3col{label, @ref overview_xrcformat_type_text,
1158 Menu's label (default: empty, but required for menus other
1160 @row3col{help, @ref overview_xrcformat_type_text,
1161 Help shown in statusbar when the menu is selected (only for submenus
1162 of another wxMenu, default: none).}
1163 @row3col{enabled, @ref overview_xrcformat_type_bool,
1164 Is the submenu item enabled (only for submenus of another wxMenu,
1168 Note that unlike most controls, wxMenu does @em not have
1169 @ref overview_xrcformat_std_props.
1171 A menu object can have one or more child objects of the wxMenuItem or wxMenu
1172 classes or @c break or @c separator pseudo-classes.
1174 The @c separator pseudo-class is used to insert separators into the menu and
1175 has neither properties nor children. Likewise, @c break inserts a break (see
1178 wxMenuItem objects support the following properties:
1181 @hdr3col{property, type, description}
1182 @row3col{label, @ref overview_xrcformat_type_text,
1183 Item's label (required).}
1184 @row3col{accel, @ref overview_xrcformat_type_text_notrans,
1185 Item's accelerator (default: none).}
1186 @row3col{radio, @ref overview_xrcformat_type_bool,
1187 Item's kind is wxITEM_RADIO (default: 0)?}
1188 @row3col{checkable, @ref overview_xrcformat_type_bool,
1189 Item's kind is wxITEM_CHECK (default: 0)?}
1190 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1191 Bitmap to show with the item (default: none).}
1192 @row3col{bitmap2, @ref overview_xrcformat_type_bitmap,
1193 Bitmap for the checked state (wxMSW, if checkable; default: none).}
1194 @row3col{help, @ref overview_xrcformat_type_text,
1195 Help shown in statusbar when the item is selected (default: none).}
1196 @row3col{enabled, @ref overview_xrcformat_type_bool,
1197 Is the item enabled (default: 1)?}
1198 @row3col{checked, @ref overview_xrcformat_type_bool,
1199 Is the item checked initially (default: 0)?}
1204 <object class="wxMenu" name="menu_edit">
1205 <style>wxMENU_TEAROFF</style>
1206 <label>_Edit</label>
1207 <object class="wxMenuItem" name="wxID_FIND">
1208 <label>_Find...</label>
1209 <accel>Ctrl-F</accel>
1211 <object class="separator"/>
1212 <object class="wxMenuItem" name="menu_fuzzy">
1213 <label>Translation is _fuzzy</label>
1214 <checkable>1</checkable>
1216 <object class="wxMenu" name="submenu">
1217 <label>A submenu</label>
1218 <object class="wxMenuItem" name="foo">...</object>
1221 <object class="separator" platform="unix"/>
1222 <object class="wxMenuItem" name="wxID_PREFERENCES" platform="unix">
1223 <label>_Preferences</label>
1228 @subsubsection xrc_wxmenubar wxMenuBar
1230 No properties. Note that unlike most controls, wxMenuBar does @em not have
1231 @ref overview_xrcformat_std_props.
1233 A menubar can have one or more child objects of the @ref xrc_wxmenu "wxMenu"
1237 @subsubsection xrc_wxnotebook wxNotebook
1239 A notebook can have one or more child objects of the @c notebookpage
1240 pseudo-class and one child object of the @ref xrc_wximagelist class.
1241 @c notebookpage objects have the following properties:
1244 @hdr3col{property, type, description}
1245 @row3col{label, @ref overview_xrcformat_type_text,
1246 Page's title (required).}
1247 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1248 Bitmap shown alongside the label (default: none).}
1249 @row3col{image, integer,
1250 The zero-based index of the image associated with the item
1251 into the image list.}
1252 @row3col{selected, @ref overview_xrcformat_type_bool,
1253 Is the page selected initially (only one page can be selected; default: 0)?}
1256 Each @c notebookpage has exactly one non-toplevel window as its child.
1260 <object class="wxNotebook">
1261 <style>wxBK_BOTTOM</style>
1262 <object class="notebookpage">
1263 <label>Page 1</label>
1264 <object class="wxPanel" name="page_1">
1268 <object class="notebookpage">
1269 <label>Page 2</label>
1270 <object class="wxPanel" name="page_2">
1278 @subsubsection xrc_wxownerdrawncombobox wxOwnerDrawnComboBox
1280 wxOwnerDrawnComboBox has the same properties as
1281 @ref xrc_wxcombobox "wxComboBox", plus the following additional properties:
1284 @hdr3col{property, type, description}
1285 @row3col{buttonsize, @ref overview_xrcformat_type_size,
1286 Size of the dropdown button (default: default).}
1290 @subsubsection xrc_wxpanel wxPanel
1292 No additional properties.
1294 wxPanel may have optional children: either exactly one
1295 @ref overview_xrcformat_sizers "sizer" child or any number of non-toplevel window
1299 @subsubsection xrc_wxpropertysheetdialog wxPropertySheetDialog
1302 @hdr3col{property, type, description}
1303 @row3col{title, @ref overview_xrcformat_type_text,
1304 Dialog's title (default: empty).}
1305 @row3col{icon, @ref overview_xrcformat_type_bitmap,
1306 Dialog's icon (default: not used).}
1307 @row3col{centered, @ref overview_xrcformat_type_bool,
1308 Whether the dialog should be centered on the screen (default: 0).}
1309 @row3col{buttons, @ref overview_xrcformat_type_style,
1310 Buttons to show, combination of flags accepted by
1311 wxPropertySheetDialog::CreateButtons() (default: 0).}
1314 A sheet dialog can have one or more child objects of the @c propertysheetpage
1315 pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its
1316 @c notebookpage). @c propertysheetpage objects have the following properties:
1319 @hdr3col{property, type, description}
1320 @row3col{label, @ref overview_xrcformat_type_text,
1321 Sheet page's title (required).}
1322 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1323 Bitmap shown alongside the label (default: none).}
1324 @row3col{selected, @ref overview_xrcformat_type_bool,
1325 Is the page selected initially (only one page can be selected; default: 0)?}
1328 Each @c propertysheetpage has exactly one non-toplevel window as its child.
1331 @subsubsection xrc_wxradiobutton wxRadioButton
1334 @hdr3col{property, type, description}
1335 @row3col{label, @ref overview_xrcformat_type_text,
1336 Label shown on the radio button (required).}
1337 @row3col{value, @ref overview_xrcformat_type_bool,
1338 Initial value of the control (default: 0).}
1342 @subsubsection xrc_wxradiobox wxRadioBox
1345 @hdr3col{property, type, description}
1346 @row3col{label, @ref overview_xrcformat_type_text,
1347 Label for the whole box (required).}
1348 @row3col{dimension, integer,
1349 Specifies the maximum number of rows (if style contains
1350 @c wxRA_SPECIFY_ROWS) or columns (if style contains @c wxRA_SPECIFY_COLS)
1351 for a two-dimensional radiobox (default: 1).}
1352 @row3col{selection, integer,
1353 Index of the initially selected item or -1 for no selection (default: -1).}
1354 @row3col{content, items,
1355 Content of the control; this property has any number of @c \<item\> XML
1356 elements as its children, with the items text as their text values
1357 (see below; default: empty).}
1360 The @c \<item\> elements have radio buttons' labels as their text values. They
1361 can also have some optional XML @em attributes (not properties!):
1364 @hdr3col{attribute, type, description}
1365 @row3col{tooltip, @ref overview_xrcformat_type_string,
1366 Tooltip to show over this ratio button (default: none).}
1367 @row3col{helptext, @ref overview_xrcformat_type_string,
1368 Contextual help for this radio button (default: none).}
1369 @row3col{enabled, @ref overview_xrcformat_type_bool,
1370 Is the button enabled (default: 1)?}
1371 @row3col{hidden, @ref overview_xrcformat_type_bool,
1372 Is the button hidden initially (default: 0)?}
1377 <object class="wxRadioBox" name="controls_radiobox">
1378 <style>wxRA_SPECIFY_COLS</style>
1379 <label>Radio stations</label>
1380 <dimension>1</dimension>
1381 <selection>0</selection>
1383 <item tooltip="Powerful radio station" helptext="This station is for amateurs of hard rock and heavy metal">Power 108</item>
1384 <item tooltip="Disabled radio station" enabled="0">Power 0</item>
1385 <item tooltip="">WMMS 100.7</item>
1386 <item tooltip="E=mc^2">Energy 98.3</item>
1387 <item helptext="Favourite chukcha's radio">CHUM FM</item>
1389 <item hidden="1">Very quit station</item>
1395 @subsubsection xrc_wxrichtextctrl wxRichTextCtrl
1398 @hdr3col{property, type, description}
1399 @row3col{value, @ref overview_xrcformat_type_text,
1400 Initial value of the control (default: empty).}
1401 @row3col{maxlength, integer,
1402 Maximum length of the text entered (default: unlimited).}
1406 @subsubsection xrc_wxscrollbar wxScrollBar
1409 @hdr3col{property, type, description}
1410 @row3col{value, integer,
1411 Initial position of the scrollbar (default: 0).}
1412 @row3col{range, integer,
1413 Maximum value of the gauge (default: 10).}
1414 @row3col{thumbsize, integer,
1415 Size of the thumb (default: 1).}
1416 @row3col{pagesize, integer,
1417 Page size (default: 1).}
1420 @subsubsection xrc_wxscrolledwindow wxScrolledWindow
1423 @hdr3col{property, type, description}
1424 @row3col{scrollrate, @ref overview_xrcformat_type_size,
1425 Scroll rate in @em x and @em y directions (default: not set;
1426 required if the window has a sizer child).}
1429 wxScrolledWindow may have optional children: either exactly one
1430 @ref overview_xrcformat_sizers "sizer" child or any number of non-toplevel window
1431 objects. If sizer child is used, wxSizer::FitInside() is used (instead of
1432 wxSizer::Fit() as usual) and so the children don't determine scrolled window's
1433 minimal size, they only affect @em virtual size. Usually, both @c scrollrate
1434 and either @c size or @c minsize on containing sizer item should be used
1438 @subsubsection xrc_wxsimplehtmllistbox wxSimpleHtmlListBox
1440 wxSimpleHtmlListBox has same properties as @ref xrc_wxlistbox "wxListBox".
1441 The only difference is that the text contained in @c \<item\> elements is
1442 HTML markup. Note that the markup has to be escaped:
1445 <object class="wxSimpleHtmlListBox">
1447 <item><b>Bold</b> Milk</item>
1452 (X)HTML markup elements cannot be included directly:
1455 <object class="wxSimpleHtmlListBox">
1457 <!-- This is incorrect, doesn't work! -->
1458 <item><b>Bold</b> Milk</item>
1464 @subsubsection xrc_wxslider wxSlider
1467 @hdr3col{property, type, description}
1468 @row3col{value, integer,
1469 Initial value of the control (default: 0).}
1470 @row3col{min, integer,
1471 Minimum allowed value (default: 0).}
1472 @row3col{max, integer,
1473 Maximum allowed value (default: 100).}
1474 @row3col{pagesize, integer,
1475 Page size; number of steps the slider moves when the user moves
1476 pages up or down (default: unset).}
1477 @row3col{linesize, integer,
1478 Line size; number of steps the slider moves when the user moves it
1479 up or down a line (default: unset).}
1480 @row3col{tickfreq, integer,
1481 Tick marks frequency (Windows only; default: unset).}
1482 @row3col{tick, integer,
1483 Tick position (Windows only; default: unset).}
1484 @row3col{thumb, integer,
1485 Thumb length (Windows only; default: unset).}
1486 @row3col{selmin, integer,
1487 Selection start position (Windows only; default: unset).}
1488 @row3col{selmax, integer,
1489 Selection end position (Windows only; default: unset).}
1493 @subsubsection xrc_wxspinbutton wxSpinButton
1496 @hdr3col{property, type, description}
1497 @row3col{value, integer,
1498 Initial value of the control (default: 0).}
1499 @row3col{min, integer,
1500 Minimum allowed value (default: 0).}
1501 @row3col{max, integer,
1502 Maximum allowed value (default: 100).}
1506 @subsubsection xrc_wxspinctrl wxSpinCtrl
1508 wxSpinCtrl supports the same properties as @ref xrc_wxspinbutton and, since
1509 wxWidgets 2.9.5, another one:
1511 @row3col{base, integer,
1512 Numeric base, currently can be only 10 or 16 (default: 10).}
1516 @subsubsection xrc_wxsplitterwindow wxSplitterWindow
1519 @hdr3col{property, type, description}
1520 @row3col{orientation, @ref overview_xrcformat_type_string,
1521 Orientation of the splitter, either "vertical" or "horizontal" (default: horizontal).}
1522 @row3col{sashpos, integer,
1523 Initial position of the sash (default: 0).}
1524 @row3col{minsize, integer,
1525 Minimum child size (default: not set).}
1526 @row3col{gravity, @ref overview_xrcformat_type_float,
1527 Sash gravity, see wxSplitterWindow::SetSashGravity() (default: not set).}
1530 wxSplitterWindow must have one or two children that are non-toplevel window
1531 objects. If there's only one child, it is used as wxSplitterWindow's only
1532 visible child. If there are two children, the first one is used for left/top
1533 child and the second one for right/bottom child window.
1536 @subsubsection xrc_wxsearchctrl wxSearchCtrl
1539 @hdr3col{property, type, description}
1540 @row3col{value, @ref overview_xrcformat_type_text,
1541 Initial value of the control (default: empty).}
1545 @subsubsection xrc_wxstatusbar wxStatusBar
1548 @hdr3col{property, type, description}
1549 @row3col{fields, integer,
1550 Number of status bar fields (default: 1).}
1551 @row3col{widths, @ref overview_xrcformat_type_string,
1552 Comma-separated list of @em fields integers. Each value specifies width
1553 of one field; the values are interpreted using the same convention used
1554 by wxStatusBar::SetStatusWidths().}
1555 @row3col{styles, @ref overview_xrcformat_type_string,
1556 Comma-separated list of @em fields flags. Each value specifies status bar
1557 fieldd style and can be one of @c wxSB_NORMAL, @c wxSB_FLAT or
1558 @c wxSB_RAISED. See wxStatusBar::SetStatusStyles() for their description.}
1563 @subsubsection xrc_wxstaticbitmap wxStaticBitmap
1566 @hdr3col{property, type, description}
1567 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1568 Bitmap to display (required).}
1571 @subsubsection xrc_wxstaticbox wxStaticBox
1574 @hdr3col{property, type, description}
1575 @row3col{label, @ref overview_xrcformat_type_text,
1576 Static box's label (required).}
1580 @subsubsection xrc_wxstaticline wxStaticLine
1582 No additional properties.
1585 @subsubsection xrc_wxstatictext wxStaticText
1588 @hdr3col{property, type, description}
1589 @row3col{label, @ref overview_xrcformat_type_text,
1590 Label to display (required).}
1591 @row3col{wrap, integer,
1592 Wrap the text so that each line is at most the given number of pixels, see
1593 wxStaticText::Wrap() (default: no wrap).}
1596 @subsubsection xrc_wxtextctrl wxTextCtrl
1599 @hdr3col{property, type, description}
1600 @row3col{value, @ref overview_xrcformat_type_text,
1601 Initial value of the control (default: empty).}
1602 @row3col{maxlength, integer,
1603 Maximum length of the text which can be entered by user (default: unlimited).}
1607 @subsubsection xrc_wxtimepickerctrl wxTimePickerCtrl
1609 No additional properties.
1612 @subsubsection xrc_wxtogglebutton wxToggleButton
1615 @hdr3col{property, type, description}
1616 @row3col{label, @ref overview_xrcformat_type_text,
1617 Label to display on the button (required).}
1618 @row3col{checked, @ref overview_xrcformat_type_bool,
1619 Should the button be checked/pressed initially (default: 0)?}
1622 @subsubsection xrc_wxtoolbar wxToolBar
1625 @hdr3col{property, type, description}
1626 @row3col{bitmapsize, @ref overview_xrcformat_type_size,
1627 Size of toolbar bitmaps (default: not set).}
1628 @row3col{margins, @ref overview_xrcformat_type_size,
1629 Margins (default: platform default).}
1630 @row3col{packing, integer,
1631 Packing, see wxToolBar::SetToolPacking() (default: not set).}
1632 @row3col{separation, integer,
1633 Default separator size, see wxToolBar::SetToolSeparation() (default: not set).}
1634 @row3col{dontattachtoframe, @ref overview_xrcformat_type_bool,
1635 If set to 0 and the toolbar object is child of a wxFrame,
1636 wxFrame::SetToolBar() is called; otherwise, you have to add it to a frame
1637 manually. The toolbar is attached by default, you have to set this property
1638 to 1 to disable this behaviour (default: 0).}
1641 A toolbar can have one or more child objects of any wxControl-derived class or
1642 one of two pseudo-classes: @c separator or @c tool.
1644 The @c separator pseudo-class is used to insert separators into the toolbar and
1645 has neither properties nor children. Similarly, the @c space pseudo-class is
1646 used for stretchable spaces (see wxToolBar::AddStretchableSpace(), new since
1649 The @c tool pseudo-class objects specify toolbar buttons and have the following
1653 @hdr3col{property, type, description}
1654 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1655 Tool's bitmap (required).}
1656 @row3col{bitmap2, @ref overview_xrcformat_type_bitmap,
1657 Bitmap for disabled tool (default: derived from @c bitmap).}
1658 @row3col{label, @ref overview_xrcformat_type_text,
1659 Label to display on the tool (default: no label).}
1660 @row3col{radio, @ref overview_xrcformat_type_bool,
1661 Item's kind is wxITEM_RADIO (default: 0)?}
1662 @row3col{toggle, @ref overview_xrcformat_type_bool,
1663 Item's kind is wxITEM_CHECK (default: 0)?}
1664 @row3col{dropdown, see below,
1665 Item's kind is wxITEM_DROPDOWN (default: 0)? (only available since wxWidgets 2.9.0)}
1666 @row3col{tooltip, @ref overview_xrcformat_type_text,
1667 Tooltip to use for the tool (default: none).}
1668 @row3col{longhelp, @ref overview_xrcformat_type_text,
1669 Help text shown in statusbar when the mouse is on the tool (default: none).}
1670 @row3col{disabled, @ref overview_xrcformat_type_bool,
1671 Is the tool initially disabled (default: 0)?}
1672 @row3col{checked, @ref overview_xrcformat_type_bool,
1673 Is the tool initially checked (default: 0)? (only available since wxWidgets 2.9.3)}
1676 The presence of a @c dropdown property indicates that the tool is of type
1677 wxITEM_DROPDOWN. It must be either empty or contain exactly one @ref
1678 xrc_wxmenu child object defining the drop-down button associated menu.
1680 Notice that @c radio, @c toggle and @c dropdown are mutually exclusive.
1682 Children that are neither @c tool nor @c separator must be instances of classes
1683 derived from wxControl and are added to the toolbar using
1684 wxToolBar::AddControl().
1688 <object class="wxToolBar">
1689 <style>wxTB_FLAT|wxTB_NODIVIDER</style>
1690 <object class="tool" name="foo">
1691 <bitmap>foo.png</bitmap>
1694 <object class="tool" name="bar">
1695 <bitmap>bar.png</bitmap>
1698 <object class="separator"/>
1699 <object class="tool" name="view_auto">
1700 <bitmap>view.png</bitmap>
1703 <object class="wxMenu">
1704 <object class="wxMenuItem" name="view_as_text">
1705 <label>View as text</label>
1707 <object class="wxMenuItem" name="view_as_hex">
1708 <label>View as binary</label>
1713 <object class="space"/>
1714 <object class="wxComboBox">
1717 <item>a combobox</item>
1718 <item>in the toolbar</item>
1726 @subsubsection xrc_wxtoolbook wxToolbook
1728 A toolbook can have one or more child objects of the @c toolbookpage
1729 pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its
1730 @c notebookpage) and one child object of the @ref xrc_wximagelist class.
1731 @c toolbookpage objects have the following properties:
1734 @hdr3col{property, type, description}
1735 @row3col{label, @ref overview_xrcformat_type_text,
1736 Sheet page's title (required).}
1737 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1738 Bitmap shown alongside the label (default: none).}
1739 @row3col{image, integer,
1740 The zero-based index of the image associated with the item
1741 into the image list.}
1742 @row3col{selected, @ref overview_xrcformat_type_bool,
1743 Is the page selected initially (only one page can be selected; default: 0)?}
1746 Each @c toolbookpage has exactly one non-toplevel window as its child.
1749 @subsubsection xrc_wxtreectrl wxTreeCtrl
1751 A treectrl can have one child object of the @ref xrc_wximagelist class.
1753 No additional properties.
1756 @subsubsection xrc_wxtreebook wxTreebook
1758 A treebook can have one or more child objects of the @c treebookpage
1759 pseudo-class (similarly to @ref xrc_wxnotebook "wxNotebook" and its
1760 @c notebookpage) and one child object of the @ref xrc_wximagelist class.
1761 @c treebookpage objects have the following properties:
1764 @hdr3col{property, type, description}
1765 @row3col{depth, integer,
1766 Page's depth in the labels tree (required; see below).}
1767 @row3col{label, @ref overview_xrcformat_type_text,
1768 Sheet page's title (required).}
1769 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1770 Bitmap shown alongside the label (default: none).}
1771 @row3col{image, integer,
1772 The zero-based index of the image associated with the item
1773 into the image list.}
1774 @row3col{selected, @ref overview_xrcformat_type_bool,
1775 Is the page selected initially (only one page can be selected; default: 0)?}
1776 @row3col{expanded, @ref overview_xrcformat_type_bool,
1777 If set to 1, the page is initially expanded. By default all pages are
1778 initially collapsed.}
1781 Each @c treebookpage has exactly one non-toplevel window as its child.
1783 The tree of labels is not described using nested @c treebookpage objects, but
1784 using the @em depth property. Toplevel pages have depth 0, their child pages
1785 have depth 1 and so on. A @c treebookpage's label is inserted as child of
1786 the latest preceding page with depth equal to @em depth-1. For example, this
1790 <object class="wxTreebook">
1792 <object class="treebookpage">
1794 <label>Page 1</label>
1795 <object class="wxPanel">...</object>
1797 <object class="treebookpage">
1799 <label>Subpage 1A</label>
1800 <object class="wxPanel">...</object>
1802 <object class="treebookpage">
1804 <label>Subsubpage 1</label>
1805 <object class="wxPanel">...</object>
1807 <object class="treebookpage">
1809 <label>Subpage 1B</label>
1810 <object class="wxPanel">...</object>
1812 <object class="treebookpage">
1814 <label>Subsubpage 2</label>
1815 <object class="wxPanel">...</object>
1817 <object class="treebookpage">
1819 <label>Page 2</label>
1820 <object class="wxPanel">...</object>
1825 corresponds to the following tree of labels:
1835 @subsubsection xrc_wxwizard wxWizard
1838 @hdr3col{property, type, description}
1839 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1840 Bitmap to display on the left side of the wizard (default: none).}
1843 A wizard object can have one or more child objects of the wxWizardPage or
1844 wxWizardPageSimple classes. They both support the following properties
1845 (in addition to @ref overview_xrcformat_std_props):
1848 @hdr3col{property, type, description}
1849 @row3col{bitmap, @ref overview_xrcformat_type_bitmap,
1850 Page-specific bitmap (default: none).}
1853 wxWizardPageSimple pages are automatically chained together; wxWizardPage pages
1854 transitions must be handled programmatically.
1857 @section overview_xrcformat_sizers Sizers
1859 Sizers are handled slightly differently in XRC resources than they are in
1860 wxWindow hierarchy. wxWindow's sizers hierarchy is parallel to the wxWindow
1861 children hierarchy: child windows are children of their parent window and
1862 the sizer (or sizers) form separate hierarchy attached to the window with
1863 wxWindow::SetSizer().
1865 In XRC, the two hierarchies are merged together: sizers are children of other
1866 sizers or windows and they can contain child window objects.
1868 If a sizer is child of a window object in the resource, it must be the only
1869 child and it will be attached to the parent with wxWindow::SetSizer().
1870 Additionally, if the window doesn't have its size explicitly set,
1871 wxSizer::Fit() is used to resize the window. If the parent window is
1872 toplevel window, wxSizer::SetSizeHints() is called to set its hints.
1874 A sizer object can have one or more child objects of one of two pseudo-classes:
1875 @c sizeritem or @c spacer (see @ref overview_xrcformat_wxstddialogbuttonsizer for
1876 an exception). The former specifies an element (another sizer or a window)
1877 to include in the sizer, the latter adds empty space to the sizer.
1879 @c sizeritem objects have exactly one child object: either another sizer
1880 object, or a window object. @c spacer objects don't have any children, but
1881 they have one property:
1884 @hdr3col{property, type, description}
1885 @row3col{size, @ref overview_xrcformat_type_size, Size of the empty space (required).}
1888 Both @c sizeritem and @c spacer objects can have any of the following
1892 @hdr3col{property, type, description}
1893 @row3col{option, integer,
1894 The "option" value for sizers. Used by wxBoxSizer to set proportion of
1895 the item in the growable direction (default: 0).}
1896 @row3col{flag, @ref overview_xrcformat_type_style,
1897 wxSizerItem flags (default: 0).}
1898 @row3col{border, @ref overview_xrcformat_type_dimension,
1899 Size of the border around the item (directions are specified in flags)
1901 @row3col{minsize, @ref overview_xrcformat_type_size,
1902 Minimal size of this item (default: no min size).}
1903 @row3col{ratio, @ref overview_xrcformat_type_size,
1904 Item ratio, see wxSizer::SetRatio() (default: no ratio).}
1905 @row3col{cellpos, @ref overview_xrcformat_type_pos,
1906 (wxGridBagSizer only) Position, see wxGBSizerItem::SetPos() (required). }
1907 @row3col{cellspan, @ref overview_xrcformat_type_size,
1908 (wxGridBagSizer only) Span, see wxGBSizerItem::SetSpan() (required). }
1911 Example of sizers XRC code:
1913 <object class="wxDialog" name="derived_dialog">
1914 <title>Derived Dialog Example</title>
1915 <centered>1</centered>
1916 <!-- this sizer is set to be this dialog's sizer: -->
1917 <object class="wxFlexGridSizer">
1922 <growablecols>0</growablecols>
1923 <growablerows>0</growablerows>
1924 <object class="sizeritem">
1925 <flag>wxALIGN_CENTRE|wxALL</flag>
1927 <object class="wxButton" name="my_button">
1928 <label>My Button</label>
1931 <object class="sizeritem">
1932 <flag>wxALIGN_CENTRE|wxALL</flag>
1934 <object class="wxBoxSizer">
1935 <orient>wxHORIZONTAL</orient>
1936 <object class="sizeritem">
1937 <flag>wxALIGN_CENTRE|wxALL</flag>
1939 <object class="wxCheckBox" name="my_checkbox">
1940 <label>Enable this text control:</label>
1943 <object class="sizeritem">
1944 <flag>wxALIGN_CENTRE|wxALL</flag>
1946 <object class="wxTextCtrl" name="my_textctrl">
1958 The sizer classes that can be used are listed below, together with their
1959 class-specific properties. All classes support the following properties:
1962 @hdr3col{property, type, description}
1963 @row3col{minsize, @ref overview_xrcformat_type_size,
1964 Minimal size that this sizer will have, see wxSizer::SetMinSize()
1965 (default: no min size).}
1968 @subsection overview_xrcformat_wxboxsizer wxBoxSizer
1971 @hdr3col{property, type, description}
1972 @row3col{orient, @ref overview_xrcformat_type_style,
1973 Sizer orientation, "wxHORIZONTAL" or "wxVERTICAL" (default: wxHORIZONTAL).}
1976 @subsection overview_xrcformat_wxstaticsboxizer wxStaticBoxSizer
1979 @hdr3col{property, type, description}
1980 @row3col{orient, @ref overview_xrcformat_type_style,
1981 Sizer orientation, "wxHORIZONTAL" or "wxVERTICAL" (default: wxHORIZONTAL).}
1982 @row3col{label, @ref overview_xrcformat_type_text,
1983 Label to be used for the static box around the sizer (required).}
1986 @subsection overview_xrcformat_wxgridsizer wxGridSizer
1989 @hdr3col{property, type, description}
1990 @row3col{rows, integer, Number of rows in the grid (default: 0 - determine automatically).}
1991 @row3col{cols, integer, Number of columns in the grid (default: 0 - determine automatically).}
1992 @row3col{vgap, integer, Vertical gap between children (default: 0).}
1993 @row3col{hgap, integer, Horizontal gap between children (default: 0).}
1996 @subsection overview_xrcformat_wxflexgridsizer wxFlexGridSizer
1999 @hdr3col{property, type, description}
2000 @row3col{rows, integer, Number of rows in the grid (default: 0 - determine automatically).}
2001 @row3col{cols, integer, Number of columns in the grid (default: 0 - determine automatically).}
2002 @row3col{vgap, integer, Vertical gap between children (default: 0).}
2003 @row3col{hgap, integer, Horizontal gap between children (default: 0).}
2004 @row3col{growablerows, comma-separated integers list,
2005 Comma-separated list of indexes of rows that are growable
2007 @row3col{growablecols, comma-separated integers list,
2008 Comma-separated list of indexes of columns that are growable
2012 @subsection overview_xrcformat_wxgridbagsizer wxGridBagSizer
2015 @hdr3col{property, type, description}
2016 @row3col{vgap, integer, Vertical gap between children (default: 0).}
2017 @row3col{hgap, integer, Horizontal gap between children (default: 0).}
2018 @row3col{growablerows, comma-separated integers list,
2019 Comma-separated list of indexes of rows that are growable
2021 @row3col{growablecols, comma-separated integers list,
2022 Comma-separated list of indexes of columns that are growable
2026 @subsection overview_xrcformat_wxwrapsizer wxWrapSizer
2029 @hdr3col{property, type, description}
2030 @row3col{orient, @ref overview_xrcformat_type_style,
2031 Sizer orientation, "wxHORIZONTAL" or "wxVERTICAL" (required).}
2032 @row3col{flag, @ref overview_xrcformat_type_style, wxWrapSizer flags (default: 0).}
2035 @subsection overview_xrcformat_wxstddialogbuttonsizer wxStdDialogButtonSizer
2037 Unlike other sizers, wxStdDialogButtonSizer has neither @c sizeritem
2038 nor @c spacer children. Instead, it has one or more children of the
2039 @c button pseudo-class. @c button objects have no properties and they must
2040 always have exactly one child of the @c wxButton class or a class derived from
2045 <object class="wxStdDialogButtonSizer">
2046 <object class="button">
2047 <object class="wxButton" name="wxID_OK">
2051 <object class="button">
2052 <object class="wxButton" name="wxID_CANCEL">
2053 <label>Cancel</label>
2061 @section overview_xrcformat_other_objects Other Objects
2063 In addition to describing UI elements, XRC files can contain non-windows
2064 objects such as bitmaps or icons. This is a concession to Windows developers
2065 used to storing them in Win32 resources.
2067 Note that unlike Win32 resources, bitmaps included in XRC files are @em not
2068 embedded in the XRC file itself. XRC file only contains a reference to another
2069 file with bitmap data.
2071 @subsection overview_xrcformat_bitmap wxBitmap
2073 Bitmaps are stored in @c \<object\> element with class set to @c wxBitmap. Such
2074 bitmaps can then be loaded using wxXmlResource::LoadBitmap(). The content of
2075 the element is exactly same as in the case of
2076 @ref overview_xrcformat_type_bitmap "bitmap properties", except that toplevel
2077 @c \<object\> is used.
2079 For example, instead of:
2081 <bitmap>mybmp.png</bitmap>
2082 <bitmap stock_id="wxART_NEW"/>
2084 toplevel wxBitmap resources would look like:
2086 <object class="wxBitmap" name="my_bitmap">mybmp.png</object>
2087 <object class="wxBitmap" name="my_new_bitmap" stock_id="wxART_NEW"/>
2091 @subsection overview_xrcformat_icon wxIcon
2093 wxIcon resources are identical to @ref overview_xrcformat_bitmap "wxBitmap ones",
2094 except that the class is @c wxIcon.
2097 @section overview_xrcformat_platform Platform Specific Content
2099 It is possible to conditionally process parts of XRC files on some platforms
2100 only and ignore them on other platforms. @em Any element in XRC file, be it
2101 toplevel or arbitrarily nested one, can have the @c platform attribute. When
2102 used, @c platform contains |-separated list of platforms that this element
2103 should be processed on. It is filtered out and ignored on any other platforms.
2105 Possible elemental values are:
2107 @itemdef{ @c win, Windows }
2108 @itemdef{ @c mac, Mac OS X (or Mac Classic in wxWidgets version supporting it) }
2109 @itemdef{ @c unix, Any Unix platform @em except OS X }
2110 @itemdef{ @c os2, OS/2 }
2115 <label platform="win">Windows</label>
2116 <label platform="unix">Unix</label>
2117 <label platform="mac">Mac OS X</label>
2118 <help platform="mac|unix">Not a Windows machine</help>
2123 @section overview_xrcformat_idranges ID Ranges
2125 Usually you won't care what value the XRCID macro returns for the ID of an
2126 object. Sometimes though it is convenient to have a range of IDs that are
2127 guaranteed to be consecutive. An example of this would be connecting a group of
2128 similar controls to the same event handler.
2130 The following XRC fragment 'declares' an ID range called @em foo and another
2131 called @em bar; each with some items.
2134 <object class="wxButton" name="foo[start]">
2135 <object class="wxButton" name="foo[end]">
2136 <object class="wxButton" name="foo[2]">
2138 <object class="wxButton" name="bar[0]">
2139 <object class="wxButton" name="bar[2]">
2140 <object class="wxButton" name="bar[1]">
2142 <ids-range name="foo" />
2143 <ids-range name="bar" size="30" start="10000" />
2146 For the range foo, no @em size or @em start parameters were given, so the size
2147 will be calculated from the number of range items, and IDs allocated by
2148 wxWindow::NewControlId (so they'll be negative). Range bar asked for a size of
2149 30, so this will be its minimum size: should it have more items, the range will
2150 automatically expand to fit them. It specified a start ID of 10000, so
2151 XRCID("bar[0]") will be 10000, XRCID("bar[1]") 10001 etc. Note that if you
2152 choose to supply a start value it must be positive, and it's your
2153 responsibility to avoid clashes.
2155 For every ID range, the first item can be referenced either as
2156 <em>rangename</em>[0] or <em>rangename</em>[start]. Similarly
2157 <em>rangename</em>[end] is the last item. Using [start] and [end] is more
2158 descriptive in e.g. a Bind() event range or a @em for loop, and they don't have
2159 to be altered whenever the number of items changes.
2161 Whether a range has positive or negative IDs, [start] is always a smaller
2162 number than [end]; so code like this works as expected:
2165 for (int n=XRCID("foo[start]"); n <= XRCID("foo[end]"); ++n)
2169 ID ranges can be seen in action in the <em>objref</em> dialog section of the
2173 @li All the items in an ID range must be contained in the same XRC file.
2174 @li You can't use an ID range in a situation where static initialisation
2175 occurs; in particular, they won't work as expected in an event table. This is
2176 because the event table's IDs are set to their integer values before the XRC
2177 file is loaded, and aren't subsequently altered when the XRCID value changes.
2181 @section overview_xrcformat_extending Extending the XRC Format
2183 The XRC format is designed to be extensible and allows specifying and loading
2184 custom controls. The three available mechanisms are described in the rest of
2185 this section in the order of increasing complexity.
2187 @subsection overview_xrcformat_extending_subclass Subclassing
2189 The simplest way to add custom controls is to set the @c subclass attribute
2190 of @c \<object\> element:
2193 <object name="my_value" class="wxTextCtrl" subclass="MyTextCtrl">
2194 <style>wxTE_MULTILINE</style>
2195 ...etc., setup wxTextCtrl as usual...
2199 In that case, wxXmlResource will create an instance of the specified subclass
2200 (@c MyTextCtrl in the example above) instead of the class (@c wxTextCtrl above)
2201 when loading the resource. However, the rest of the object's loading (calling
2202 its Create() method, setting its properties, loading any children etc.)
2203 will proceed in @em exactly the same way as it would without @c subclass
2204 attribute. In other words, this approach is only sufficient when the custom
2205 class is just a small modification (e.g. overridden methods or customized
2206 events handling) of an already supported classes.
2208 The subclass must satisfy a number of requirements:
2210 -# It must be derived from the class specified in @c class attribute.
2211 -# It must be visible in wxWidget's pseudo-RTTI mechanism, i.e. there must be
2212 a DECLARE_DYNAMIC_CLASS() entry for it.
2213 -# It must support two-phase creation. In particular, this means that it has
2214 to have default constructor.
2215 -# It cannot provide custom Create() method and must be constructible using
2216 base @c class' Create() method (this is because XRC will call Create() of
2217 @c class, not @c subclass). In other words, @em creation of the control
2218 must not be customized.
2221 @subsection overview_xrcformat_extending_unknown Unknown Objects
2223 A more flexible solution is to put a @em placeholder in the XRC file and
2224 replace it with custom control after the resource is loaded. This is done by
2225 using the @c unknown pseudo-class:
2228 <object class="unknown" name="my_placeholder"/>
2231 The placeholder is inserted as dummy wxPanel that will hold custom control in
2232 it. At runtime, after the resource is loaded and a window created from it
2233 (using e.g. wxXmlResource::LoadDialog()), use code must call
2234 wxXmlResource::AttachUnknownControl() to insert the desired control into
2235 placeholder container.
2237 This method makes it possible to insert controls that are not known to XRC at
2238 all, but it's also impossible to configure the control in XRC description in
2239 any way. The only properties that can be specified are
2240 the @ref overview_xrcformat_std_props "standard window properties".
2242 @note @c unknown class cannot be combined with @c subclass attribute,
2243 they are mutually exclusive.
2246 @subsection overview_xrcformat_extending_custom Adding Custom Classes
2248 Finally, XRC allows adding completely new classes in addition to the ones
2249 listed in this document. A class for which wxXmlResourceHandler is implemented
2250 can be used as first-class object in XRC simply by passing class name as the
2251 value of @c class attribute:
2254 <object name="my_ctrl" class="MyWidget">
2255 <my_prop>foo</my_prop>
2256 ...etc., whatever MyWidget handler accepts...
2260 The only requirements on the class are that
2261 -# the class must derive from wxObject
2262 -# it must support wxWidget's pseudo-RTTI mechanism
2264 Child elements of @c \<object\> are handled by the custom handler and there are
2265 no limitations on them imposed by XRC format.
2267 This is the only mechanism that works for toplevel objects -- custom controls
2268 are accessible using the type-unsafe wxXmlResource::LoadObject() method.
2272 @section overview_xrcformat_packed Packed XRC Files
2274 In addition to plain XRC files, wxXmlResource supports (if wxFileSystem support
2275 is compiled in) compressed XRC resources. Compressed resources have either
2276 .zip or .xrs extension and are simply ZIP files that contain arbitrary
2277 number of XRC files and their dependencies (bitmaps, icons etc.).
2281 @section overview_xrcformat_oldversions Older Format Versions
2283 This section describes differences in older revisions of XRC format (i.e.
2284 files with older values of @c version attribute of @c \<resource\>).
2287 @subsection overview_xrcformat_pre_v2530 Versions Before 2.5.3.0
2289 Version 2.5.3.0 introduced C-like handling of "\\" in text. In older versions,
2290 "\n", "\t" and "\r" escape sequences were replaced with respective characters
2291 in the same matter it's done in C, but "\\" was left intact instead of being
2292 replaced with single "\", as one would expect. Starting with 2.5.3.0, all of
2293 them are handled in C-like manner.
2296 @subsection overview_xrcformat_pre_v2301 Versions Before 2.3.0.1
2298 Prior to version 2.3.0.1, "$" was used for accelerators instead of "_"
2299 or "&". For example,
2301 <label>$File</label>
2303 was used in place of current version's
2305 <label>_File</label>