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) 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
  23
  24
  25 1. Terminology
  26 ==============
  27
  28 The usual XML terminology applies. In particular, we shall use the terms
  29 NODE, PROPERTY and VALUE in the XML sense:
  30
  31     <node property1="value1" property2="value2">...</node>
  32
  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:
  37
  38     <?xml version="1.0" encoding="utf-8">
  39     <resource xmlns="http://www.wxwindows.org/wxxrc" version="2.3.0.1">
  40         <object class="wxPanel">
  41             <style>wxSUNKEN_BORDER</style>             <!-- attr -->
  42             <object class="wxStaticText">
  43                 <label>A label</label>                 <!-- attr -->
  44                 <pos>10,10</pos>                       <!-- attr -->
  45             </object>
  46         </object>
  47     </resource>
  48
  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
  56 2. Elementary description
  57 =========================
  58
  59 XRC resource file is a well-formed XML 1.0 document. All elements of XRC file
  60 are from the http://www.wxwindows.org/wxxrc namespace.
  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
  74 entitled "Version Note".
  75
  76 The <resource> node contains namespace declaration, too:
  77
  78     <resource xmlns="http://www.wxwindows.org/wxxrc" version="2.3.0.1">
  79
  80 The <resource> node is only allowed to have <object> and <object_ref>
  81 subnodes, all of which must have the "name" property.
  82
  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
  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.
  96
  97 Example:
  98
  99     <object name="MyList1" class="wxListCtrl" subclass="MyListCtrlClass">
 100         ...
 101     </object>
 102
 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.
 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! -->
 125     </object_ref>
 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
 183
 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).
 188
 189
 190 Style[wxSomeClass]
 191 ------------------
 192 List of style flags that can be passed to wxSomeClass' constructor. Flags are
 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.
 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
 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.
 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
 223
 224
 225 4. Supported classes
 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
 306 wxSplitterWindow
 307 ----------------
 308 position                   Position                -1,-1
 309 size                       Size                    -1,-1
 310 style                      Style[wxSplitterWindow] wxSP_3D
 311 sashpos                    Integer                 0
 312                            (Initial sash position)
 313 minsize                    Integer                 -1
 314                            (Minimal panel size)
 315 orientation                "horizontal"|"vertical" horizontal
 316
 317 wxSplitterWindow must have at least one and at most two children objects.
 318 If there's only one child object, it is passed to wxSplitterWindow::Initialize
 319 and the splitter is created unsplitted. If there are two children, the
 320 splitter is created splitted, either horizontally or vertically depending
 321 on the value of "orientation" attribute.
 322
 323
 324 wxToolBar
 325 ---------
 326 position                   Position                -1,-1
 327 size                       Size                    -1,-1
 328 style                      Style[wxToolBar]        wxNO_BORDER|wxTB_HORIZONTAL
 329 bitmapsize                 Size                    -1,-1
 330                            (Size of contained bitmaps)
 331 margins                    Size                    -1,-1
 332 packing                    Integer                 -1
 333 separation                 Integer                 -1
 334
 335 wxToolBar node may have children <object> and <object_ref> nodes. Their class
 336 may be either "tool", "separator" or any wxWindows class derived from
 337 wxControl. "tool" and "separator" are special pseudo-classes that may only
 338 appear within wxToolBar node. Their attributes are as follows:
 339
 340     separator
 341     ---------
 342     (doesn't have any attributes)
 343
 344     tool
 345     ----
 346     bitmap                 Bitmap
 347     bitmap2                Bitmap                  wxNullBitmap
 348     toggle                 Boolean                 0
 349     radio                  Boolean                 0
 350     label                  I18nString              ""
 351     tooltip                I18nString              ""
 352     longhelp               I18nString              ""
 353     position               Position                -1,-1
 354
 355     Constraints:
 356       At most one of "toggle" and "radio" attributes may be 1.
 357       Attribute "position" may not appear if "label" or "radio" attributes
 358       are used or if parent wxToolBar's style contains wxTB_TEXT.
 359
 360     Note:
 361       Use of "position" attribute is strongly discouraged, it is deprecated
 362       usage of wxToolBar and it is not supported by MSW and GTK
 363       implementations.
 364
 365 Children objects are added to the toolbar using AddTool for "tool" class,
 366 AddSeparator for "separator" and AddControl for other classes.
 367
 368
 369
 370 5. More features
 371 ================
 372
 373 FIXME -- "platform" property handling
 374
 375
 376 === EOF ===
 377
 378 Version: $Id$