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