[wxWidgets.git] / docs / tech / tn0014.txt

                      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_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 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$
Commit	Line	Data
50ccbaaa VS	1	XRC resources format specification
	2	==================================
	3
	4	!!!!! NOT YET FINISHED !!!!!
	5
	6	0. Introduction
2b5f62a0	7	===============
50ccbaaa VS	8
	9	This note describes the file format used for storing XRC resources that are
	10	used by wxXmlResource class. It is probably only useful for those implementing
	11	dialog editors with XRC support.
	12
	13	If you only want to use the resources, you can choose from a number of editors:
	14	a) wxDesigner (http://www.roebling.de)
	15	b) XRCed (wxPython/tools)
	16	c) wxWorkshop (http://wxworkshop.sf.net)
	17	b) wxrcedit (contrib/utils/wxrcedit)
	18
	19	The XRC format is based on XML 1.0 (please consult W3C's specification). There
	20	is no DTD available since it is not possible to fully describe the format with
	21	the limited expressive power of DTDs.
	22
2b5f62a0 VZ	23
2b5f62a0 VZ	24
50ccbaaa	25	1. Terminology
2b5f62a0	26	==============
50ccbaaa VS	27
50ccbaaa VS	28	The usual XML terminology applies. In particular, we shall use the terms
2b5f62a0	29	NODE, PROPERTY and VALUE in the XML sense:
50ccbaaa VS	30
	31	<node property1="value1" property2="value2">...</node>
	32
2b5f62a0 VZ	33	The term ATTRIBUTE is specific to XRC and refers to a subnode
	34	of an <object> or <object_ref> node that is itself not <object> or <object_ref>.
	35	In the example bellow, <pos>, <label> and <style> are attributes, while neither
	36	<resource> nor either of <object>s is:
50ccbaaa VS	37
50ccbaaa VS	38	<?xml version="1.0" encoding="utf-8">
40e2d134	39	<resource xmlns="http://www.wxwindows.org/wxxrc" version="2.3.0.1">
50ccbaaa	40	<object class="wxPanel">
2b5f62a0	41	<style>wxSUNKEN_BORDER</style> <!-- attr -->
50ccbaaa	42	<object class="wxStaticText">
2b5f62a0 VZ	43	<label>A label</label> <!-- attr -->
2b5f62a0 VZ	44	<pos>10,10</pos> <!-- attr -->
50ccbaaa VS	45	</object>
	46	</object>
	47	</resource>
	48
2b5f62a0 VZ	49	ATTRIBUTE VALUE is the content of all text elements within attribute tag. In the
	50	above example, "wxSUNKEN_BORDER", "A label" and "10,10" are attribute values.
	51	ATTRIBUTE TYPE defines what attribute values are valid for given attribute (you
	52	can think of it as attribute value syntax definition).
	53
	54
	55
50ccbaaa	56	2. Elementary description
2b5f62a0	57	=========================
50ccbaaa	58
40e2d134 VS	59	XRC resource file is a well-formed XML 1.0 document. All elements of XRC file are
40e2d134 VS	60	from the http://www.wxwindows.org/wxxrc namespace.
50ccbaaa VS	61
	62	The root node of XRC document must be <resource>. The <resource> node has
	63	optional "version" property. Default version (in absence of the version
	64	property) is "0.0.0.0". The version consists of four integers separated by
	65	periods. Version of XRC format changes only if there was an incompatible
	66	change introduced (i.e. either the library cannot understand old resource
	67	files or older versions of the library wouldn't understand the new format).
	68	The first three integers are major, minor and release number of the wxWindows
	69	release when the change was introduced, the last one is revision number and
	70	is 0 for the first incompatible change in given wxWindows release, 1 for
	71	the second etc.
	72
	73	Differences between versions are described within this document in paragraphs
2b5f62a0	74	entitled "Version Note".
50ccbaaa	75
40e2d134 VS	76	The <resource> node contains namespace declaration, too:
	77
	78	<resource xmlns="http://www.wxwindows.org/wxxrc" version="2.3.0.1">
	79
50ccbaaa VS	80	The <resource> node is only allowed to have <object> and <object_ref>
	81	subnodes, all of which must have the "name" property.
	82
2b5f62a0 VZ	83	The <object> node represents a single object (GUI element) and it usually maps
	84	directly to a wxWindows class instance. It three properties: "name", "class"
	85	and "subclass". "class" must always be present, it tells XRC what wxWindows
	86	object should be created in this place. The other two are optional.
	87	"name" is ID used to identify the object. It is the value passed to the XRCID() macro
	88	and is also used to construct wxWindow's id and name attributes and must be unique
	89	among all children of the neareset container object (wxDialog, wxFrame, wxPanel,
	90	wxNotebook) upside from the object in XML nodes hiearchy (two distinct containers
	91	may contain objects with same "name", though). "subclass" is
	92	optional name of class whose constructor will be called instead of the constructor
	93	for "class". Subclass must be available in the program that loads the resource,
	94	must be derived from "class" and must be registered within wxWindows' RTTI system.
	95
	96	Example:
	97
	98	<object name="MyList1" class="wxListCtrl" subclass="MyListCtrlClass">
	99	...
	100	</object>
	101
	102	<object> node may have arbitrary child nodes. What child nodes and their semantics
	103	are class-dependent and are defined later in this document. The user is allowed
	104	to register new object handlers within XRC and extend it to accept new <object>
	105	classes (and therefore different <object>'s child nodes).
	106
	107	<object_ref> node is identical to <object>, except that it does _not_ have "class"
	108	property and has additonal required property "ref". It's concept is similar to Unix
	109	symlinks: value of the "ref" property is equal to the value of "name" property of
	110	some existing node (called referred node) in the resources (not neccessary top-level).
	111	Referred node's "class" property and all subnodes are copied in place of the referee
	112	<object_ref> node which is then processed as regular <object> node. If the <object_ref>
	113	node itself has child nodes, then these nodes _override_ any nodes from the referred node.
	114
	115	Example:
	116
	117	<object name="foo" class="wxTextCtrl">
	118	<value>hello</value>
	119	<size>100,-1d</size>
	120	</object>
	121	<object_ref name="bar" ref="foo">
	122	<value>bar</value> <!-- override! -->
0fa2e104	123	</object_ref>
2b5f62a0 VZ	124
	125	is identical to:
	126
	127	<object name="foo" class="wxTextCtrl">
	128	<value>hello</value>
	129	<size>100,-1d</size>
	130	</object>
	131	<object name="bar" class="wxTextCtrl">
	132	<value>bar</value>
	133	<size>100,-1d</size>
	134	</object>
	135
	136
	137
	138	3. Common attribute types
	139	=========================
	140
	141	There are several attribute types (see section 1. Terminology) that are common
	142	to many attributes of different classes:
	143
	144	String
	145	------
	146	Any text. Some characters have special interpretation and are translated
	147	by XRC parser according to this table:
	148	"_" -> "&" ('&' is used to underline e.g. menu items in wxWindows)
	149	"__" -> "_"
	150	"\n" -> line break (C character '\n')
	151	"\r" -> carriage return (C character '\r')
	152	"\t" -> tabelator (C character '\t')
	153
	154	Version Note:
	155	'$' was used instead of '_' prior to version 2.3.0.1.
	156
	157
	158	I18nString
	159	----------
	160	Like String, but the value is translated to native language using wxLocale
	161	at runtime (unless it was disabled by not passing wxXRC_USE_LOCALE flag to
	162	wxXmlResource constructor). Used for strings that are "visible" in the GUI.
	163
	164
	165	UnsignedInteger
	166	---------------
	167	This is obvious. Only digits 0-9 may be present and there must be at least
	168	one digit.
	169
	170
	171	Integer
	172	-------
	173	Like UnsignedInteger but may be prefixed with '-' (ints less than zero).
	174
	175
	176	Position
	177	--------
	178	Specifies (window's) position in 2D space. Syntax is <integer>,<integer>[d]
	179	where <integer> is valid value of Integer type.
	180
50ccbaaa	181
2b5f62a0 VZ	182	Size
	183	----
	184	Syntax is same as Position's syntax, but the values are interpreted as window
	185	size (wxSize type) and not position (wxPosition type).
50ccbaaa VS	186
50ccbaaa VS	187
2b5f62a0 VZ	188	Style[wxSomeClass]
	189	------------------
	190	List of style flags that can be passed to wxSomeClass' constructor. Flags are
	191	written in same way as in C++ code (e.g. "wxSUNKEN_BORDER", "wxHW_SCROLLBAR_NEVER")
	192	and are delimined with any combination of whitespaces and '\|'. Possible flags
	193	are class-dependent and are not described in this technote. Please refer to wxWindows
	194	manual for all styles that given class can accept; if XRC does not accept a flag
	195	listed in wxWindows documentation, it is a bug.
	196
	197
	198	Bitmap
	199	------
	200	Attribute value is interpreted as filename (either absolute or relative to
	201	the location of XRC resource file). In addition, attribute node may have
	202	"stock_id" and "stock_client" properties. Their values may be any of wxArtID (or
	203	wxArtClient respectively) values as used by wxArtProvider (because the user may
	204	define own constants, efectively any string is legal here). Examples are
	205	"wxART_FILE_OPEN" (id) or "wxART_MENU" (client).
	206
	207	Any of "stock_id" or "stock_client" properties or the filename may be omitted. XRC
	208	determines the bitmap to use according to this algorithm:
	209	1. If there is non-empty "stock_id" property, query wxArtProvider for the bitmap
	210	(if there is no "stock_client", use default one, which is usually wxART_OTHER;
	211	exceptions are noted in class-specific sections bellow). If the query fails,
	212	continue to 2.
	213	2. Load the bitmap from the file in attribute value.
	214
	215
	216	Boolean
	217	-------
	218	Boolean value, either "0" (false) or "1" (true).
	219
50ccbaaa	220
50ccbaaa VS	221
50ccbaaa VS	222	4. Supported classes
2b5f62a0 VZ	223	====================
	224
	225	Attributes are listed in tables in the following format:
	226	attribute name attribute type default value, if any
	227	[(optional remarks....................
	228	...................................)]
	229
	230	wxBitmap
	231	--------
	232	This is a special case, because it does not create a wxWindow instance but
	233	creates wxBitmap instead. Another exceptional thing is that it does not have
	234	any attributes. Instead, the node itself is interpreted as if it were attribute
	235	of type Bitmap.
	236
	237	Example: <object class="wxBitmap">bitmaps/foo.gif</object>
	238
	239
	240	wxIcon
	241	------
	242	Identical to wxBitmap class, except that it creates wxIcon instead of wxBitmap.
	243
	244
	245	wxButton
	246	--------
	247	position Position -1,-1
	248	size Size -1,-1
	249	style Style[wxButton]
	250
	251	label I18nString
	252	default Boolean false
	253	(Is the button default button?)
	254
	255
	256	wxCalendarCtrl
	257	--------------
	258	position Position -1,-1
	259	size Size -1,-1
	260	style Style[wxCalendarCtrl]
	261
	262
	263	wxCheckBox
	264	----------
	265	position Position -1,-1
	266	size Size -1,-1
	267	style Style[wxCheckBox]
	268	checked Boolean false
	269
	270
	271	wxCheckList
	272	-----------
	273	position Position -1,-1
	274	size Size -1,-1
	275	style Style[wxCheckList]
	276	content (see bellow) (empty)
	277
	278	Optional "content" attribute does not have attribute value. Instead,
	279	arbitrary number of <item> nodes may be rooted under it (the control
	280	is filled with strings contained in these nodes). Each <item>
	281	node must contain I18nString value and may have "checked" property
	282	with possible values "0" or "1" indicating the the item is initially
	283	checked.
	284
	285	Example:
	286	<object class="wxCheckList">
287	<content>
288	<item>One</item>
289	<item checked="1">Two</item>
290	<item checked="1">Three</item>
291	<item>Four</item>
292	</content>
293	</object>
294
295
296	wxScrolledWindow
297	----------------
298	position Position -1,-1
299	size Size -1,-1
300	style Style[wxScrolledWindow] wxHSCROLL \| wxVSCROLL
301
302
303
304	5. More features
305	================
306
307	FIXME -- "platform" property handling
50ccbaaa	308
50ccbaaa VS	309
	310	=== EOF ===
	311
	312	Version: $Id$