]> git.saurik.com Git - wxWidgets.git/blame - contrib/src/xml/FORMAT.txt
added wxHtmlHelpController::GetHelpData and removed SetBookBasePath (you can use...
[wxWidgets.git] / contrib / src / xml / FORMAT.txt
CommitLineData
1cfae2e0
VS
1
2 XML resources file format
3 ===============================
4
5 1. Basics
6-----------
7
8XML resource is well-formed XML document, i.e. all tags are paired
9and there is only one root node, which is always <resource>.
10
11In the following text, I will use standard XML terminology:
12
13<tag_one prop1="prop" prop2='yes'>
14 <tag_two/>
15</tag_one>
16
17Here, tag_one is a node (the word 'tag' refers to the type of the node),
18prop1 and prop2 are properties and tag_two is a child node of tag_one.
19Property's default value is the value that will be assigned to the property
20if you do not specify it explicitly.
21
22I will use the term "primary node" to refer to nodes than represent controls,
23dialogs 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
36In the example above, <label>, <pos>, <size> and <title> are "variables",
37i.e. they contain a value and not a list of children (unlike <children> node).
38
39Any node (but the root one) may have property "platform" with possible
40values "unix", "win", "mac" or "os2". All nodes with "platform" property
41specified and other than the platform the program is currently being executed
42on will be removed when reading XML resource file.
43
44Root node may have children of these and only these types: <menu>, <menubar>,
45<dialog>, <panel>
46
47
48
49 2. IDs
50--------
51
52Any primary node may have property "name" used to identify it. Default value
53is "-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
67are translated into corresponding wxWindows ID constant, XMLID macro is used
68otherwise to generate unique ID. wxWindows control created from named node
69will have name=name and id=XMLID(name) or wxID_XXXX.
70
71
72 3. Common variables types
73---------------------------
74
75Variables are always of a known type:
76
77bool - 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
81integer - integer value, i.e. digits 0-9 plus optional minus sign.
82
83text - 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
87style - (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
93color - 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
97coord - 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
113Most 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
126where children node is supported only by panels, dialogs etc. -- see
127nodes description for details.
128
129In the following text,
130
131 TYPE var_name [ (= default_value) ]
132
133means that given primary node may have child node with name var_name
134and content type TYPE. If default value is given, the node is optional
135and default_value will be used if not specified. Otherwise, the node
136is mandatory and must always be present. For example, "color fg" means
137than 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,
145textctrl etc.) accept the following properties:
146
147coord pos (= -1,-1) position of the control. Default value
148 equals to wxDefaultPosition
149coord size (= -1,-1) size of the control. Default value equals to
150 wxDefaultSize
151text tooltip window's tooltip
152color bg background color of the control
153color fg foreground/text color of the control
154style style control style flag. Default value is
155 control-dependent (but 0 is common value)
156style exstyle control extended style flag
157bool enabled (= 1) is the control enabled?
158bool hidden (= 0) is the control hidden?
159bool focused (= 0) has the control focus?
160
161
162_Usually_ (but not always, only when it makes sense) controls support text
163variable label which contains displayed text and/or value which contains
164editable text. These are always explicitly mentioned in tag description.
165
166
167
168
169 6. Tags description
170---------------------
171
172If '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