XML resources file format =============================== 1. Basics ----------- XML resource is well-formed XML document, i.e. all tags are paired and there is only one root node, which is always <resource>. In the following text, I will use standard XML terminology: <tag_one prop1="prop" prop2='yes'> <tag_two/> </tag_one> Here, tag_one is a node (the word 'tag' refers to the type of the node), prop1 and prop2 are properties and tag_two is a child node of tag_one. Property's default value is the value that will be assigned to the property if you do not specify it explicitly. I will use the term "primary node" to refer to nodes than represent controls, dialogs etc. "Secondary nodes" are nodes used to store data: <dialog name="my_dlg"> primary <title>Demo Dialog...</title> secondary <size>100,200d</size> secondary <children> secondary <button name="wxID_OK"> primary <label>Ok</label> secondary <pos>10,10d</pos> secondary </button> </children> </dialog> In the example above, <label>, <pos>, <size> and <title> are "variables", i.e. they contain a value and not a list of children (unlike <children> node). Any node (but the root one) may have property "platform" with possible values "unix", "win", "mac" or "os2". All nodes with "platform" property specified and other than the platform the program is currently being executed on will be removed when reading XML resource file. Root node may have children of these and only these types: <menu>, <menubar>, <dialog>, <panel> 2. IDs -------- Any primary node may have property "name" used to identify it. Default value is "-1", any string is legal name. Names wxID_OPEN, wxID_CLOSE, wxID_NEW, wxID_SAVE, wxID_SAVEAS, wxID_REVERT, wxID_EXIT, wxID_UNDO, wxID_REDO, wxID_HELP, wxID_PRINT, wxID_PRINT_SETUP, wxID_PREVIEW, wxID_ABOUT, wxID_HELP_CONTENTS, wxID_HELP_COMMANDS, wxID_HELP_PROCEDURES, wxID_CUT, wxID_COPY, wxID_PASTE, wxID_CLEAR, wxID_FIND, wxID_DUPLICATE, wxID_SELECTALL, wxID_OK, wxID_CANCEL, wxID_APPLY, wxID_YES, wxID_NO, wxID_STATIC, wxID_FORWARD, wxID_BACKWARD, wxID_DEFAULT, wxID_MORE, wxID_SETUP, wxID_RESET, wxID_HELP_CONTEXT are translated into corresponding wxWindows ID constant, XMLID macro is used otherwise to generate unique ID. wxWindows control created from named node will have name=name and id=XMLID(name) or wxID_XXXX. 3. Common variables types --------------------------- Variables are always of a known type: bool - boolean value. "1", "true", "t", "on" mean TRUE, anything else (namely "0", "false", "f", "off") means FALSE. FIXME: maybe use only 1/0 ?? integer - integer value, i.e. digits 0-9 plus optional minus sign. text - anything. Within text node all occurences of $ are replaced by & (used for shortcuts, e.g. "E&xit"), $$ by $, \\, \n, \r, \t as usual in C++. style - (also called flags) list of flags delimined by any combination of spaces and | characters. Resources parser accepts only _registered_ flags -- i.e. flags that are valid for given node/control. Example: <flag>wxEXPAND | wxTOP|wxBOTTOM</flag> color - color in HTML format: #rrggbb where rr,gg,bb are hexadecimal values (00-FF) for red, green and blue components in the RGB color model coord - size or position information. Consists of two integers separated by comma ("x,y"). The values are in pixels unless "d" is attached to the right side of it -- in which case the values are interpreted as dialog units. Value of -1 means "use default". Examples: 30,30 -1,-1 50,-1 145,56d 67,-1d 4. Layout ----------- Most common nodes layout is as follows: <primary_node name="name" platform="platform"> <var_1>...</var_1> . . . <var_n>...</var_n> <children> (n primary nodes) </children> </primary_node> where children node is supported only by panels, dialogs etc. -- see nodes description for details. In the following text, TYPE var_name [ (= default_value) ] means that given primary node may have child node with name var_name and content type TYPE. If default value is given, the node is optional and default_value will be used if not specified. Otherwise, the node is mandatory and must always be present. For example, "color fg" means than variable tag fg, e.g. <fg>#rr0000</fg> is expected. 5. Common controls variables ------------------------------ _All_ nodes that represent wxWindows controls (gauge, panel, dialog, textctrl etc.) accept the following properties: coord pos (= -1,-1) position of the control. Default value equals to wxDefaultPosition coord size (= -1,-1) size of the control. Default value equals to wxDefaultSize text tooltip window's tooltip color bg background color of the control color fg foreground/text color of the control style style control style flag. Default value is control-dependent (but 0 is common value) style exstyle control extended style flag bool enabled (= 1) is the control enabled? bool hidden (= 0) is the control hidden? bool focused (= 0) has the control focus? _Usually_ (but not always, only when it makes sense) controls support text variable label which contains displayed text and/or value which contains editable text. These are always explicitly mentioned in tag description. 6. Tags description --------------------- If 'Control' is derived from wxControl, it supports all variables from '5.' 'Styles' section lists all acceptable flags for style and exstyle variables. <panel> --------- Control: wxPanel Variables: only common controls variables Styles: wxNO_3D, wxTAB_TRAVERSAL, wxWS_EX_VALIDATE_RECURSIVELY <dialog> ---------- Control: wxDialog Variables: style style (= wxDEFAULT_DIALOG_style) text title dialog's title Styles: wxSTAY_ON_TOP, wxCAPTION, wxDEFAULT_DIALOG_style, wxTHICK_FRAME, wxSYSTEM_MENU, wxRESIZE_BORDER, wxRESIZE_BOX, wxDIALOG_MODAL, wxDIALOG_MODELESS, wxNO_3D, wxTAB_TRAVERSAL, wxWS_EX_VALIDATE_RECURSIVELY <boxsizer> -------------- Control: wxBoxSizer (not a control) Behaviour: boxsizer's parent must be either <panel>, <dialog> or another sizer, nothing else! If the sizer does not have parent sizer, the sizer will attach itself to the parent panel/dialog using SetAutoLayout(TRUE) and SetSizer(). If the parent panel/dialog has default size (i.e. not specified in the resource), the sizer will fit it using wxSizer::Fit(). If the parent panel/dialog is resizable, size hints will be set automatically. Variables: style orient (= wxHORIZONTAL) orientation, either wxHORIZONTAL or wxVERTICAL Styles: wxHORIZONTAL, wxVERTICAL (for orient variable) wxLEFT, wxRIGHT, wxTOP, wxBOTTOM, wxNORTH, wxSOUTH, wxEAST, wxWEST, wxALL, wxGROW, wxEXPAND, wxSHAPED, wxSTRETCH_NOT, wxALIGN_CENTER, wxALIGN_CENTRE, wxALIGN_LEFT, wxALIGN_TOP, wxALIGN_RIGHT, wxALIGN_BOTTOM, wxALIGN_CENTER_HORIZONTAL, wxALIGN_CENTRE_HORIZONTAL, wxALIGN_CENTER_HORIZONTAL, wxALIGN_CENTRE_HORIZONTAL (for flag variable of <item> or <spacer> child nodes) Child nodes: Contains child node <children> which has arbitrary number of <sizeritem> and <spacer> child nodes. <sizeritem> ------------- Variables: integer option (= 0) relative size of the widget style flag (= 0) style flag integer border (= 0) surrounding border Has exactly one child node <window> that contains the control (or child sizer because sizers may be nested) to be inserted into the sizer. <spacer> ---------- Variables: integer option (= 0) relative size of the widget style flag (= 0) style flag integer border (= 0) surrounding border Inserts empty space into the sizer <staticboxsizer> ------------------ Control: wxStaticBoxSizer (not a control) Same as <boxsizer> except that it has additional variable: text label (= "") label of surrounding static box wxStaticBox required by wxStaticBoxSizer is created automatically! <notebooksizer> ----------------- Control: wxNotebookSizer (not a control) Behaviour: notebooksizer's parent must be a sizer (not notebooksizer, see below)! Variables: none Styles: none Child nodes: Has exactly one child node <window> that contains the notebook (nothing else is allowed!) to be inserted into the sizer. <textctrl> ------------ Control: wxTextCtrl Variables: text value (= "")default text of the control Styles: wxTE_PROCESS_ENTER, wxTE_PROCESS_TAB, wxTE_MULTILINE, wxTE_PASSWORD, wxTE_READONLY, wxHSCROLL <htmlwindow> -------------- Control: wxHtmlWindow Variables: integer borders (= 0) window's borders (see wxHtmlWindow::SetBorders) text url (= "") if present, given page will be loaded text htmlcode (= "") if present, given _text_ will be displayed (you will have to use CDATA section to embed HTML code into XML document) Styles: wxHW_SCROLLBAR_NEVER, wxHW_SCROLLBAR_AUTO