3103e8a97e
Olly Betts git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@34436 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
489 lines
17 KiB
Plaintext
489 lines
17 KiB
Plaintext
XRC resources format specification
|
|
==================================
|
|
|
|
!!!!! NOT YET FINISHED !!!!!
|
|
|
|
0. Introduction
|
|
===============
|
|
|
|
This note describes the file format used for storing XRC resources that are
|
|
used by wxXmlResource class. It is probably only useful for those implementing
|
|
dialog editors with XRC support.
|
|
|
|
If you only want to use the resources, you can choose from a number of editors:
|
|
a) wxDesigner (http://www.roebling.de)
|
|
b) XRCed (wxPython/tools)
|
|
c) DialogBlocks (wxPython/tools)
|
|
|
|
and others listed on the Resources section of the wxWidgets web
|
|
site.
|
|
|
|
The XRC format is based on XML 1.0 (please consult W3C's specification). There
|
|
is no DTD available since it is not possible to fully describe the format with
|
|
the limited expressive power of DTDs.
|
|
|
|
|
|
Note: see also http://ldaptool.sourceforge.net/XRCGuide/XRCGuideSingle/
|
|
|
|
|
|
|
|
1. Terminology
|
|
==============
|
|
|
|
The usual XML terminology applies. In particular, we shall use the terms
|
|
NODE, PROPERTY and VALUE in the XML sense:
|
|
|
|
<node property1="value1" property2="value2">...</node>
|
|
|
|
The term ATTRIBUTE is specific to XRC and refers to a subnode
|
|
of an <object> or <object_ref> node that is itself not <object> or <object_ref>.
|
|
In the example below, <pos>, <label> and <style> are attributes, while neither
|
|
<resource> nor either of <object>s is:
|
|
|
|
<?xml version="1.0" encoding="utf-8">
|
|
<resource xmlns="http://www.wxwidgets.org/wxxrc" version="2.5.3.0">
|
|
<object class="wxPanel">
|
|
<style>wxSUNKEN_BORDER</style> <!-- attr -->
|
|
<object class="wxStaticText">
|
|
<label>A label</label> <!-- attr -->
|
|
<pos>10,10</pos> <!-- attr -->
|
|
</object>
|
|
</object>
|
|
</resource>
|
|
|
|
ATTRIBUTE VALUE is the content of all text elements within attribute tag. In the
|
|
above example, "wxSUNKEN_BORDER", "A label" and "10,10" are attribute values.
|
|
ATTRIBUTE TYPE defines what attribute values are valid for given attribute (you
|
|
can think of it as attribute value syntax definition).
|
|
|
|
|
|
|
|
2. Elementary description
|
|
=========================
|
|
|
|
XRC resource file is a well-formed XML 1.0 document. All elements of XRC file
|
|
are from the http://www.wxwidgets.org/wxxrc namespace.
|
|
|
|
The root node of XRC document must be <resource>. The <resource> node has
|
|
optional "version" property. Default version (in absence of the version
|
|
property) is "0.0.0.0". The version consists of four integers separated by
|
|
periods. Version of XRC format changes only if there was an incompatible
|
|
change introduced (i.e. either the library cannot understand old resource
|
|
files or older versions of the library wouldn't understand the new format).
|
|
The first three integers 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 etc.
|
|
|
|
Differences between versions are described within this document in paragraphs
|
|
entitled "Version Note".
|
|
|
|
The <resource> node contains namespace declaration, too:
|
|
|
|
<resource xmlns="http://www.wxwidgets.org/wxxrc" version="2.5.3.0">
|
|
|
|
The <resource> node is only allowed to have <object> and <object_ref>
|
|
subnodes, all of which must have the "name" property.
|
|
|
|
The <object> node represents a single object (GUI element) and it usually maps
|
|
directly to a wxWidgets class instance. It three properties: "name", "class"
|
|
and "subclass". "class" must always be present, it tells XRC what wxWidgets
|
|
object should be created in this place. The other two are optional. "name" is
|
|
ID used to identify the object. It is the value passed to the XRCID() macro and
|
|
is also used to construct wxWindow's id and name attributes and must be unique
|
|
among all children of the nearest container object (wxDialog, wxFrame,
|
|
wxPanel, wxNotebook) upside from the object in XML nodes hierarchy (two distinct
|
|
containers may contain objects with same "name", though). "subclass" is
|
|
optional name of class whose constructor will be called instead of the
|
|
constructor for "class". Subclass must be available in the program that loads
|
|
the resource, must be derived from "class" and must be registered within
|
|
wxWidgets' RTTI system.
|
|
|
|
Example:
|
|
|
|
<object name="MyList1" class="wxListCtrl" subclass="MyListCtrlClass">
|
|
...
|
|
</object>
|
|
|
|
<object> node may have arbitrary child nodes. What child nodes and their
|
|
semantics are class-dependent and are defined later in this document. The user
|
|
is allowed to register new object handlers within XRC and extend it to accept
|
|
new <object> classes (and therefore different <object>'s child nodes).
|
|
|
|
<object_ref> node is identical to <object>, except that it does _not_ have
|
|
"class" property and has additional required property "ref". Its concept is
|
|
similar to Unix symlinks: value of the "ref" property is equal to the value of
|
|
"name" property of some existing node (called referred node) in the resources
|
|
(not necessary top-level). Referred node's "class" property and all subnodes
|
|
are copied in place of the referee <object_ref> node which is then processed as
|
|
regular <object> node. If the <object_ref> node itself has child nodes, then
|
|
these nodes _override_ any nodes from the referred node.
|
|
|
|
Example:
|
|
|
|
<object name="foo" class="wxTextCtrl">
|
|
<value>hello</value>
|
|
<size>100,-1d</size>
|
|
</object>
|
|
<object_ref name="bar" ref="foo">
|
|
<value>bar</value> <!-- override! -->
|
|
</object_ref>
|
|
|
|
is identical to:
|
|
|
|
<object name="foo" class="wxTextCtrl">
|
|
<value>hello</value>
|
|
<size>100,-1d</size>
|
|
</object>
|
|
<object name="bar" class="wxTextCtrl">
|
|
<value>bar</value>
|
|
<size>100,-1d</size>
|
|
</object>
|
|
|
|
|
|
|
|
3. Common attribute types
|
|
=========================
|
|
|
|
There are several attribute types (see section 1. Terminology) that are common
|
|
to many attributes of different classes:
|
|
|
|
String
|
|
------
|
|
Any text. Some characters have special interpretation and are translated
|
|
by XRC parser according to this table:
|
|
"_" -> "&" ('&' is used to underline e.g. menu items in wxWidgets)
|
|
"__" -> "_"
|
|
"\n" -> line break (C character '\n')
|
|
"\r" -> carriage return (C character '\r')
|
|
"\t" -> tab (C character '\t')
|
|
"\\" -> "\"
|
|
(introduced in version 2.5.3.0, not done in earlier versions)
|
|
|
|
Version Note:
|
|
'$' was used instead of '_' prior to version 2.3.0.1.
|
|
|
|
|
|
I18nString
|
|
----------
|
|
Like String, but the value is translated to native language using wxLocale
|
|
at runtime (unless it was disabled by not passing wxXRC_USE_LOCALE flag to
|
|
wxXmlResource constructor). Used for strings that are "visible" in the GUI.
|
|
|
|
|
|
UnsignedInteger
|
|
---------------
|
|
This is obvious. Only digits 0-9 may be present and there must be at least
|
|
one digit.
|
|
|
|
|
|
Integer
|
|
-------
|
|
Like UnsignedInteger but may be prefixed with '-' (ints less than zero).
|
|
|
|
|
|
Position
|
|
--------
|
|
Specifies (window's) position in 2D space. Syntax is <integer>,<integer>[d]
|
|
where <integer> is valid value of Integer type.
|
|
|
|
|
|
Size
|
|
----
|
|
Syntax is same as Position's syntax, but the values are interpreted as window
|
|
size (wxSize type) and not position (wxPosition type).
|
|
|
|
|
|
Style[wxSomeClass]
|
|
------------------
|
|
List of style flags that can be passed to wxSomeClass' constructor. Flags are
|
|
written in same way as in C++ code (e.g. "wxSUNKEN_BORDER",
|
|
"wxHW_SCROLLBAR_NEVER") and are delimited with any combination of whitespaces
|
|
and '|'. Possible flags are class-dependent and are not described in this
|
|
technote. Please refer to wxWidgets manual for all styles that given class can
|
|
accept; if XRC does not accept a flag listed in wxWidgets documentation, it is
|
|
a bug.
|
|
|
|
|
|
Bitmap
|
|
------
|
|
Attribute value is interpreted as filename (either absolute or relative to
|
|
the location of XRC resource file). In addition, attribute node may have
|
|
"stock_id" and "stock_client" properties. Their values may be any of wxArtID (or
|
|
wxArtClient respectively) values as used by wxArtProvider (because the user may
|
|
define own constants, effectively any string is legal here). Examples are
|
|
"wxART_FILE_OPEN" (id) or "wxART_MENU" (client).
|
|
|
|
Any of "stock_id" or "stock_client" properties or the filename may be omitted.
|
|
XRC determines the bitmap to use according to this algorithm:
|
|
1. If there is non-empty "stock_id" property, query wxArtProvider for the
|
|
bitmap (if there is no "stock_client", use default one, which is usually
|
|
wxART_OTHER; exceptions are noted in class-specific sections below). If
|
|
the query fails, continue to 2.
|
|
2. Load the bitmap from the file in attribute value.
|
|
|
|
|
|
Boolean
|
|
-------
|
|
Boolean value, either "0" (false) or "1" (true).
|
|
|
|
|
|
Font
|
|
----
|
|
Font value. A font can be described either in terms of its elementary
|
|
properties, or it can be derived from one of system fonts. The font node
|
|
may contain following subnodes (the table lists subnode name on the left and
|
|
variable type as per the definitions above on the right side):
|
|
|
|
size UnsignedInteger
|
|
style normal | italic | slant
|
|
weight normal | bold | light
|
|
family roman | script | decorative | swiss | modern | teletype
|
|
underlined Boolean
|
|
face comma-separated list of faces
|
|
encoding charset of the font (meaningless in Unicode build), as string
|
|
sysfont symbolic name of system standard font
|
|
(one of wxSYS_*_FONT constants)
|
|
relativesize Float, font size relative to choosen system font's size;
|
|
can only be used when 'sysfont' is used and when 'size' is not
|
|
used
|
|
|
|
All of them are optional, if they are missing, wxFont default is used.
|
|
|
|
Examples:
|
|
|
|
<font>
|
|
<face>arial,helvetica</face>
|
|
<size>12</size>
|
|
</font>
|
|
|
|
<font>
|
|
<sysfont>wxSYS_DEFAULT_GUI_FONT</sysfont>
|
|
<weight>bold</weight>
|
|
<relativesize>1.5</relativesize>
|
|
</font>
|
|
|
|
|
|
Colour
|
|
------
|
|
A colour value is either explicit RGB value in the standard #rrggbb format
|
|
where rr, gg and bb are hexadecimal case-insensitive values in the 00..FF
|
|
range, or a symbolic name. Symbolic names are wxSYS_COLOUR_* constants defined
|
|
by wxWidgets, written as strings.
|
|
|
|
Example:
|
|
|
|
<bg>wxSYS_COLOUR_SCROLLBAR</bg>
|
|
<fg>#FF0000</fg>
|
|
|
|
|
|
|
|
4. Supported classes
|
|
====================
|
|
|
|
Attributes are listed in tables in the following format:
|
|
attribute name attribute type default value, if any
|
|
[(optional remarks....................
|
|
...................................)]
|
|
|
|
wxBitmap
|
|
--------
|
|
This is a special case, because it does not create a wxWindow instance but
|
|
creates wxBitmap instead. Another exceptional thing is that it does not have
|
|
any attributes. Instead, the node itself is interpreted as if it were attribute
|
|
of type Bitmap.
|
|
|
|
Example: <object class="wxBitmap">bitmaps/foo.gif</object>
|
|
|
|
|
|
wxIcon
|
|
------
|
|
Identical to wxBitmap class, except that it creates wxIcon instead of wxBitmap.
|
|
|
|
|
|
wxButton
|
|
--------
|
|
pos Position -1,-1
|
|
size Size -1,-1
|
|
style Style[wxButton]
|
|
|
|
label I18nString
|
|
default Boolean false
|
|
(Is the button default button?)
|
|
|
|
|
|
wxCalendarCtrl
|
|
--------------
|
|
pos Position -1,-1
|
|
size Size -1,-1
|
|
style Style[wxCalendarCtrl]
|
|
|
|
|
|
wxCheckBox
|
|
----------
|
|
pos Position -1,-1
|
|
size Size -1,-1
|
|
style Style[wxCheckBox]
|
|
checked Boolean false
|
|
|
|
|
|
wxCheckList
|
|
-----------
|
|
pos Position -1,-1
|
|
size Size -1,-1
|
|
style Style[wxCheckList]
|
|
content (see below) (empty)
|
|
|
|
Optional "content" attribute does not have attribute value. Instead,
|
|
arbitrary number of <item> nodes may be rooted under it (the control
|
|
is filled with strings contained in these nodes). Each <item>
|
|
node must contain I18nString value and may have "checked" property
|
|
with possible values "0" or "1" indicating the the item is initially
|
|
checked.
|
|
|
|
Example:
|
|
<object class="wxCheckList">
|
|
<content>
|
|
<item>One</item>
|
|
<item checked="1">Two</item>
|
|
<item checked="1">Three</item>
|
|
<item>Four</item>
|
|
</content>
|
|
</object>
|
|
|
|
|
|
wxDatePickerCtrl
|
|
----------------
|
|
pos Position -1,-1
|
|
size Size -1,-1
|
|
style Style[wxDatePickerCtrl]
|
|
|
|
|
|
wxDialog
|
|
--------
|
|
pos Position -1,-1
|
|
size Size -1,-1
|
|
style Style[wxDialog] wxDEFAULT_DIALOG_STYLE
|
|
title I18nString ""
|
|
icon Bitmap (empty)
|
|
centered Boolean false
|
|
|
|
wxDialog may have children objects.
|
|
|
|
|
|
wxFrame
|
|
--------
|
|
pos Position -1,-1
|
|
size Size -1,-1
|
|
style Style[wxDialog] wxDEFAULT_FRAME_STYLE
|
|
title I18nString ""
|
|
icon Bitmap (empty)
|
|
centered Boolean false
|
|
|
|
wxFrame may have children objects. There can be at most one wxToolBar,
|
|
wxMenuBar and wxStatusBar children; objects of these types are automatically
|
|
set as frame's tool-, menu- and statusbar respectively.
|
|
|
|
|
|
wxMDIParentFrame
|
|
----------------
|
|
|
|
Supports same attributes and children nodes as wxFrame. Additionally, children
|
|
may be of the wxMDIChildFrame type.
|
|
|
|
|
|
wxMDIChildFrame
|
|
---------------
|
|
|
|
Supports same attributes and children nodes as wxFrame.
|
|
|
|
|
|
wxScrolledWindow
|
|
----------------
|
|
pos Position -1,-1
|
|
size Size -1,-1
|
|
style Style[wxScrolledWindow] wxHSCROLL | wxVSCROLL
|
|
|
|
wxScolledWindow may have children objects.
|
|
|
|
|
|
wxSplitterWindow
|
|
----------------
|
|
pos Position -1,-1
|
|
size Size -1,-1
|
|
style Style[wxSplitterWindow] wxSP_3D
|
|
sashpos Integer 0
|
|
(Initial sash position)
|
|
minsize Integer -1
|
|
(Minimal panel size)
|
|
orientation "horizontal"|"vertical" horizontal
|
|
|
|
wxSplitterWindow must have at least one and at most two children objects.
|
|
If there's only one child object, it is passed to wxSplitterWindow::Initialize
|
|
and the splitter is created unsplit. If there are two children, the
|
|
splitter is created split, either horizontally or vertically depending
|
|
on the value of "orientation" attribute.
|
|
|
|
|
|
wxStatusBar
|
|
-----------
|
|
fields Integer number of fields
|
|
widths Width1, Width2, Width3, ...
|
|
|
|
|
|
wxToolBar
|
|
---------
|
|
pos Position -1,-1
|
|
size Size -1,-1
|
|
style Style[wxToolBar] wxNO_BORDER|wxTB_HORIZONTAL
|
|
bitmapsize Size -1,-1
|
|
(Size of contained bitmaps)
|
|
margins Size -1,-1
|
|
packing Integer -1
|
|
separation Integer -1
|
|
|
|
wxToolBar node may have children <object> and <object_ref> nodes. Their class
|
|
may be either "tool", "separator" or any wxWidgets class derived from
|
|
wxControl. "tool" and "separator" are special pseudo-classes that may only
|
|
appear within wxToolBar node. Their attributes are as follows:
|
|
|
|
separator
|
|
---------
|
|
(doesn't have any attributes)
|
|
|
|
tool
|
|
----
|
|
bitmap Bitmap
|
|
bitmap2 Bitmap wxNullBitmap
|
|
toggle Boolean 0
|
|
radio Boolean 0
|
|
label I18nString ""
|
|
tooltip I18nString ""
|
|
longhelp I18nString ""
|
|
pos Position -1,-1
|
|
|
|
Constraints:
|
|
At most one of "toggle" and "radio" attributes may be 1.
|
|
Attribute "pos" may not appear if "label" or "radio" attributes
|
|
are used or if parent wxToolBar's style contains wxTB_TEXT.
|
|
|
|
Note:
|
|
Use of "pos" attribute is strongly discouraged, it is deprecated
|
|
usage of wxToolBar and it is not supported by MSW and GTK
|
|
implementations.
|
|
|
|
Children objects are added to the toolbar using AddTool for "tool" class,
|
|
AddSeparator for "separator" and AddControl for other classes.
|
|
|
|
|
|
|
|
5. More features
|
|
================
|
|
|
|
FIXME -- "platform" property handling
|
|
|
|
|
|
=== EOF ===
|
|
|
|
Version: $Id$
|