contrib/src/xml/FORMAT.txt

   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