docs/tech/tn0014.txt

   1                       XRC resources format specification
   2                       ==================================
   3
   4                          !!!!! NOT YET FINISHED !!!!!
   5
   6 0. Introduction
   7 ===============
   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) DialogBlocks (wxPython/tools)
  17
  18 and others listed on the Resources section of the wxWidgets web
  19 site.
  20
  21 The XRC format is based on XML 1.0 (please consult W3C's specification). There
  22 is no DTD available since it is not possible to fully describe the format with
  23 the limited expressive power of DTDs.
  24
  25
  26 Note: see also http://ldaptool.sourceforge.net/XRCGuide/XRCGuideSingle/
  27
  28
  29
  30 1. Terminology
  31 ==============
  32
  33 The usual XML terminology applies. In particular, we shall use the terms
  34 NODE, PROPERTY and VALUE in the XML sense:
  35
  36     <node property1="value1" property2="value2">...</node>
  37
  38 The term ATTRIBUTE is specific to XRC and refers to a subnode
  39 of an <object> or <object_ref> node that is itself not <object> or <object_ref>.
  40 In the example below, <pos>, <label> and <style> are attributes, while neither
  41 <resource> nor either of <object>s is:
  42
  43     <?xml version="1.0" encoding="utf-8">
  44     <resource xmlns="http://www.wxwidgets.org/wxxrc" version="2.5.3.0">
  45         <object class="wxPanel">
  46             <style>wxSUNKEN_BORDER</style>             <!-- attr -->
  47             <object class="wxStaticText">
  48                 <label>A label</label>                 <!-- attr -->
  49                 <pos>10,10</pos>                       <!-- attr -->
  50             </object>
  51         </object>
  52     </resource>
  53
  54 ATTRIBUTE VALUE is the content of all text elements within attribute tag. In the
  55 above example, "wxSUNKEN_BORDER", "A label" and "10,10" are attribute values.
  56 ATTRIBUTE TYPE defines what attribute values are valid for given attribute (you
  57 can think of it as attribute value syntax definition).
  58
  59
  60
  61 2. Elementary description
  62 =========================
  63
  64 XRC resource file is a well-formed XML 1.0 document. All elements of XRC file
  65 are from the http://www.wxwidgets.org/wxxrc namespace.
  66
  67 The root node of XRC document must be <resource>. The <resource> node has
  68 optional "version" property. Default version  (in absence of the version
  69 property) is "0.0.0.0". The version consists of four integers separated by
  70 periods. Version of XRC format changes only if there was an incompatible
  71 change introduced (i.e. either the library cannot understand old resource
  72 files or older versions of the library wouldn't understand the new format).
  73 The first three integers are major, minor and release number of the wxWidgets
  74 release when the change was introduced, the last one is revision number and
  75 is 0 for the first incompatible change in given wxWidgets release, 1 for
  76 the second etc.
  77
  78 Differences between versions are described within this document in paragraphs
  79 entitled "Version Note".
  80
  81 The <resource> node contains namespace declaration, too:
  82
  83     <resource xmlns="http://www.wxwidgets.org/wxxrc" version="2.5.3.0">
  84
  85 The <resource> node is only allowed to have <object> and <object_ref>
  86 subnodes, all of which must have the "name" property.
  87
  88 The <object> node represents a single object (GUI element) and it usually maps
  89 directly to a wxWidgets class instance. It three properties: "name", "class"
  90 and "subclass". "class" must always be present, it tells XRC what wxWidgets
  91 object should be created in this place. The other two are optional.  "name" is
  92 ID used to identify the object. It is the value passed to the XRCID() macro and
  93 is also used to construct wxWindow's id and name attributes and must be unique
  94 among all children of the nearest container object (wxDialog, wxFrame,
  95 wxPanel, wxNotebook) upside from the object in XML nodes hierarchy (two distinct
  96 containers may contain objects with same "name", though). "subclass" is
  97 optional name of class whose constructor will be called instead of the
  98 constructor for "class". Subclass must be available in the program that loads
  99 the resource, must be derived from "class" and must be registered within
 100 wxWidgets' RTTI system.
 101
 102 Example:
 103
 104     <object name="MyList1" class="wxListCtrl" subclass="MyListCtrlClass">
 105         ...
 106     </object>
 107
 108 <object> node may have arbitrary child nodes. What child nodes and their
 109 semantics are class-dependent and are defined later in this document. The user
 110 is allowed to register new object handlers within XRC and extend it to accept
 111 new <object> classes (and therefore different <object>'s child nodes).
 112
 113 <object_ref> node is identical to <object>, except that it does _not_ have
 114 "class" property and has additional required property "ref". It's concept is
 115 similar to Unix symlinks: value of the "ref" property is equal to the value of
 116 "name" property of some existing node (called referred node) in the resources
 117 (not necessary top-level).  Referred node's "class" property and all subnodes
 118 are copied in place of the referee <object_ref> node which is then processed as
 119 regular <object> node. If the <object_ref> node itself has child nodes, then
 120 these nodes _override_ any nodes from the referred node.
 121
 122 Example:
 123
 124     <object name="foo" class="wxTextCtrl">
 125         <value>hello</value>
 126         <size>100,-1d</size>
 127     </object>
 128     <object_ref name="bar" ref="foo">
 129         <value>bar</value>               <!-- override! -->
 130     </object_ref>
 131
 132 is identical to:
 133
 134     <object name="foo" class="wxTextCtrl">
 135         <value>hello</value>
 136         <size>100,-1d</size>
 137     </object>
 138     <object name="bar" class="wxTextCtrl">
 139         <value>bar</value>
 140         <size>100,-1d</size>
 141     </object>
 142
 143
 144
 145 3. Common attribute types
 146 =========================
 147
 148 There are several attribute types (see section 1. Terminology) that are common
 149 to many attributes of different classes:
 150
 151 String
 152 ------
 153 Any text. Some characters have special interpretation and are translated
 154 by XRC parser according to this table:
 155     "_"    -> "&"  ('&' is used to underline e.g. menu items in wxWidgets)
 156     "__"   -> "_"
 157     "\n"   -> line break (C character '\n')
 158     "\r"   -> carriage return (C character '\r')
 159     "\t"   -> tab (C character '\t')
 160     "\\"   -> "\"
 161               (introduced in version 2.5.3.0, not done in earlier versions)
 162
 163 Version Note:
 164     '$' was used instead of '_' prior to version 2.3.0.1.
 165
 166
 167 I18nString
 168 ----------
 169 Like String, but the value is translated to native language using wxLocale
 170 at runtime (unless it was disabled by not passing wxXRC_USE_LOCALE flag to
 171 wxXmlResource constructor). Used for strings that are "visible" in the GUI.
 172
 173
 174 UnsignedInteger
 175 ---------------
 176 This is obvious. Only digits 0-9 may be present and there must be at least
 177 one digit.
 178
 179
 180 Integer
 181 -------
 182 Like UnsignedInteger but may be prefixed with '-' (ints less than zero).
 183
 184
 185 Position
 186 --------
 187 Specifies (window's) position in 2D space. Syntax is <integer>,<integer>[d]
 188 where <integer> is valid value of Integer type.
 189
 190
 191 Size
 192 ----
 193 Syntax is same as Position's syntax, but the values are interpreted as window
 194 size (wxSize type) and not position (wxPosition type).
 195
 196
 197 Style[wxSomeClass]
 198 ------------------
 199 List of style flags that can be passed to wxSomeClass' constructor. Flags are
 200 written in same way as in C++ code (e.g. "wxSUNKEN_BORDER",
 201 "wxHW_SCROLLBAR_NEVER") and are delimited with any combination of whitespaces
 202 and '|'. Possible flags are class-dependent and are not described in this
 203 technote. Please refer to wxWidgets manual for all styles that given class can
 204 accept; if XRC does not accept a flag listed in wxWidgets documentation, it is
 205 a bug.
 206
 207
 208 Bitmap
 209 ------
 210 Attribute value is interpreted as filename (either absolute or relative to
 211 the location of XRC resource file). In addition, attribute node may have
 212 "stock_id" and "stock_client" properties. Their values may be any of wxArtID (or
 213 wxArtClient respectively) values as used by wxArtProvider (because the user may
 214 define own constants, effectively any string is legal here). Examples are
 215 "wxART_FILE_OPEN" (id) or "wxART_MENU" (client).
 216
 217 Any of "stock_id" or "stock_client" properties or the filename may be omitted.
 218 XRC determines the bitmap to use according to this algorithm:
 219   1. If there is non-empty "stock_id" property, query wxArtProvider for the
 220      bitmap (if there is no "stock_client", use default one, which is usually
 221      wxART_OTHER; exceptions are noted in class-specific sections below). If
 222      the query fails, continue to 2.
 223   2. Load the bitmap from the file in attribute value.
 224
 225
 226 Boolean
 227 -------
 228 Boolean value, either "0" (false) or "1" (true).
 229
 230
 231 Font
 232 ----
 233 Font value. A font can be described either in terms of its elementary
 234 properties, or it can be derived from one of system fonts. The font node
 235 may contain following subnodes (the table lists subnode name on the left and
 236 variable type as per the definitions above on the right side):
 237
 238 size            UnsignedInteger
 239 style           normal | italic | slant
 240 weight          normal | bold | light
 241 family          roman | script | decorative | swiss | modern | teletype
 242 underlined      Boolean
 243 face            comma-separated list of faces
 244 encoding        charset of the font (meaningless in Unicode build), as string
 245 sysfont         symbolic name of system standard font
 246                 (one of wxSYS_*_FONT constants)
 247 relativesize    Float, font size relative to choosen system font's size;
 248                 can only be used when 'sysfont' is used and when 'size' is not
 249                 used
 250
 251 All of them are optional, if they are missing, wxFont default is used.
 252
 253 Examples:
 254
 255     <font>
 256         <face>arial,helvetica</face>
 257         <size>12</size>
 258     </font>
 259
 260     <font>
 261         <sysfont>wxSYS_DEFAULT_GUI_FONT</sysfont>
 262         <weight>bold</weight>
 263         <relativesize>1.5</relativesize>
 264     </font>
 265
 266
 267 Colour
 268 ------
 269 A colour value is either explicit RGB value in the standard #rrggbb format
 270 where rr, gg and bb are hexadecimal case-insensitive values in the 00..FF
 271 range, or a symbolic name. Symbolic names are wxSYS_COLOUR_* constants defined
 272 by wxWidgets, written as strings.
 273
 274 Example:
 275
 276     <bg>wxSYS_COLOUR_SCROLLBAR</bg>
 277     <fg>#FF0000</fg>
 278
 279
 280
 281 4. Supported classes
 282 ====================
 283
 284 Attributes are listed in tables in the following format:
 285 attribute name             attribute type          default value, if any
 286                            [(optional remarks....................
 287                            ...................................)]
 288
 289 wxBitmap
 290 --------
 291 This is a special case, because it does not create a wxWindow instance but
 292 creates wxBitmap instead. Another exceptional thing is that it does not have
 293 any attributes. Instead, the node itself is interpreted as if it were attribute
 294 of type Bitmap.
 295
 296 Example: <object class="wxBitmap">bitmaps/foo.gif</object>
 297
 298
 299 wxIcon
 300 ------
 301 Identical to wxBitmap class, except that it creates wxIcon instead of wxBitmap.
 302
 303
 304 wxButton
 305 --------
 306 pos                        Position                -1,-1
 307 size                       Size                    -1,-1
 308 style                      Style[wxButton]
 309
 310 label                      I18nString
 311 default                    Boolean                 false
 312                            (Is the button default button?)
 313
 314
 315 wxCalendarCtrl
 316 --------------
 317 pos                        Position                -1,-1
 318 size                       Size                    -1,-1
 319 style                      Style[wxCalendarCtrl]
 320
 321
 322 wxCheckBox
 323 ----------
 324 pos                        Position                -1,-1
 325 size                       Size                    -1,-1
 326 style                      Style[wxCheckBox]
 327 checked                    Boolean                 false
 328
 329
 330 wxCheckList
 331 -----------
 332 pos                        Position                -1,-1
 333 size                       Size                    -1,-1
 334 style                      Style[wxCheckList]
 335 content                    (see below)             (empty)
 336
 337 Optional "content" attribute does not have attribute value. Instead,
 338 arbitrary number of <item> nodes may be rooted under it (the control
 339 is filled with strings contained in these nodes). Each <item>
 340 node must contain I18nString value and may have "checked" property
 341 with possible values "0" or "1" indicating the the item is initially
 342 checked.
 343
 344 Example:
 345 <object class="wxCheckList">
 346     <content>
 347       <item>One</item>
 348       <item checked="1">Two</item>
 349       <item checked="1">Three</item>
 350       <item>Four</item>
 351     </content>
 352 </object>
 353
 354
 355 wxDatePickerCtrl
 356 ----------------
 357 pos                        Position                -1,-1
 358 size                       Size                    -1,-1
 359 style                      Style[wxDatePickerCtrl]
 360
 361
 362 wxDialog
 363 --------
 364 pos                        Position                -1,-1
 365 size                       Size                    -1,-1
 366 style                      Style[wxDialog]         wxDEFAULT_DIALOG_STYLE
 367 title                      I18nString              ""
 368 icon                       Bitmap                  (empty)
 369 centered                   Boolean                 false
 370
 371 wxDialog may have children objects.
 372
 373
 374 wxFrame
 375 --------
 376 pos                        Position                -1,-1
 377 size                       Size                    -1,-1
 378 style                      Style[wxDialog]         wxDEFAULT_FRAME_STYLE
 379 title                      I18nString              ""
 380 icon                       Bitmap                  (empty)
 381 centered                   Boolean                 false
 382
 383 wxFrame may have children objects. There can be at most one wxToolBar,
 384 wxMenuBar and wxStatusBar children; objects of these types are automatically
 385 set as frame's tool-, menu- and statusbar respectively.
 386
 387
 388 wxMDIParentFrame
 389 ----------------
 390
 391 Supports same attributes and children nodes as wxFrame. Additionally, children
 392 may be of the wxMDIChildFrame type.
 393
 394
 395 wxMDIChildFrame
 396 ---------------
 397
 398 Supports same attributes and children nodes as wxFrame.
 399
 400
 401 wxScrolledWindow
 402 ----------------
 403 pos                        Position                -1,-1
 404 size                       Size                    -1,-1
 405 style                      Style[wxScrolledWindow] wxHSCROLL | wxVSCROLL
 406
 407 wxScolledWindow may have children objects.
 408
 409
 410 wxSplitterWindow
 411 ----------------
 412 pos                        Position                -1,-1
 413 size                       Size                    -1,-1
 414 style                      Style[wxSplitterWindow] wxSP_3D
 415 sashpos                    Integer                 0
 416                            (Initial sash position)
 417 minsize                    Integer                 -1
 418                            (Minimal panel size)
 419 orientation                "horizontal"|"vertical" horizontal
 420
 421 wxSplitterWindow must have at least one and at most two children objects.
 422 If there's only one child object, it is passed to wxSplitterWindow::Initialize
 423 and the splitter is created unsplit. If there are two children, the
 424 splitter is created split, either horizontally or vertically depending
 425 on the value of "orientation" attribute.
 426
 427
 428 wxStatusBar
 429 -----------
 430 fields                     Integer number of fields
 431 widths                     Width1, Width2, Width3, ...
 432
 433
 434 wxToolBar
 435 ---------
 436 pos                        Position                -1,-1
 437 size                       Size                    -1,-1
 438 style                      Style[wxToolBar]        wxNO_BORDER|wxTB_HORIZONTAL
 439 bitmapsize                 Size                    -1,-1
 440                            (Size of contained bitmaps)
 441 margins                    Size                    -1,-1
 442 packing                    Integer                 -1
 443 separation                 Integer                 -1
 444
 445 wxToolBar node may have children <object> and <object_ref> nodes. Their class
 446 may be either "tool", "separator" or any wxWidgets class derived from
 447 wxControl. "tool" and "separator" are special pseudo-classes that may only
 448 appear within wxToolBar node. Their attributes are as follows:
 449
 450     separator
 451     ---------
 452     (doesn't have any attributes)
 453
 454     tool
 455     ----
 456     bitmap                 Bitmap
 457     bitmap2                Bitmap                  wxNullBitmap
 458     toggle                 Boolean                 0
 459     radio                  Boolean                 0
 460     label                  I18nString              ""
 461     tooltip                I18nString              ""
 462     longhelp               I18nString              ""
 463     pos                    Position                -1,-1
 464
 465     Constraints:
 466       At most one of "toggle" and "radio" attributes may be 1.
 467       Attribute "pos" may not appear if "label" or "radio" attributes
 468       are used or if parent wxToolBar's style contains wxTB_TEXT.
 469
 470     Note:
 471       Use of "pos" attribute is strongly discouraged, it is deprecated
 472       usage of wxToolBar and it is not supported by MSW and GTK
 473       implementations.
 474
 475 Children objects are added to the toolbar using AddTool for "tool" class,
 476 AddSeparator for "separator" and AddControl for other classes.
 477
 478
 479
 480 5. More features
 481 ================
 482
 483 FIXME -- "platform" property handling
 484
 485
 486 === EOF ===
 487
 488 Version: $Id$