/////////////////////////////////////////////////////////////////////////////
// Name:        xrc_format.h
// Purpose:     XRC format specification
// Author:      Vaclav Slavik
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**

@page xrc_format XRC file format

Table of contents:
 - @ref xrc_format_overview
 - @ref xrc_format_root
 - @ref xrc_format_objects
    - @ref xrc_format_object
    - @ref xrc_format_object_ref
 - @ref xrc_format_datatypes
 - @ref xrc_format_windows
    - @ref xrc_format_std_props
    - @ref xrc_format_controls
 - @ref xrc_format_sizers
 - @ref xrc_format_other_objects
 - @ref xrc_format_platform
 - @ref xrc_format_extending
    - @ref xrc_format_extending_subclass
    - @ref xrc_format_extending_unknown
    - @ref xrc_format_extending_custom
 - @ref xrc_format_packed
 - @ref xrc_format_oldversions

This document describes the format of XRC resource files, as used by
wxXmlResource.


@section xrc_format_overview Overview

XRC file is a XML file with all of its elements in the
@c http://www.wxwidgets.org/wxxrc namespace. For backward compatibility,
@c http://www.wxwindows.org/wxxrc namespace is accepted as well (and treated
as identical to @c http://www.wxwidgets.org/wxxrc), but it shouldn't be used
in new XRC files.

XRC file contains definitions for one or more @em objects -- typically
windows. The objects may themselves contain child objects.

Objects defined at the top level, under the
@ref xrc_format_root "root element", can be accessed using
wxXmlResource::LoadDialog() and other LoadXXX methods. They must have
@c name attribute that is used as LoadXXX's argument (see
@ref xrc_format_object for details).

Child objects are not directly accessible via wxXmlResource, they can only
be accessed using XRCCTRL().


@section xrc_format_root Root element: <resource>

The root element is always @c <resource>. It has one optional attribute, @c
version. If set, it specifies version of the file. In absence of @c version
attribute, the default is @c "0.0.0.0".

The version consists of four integers separated by periods.  The first three
components are major, minor and release number of the wxWidgets release when
the change was introduced, the last one is revision number and is 0 for the
first incompatible change in given wxWidgets release, 1 for the second and so
on.  The version changes only if there was an incompatible change introduced;
merely adding new kind of objects does not constitute incompatible change.

At the time of writing, the latest version is @c "2.5.3.0".

Note that even though @c version attribute is optional, it should always be
specified to take advantage of the latest capabilities:

@code
<?xml version="1.0"?>
<resource xmlns="http://www.wxwidgets.org/wxxrc" version="2.5.3.0">
    ...
</resource>
@endcode

@c <resource> may have arbitrary number of
@ref xrc_format_objects "object elements" as its children; they are referred
to as @em toplevel objects in the rest of this document. Unlike objects defined
deeper in the hierarchy, toplevel objects @em must have their @c name attribute
set and it must be set to a value unique among root's children.



@section xrc_format_objects Defining objects

@subsection xrc_format_object <object>

The @c <object> element represents a single object (typically a GUI element)
and it usually maps directly to a wxWidgets class instance. It has one
mandatory attribute, @c class, and optional @c name and @c subclass attributes.

The @c class attribute must always be present, it tells XRC what wxWidgets
object should be created and by which wxXmlResourceHandler.

@c name is the identifier used to identify the object. This name serves three
purposes:

 -# It is used by wxXmlResource's various LoadXXX() methods to find the
    resource by name passed as argument.
 -# wxWindow's name (see wxWindow::GetName()) is set to it.
 -# Numeric ID of a window or menu item is derived from the name.
    If the value represents an integer (in decimal notation), it is used for
    the numeric ID unmodified.  If it is one of the wxID_XXX literals defined
    by wxWidgets (see @ref page_stockitems), its respective value is used.
    Otherwise, the name is transformed into dynamically generated ID. See
    wxXmlResource::GetXRCID() for more information.

Name attributes must be unique at the top level (where the name is used to
load resources) and should be unique among all controls within the same
toplevel window (wxDialog, wxFrame).

The @c subclass attribute optional name of class whose constructor will be
called instead of the constructor for "class".
See @ref xrc_format_extending_subclass for more details.

