contrib/src/xml/FORMAT.txt


                         XML resources file format
                      ===============================

 1. Basics
-----------

XML resource is well-formed XML document, i.e. all tags are paired
and there is only one root node, which is always <resource>.

In the following text, I will use standard XML terminology:

<tag_one prop1="prop" prop2='yes'>
   <tag_two/>
</tag_one>

Here, tag_one is a node (the word 'tag' refers to the type of the node),
prop1 and prop2 are properties and tag_two is a child node of tag_one.
Property's default value is the value that will be assigned to the property
if you do not specify it explicitly.

I will use the term "primary node" to refer to nodes than represent controls,
dialogs etc. "Secondary nodes" are nodes used to store data:

<dialog name="my_dlg">                primary
  <title>Demo Dialog...</title>       secondary
  <size>100,200d</size>               secondary
  <children>                          secondary
    <button name="wxID_OK">           primary
      <label>Ok</label>               secondary
      <pos>10,10d</pos>               secondary
    </button>
  </children>
</dialog>

In the example above, <label>, <pos>, <size> and <title> are "variables",
i.e. they contain a value and not a list of children (unlike <children> node).

Any node (but the root one) may have property "platform" with possible
values "unix", "win", "mac" or "os2". All nodes with "platform" property
specified and other than the platform the program is currently being executed
on will be removed when reading XML resource file.

Root node may have children of these and only these types: <menu>, <menubar>,
<dialog>, <panel>


 2. IDs
--------

Any primary node may have property "name" used to identify it. Default value
is "-1", any string is legal name. Names
    wxID_OPEN, wxID_CLOSE, wxID_NEW,
    wxID_SAVE, wxID_SAVEAS, wxID_REVERT,
    wxID_EXIT, wxID_UNDO, wxID_REDO,
    wxID_HELP, wxID_PRINT, wxID_PRINT_SETUP,
    wxID_PREVIEW, wxID_ABOUT, wxID_HELP_CONTENTS,
    wxID_HELP_COMMANDS, wxID_HELP_PROCEDURES,
    wxID_CUT, wxID_COPY, wxID_PASTE,
    wxID_CLEAR, wxID_FIND, wxID_DUPLICATE,
    wxID_SELECTALL, wxID_OK, wxID_CANCEL,
    wxID_APPLY, wxID_YES, wxID_NO,
    wxID_STATIC, wxID_FORWARD, wxID_BACKWARD,
    wxID_DEFAULT, wxID_MORE, wxID_SETUP,
    wxID_RESET, wxID_HELP_CONTEXT
are translated into corresponding wxWindows ID constant, XMLID macro is used
otherwise to generate unique ID. wxWindows control created from named node
will have name=name and id=XMLID(name) or wxID_XXXX.


 3. Common variables types
---------------------------

Variables are always of a known type:

bool       - boolean value. "1", "true", "t", "on" mean TRUE, anything
             else (namely "0", "false", "f", "off") means FALSE.
             FIXME: maybe use only 1/0 ??

integer    - integer value, i.e. digits 0-9 plus optional minus sign.

text       - anything. Within text node all occurences of $ are replaced
             by & (used for shortcuts, e.g. "E&xit"), $$ by $, \\, \n, \r,
             \t as usual in C++.

style      - (also called flags) list of flags delimined by any combination
             of spaces and | characters. Resources parser accepts only
             _registered_ flags -- i.e. flags that are valid for given
             node/control. Example:
                  <flag>wxEXPAND | wxTOP|wxBOTTOM</flag>

color      - color in HTML format: #rrggbb where rr,gg,bb are hexadecimal
             values (00-FF) for red, green and blue components in
             the RGB color model

coord      - size or position information. Consists of two integers
             separated by comma ("x,y"). The values are in pixels
             unless "d" is attached to the right side of it --
             in which case the values are interpreted as dialog units.
             Value of -1 means "use default". Examples:
                  30,30
                  -1,-1
                  50,-1
                  145,56d
                  67,-1d


 4. Layout
-----------

Most common nodes layout is as follows:

<primary_node name="name" platform="platform">
    <var_1>...</var_1>
    .
    .
    .
    <var_n>...</var_n>
    <children>
        (n primary nodes)
    </children>
</primary_node>

where children node is supported only by panels, dialogs etc. -- see
nodes description for details.

In the following text,

   TYPE var_name [ (= default_value) ]

