2b5f62a0b2
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@18040 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
313 lines
11 KiB
Plaintext
313 lines
11 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) wxWorkshop (http://wxworkshop.sf.net)
|
|
b) wxrcedit (contrib/utils/wxrcedit)
|
|
|
|
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.
|
|
|
|
|
|
|
|
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 bellow, <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.wxwindows.org/wxxrc" version="2.3.0.1">
|
|
<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.wxwindows.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 wxWindows
|
|
release when the change was introduced, the last one is revision number and
|
|
is 0 for the first incompatible change in given wxWindows 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.wxwindows.org/wxxrc" version="2.3.0.1">
|
|
|
|
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 wxWindows class instance. It three properties: "name", "class"
|
|
and "subclass". "class" must always be present, it tells XRC what wxWindows
|
|
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 neareset container object (wxDialog, wxFrame, wxPanel,
|
|
wxNotebook) upside from the object in XML nodes hiearchy (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 wxWindows' 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 additonal required property "ref". It's 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 neccessary 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>
|
|
|
|
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 wxWindows)
|
|
"__" -> "_"
|
|
"\n" -> line break (C character '\n')
|
|
"\r" -> carriage return (C character '\r')
|
|
"\t" -> tabelator (C character '\t')
|
|
|
|
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 delimined with any combination of whitespaces and '|'. Possible flags
|
|
are class-dependent and are not described in this technote. Please refer to wxWindows
|
|
manual for all styles that given class can accept; if XRC does not accept a flag
|
|
listed in wxWindows 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, efectively 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 bellow). 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).
|
|
|
|
|
|
|
|
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
|
|
--------
|
|
position Position -1,-1
|
|
size Size -1,-1
|
|
style Style[wxButton]
|
|
|
|
label I18nString
|
|
default Boolean false
|
|
(Is the button default button?)
|
|
|
|
|
|
wxCalendarCtrl
|
|
--------------
|
|
position Position -1,-1
|
|
size Size -1,-1
|
|
style Style[wxCalendarCtrl]
|
|
|
|
|
|
wxCheckBox
|
|
----------
|
|
position Position -1,-1
|
|
size Size -1,-1
|
|
style Style[wxCheckBox]
|
|
checked Boolean false
|
|
|
|
|
|
wxCheckList
|
|
-----------
|
|
position Position -1,-1
|
|
size Size -1,-1
|
|
style Style[wxCheckList]
|
|
content (see bellow) (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>
|
|
|
|
|
|
wxScrolledWindow
|
|
----------------
|
|
position Position -1,-1
|
|
size Size -1,-1
|
|
style Style[wxScrolledWindow] wxHSCROLL | wxVSCROLL
|
|
|
|
|
|
|
|
5. More features
|
|
================
|
|
|
|
FIXME -- "platform" property handling
|
|
|
|
|
|
=== EOF ===
|
|
|
|
Version: $Id$
|