diff --git a/docs/tech/tn0014.txt b/docs/tech/tn0014.txt index e837e8554d..fa6c05add7 100644 --- a/docs/tech/tn0014.txt +++ b/docs/tech/tn0014.txt @@ -4,7 +4,7 @@ !!!!! NOT YET FINISHED !!!!! 0. Introduction ---------------- +=============== This note describes the file format used for storing XRC resources that are used by wxXmlResource class. It is probably only useful for those implementing @@ -21,32 +21,40 @@ is no DTD available since it is not possible to fully describe the format with the limited expressive power of DTDs. + 1. Terminology --------------- +============== The usual XML terminology applies. In particular, we shall use the terms -"node", "property" and "value" in the XML sense: +NODE, PROPERTY and VALUE in the XML sense: ... -The term "attribute" is specific to XRC and refers to a property-less subnode -of an or node. In the example bellow, , +ATTRIBUTE VALUE is the content of all text elements within attribute tag. In the +above example, "wxSUNKEN_BORDER", "A label" and "10,10" are attribute values. +ATTRIBUTE TYPE defines what attribute values are valid for given attribute (you +can think of it as attribute value syntax definition). + + 2. Elementary description -------------------------- +========================= XRC resource file is a well-formed XML 1.0 document. All elements of XRC file are from the http://www.wxwindows.org/wxxrc namespace. @@ -126,15 +134,133 @@ is identical to: -3. Common attributes --------------------- -TODO +3. Common attribute types +========================= + +There are several attribute types (see section 1. Terminology) that are common +to many attributes of different classes: + +String +------ +Any text. Some characters have special interpretation and are translated +by XRC parser according to this table: + "_" -> "&" ('&' is used to underline e.g. menu items in wxWindows) + "__" -> "_" + "\n" -> line break (C character '\n') + "\r" -> carriage return (C character '\r') + "\t" -> tabelator (C character '\t') + +Version Note: + '$' was used instead of '_' prior to version 2.3.0.1. + + +I18nString +---------- +Like String, but the value is translated to native language using wxLocale +at runtime (unless it was disabled by not passing wxXRC_USE_LOCALE flag to +wxXmlResource constructor). Used for strings that are "visible" in the GUI. + + +UnsignedInteger +--------------- +This is obvious. Only digits 0-9 may be present and there must be at least +one digit. + + +Integer +------- +Like UnsignedInteger but may be prefixed with '-' (ints less than zero). + + +Position +-------- +Specifies (window's) position in 2D space. Syntax is ,[d] +where is valid value of Integer type. + + +Size +---- +Syntax is same as Position's syntax, but the values are interpreted as window +size (wxSize type) and not position (wxPosition type). + + +Style[wxSomeClass] +------------------ +List of style flags that can be passed to wxSomeClass' constructor. Flags are +written in same way as in C++ code (e.g. "wxSUNKEN_BORDER", "wxHW_SCROLLBAR_NEVER") +and are delimined with any combination of whitespaces and '|'. Possible flags +are class-dependent and are not described in this technote. Please refer to wxWindows +manual for all styles that given class can accept; if XRC does not accept a flag +listed in wxWindows documentation, it is a bug. + + +Bitmap +------ +Attribute value is interpreted as filename (either absolute or relative to +the location of XRC resource file). In addition, attribute node may have +"stock_id" and "stock_client" properties. Their values may be any of wxArtID (or +wxArtClient respectively) values as used by wxArtProvider (because the user may +define own constants, efectively any string is legal here). Examples are +"wxART_FILE_OPEN" (id) or "wxART_MENU" (client). + +Any of "stock_id" or "stock_client" properties or the filename may be omitted. XRC +determines the bitmap to use according to this algorithm: + 1. If there is non-empty "stock_id" property, query wxArtProvider for the bitmap + (if there is no "stock_client", use default one, which is usually wxART_OTHER; + exceptions are noted in class-specific sections bellow). If the query fails, + continue to 2. + 2. Load the bitmap from the file in attribute value. + + 4. Supported classes --------------------- +==================== + +Attributes are listed in tables in the following format: +attribute name attribute type default value, if any + [(optional remarks.................... + ...................................)] + +wxBitmap +-------- +This is a special case, because it does not create a wxWindow instance but +creates wxBitmap instead. Another exceptional thing is that it does not have +any attributes. Instead, the node itself is interpreted as if it were attribute +of type Bitmap. + +Example: bitmaps/foo.gif + + +wxIcon +------ +Identical to wxBitmap class, except that it creates wxIcon instead of wxBitmap. + + +wxButton +-------- +position Position -1,-1 +size Size -1,-1 +style Style[wxButton] + +label I18nString +default Boolean false + (Is the button default button?) + + +wxCalendarCtrl +-------------- +position Position -1,-1 +size Size -1,-1 +style Style[wxButton] + + + +5. More features +================ + +FIXME -- "platform" property handling -TODO === EOF ===