means that given primary node may have child node with name var_name
and content type TYPE. If default value is given, the node is optional
and default_value will be used if not specified. Otherwise, the node
is mandatory and must always be present. For example, "color fg" means
than variable tag fg, e.g. <fg>#rr0000</fg> is expected.


 5. Common controls variables
------------------------------

_All_ nodes that represent wxWindows controls (gauge, panel, dialog,
textctrl etc.) accept the following properties:

coord   pos       (= -1,-1) position of the control. Default value
                  equals to wxDefaultPosition
coord   size      (= -1,-1) size of the control. Default value equals to
                  wxDefaultSize
text    tooltip   window's tooltip
color   bg        background color of the control
color   fg        foreground/text color of the control
style   style     control style flag. Default value is
                  control-dependent (but 0 is common value)
style   exstyle   control extended style flag
bool    enabled   (= 1) is the control enabled?
bool    hidden    (= 0) is the control hidden?
bool    focused   (= 0) has the control focus?


_Usually_ (but not always, only when it makes sense) controls support text
variable label which contains displayed text and/or value which contains
editable text. These are always explicitly mentioned in tag description.


 6. Tags description
---------------------

If 'Control' is derived from wxControl, it supports all variables from '5.'
'Styles' section lists all acceptable flags for style and exstyle variables.


 <panel>
---------
      Control:
         wxPanel

      Variables:
         only common controls variables

      Styles:
         wxNO_3D, wxTAB_TRAVERSAL, wxWS_EX_VALIDATE_RECURSIVELY


 <dialog>
----------
      Control:
         wxDialog

      Variables:
         style    style     (= wxDEFAULT_DIALOG_style)
         text     title     dialog's title

      Styles:
         wxSTAY_ON_TOP, wxCAPTION, wxDEFAULT_DIALOG_style, wxTHICK_FRAME,
         wxSYSTEM_MENU, wxRESIZE_BORDER, wxRESIZE_BOX, wxDIALOG_MODAL,
         wxDIALOG_MODELESS, wxNO_3D, wxTAB_TRAVERSAL,
         wxWS_EX_VALIDATE_RECURSIVELY


 <boxsizer>
--------------
      Control:
         wxBoxSizer (not a control)

      Behaviour:
         boxsizer's parent must be either <panel>, <dialog> or another
         sizer, nothing else!

         If the sizer does not have parent sizer, the sizer will attach itself
         to the parent panel/dialog using SetAutoLayout(TRUE) and SetSizer().
         If the parent panel/dialog has default size (i.e. not specified in
         the resource), the sizer will fit it using wxSizer::Fit(). If the
         parent panel/dialog is resizable, size hints will be set
         automatically.

      Variables:
         style    orient    (= wxHORIZONTAL) orientation, either
                            wxHORIZONTAL or wxVERTICAL

      Styles:
         wxHORIZONTAL, wxVERTICAL (for orient variable)

         wxLEFT, wxRIGHT, wxTOP, wxBOTTOM, wxNORTH, wxSOUTH, wxEAST, wxWEST,
         wxALL, wxGROW, wxEXPAND, wxSHAPED, wxSTRETCH_NOT, wxALIGN_CENTER,
         wxALIGN_CENTRE, wxALIGN_LEFT, wxALIGN_TOP, wxALIGN_RIGHT,
         wxALIGN_BOTTOM, wxALIGN_CENTER_HORIZONTAL, wxALIGN_CENTRE_HORIZONTAL,
         wxALIGN_CENTER_HORIZONTAL, wxALIGN_CENTRE_HORIZONTAL (for flag
         variable of <item> or <spacer> child nodes)

      Child nodes:
         Contains child node <children> which has arbitrary number of
         <sizeritem> and <spacer> child nodes.

          <sizeritem>
         -------------
            Variables:
               integer  option    (= 0) relative size of the widget
               style    flag      (= 0) style flag
               integer  border    (= 0) surrounding border

            Has exactly one child node <window> that contains the control
            (or child sizer because sizers may be nested)
            to be inserted into the sizer.

          <spacer>
         ----------
            Variables:
               integer  option    (= 0) relative size of the widget
               style    flag      (= 0) style flag
               integer  border    (= 0) surrounding border

            Inserts empty space into the sizer


 <staticboxsizer>
------------------
      Control:
         wxStaticBoxSizer (not a control)

      Same as <boxsizer> except that it has additional variable:

               text     label     (= "") label of surrounding static box

      wxStaticBox required by wxStaticBoxSizer is created automatically!


 <notebooksizer>
