some more XRC docs

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/branches/WX_2_4_BRANCH@17500 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

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:
 
     <node property1="value1" property2="value2">...</node>
 
-The term "attribute" is specific to XRC and refers to a property-less subnode 
+The term ATTRIBUTE is specific to XRC and refers to a subnode 
-of an <object> or <object_ref> node. In the example bellow, <pos>, <label> and
+of an <object> or <object_ref> node that is itself not <object> or <object_ref>. 
-<style> are attributes, while neither <resource> nor either of <object>s is:
+In the example bellow, <pos>, <label> and <style> are attributes, while neither 
+<resource> nor either of <object>s is:
 
     <?xml version="1.0" encoding="utf-8">
     <resource xmlns="http://www.wxwindows.org/wxxrc" version="2.3.0.1">
         <object class="wxPanel">
-            <style>wxSUNKEN_BORDER</style>
+            <style>wxSUNKEN_BORDER</style>             <!-- attr -->
             <object class="wxStaticText">
-                <label>A label</label>
+                <label>A label</label>                 <!-- attr -->
-                <pos>10,10</pos>
+                <pos>10,10</pos>                       <!-- attr -->
             </object>
         </object>
     </resource>
 
+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:
     </object>
 
 
-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 <integer>,<integer>[d]
+where <integer> 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: <object class="wxBitmap">bitmaps/foo.gif</object>
+
+
+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 ===