62ac23612f
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/branches/WX_2_4_BRANCH@17471 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
142 lines
5.3 KiB
Plaintext
142 lines
5.3 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 property-less subnode
|
|
of an <object> or <object_ref> node. 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>
|
|
<object class="wxStaticText">
|
|
<label>A label</label>
|
|
<pos>10,10</pos>
|
|
</object>
|
|
</object>
|
|
</resource>
|
|
|
|
|
|
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 attributes
|
|
--------------------
|
|
|
|
TODO
|
|
|
|
4. Supported classes
|
|
--------------------
|
|
|
|
TODO
|
|
|
|
=== EOF ===
|
|
|
|
Version: $Id$
|