-----------------
      Control:
         wxNotebookSizer (not a control)

      Behaviour:
         notebooksizer's parent must be a sizer (not notebooksizer,
         see below)!

      Variables:
         none

      Styles:
         none

      Child nodes:
         Has exactly one child node <window> that contains the notebook
         (nothing else is allowed!) to be inserted into the sizer.


 <textctrl>
------------
      Control:
         wxTextCtrl

      Variables:
         text     value     (= "")default text of the control

      Styles:
         wxTE_PROCESS_ENTER, wxTE_PROCESS_TAB, wxTE_MULTILINE, wxTE_PASSWORD,
         wxTE_READONLY, wxHSCROLL


 <htmlwindow>
--------------
      Control:
         wxHtmlWindow

      Variables:
         integer  borders   (= 0) window's borders
                            (see wxHtmlWindow::SetBorders)
         text     url       (= "") if present, given page will be loaded
         text     htmlcode  (= "") if present, given _text_ will be displayed
                            (you will have to use CDATA section
                            to embed HTML code into XML document)

      Styles:
         wxHW_SCROLLBAR_NEVER, wxHW_SCROLLBAR_AUTO
Commit	Line	Data
	1
	2	XML resources file format
	3	===============================
	4
	5	1. Basics
	6	-----------
	7
	8	XML resource is well-formed XML document, i.e. all tags are paired
	9	and there is only one root node, which is always <resource>.
	10
	11	In the following text, I will use standard XML terminology:
	12
	13	<tag_one prop1="prop" prop2='yes'>
	14	<tag_two/>
	15	</tag_one>
	16
	17	Here, tag_one is a node (the word 'tag' refers to the type of the node),
	18	prop1 and prop2 are properties and tag_two is a child node of tag_one.
	19	Property's default value is the value that will be assigned to the property
	20	if you do not specify it explicitly.
	21
	22	I will use the term "primary node" to refer to nodes than represent controls,
	23	dialogs etc. "Secondary nodes" are nodes used to store data:
	24
	25	<dialog name="my_dlg"> primary
	26	<title>Demo Dialog...</title> secondary
	27	<size>100,200d</size> secondary
	28	<children> secondary
	29	<button name="wxID_OK"> primary
	30	<label>Ok</label> secondary
	31	<pos>10,10d</pos> secondary
	32	</button>
	33	</children>
	34	</dialog>
	35
	36	In the example above, <label>, <pos>, <size> and <title> are "variables",
	37	i.e. they contain a value and not a list of children (unlike <children> node).
	38
	39	Any node (but the root one) may have property "platform" with possible
	40	values "unix", "win", "mac" or "os2". All nodes with "platform" property
	41	specified and other than the platform the program is currently being executed
	42	on will be removed when reading XML resource file.
	43
	44	Root node may have children of these and only these types: <menu>, <menubar>,
	45	<dialog>, <panel>
	46
	47
	48
	49	2. IDs
	50	--------
	51
	52	Any primary node may have property "name" used to identify it. Default value
	53	is "-1", any string is legal name. Names
	54	wxID_OPEN, wxID_CLOSE, wxID_NEW,
	55	wxID_SAVE, wxID_SAVEAS, wxID_REVERT,
	56	wxID_EXIT, wxID_UNDO, wxID_REDO,
	57	wxID_HELP, wxID_PRINT, wxID_PRINT_SETUP,
	58	wxID_PREVIEW, wxID_ABOUT, wxID_HELP_CONTENTS,
	59	wxID_HELP_COMMANDS, wxID_HELP_PROCEDURES,
	60	wxID_CUT, wxID_COPY, wxID_PASTE,
	61	wxID_CLEAR, wxID_FIND, wxID_DUPLICATE,
	62	wxID_SELECTALL, wxID_OK, wxID_CANCEL,
	63	wxID_APPLY, wxID_YES, wxID_NO,
	64	wxID_STATIC, wxID_FORWARD, wxID_BACKWARD,
	65	wxID_DEFAULT, wxID_MORE, wxID_SETUP,
	66	wxID_RESET, wxID_HELP_CONTEXT
	67	are translated into corresponding wxWindows ID constant, XMLID macro is used
	68	otherwise to generate unique ID. wxWindows control created from named node
	69	will have name=name and id=XMLID(name) or wxID_XXXX.
	70
	71
	72	3. Common variables types
	73	---------------------------
	74
	75	Variables are always of a known type:
	76
	77	bool - boolean value. "1", "true", "t", "on" mean TRUE, anything
	78	else (namely "0", "false", "f", "off") means FALSE.
	79	FIXME: maybe use only 1/0 ??
	80
	81	integer - integer value, i.e. digits 0-9 plus optional minus sign.
	82
	83	text - anything. Within text node all occurences of $ are replaced
	84	by & (used for shortcuts, e.g. "E&xit"), $$ by $, \\, \n, \r,
	85	\t as usual in C++.
	86
	87	style - (also called flags) list of flags delimined by any combination
	88	of spaces and \| characters. Resources parser accepts only
	89	_registered_ flags -- i.e. flags that are valid for given
	90	node/control. Example:
	91	<flag>wxEXPAND \| wxTOP\|wxBOTTOM</flag>
	92
	93	color - color in HTML format: #rrggbb where rr,gg,bb are hexadecimal
	94	values (00-FF) for red, green and blue components in
	95	the RGB color model
	96
	97	coord - size or position information. Consists of two integers
	98	separated by comma ("x,y"). The values are in pixels
	99	unless "d" is attached to the right side of it --
	100	in which case the values are interpreted as dialog units.
	101	Value of -1 means "use default". Examples:
	102	30,30
	103	-1,-1
	104	50,-1
	105	145,56d
	106	67,-1d
	107
	108
	109
	110	4. Layout
	111	-----------
	112
	113	Most common nodes layout is as follows:
	114
	115	<primary_node name="name" platform="platform">
	116	<var_1>...</var_1>
	117	.
	118	.
	119	.
	120	<var_n>...</var_n>
	121	<children>
	122	(n primary nodes)
	123	</children>
	124	</primary_node>
	125
	126	where children node is supported only by panels, dialogs etc. -- see
	127	nodes description for details.
	128
	129	In the following text,
	130
	131	TYPE var_name [ (= default_value) ]
	132
	133	means that given primary node may have child node with name var_name
	134	and content type TYPE. If default value is given, the node is optional
	135	and default_value will be used if not specified. Otherwise, the node
	136	is mandatory and must always be present. For example, "color fg" means
	137	than variable tag fg, e.g. <fg>#rr0000</fg> is expected.
	138
	139
	140
	141	5. Common controls variables
	142	------------------------------
	143
	144	_All_ nodes that represent wxWindows controls (gauge, panel, dialog,
	145	textctrl etc.) accept the following properties:
	146
	147	coord pos (= -1,-1) position of the control. Default value
	148	equals to wxDefaultPosition
	149	coord size (= -1,-1) size of the control. Default value equals to
	150	wxDefaultSize
	151	text tooltip window's tooltip
	152	color bg background color of the control
	153	color fg foreground/text color of the control
	154	style style control style flag. Default value is
	155	control-dependent (but 0 is common value)
	156	style exstyle control extended style flag
	157	bool enabled (= 1) is the control enabled?
	158	bool hidden (= 0) is the control hidden?
	159	bool focused (= 0) has the control focus?
	160
	161
	162	_Usually_ (but not always, only when it makes sense) controls support text
	163	variable label which contains displayed text and/or value which contains
	164	editable text. These are always explicitly mentioned in tag description.
	165
	166
	167
	168
	169	6. Tags description
	170	---------------------
	171
	172	If 'Control' is derived from wxControl, it supports all variables from '5.'
	173	'Styles' section lists all acceptable flags for style and exstyle variables.
	174
	175
	176	<panel>
	177	---------
	178	Control:
	179	wxPanel
	180
	181	Variables:
	182	only common controls variables
	183
	184	Styles:
	185	wxNO_3D, wxTAB_TRAVERSAL, wxWS_EX_VALIDATE_RECURSIVELY
	186
	187
	188
	189	<dialog>
	190	----------
	191	Control:
	192	wxDialog
	193
	194	Variables:
	195	style style (= wxDEFAULT_DIALOG_style)
	196	text title dialog's title
	197
	198	Styles:
	199	wxSTAY_ON_TOP, wxCAPTION, wxDEFAULT_DIALOG_style, wxTHICK_FRAME,
	200	wxSYSTEM_MENU, wxRESIZE_BORDER, wxRESIZE_BOX, wxDIALOG_MODAL,
	201	wxDIALOG_MODELESS, wxNO_3D, wxTAB_TRAVERSAL,
	202	wxWS_EX_VALIDATE_RECURSIVELY
	203
	204
	205
	206	<boxsizer>
	207	--------------
	208	Control:
	209	wxBoxSizer (not a control)
	210
	211	Behaviour:
	212	boxsizer's parent must be either <panel>, <dialog> or another
	213	sizer, nothing else!
	214
	215	If the sizer does not have parent sizer, the sizer will attach itself
	216	to the parent panel/dialog using SetAutoLayout(TRUE) and SetSizer().
	217	If the parent panel/dialog has default size (i.e. not specified in
	218	the resource), the sizer will fit it using wxSizer::Fit(). If the
	219	parent panel/dialog is resizable, size hints will be set
	220	automatically.
	221
	222	Variables:
	223	style orient (= wxHORIZONTAL) orientation, either
	224	wxHORIZONTAL or wxVERTICAL
	225
	226	Styles:
	227	wxHORIZONTAL, wxVERTICAL (for orient variable)
	228
	229	wxLEFT, wxRIGHT, wxTOP, wxBOTTOM, wxNORTH, wxSOUTH, wxEAST, wxWEST,
	230	wxALL, wxGROW, wxEXPAND, wxSHAPED, wxSTRETCH_NOT, wxALIGN_CENTER,
	231	wxALIGN_CENTRE, wxALIGN_LEFT, wxALIGN_TOP, wxALIGN_RIGHT,
	232	wxALIGN_BOTTOM, wxALIGN_CENTER_HORIZONTAL, wxALIGN_CENTRE_HORIZONTAL,
	233	wxALIGN_CENTER_HORIZONTAL, wxALIGN_CENTRE_HORIZONTAL (for flag
	234	variable of <item> or <spacer> child nodes)
	235
	236	Child nodes:
	237	Contains child node <children> which has arbitrary number of
	238	<sizeritem> and <spacer> child nodes.
	239
	240	<sizeritem>
	241	-------------
	242	Variables:
	243	integer option (= 0) relative size of the widget
	244	style flag (= 0) style flag
	245	integer border (= 0) surrounding border
	246
	247	Has exactly one child node <window> that contains the control
	248	(or child sizer because sizers may be nested)
	249	to be inserted into the sizer.
	250
	251	<spacer>
	252	----------
	253	Variables:
	254	integer option (= 0) relative size of the widget
	255	style flag (= 0) style flag
	256	integer border (= 0) surrounding border
	257
	258	Inserts empty space into the sizer
	259
	260
	261
	262	<staticboxsizer>
	263	------------------
	264	Control:
	265	wxStaticBoxSizer (not a control)
	266
	267	Same as <boxsizer> except that it has additional variable:
	268
	269	text label (= "") label of surrounding static box
	270
	271	wxStaticBox required by wxStaticBoxSizer is created automatically!
	272
	273
	274
	275	<notebooksizer>
	276	-----------------
	277	Control:
	278	wxNotebookSizer (not a control)
	279
	280	Behaviour:
	281	notebooksizer's parent must be a sizer (not notebooksizer,
	282	see below)!
	283
	284	Variables:
	285	none
	286
	287	Styles:
	288	none
	289
	290	Child nodes:
	291	Has exactly one child node <window> that contains the notebook
	292	(nothing else is allowed!) to be inserted into the sizer.
	293
	294
	295
	296	<textctrl>
	297	------------
	298	Control:
	299	wxTextCtrl
	300
	301	Variables:
	302	text value (= "")default text of the control
	303
	304	Styles:
	305	wxTE_PROCESS_ENTER, wxTE_PROCESS_TAB, wxTE_MULTILINE, wxTE_PASSWORD,
	306	wxTE_READONLY, wxHSCROLL
	307
	308
	309
	310	<htmlwindow>
	311	--------------
	312	Control:
	313	wxHtmlWindow
	314
	315	Variables:
	316	integer borders (= 0) window's borders
	317	(see wxHtmlWindow::SetBorders)
	318	text url (= "") if present, given page will be loaded
	319	text htmlcode (= "") if present, given _text_ will be displayed
	320	(you will have to use CDATA section
	321	to embed HTML code into XML document)
	322
	323	Styles:
	324	wxHW_SCROLLBAR_NEVER, wxHW_SCROLLBAR_AUTO