[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


wxToolBar
---------
position                   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 wxWindows 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              ""
    position               Position                -1,-1

    Constraints:
      At most one of "toggle" and "radio" attributes may be 1.
      Attribute "position" may not appear if "label" or "radio" attributes
      are used or if parent wxToolBar's style contains wxTB_TEXT.
    
    Note:
      Use of "position" 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$
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
432be5aa VS	59	XRC resource file is a well-formed XML 1.0 document. All elements of XRC file
432be5aa VS	60	are 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
432be5aa VS	86	object should be created in this place. The other two are optional. "name" is
	87	ID used to identify the object. It is the value passed to the XRCID() macro and
	88	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,
	90	wxPanel, wxNotebook) upside from the object in XML nodes hiearchy (two distinct
	91	containers may contain objects with same "name", though). "subclass" is
	92	optional name of class whose constructor will be called instead of the
	93	constructor for "class". Subclass must be available in the program that loads
	94	the resource, must be derived from "class" and must be registered within
	95	wxWindows' RTTI system.
2b5f62a0 VZ	96
	97	Example:
	98
	99	<object name="MyList1" class="wxListCtrl" subclass="MyListCtrlClass">
	100	...
	101	</object>
	102
432be5aa VS	103	<object> node may have arbitrary child nodes. What child nodes and their
	104	semantics are class-dependent and are defined later in this document. The user
	105	is allowed to register new object handlers within XRC and extend it to accept
	106	new <object> classes (and therefore different <object>'s child nodes).
	107
	108	<object_ref> node is identical to <object>, except that it does _not_ have
	109	"class" property and has additonal required property "ref". It's concept is
	110	similar to Unix symlinks: value of the "ref" property is equal to the value of
	111	"name" property of some existing node (called referred node) in the resources
	112	(not neccessary top-level). Referred node's "class" property and all subnodes
	113	are copied in place of the referee <object_ref> node which is then processed as
	114	regular <object> node. If the <object_ref> node itself has child nodes, then
	115	these nodes _override_ any nodes from the referred node.
2b5f62a0 VZ	116
	117	Example:
	118
	119	<object name="foo" class="wxTextCtrl">
	120	<value>hello</value>
	121	<size>100,-1d</size>
	122	</object>
	123	<object_ref name="bar" ref="foo">
	124	<value>bar</value> <!-- override! -->
0fa2e104	125	</object_ref>
2b5f62a0 VZ	126
	127	is identical to:
	128
	129	<object name="foo" class="wxTextCtrl">
	130	<value>hello</value>
	131	<size>100,-1d</size>
	132	</object>
	133	<object name="bar" class="wxTextCtrl">
	134	<value>bar</value>
	135	<size>100,-1d</size>
	136	</object>
	137
	138
	139
	140	3. Common attribute types
	141	=========================
	142
	143	There are several attribute types (see section 1. Terminology) that are common
	144	to many attributes of different classes:
	145
	146	String
	147	------
	148	Any text. Some characters have special interpretation and are translated
	149	by XRC parser according to this table:
	150	"_" -> "&" ('&' is used to underline e.g. menu items in wxWindows)
	151	"__" -> "_"
	152	"\n" -> line break (C character '\n')
	153	"\r" -> carriage return (C character '\r')
	154	"\t" -> tabelator (C character '\t')
	155
	156	Version Note:
	157	'$' was used instead of '_' prior to version 2.3.0.1.
	158
	159
	160	I18nString
	161	----------
	162	Like String, but the value is translated to native language using wxLocale
	163	at runtime (unless it was disabled by not passing wxXRC_USE_LOCALE flag to
	164	wxXmlResource constructor). Used for strings that are "visible" in the GUI.
	165
	166
	167	UnsignedInteger
	168	---------------
	169	This is obvious. Only digits 0-9 may be present and there must be at least
	170	one digit.
	171
	172
	173	Integer
	174	-------
	175	Like UnsignedInteger but may be prefixed with '-' (ints less than zero).
	176
	177
	178	Position
	179	--------
	180	Specifies (window's) position in 2D space. Syntax is <integer>,<integer>[d]
	181	where <integer> is valid value of Integer type.
	182
50ccbaaa	183
2b5f62a0 VZ	184	Size
	185	----
	186	Syntax is same as Position's syntax, but the values are interpreted as window
	187	size (wxSize type) and not position (wxPosition type).
50ccbaaa VS	188
50ccbaaa VS	189
2b5f62a0 VZ	190	Style[wxSomeClass]
	191	------------------
	192	List of style flags that can be passed to wxSomeClass' constructor. Flags are
432be5aa VS	193	written in same way as in C++ code (e.g. "wxSUNKEN_BORDER",
	194	"wxHW_SCROLLBAR_NEVER") and are delimined with any combination of whitespaces
	195	and '\|'. Possible flags are class-dependent and are not described in this
	196	technote. Please refer to wxWindows manual for all styles that given class can
	197	accept; if XRC does not accept a flag listed in wxWindows documentation, it is
	198	a bug.
2b5f62a0 VZ	199
	200
	201	Bitmap
	202	------
	203	Attribute value is interpreted as filename (either absolute or relative to
	204	the location of XRC resource file). In addition, attribute node may have
	205	"stock_id" and "stock_client" properties. Their values may be any of wxArtID (or
	206	wxArtClient respectively) values as used by wxArtProvider (because the user may
	207	define own constants, efectively any string is legal here). Examples are
	208	"wxART_FILE_OPEN" (id) or "wxART_MENU" (client).
	209
432be5aa VS	210	Any of "stock_id" or "stock_client" properties or the filename may be omitted.
	211	XRC determines the bitmap to use according to this algorithm:
	212	1. If there is non-empty "stock_id" property, query wxArtProvider for the
	213	bitmap (if there is no "stock_client", use default one, which is usually
	214	wxART_OTHER; exceptions are noted in class-specific sections bellow). If
	215	the query fails, continue to 2.
2b5f62a0 VZ	216	2. Load the bitmap from the file in attribute value.
	217
	218
	219	Boolean
	220	-------
	221	Boolean value, either "0" (false) or "1" (true).
	222
50ccbaaa	223
50ccbaaa VS	224
50ccbaaa VS	225	4. Supported classes
2b5f62a0 VZ	226	====================
	227
	228	Attributes are listed in tables in the following format:
	229	attribute name attribute type default value, if any
	230	[(optional remarks....................
	231	...................................)]
	232
	233	wxBitmap
	234	--------
	235	This is a special case, because it does not create a wxWindow instance but
	236	creates wxBitmap instead. Another exceptional thing is that it does not have
	237	any attributes. Instead, the node itself is interpreted as if it were attribute
	238	of type Bitmap.
	239
	240	Example: <object class="wxBitmap">bitmaps/foo.gif</object>
	241
	242
	243	wxIcon
	244	------
	245	Identical to wxBitmap class, except that it creates wxIcon instead of wxBitmap.
	246
	247
	248	wxButton
	249	--------
	250	position Position -1,-1
	251	size Size -1,-1
	252	style Style[wxButton]
	253
	254	label I18nString
	255	default Boolean false
	256	(Is the button default button?)
	257
	258
	259	wxCalendarCtrl
	260	--------------
	261	position Position -1,-1
	262	size Size -1,-1
	263	style Style[wxCalendarCtrl]
	264
	265
	266	wxCheckBox
	267	----------
	268	position Position -1,-1
	269	size Size -1,-1
	270	style Style[wxCheckBox]
	271	checked Boolean false
	272
	273
	274	wxCheckList
	275	-----------
	276	position Position -1,-1
	277	size Size -1,-1
	278	style Style[wxCheckList]
	279	content (see bellow) (empty)
	280
	281	Optional "content" attribute does not have attribute value. Instead,
	282	arbitrary number of <item> nodes may be rooted under it (the control
	283	is filled with strings contained in these nodes). Each <item>
	284	node must contain I18nString value and may have "checked" property
	285	with possible values "0" or "1" indicating the the item is initially
	286	checked.
	287
	288	Example:
	289	<object class="wxCheckList">
290	<content>
291	<item>One</item>
292	<item checked="1">Two</item>
293	<item checked="1">Three</item>
294	<item>Four</item>
295	</content>
296	</object>
297
298
299	wxScrolledWindow
300	----------------
301	position Position -1,-1
302	size Size -1,-1
303	style Style[wxScrolledWindow] wxHSCROLL \| wxVSCROLL
304
305
432be5aa VS	306	wxToolBar
	307	---------
	308	position Position -1,-1
	309	size Size -1,-1
	310	style Style[wxToolBar] wxNO_BORDER\|wxTB_HORIZONTAL
	311	bitmapsize Size -1,-1
	312	(Size of contained bitmaps)
	313	margins Size -1,-1
	314	packing Integer -1
	315	separation Integer -1
	316
	317	wxToolBar node may have children <object> and <object_ref> nodes. Their class
	318	may be either "tool", "separator" or any wxWindows class derived from
	319	wxControl. "tool" and "separator" are special pseudo-classes that may only
	320	appear within wxToolBar node. Their attributes are as follows:
	321
	322	separator
	323	---------
	324	(doesn't have any attributes)
	325
	326	tool
	327	----
	328	bitmap Bitmap
	329	bitmap2 Bitmap wxNullBitmap
	330	toggle Boolean 0
	331	radio Boolean 0
	332	label I18nString ""
	333	tooltip I18nString ""
	334	longhelp I18nString ""
	335	position Position -1,-1
	336
	337	Constraints:
	338	At most one of "toggle" and "radio" attributes may be 1.
	339	Attribute "position" may not appear if "label" or "radio" attributes
	340	are used or if parent wxToolBar's style contains wxTB_TEXT.
	341
	342	Note:
	343	Use of "position" attribute is strongly discouraged, it is deprecated
	344	usage of wxToolBar and it is not supported by MSW and GTK
	345	implementations.
	346
	347	Children objects are added to the toolbar using AddTool for "tool" class,
	348	AddSeparator for "separator" and AddControl for other classes.
	349
	350
2b5f62a0 VZ	351
	352	5. More features
	353	================
	354
	355	FIXME -- "platform" property handling
50ccbaaa	356
50ccbaaa VS	357
	358	=== EOF ===
	359
	360	Version: $Id$