@c <object> element may -- and almost always do -- have children elements.
These come in two varieties:

 -# Object's properties. A @em property is a value describing part of object's
    behaviour, for example the "label" property on wxButton defines its label.
    In the most common form, property is a single element with text content
    ("<label>Cancel</label"), but they may use nested subelements too (e.g.
    @ref xrc_format_type_font "font property"). A property can only be
    listed once in an object's definition.
 -# Child objects. Window childs, sizers, sizer items or notebook pages
    are all examples of child objects. They are represented using nested
    @c <object> elements and are can be repeated more than once. The specifics
    of which object classes are allowed as children are class-specific and
    are documented below in @ref xrc_format_controls.

Example:
@code
<object class="wxDialog" name="example_dialog">
    <!-- properties: -->
    <title>Non-Derived Dialog Example</title>
    <centered>1</centered>
    <!-- child objects: -->
    <object class="wxBoxSizer">
        <orient>wxVERTICAL</orient>
        <cols>1</cols>
        <rows>0</rows>
        ...
    </object>
</object>
@endcode


@subsection xrc_format_object_ref <object_ref>

Anywhere an @c <object> element can be used, @c <object_ref> may be used
instead. @c <object_ref> is a @em reference to another named (i.e. with the
@c name attribute) @c <object> element. It has one mandatory attribute,
@c ref, with value containing the name of a named @c <object> element. When an
@c <object_ref> is encountered, a copy of the referenced @c <object> element
is made in place of @c <object_ref> occurrence and processed as usual.

For example, the following code:
@code
<object class="wxDialog" name="my_dlg">
    ...
</object>
<object_ref name="my_dlg_alias" ref="my_dlg"/>
@endcode
is equivalent to
@code
<object class="wxDialog" name="my_dlg">
    ...
</object>
<object class="wxDialog" name="my_dlg_alias">
    ... <!-- same as in my_dlg -->
</object>
@endcode

Additionally, it is possible to override some parts of the referenced object
in the @c <object_ref> pointing to it. This is useful for putting repetitive
parts of XRC definitions into a template that can be reused and customized in
several places. The two parts are merged as follows:

 -# The referred object is used as the initial content.
 -# All attributes set on @c <object_ref> are added to it.
 -# All child elements of @c <object_ref> are scanned. If an element with
    the same name (and, if specified, the @c name attribute too) is found
    in the referred object, they are recursively merged.
 -# Child elements in @c <object_ref> that do not have a match in the referred
    object are appended to the list of children of the resulting element by
    default. Optionally, they may have @c insert_at attribute with two possible
    values, "begin" or "end". When set to "begin", the element is prepended to
    the list of children instead of appended.

For example, "my_dlg" in this snippet:
@code
<object class="wxDialog" name="template">
    <title>Dummy dialog</title>
    <size>400,400</size>
</object>
<object_ref ref="template" name="my_dlg">
    <title>My dialog</title>
    <centered>1</centered>
</object>
@endcode
is identical to:
@code
<object_ref ref="template" name="my_dlg">
    <title>My dialog</title>
    <size>400,400</size>
    <centered>1</centered>
</object>
@endcode


@section xrc_format_datatypes Data types

There are several property data types that are frequently reused by different
properties. Rather than describing their format in the documentation of
every property, we list commonly used types in this section and document
their format.


@subsection xrc_format_type_bool Boolean

Boolean values are expressed using either "1" literal (true) or "0" (false).


@subsection xrc_format_type_float Floating-point value

Floating point values use POSIX (C locale) formatting -- decimal separator
is "." regardless of the locale.


@subsection xrc_format_type_colour Colour

Colour specification can be either any string colour representation accepted
by wxColour::Set() or any wxSYS_COLOUR_XXX symbolic name accepted by
wxSystemSettings::GetColour(). In particular, the following forms are supported:

@li named colours from wxColourDatabase
@li HTML-like "#rrggbb" syntax (but not "#rgb")
@li CSS-style "rgb(r,g,b)" and "rgba(r,g,b,a)"
@li wxSYS_COLOUR_XXX symbolic names

Some examples:
@code
<fg>red</fg>
<fg>#ff0000</fg>
<fg>rgb(255,0,0)</fg>
<fg>wxSYS_COLOUR_HIGHLIGHT</fg>
@endcode


@subsection xrc_format_type_size Size

Sizes and positions have the form of string with two comma-separated integer
components, with optional "d" suffix. Semi-formally:

  size := x "," y ["d"]

where x and y are integers. Either of the components (or both) may be "-1" to
signify default value. As a shortcut, empty string is equivalent to "-1,-1"
(= wxDefaultSize or wxDefaultPosition).

When the "d" suffix is used, integer values are interpreted as
@ref wxWindow::ConvertDialogToPixels() "dialog units" in the parent window.

Examples:
@code
42,-1
100,100
100,50d
@endcode

@subsection xrc_format_type_pos Position

Same as @ref xrc_format_type_size.


@subsection xrc_format_type_dimension Dimension

Similarly to @ref xrc_format_type_size "sizes", dimensions are expressed
as integers with optional "d" suffix. When "d" suffix is used, the integer
preceding it is interpreted as dialog units in the parent window.


@subsection xrc_format_type_text Text

String properties use several escape sequences that are translated according to
the following table:
@beginDefList
@itemdef{ "_", "&" (used for accelerators in wxWidgets) }
@itemdef{ "__", "_" }
@itemdef{ "\n", line break }
@itemdef{ "\r", carriage return }
@itemdef{ "\t", tab }
@itemdef{ "\\", "\" }
@endDefList

By default, the text is translated using wxLocale::GetTranslation() before
it is used. This can be disabled either globally by not passing
wxXRC_USE_LOCALE to wxXmlResource constructor, or by setting the @c translate
attribute on the property node to "0":
@code
<!-- this is not translated: -->
<label translate="0">_Unix</label>
<!-- but this is: -->
<help>Use Unix-style newlines</help>
@endcode

@note Even though the "_" character is used instead of "&" for accelerators,
      it is still possible to use "&". The latter has to be encoded as "&amp;",
      though, so using "_" is more convenient.

@see @ref xrc_format_pre_v2530, @ref xrc_format_pre_v2301


@subsection xrc_format_type_text_notrans Non-translatable text

Like @ref xrc_format_type_text, but the text is never translated and
@c translate attribute cannot be used.


@subsection xrc_format_type_bitmap Bitmap

Bitmap properties contain specification of a single bitmap or icon. In the most
basic form, their text value is simply a relative filename (or another
wxFileSystem URL) of the bitmap to use. For example:
@code
<object class="tool" name="wxID_NEW">
    <tooltip>New</tooltip>
    <bitmap>new.png</bitmap>
</object>
@endcode
The value is interpreted as path relative to the location of XRC file where the
reference occurs.

Alternatively, it is possible to specify the bitmap using wxArtProvider IDs.
In this case, the property element has no textual value (filename) and instead
has the @c stock_id XML attribute that contains stock art ID as accepted by
wxArtProvider::GetBitmap(). This can be either custom value (if the app uses
app-specific art provider) or one of the predefined wxART_XXX constants.

Optionally, @c stock_client attribute may be specified too and contain one of
the predefined wxArtClient values. If it is not specified, the default client
ID most appropriate in the context where the bitmap is referenced will be used.
In most cases, specifying @c stock_client is not needed.

Examples of stock bitmaps usage:
@code
<bitmap stock_id="fixed-width"/>        <!-- custom app-specific art -->
<bitmap stock_id="wxART_FILE_OPEN"/>    <!-- standard art->
@endcode

Specifying the bitmap directly and using @c stock_id are mutually exclusive.


@subsection xrc_format_type_style Style

Style properties (such as window's style or sizer flags) use syntax similar to
C++: the style value is OR-combination of individual flags. Symbolic names
identical to those used in C++ code are used for the flags. Flags are separated
with "|" (whitespace is allowed but not required around it).

The flags that are allowed for a given property are context-dependent.

Examples:
@code
<style>wxCAPTION|wxSYSTEM_MENU | wxRESIZE_BORDER</style>
<exstyle>wxDIALOG_EX_CONTEXTHELP</exstyle>
@endcode


@subsection xrc_format_type_font Font

XRC uses similar, but more flexible, abstract description of fonts to that
used by wxFont class. A font can be described either in terms of its elementary
properties, or it can be derived from one of system fonts.

The font property element is "composite" element: unlike majority of
properties, it doesn't have text value but contains several child elements
instead. These children are handled in the same way as object properties
and can be one of the following "sub-properties":

@beginTable
@hdr3col{property, type, description}
@row3col{size, unsigned integer,
    Pixel size of the font (default: wxNORMAL_FONT's size or @c sysfont's
    size if the @c sysfont property is used.}
@row3col{style, enum,
    One of "normal", "italic" or "slant" (default: normal).}
@row3col{weight, enum,
    One of "normal", "bold" or "light" (default: normal).}
@row3col{family, enum,
    One of "roman", "script", "decorative", "swiss", "modern" or "teletype"
    (default: roman).}
@row3col{underlined, @ref xrc_format_type_bool,
    Whether the font should be underlined (default: 0).}
@row3col{face, ,
    Comma-separated list of face names; the first one available is used
    (default: unspecified).}
@row3col{encoding, ,
    Charset of the font, unused in Unicode build), as string
    (default: unspecified).}
@row3col{sysfont, ,
    Symbolic name of system standard font(one of wxSYS_*_FONT constants).}
@row3col{relativesize, float,
    Float, font size relative to chosen system font's size; can only be
    used when 'sysfont' is used and when 'size' is not used.}
@endTable

All of them are optional, if they are missing, appropriate wxFont default is
used. If the @c sysfont property is used, then the defaults are taken from it
instead.

Examples:
@code
<font>
    <!-- fixed font: Arial if available, fall back to Helvetica -->
    <face>arial,helvetica</face>
    <size>12</size>
</font>

<font>
    <!-- enlarged, enboldened standard font: -->
    <sysfont>wxSYS_DEFAULT_GUI_FONT</sysfont>
    <weight>bold</weight>
    <relativesize>1.5</relativesize>
</font>
@endcode


@section xrc_format_windows Controls and windows

This section describes support wxWindow-derived classes in XRC format.

@subsection xrc_format_std_props Standard properties

The following properties are always (unless stated otherwise in
control-specific docs) available for @em windows objects. They are omitted
from properties lists below.

@beginTable
@hdr3col{property, type, description}
@row3col{position, @ref xrc_format_type_pos,
    Initial position of the window (default: wxDefaultPosition).}
@row3col{size, @ref xrc_format_type_size,
    Initial size of the window (default: wxDefaultSize).}
@row3col{style, @ref xrc_format_type_style,
    Window style for this control. The allowed values depend on what
    window is being created, consult respective class' constructor
    documentation for details (default: window-dependent default, usually
    wxFOO_DEFAULT_STYLE if defined for class wxFoo, 0 if not).}
@row3col{exstyle, @ref xrc_format_type_style,
    Extra style for the window, if any. See wxWindow::SetExtraStyle()
    (default: not set).}
@row3col{fg, @ref xrc_format_type_colour,
    Foreground colour of the window (default: window's default).}
@row3col{bg, @ref xrc_format_type_colour,
    Background colour of the window (default: window's default).}
@row3col{enabled, @ref xrc_format_type_bool,
    If set to 0, the control is disabled (default: 1).}
@row3col{hidden, @ref xrc_format_type_bool,
    If set to 1, the control is created hidden (default: 0).}
@row3col{tooltip, @ref xrc_format_type_text,
    Tooltip to use for the control (default: not set).}
@row3col{font, @ref xrc_format_type_font,
    Font to use for the control (default: window's default).}
@row3col{help, @ref xrc_format_type_text,
    Context-sensitive help for the control, used by wxHelpProvider
    (default: not set).}
@endTable

All of these properties are optional.


@subsection xrc_format_controls Supported controls

@subsubsection xrc_wxanimationctrl wxAnimationCtrl
FIXME

@subsubsection xrc_wxbitmapbutton wxBitmapButton
FIXME

@subsubsection xrc_wxbitmapcombobox wxBitmapComboBox
FIXME

@subsubsection xrc_wxbutton wxButton
FIXME

@subsubsection xrc_wxcalendarctrl wxCalendarCtrl
FIXME

@subsubsection xrc_wxcheckbox wxCheckBox
FIXME

@subsubsection xrc_wxchecklistbox wxCheckListBox
FIXME

@subsubsection xrc_wxchoice wxChoice
FIXME

@subsubsection xrc_wxchoicebook wxChoicebook
FIXME

@subsubsection xrc_wxcollapsiblepane wxCollapsiblePane
FIXME

@subsubsection xrc_wxcolourpickerctrl wxColourPickerCtrl
FIXME

@subsubsection xrc_wxcombobox wxComboBox
FIXME

@subsubsection xrc_wxdatepickerctrl wxDatePickerCtrl
FIXME

@subsubsection xrc_wxdialog wxDialog
FIXME

@subsubsection xrc_wxdirpickerctrl wxDirPickerCtrl
FIXME

@subsubsection xrc_wxfilepickerctrl wxFilePickerCtrl
FIXME

@subsubsection xrc_wxfontpickerctrl wxFontPickerCtrl
FIXME

@subsubsection xrc_wxfrane wxFrame
FIXME

@subsubsection xrc_wxgauge wxGauge
FIXME

@subsubsection xrc_wxgenericdirctrl wxGenericDirCtrl
FIXME

@subsubsection xrc_wxgrid wxGrid
FIXME

@subsubsection xrc_wxhtmlwindow wxHtmlWindow
FIXME

@subsubsection xrc_wxhyperlinkctrl wxHyperlinkCtrl
FIXME

@subsubsection xrc_wxlistbox wxListBox
FIXME

@subsubsection xrc_wxlistbook wxListbook
FIXME

@subsubsection xrc_wxlistctrl wxListCtrl
FIXME

@subsubsection xrc_wxmdiparentframe wxMDIParentFrame
FIXME

@subsubsection xrc_wxmdichildframe wxMDIChildFrame
FIXME

@subsubsection xrc_wxmenu wxMenu
FIXME

@subsubsection xrc_wxmenubar wxMenuBar
FIXME

@subsubsection xrc_wxnotebook wxNotebook
FIXME

@subsubsection xrc_wxownerdrawncombobox wxOwnerDrawnComboBox
FIXME

@subsubsection xrc_wxpanel wxPanel
FIXME

@subsubsection xrc_wxpropertysheetdialog wxPropertySheetDialog
FIXME

@subsubsection xrc_wxradiobutton wxRadioButton
FIXME

@subsubsection xrc_wxradiobox wxRadioBox
FIXME

@subsubsection xrc_wxrichtextctrl wxRichTextCtrl
FIXME

@subsubsection xrc_wxscrollbar wxScrollBar
FIXME

@subsubsection xrc_wxscrolledwindow wxScrolledWindow
FIXME

@subsubsection xrc_wxsimplehtmllistbox wxSimpleHtmlListBox
FIXME

@subsubsection xrc_wxslider wxSliderq
FIXME

@subsubsection xrc_wxspinctrl wxSpinCtrl
FIXME

@subsubsection xrc_wxsplitterwindow wxSplitterWindow
FIXME

@subsubsection xrc_wxsearchctrl wxSearchCtrl
FIXME

@subsubsection xrc_wxstatusbar wxStatusBar
FIXME

@subsubsection xrc_wxstaticbitmap wxStaticBitmap
FIXME

@subsubsection xrc_wxstaticbox wxStaticBox
FIXME

@subsubsection xrc_wxstaticline wxStaticLine
FIXME

@subsubsection xrc_wxstatictext wxStaticText
FIXME

@subsubsection xrc_wxtextctrl wxTextCtrl
FIXME

@subsubsection xrc_wxtogglebuttton wxToggleButton
FIXME

@subsubsection xrc_wxtoolbar wxToolBar
FIXME

@subsubsection xrc_wxtreectrl wxTreeCtrl
FIXME

@subsubsection xrc_wxtreebook wxTreebook
FIXME

@subsubsection xrc_wxwizard wxWizard
FIXME


@section xrc_format_sizers Sizers

Sizers are handled slightly differently in XRC resources than they are in
wxWindow hierarchy. wxWindow's sizers hierarchy is parallel to the wxWindow
children hieararchy: child windows are children of their parent window and
the sizer (or sizers) form separate hierarchy attached to the window with
wxWindow::SetSizer().

In XRC, the two hierarchies are merged together: sizers are children of other
sizers or windows and they can contain child window objects.

If a sizer is child of a window object in the resource, it must be the only
child and it will be attached to the parent with wxWindow::SetSizer().
Additionally, if the window doesn't have its size explicitly set,
wxSizer::Fit() is used to resize the window. If the parent window is
toplevel window, wxSizer::SetSizeHints() is called to set its hints.

A sizer object can have one or more child objects of one of two pseudo-classes:
@c sizeritem or @c spacer (see @ref xrc_format_wxstddialogbuttonsizer for
an exception). The former specifies an element (another sizer or a window)
to include in the sizer, the latter adds empty space to the sizer.

@c sizeritem objects have exactly one child object: either another sizer
object, or a window object. @c spacer objects don't have any children, but
they have one property:

@beginTable
@hdr3col{property, type, description}
@row3col{size, @ref xrc_format_type_size, Size of the empty space (required).}
@endTable

Both @c sizeritem and @c spacer objects can have any of the following
properties:

@beginTable
@hdr3col{property, type, description}
@row3col{option, integer,
    The "option" value for sizers. Used by wxBoxSizer to set proportion of
    the item in the growable direction (default: 0).}
@row3col{flag, @ref xrc_format_type_style,
    wxSizerItem flags (default: 0).}
@row3col{border, @ref xrc_format_type_dimension,
    Size of the border around the item (directions are specified in flags)
    (default: 0).}
@row3col{minsize, @ref xrc_format_type_size,
    Minimal size of this item (default: no min size).}
@row3col{ratio, @ref xrc_format_type_size,
    Item ratio, see wxSizer::SetRatio() (default: no ratio).}
@row3col{cellpos, @ref xrc_format_type_pos,
    (wxGridBagSizer only) Position, see wxGBSizerItem::SetPos() (required). }
@row3col{cellspan, @ref xrc_format_type_size,
    (wxGridBagSizer only) Span, see wxGBSizerItem::SetSpan() (required). }
@endTable

Example of sizers XRC code:
@code
<object class="wxDialog" name="derived_dialog">
    <title>Derived Dialog Example</title>
    <centered>1</centered>
    <!-- this sizer is set to be this dialog's sizer: -->
    <object class="wxFlexGridSizer">
        <cols>1</cols>
        <rows>0</rows>
        <vgap>0</vgap>
        <hgap>0</hgap>
        <growablecols>0</growablecols>
        <growablerows>0</growablerows>
        <object class="sizeritem">
            <flag>wxALIGN_CENTRE|wxALL</flag>
            <border>5</border>
            <object class="wxButton" name="my_button">
                <label>My Button</label>
            </object>
        </object>
        <object class="sizeritem">
            <flag>wxALIGN_CENTRE|wxALL</flag>
            <border>5</border>
            <object class="wxBoxSizer">
                <orient>wxHORIZONTAL</orient>
                <object class="sizeritem">
                    <flag>wxALIGN_CENTRE|wxALL</flag>
                    <border>5</border>
                    <object class="wxCheckBox" name="my_checkbox">
                        <label>Enable this text control:</label>
                    </object>
                </object>
                <object class="sizeritem">
                    <flag>wxALIGN_CENTRE|wxALL</flag>
                    <border>5</border>
                    <object class="wxTextCtrl" name="my_textctrl">
                        <size>80,-1</size>
                        <value></value>
                    </object>
                </object>
            </object>
        </object>
        ...
    </object>
</object>
@endcode

The sizer classes that can be used are listed below, together with their
class-specific properties. All classes support the following properties:

@beginTable
@hdr3col{property, type, description}
@row3col{minsize, @ref xrc_format_type_size,
    Minimal size that this sizer will have, see wxSizer::SetMinSize()
    (default: no min size).}
@endTable

@subsection xrc_format_wxboxsizer wxBoxSizer

@beginTable
@hdr3col{property, type, description}
@row3col{orient, @ref xrc_format_type_style,
    Sizer orientation, "wxHORIZONTAL" or "wxVERTICAL" (default: wxHORIZONTAL).}
@endTable

@subsection xrc_format_wxstaticsboxizer wxStaticBoxSizer

@beginTable
@hdr3col{property, type, description}
@row3col{orient, @ref xrc_format_type_style,
    Sizer orientation, "wxHORIZONTAL" or "wxVERTICAL" (default: wxHORIZONTAL).}
@row3col{label, @ref xrc_format_type_text,
    Label to be used for the static box around the sizer (required).}
@endTable

@subsection xrc_format_wxgridsizer wxGridSizer

@beginTable
@hdr3col{property, type, description}
@row3col{rows, integer, Number of rows in the grid (required).}
@row3col{cols, integer, Number of columns in the grid (required).}
@row3col{vgap, integer, Vertical gap between children (default: 0).}
@row3col{hgap, integer, Horizontal gap between children (default: 0).}
@endTable

@subsection xrc_format_wxflexgridsizer wxFlexGridSizer

@beginTable
@hdr3col{property, type, description}
@row3col{rows, integer, Number of rows in the grid (required).}
@row3col{cols, integer, Number of columns in the grid (required).}
@row3col{vgap, integer, Vertical gap between children (default: 0).}
@row3col{hgap, integer, Horizontal gap between children (default: 0).}
@row3col{growablerows, comma-separated integers list,
    Comma-separated list of indexes of rows that are growable
    (default: none).}
@row3col{growablecols, comma-separated integers list,
    Comma-separated list of indexes of columns that are growable
    (default: none).}
@endTable

@subsection xrc_format_wxgridbagsizer wxGridBagSizer

@beginTable
@hdr3col{property, type, description}
@row3col{vgap, integer, Vertical gap between children (default: 0).}
@row3col{hgap, integer, Horizontal gap between children (default: 0).}
@row3col{growablerows, comma-separated integers list,
    Comma-separated list of indexes of rows that are growable
    (default: none).}
@row3col{growablecols, comma-separated integers list,
    Comma-separated list of indexes of columns that are growable
    (default: none).}
@endTable

@subsection xrc_format_wxwrapsizer wxWrapSizer

@beginTable
@hdr3col{property, type, description}
@row3col{orient, @ref xrc_format_type_style,
    Sizer orientation, "wxHORIZONTAL" or "wxVERTICAL" (required).}
@row3col{flag, @ref xrc_format_type_style, wxWrapSizer flags (default: 0).}
@endTable

@subsection xrc_format_wxstddialogbuttonsizer wxStdDialogButtonSizer

Unlike other sizers, wxStdDialogButtonSizer doesn't have neither @c sizeritem
nor @c spacer children. Instead, it has one or more children of the
@c button pseudo-class. @c button objects have no properties and they must
always have exactly one child of the @c wxButton class or a class derived from
wxButton.

Example:
@code
<object class="wxStdDialogButtonSizer">
    <object class="button">
        <object class="wxButton" name="wxID_OK">
            <label>OK</label>
        </object>
    </object>
    <object class="button">
        <object class="wxButton" name="wxID_CANCEL">
            <label>Cancel</label>
        </object>
    </object>
</object>
@endcode



@section xrc_format_other_objects Other objects

In addition to describing UI elements, XRC files can contain non-windows
objects such as bitmaps or icons. This is a concession to Windows developers
used to storing them in Win32 resources.

Note that unlike Win32 resources, bitmaps included in XRC files are @em not
embedded in the XRC file itself. XRC file only contains a reference to another
file with bitmap data.

@subsection xrc_format_bitmap wxBitmap

Bitmaps are stored in @c <object> element with class set to @c wxBitmap. Such
bitmaps can then be loaded using wxXmlResource::LoadBitmap(). The content of
the element is exactly same as in the case of
@ref xrc_format_type_bitmap "bitmap properties", except that toplevel
@c <object> is used.

For example, instead of:
@code
<bitmap>mybmp.png</bitmap>
<bitmap stock_id="wxART_NEW"/>
@endcode
toplevel wxBitmap resources would look like:
@code
<object class="wxBitmap" name="my_bitmap">mybmp.png</object>
<object class="wxBitmap" name="my_new_bitmap" stock_id="wxART_NEW"/>
@endcode


@subsection xrc_format_icon wxIcon

wxIcon resources are identical to @ref xrc_format_bitmap "wxBitmap ones",
except that the class is @c wxIcon.


@section xrc_format_platform Platform specific content

It is possible to conditionally process parts of XRC files on some platforms
only and ignore them on other platforms. @em Any element in XRC file, be it
toplevel or arbitrarily nested one, can have the @c platform attribute. When
used, @c platform contains |-separated list of platforms that this element
should be processed on. It is filtered out and ignored on any other platforms.

Possible elemental values are:
@beginDefList
@itemdef{ @c win, Windows }
@itemdef{ @c mac, Mac OS X (or Mac Classic in wxWidgets version supporting it }
@itemdef{ @c unix, Any Unix platform @em except OS X }
@itemdef{ @c os2, OS/2 }
@endDefList

Examples:
@code
<label platform="win">Windows</label>
<label platform="unix">Unix</label>
<label platform="mac">Mac OS X</label>
<help platform="mac|unix">Not a Windows machine</help>
@endcode



@section xrc_format_extending Extending XRC format

The XRC format is designed to be extensible and allows specifying and loading
custom controls. The three available mechanisms are described in the rest of
this section in the order of increasing complexity.

@subsection xrc_format_extending_subclass Subclassing

The simplest way to add custom controls is to set the @c subclass attribute
of @c <object> element:

@code
<object name="my_value" class="wxTextCtrl" subclass="MyTextCtrl">
  <style>wxTE_MULTILINE</style>
  ...etc., setup wxTextCtrl as usual...
</object>
@endcode

In that case, wxXmlResource will create an instance of the specified subclass
(@c MyTextCtrl in the example above) instead of the class (@c wxTextCtrl above)
when loading the resource. However, the rest of the object's loading (calling
its Create() method, setting its properties, loading any children etc.)
will proceed in @em exactly the same way as it would without @c subclass
attribute. In other words, this approach is only sufficient when the custom
class is just a small modification (e.g. overridden methods or customized
events handling) of an already supported classes.

The subclass must satisfy a number of requirements:

 -# It must be derived from the class specified in @c class attribute.
 -# It must be visible in wxWidget's pseudo-RTTI mechanism, i.e. there must be
    a DECLARE_DYNAMIC_CLASS() entry for it.
 -# It must support two-phase creation. In particular, this means that it has
    to have default constructor.
 -# It cannot provide custom Create() method and must be constructible using
    base @c class' Create() method (this is because XRC will call Create() of
    @c class, not @c subclass). In other words, @em creation of the control
    must not be customized.


@subsection xrc_format_extending_unknown <object class="unknown">

A more flexible solution is to put a @em placeholder in the XRC file and
replace it with custom control after the resource is loaded. This is done by
using the @c unknown pseudo-class:

@code
<object class="unknown" name="my_placeholder"/>
@endcode

The placeholder is inserted as dummy wxPanel that will hold custom control in
it. At runtime, after the resource is loaded and a window created from it
(using e.g. wxXmlResource::LoadDialog()), use code must call
wxXmlResource::AttachUnknownControl() to insert the desired control into
placeholder container.

This method makes it possible to insert controls that are not known to XRC at
all, but it's also impossible to configure the control in XRC description in
any way. The only properties that can be specified are
the @ref xrc_format_std_props "standard window properties".

@note @c unknown class cannot be combined with @c subclass attribute,
      they are mutually exclusive.


@subsection xrc_format_extending_custom Adding custom classes

Finally, XRC allows adding completely new classes in addition to the ones
listed in this document. A class for which wxXmlResourceHandler is implemented
can be used as first-class object in XRC simply by passing class name as the
value of @c class attribute:

@code
<object name="my_ctrl" class="MyWidget">
  <my_prop>foo</my_prop>
  ...etc., whatever MyWidget handler accepts...
</object>
@endcode

The only requirements on the class are that
 -# the class must derive from wxObject
 -# it must support wxWidget's pseudo-RTTI mechanism

Child elements of @c <object> are handled by the custom handler and there are
no limitations on them imposed by XRC format.

This is the only mechanism that works for toplevel objects -- custom controls
are accessible using type-unsafe wxXmlResource::LoadObject() method.



@section xrc_format_packed Packed XRC files

In addition to plain XRC files, wxXmlResource supports (if wxFileSystem support
is compiled in) compressed XRC resources. Compressed resources have either
.zip or .xrs extension and are simply ZIP files that contain arbitrary
number of XRC files and their dependencies (bitmaps, icons etc.).



@section xrc_format_oldversions Older format versions

This section describes differences in older revisions of XRC format (i.e.
files with older values of @c version attribute of @c <resource>).


@subsection xrc_format_pre_v2530 Versions before 2.5.3.0

Version 2.5.3.0 introduced C-like handling of "\\" in text. In older versions,
"\n", "\t" and "\r" escape sequences were replaced with respective characters
in the same matter it's done in C, but "\\" was left intact instead of being
replaced with single "\", as one would expect. Starting with 2.5.3.0, all of
them are handled in C-like manner.


@subsection xrc_format_pre_v2301 Versions before 2.3.0.1

Prior to version 2.3.0.1, "$" was used for accelerators instead of "_"
or "&amp;". For example,
@code
<label>$File</label>
@endcode
was used in place of current version's
@code
<label>_File</label>
@endcode
(or "&amp;File").

*/