#LyX 1.5.1 created this file. For more info see http://www.lyx.org/
\lyxformat 276
\begin_document
\begin_header
\textclass article
\language english
\inputencoding auto
\font_roman default
\font_sans default
\font_typewriter default
\font_default_family default
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100
\graphics default
\paperfontsize default
\spacing single
\papersize default
\use_geometry false
\use_amsmath 1
\use_esint 0
\cite_engine basic
\use_bibtopic false
\paperorientation portrait
\secnumdepth 2
\tocdepth 2
\paragraph_separation indent
\defskip medskip
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\author "" 
\author "" 
\end_header

\begin_body

\begin_layout Standard
\begin_inset LatexCommand tableofcontents

\end_inset


\end_layout

\begin_layout Title
XRCed Manual
\end_layout

\begin_layout Date
Roman Rolinsky <genericsoma@gmail.com>
\end_layout

\begin_layout Section*
Introduction
\end_layout

\begin_layout Standard
XRCed is a resource editor for editing XRC resource files used in wxWidgets
 or wxPython.
 XRC is an XML-based format for describing the layout of the interface.
 When a XRC file it being parsed in the application (using wxXmlResource
 class), objects corresponding to the interface elements defined in .xrc
 file are created and can be immediately used.
 Please refer to the corresponding documentation depending on your language
 for details.
 XRC files are actually normal text files.
 Structure of an XML file is defined by a hierarchy of 
\emph on
nodes,
\emph default
 each node is delimited by a pair of 
\emph on
tags
\emph default
 in a similar manner to HTML format.
 XRC format uses a special 
\family typewriter
object
\family default
 tag for defining interface element nodes, which can contain a number of
 
\emph on
attribute
\emph default
 nodes with tag names corresponding to the attribute names, e.g.
 
\family typewriter
<pos>100,100</pos>
\family default
.
 Object nodes always have XML attribute 
\begin_inset Quotes eld
\end_inset

class
\begin_inset Quotes erd
\end_inset

 defined, e.g.
 
\family typewriter
<object class='wxFrame'>
\family default
.
\end_layout

\begin_layout Section
Getting started
\end_layout

\begin_layout Standard
XRCed interface contains these components:
\end_layout

\begin_layout Description
XML\InsetSpace \space{}
tree a tree representing the structure of the resource file.
\end_layout

\begin_layout Description
Attribute\InsetSpace \space{}
panel a panel with the information about the currently selected
 tree item.
 Class and object name is shown in the upper part and a notebook with a
 number of pages is shown below for editing object's attributes.
\end_layout

\begin_layout Description
Pull-down\InsetSpace \space{}
menu is shown when a used right-clicks inside the tree control.
 Is is used for creating new elements and basic operations such as copy/paste.
\end_layout

\begin_layout Description
Component\InsetSpace \space{}
panel is a graphical menu for creating new elements by clicking
 on icons or by dragging them on the test window.
\end_layout

\begin_layout Description
Test\InsetSpace \space{}
window can be shown for an already existing part of the resource tree
 to see the resulting appearance of the interface.
\end_layout

\begin_layout Standard
Using XRCed is easy once you understand some basic principles.
 First of all, it is using a structure-oriented tree-based editing technique,
 versus point-and-click method used in most GUI builders.
 The tree is actually almost a direct respresentation of the hierarchy of
 
\emph on
object
\emph default
 nodes in XRC file.
 More precisely, only the nodes corresponding to visible interface elements
 are shown.
 An example of an object node which is not an interface element is the sizeritem
 node.
 
\end_layout

\begin_layout Standard
XRCed tries hard to make accessible the full information contained in XRC
 file, so even the nodes which are not shown in the tree must be represented.
 This is done by adding their property pages to the attribute panel.
\end_layout

\begin_layout Standard
Secondly, creating new elements is context-dependent.
 The new elements are inserted in the tree relative to the current selection
 (except for drag-and-drop mode when the place is determined dynamically).
 Sometimes there is an ambiguity on the exact position, because some elements
 are 
\emph on
containers
\emph default
 which can have children, but it may be needed to create the new element
 as a sibling node instead of a child.
 Sibling mode can be forced by holding 
\series bold
Ctrl
\series default
 key on wxGTK/wxMSW or 
\series bold
Alt
\series default
 key on wxMac when inserting a new element.
 Similarly, a new element can be inserted as the first child of a container
 by holding 
\series bold
Shift
\series default
 key (default is to append it as the last child).
\end_layout

\begin_layout Section
Tree editing
\end_layout

\begin_layout Standard
When you create a new interface element it is attached at some point to
 the existing XML tree.
 The root node of the tree is created automatically and has only one attribute
 - the encoding.
 Root is not shown in the tree control (to save space), so its attributes
 are visible when no other elements are selected.
 
\end_layout

\begin_layout Standard
As explained in the previous section, the new elements can be put in different
 locations relative to the parent element.
 What to do if the initial location is not correct, or should be changed
 in the development process? There two ways to re-arrange elements:
\end_layout

\begin_layout Enumerate
Cut some element, then select the new parent or sibling and paste at the
 new location.
 Modifier keys can be used in the same way as for creating to alter the
 default paste behaviour when using the pull-down command or the tool button
 (pasting by using the keyboard shortcut is always using the default way).
\end_layout

\begin_layout Enumerate
Use one of the 
\begin_inset Quotes eld
\end_inset

Move
\begin_inset Quotes erd
\end_inset

 menu or toolbar commands to swap elements or change their parent/child
 configuration.
 If a move tool button is disabled, this means that it does not make sense
 to do that kind of move due to incompatible parent/child configuration.
\end_layout

\begin_layout Standard
When you cut a subtree, all elements are cut to the clipboard and will be
 pasted to the new location in the same configuration.
 On some platforms the clipboard is shared among different processes, so
 it is possible to start a second copy of XRCed and copy parts of one tree
 into another.
\end_layout

\begin_layout Subsection*
Hidden nodes
\end_layout

\begin_layout Standard
Normally one tree element corresponds to a single <object> tag.
 Sometimes it makes sense to associate contents of some <object> tags to
 element attributes related to the parent.
 A common example is a sizer object, which uses 
\series bold
sizeritem
\series default
 objects, which have a single child (a control or another sizer).
 For such simple objects an attribute page is added to the child element
 attributes.
 The side-effect of this when copying a child from one parent's subtree
 into a subtree of a parent of a different class, is that the hidden node
 attributes must be discarded.
 This is done automatically.
\end_layout

\begin_layout Subsection*
Cut/Copy/Paste
\end_layout

\begin_layout Standard
To accelerate your workflow it may be very useful to use keyboard shortcuts.
 XRCed supports standard editing shortcuts for cut/copy/paste commands.
 Pasting operation depends on the state of additional modifier keys to select
 the desired pasting location relative to the active tree selection, in
 a way similar to creating new nodes.
 
\series bold
Shift
\series default
 modifier can be used with the toolbar Paste button or tree pulldown menu
 to activate 
\begin_inset Quotes eld
\end_inset

insert
\begin_inset Quotes erd
\end_inset

 mode.
 To activate sibling mode on wxGTK/wxMSW, 
\series bold
Ctrl
\series default
 or 
\series bold
Alt
\series default
 modifier is used depending on the platform and the way of introducing Paste
 command:
\end_layout

\begin_layout Standard
\begin_inset ERT
status open

\begin_layout Standard


\backslash
begin{verbatim}
\end_layout

\begin_layout Standard

                           wxGTK and wxMSW  wxMac
\end_layout

\begin_layout Standard

-------------------------------------------------
\end_layout

\begin_layout Standard

Tool button                     Ctrl         Alt 
\end_layout

\begin_layout Standard

Pulldown menu                   Ctrl         Alt 
\end_layout

\begin_layout Standard

Ctrl+V/Control+V shortcut       Alt          Alt
\end_layout

\begin_layout Standard


\backslash
end{verbatim}
\end_layout

\end_inset


\end_layout

\begin_layout Section
Defining attributes
\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Standard
\begin_inset ERT
status open

\begin_layout Standard


\backslash
image{}{attpanel.png}
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
Attribute panel
\end_layout

\end_inset


\begin_inset LatexCommand label
name "fig:attpanel"

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
Attributes are edited using the attribute panel (Figure 
\begin_inset LatexCommand ref
reference "fig:attpanel"

\end_inset

).
 The upper part contains the class name field and, if applicable, the element
 name field.
 Lower part contains a notebook with one or several pages.
 Normally the first page contains the main attributes, the second is 
\begin_inset Quotes eld
\end_inset

Look'n'Feel
\begin_inset Quotes erd
\end_inset

 page containing visual behaviour attributes such as font, colors, etc.,
 the third is 
\begin_inset Quotes eld
\end_inset

Style
\begin_inset Quotes erd
\end_inset

 page with styles grouped in two columns - 
\series bold
Generic
\series default
 and 
\series bold
Specific, 
\series default
in addition some elements may have 
\begin_inset Quotes eld
\end_inset

ExStyle
\begin_inset Quotes erd
\end_inset

 page for defining extra styles and if there is a hidden node (such as for
 sizer items or notebook pages) a page with hidden node attributes is shown,
 named correspondingly.
\end_layout

\begin_layout Subsection*
Changing object's class
\end_layout

\begin_layout Standard
There are two ways to change the class of an element: by editing 
\begin_inset Quotes eld
\end_inset

class:
\begin_inset Quotes erd
\end_inset

 field in the attributes panel or by using 
\begin_inset Quotes eld
\end_inset

Replace With
\begin_inset Quotes erd
\end_inset

 pulldown menu command.
 XRCed tried to preserve all attributes compatible with the new class.
\end_layout

\begin_layout Section
Test window
\end_layout

\begin_layout Standard
Test view is created simply by loading a part of the resource file using
 XRC library, so it should look the same as in your application (without
 the contents and changes performed by the program, of course).
 There are elements which cannot be tested individually, but only as a part
 of a subtree.
\end_layout

\begin_layout Standard
\begin_inset Quotes eld
\end_inset

Test
\begin_inset Quotes erd
\end_inset

 command (View>Test or 
\begin_inset Quotes eld
\end_inset

radioactive sign
\begin_inset Quotes erd
\end_inset

 tool or F5) creates a view of the selected element or subtree.
 If a top-level element (such as wxDialog) is selected, it is normally created
 as a top-level window.
 When the selected element cannot be a top-level window, a miniframe is
 created and the test view is put inside.
 Currenly shown parent element is made bold in the tree control while the
 test window is opened.
\end_layout

\begin_layout Standard
It is possible to select an element by clicking on it in the test window
 after activating the 
\begin_inset Quotes eld
\end_inset

Locate
\begin_inset Quotes erd
\end_inset

 command.
 While the test window is open, it is possible to create new elements by
 dragging a Component icon on the test window.
 The parent element is highlighted by a blue box.
\end_layout

\begin_layout Subsection*
Auto-refresh mode
\end_layout

\begin_layout Standard
When auto-refresh is activated, any changes made to the attibutes or the
 tree structure of the currently selected test subtree provoke test window
 refresh (reload from the updated resource).
 Sometimes it may be prefered to freeze the test window while making modificatio
ns by deactivating auto-refresh (from the View menu or using Alt+A keyboard
 shortcut).
 To force a refresh, press Ctrl+R or select View>Refresh command.
\end_layout

\begin_layout Subsection*
Highlighting
\end_layout

\begin_layout Standard
Selected elements are highlighted with red lines in the test window.
 For sizers and sizer children in addition to the element bounding box XRCed
 draws some additional lines showing border widths.
\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Standard
\begin_inset ERT
status open

\begin_layout Standard


\backslash
image{}{hl-sizer.png}
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
Highlighting for a box sizer
\end_layout

\end_inset


\begin_inset LatexCommand label
name "fig:hl-sizer"

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Standard
\begin_inset ERT
status open

\begin_layout Standard


\backslash
image{}{ex1-tree.png}
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
XML tree
\end_layout

\end_inset


\begin_inset LatexCommand label
name "fig:ex1-tree"

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
Figure 
\begin_inset LatexCommand ref
reference "fig:hl-sizer"

\end_inset

 shows how a box sizer is highlighted.
 The tree view for this example is shown on Figure 
\begin_inset LatexCommand ref
reference "fig:ex1-tree"

\end_inset

.
 The top sizer (which is selected) is highlighted with a 2-pixel darker
 box, and its children (wxBoxSizer and wxStdDialogButtonSizer) are highlighted
 with 1-pixel lighter boxes.
 Lines sticking out of the wxStdDialogButtonSizer indicate that it has borders
 on all sides.
 Finally, the horizontal line drawn across the wxBoxSizer indicates that
 it has wxEXPAND flag set.
 
\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Standard
\begin_inset ERT
status open

\begin_layout Standard


\backslash
image{}{hl-control.png}
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
Highlighting for a control inside a sizer
\end_layout

\end_inset


\begin_inset LatexCommand label
name "fig:hl-control"

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
Figure 
\begin_inset LatexCommand ref
reference "fig:hl-control"

\end_inset

 shows how a control inside a sizer (the wxTextCtrl object) is highlighted:
 only the bounding box and borders are drawn.
\end_layout

\begin_layout Standard
When auto-refresh is off, the highlight follows selection until the tree
 structure is modified.
 To re-activate highlighting again Refresh command must be used.
\end_layout

\begin_layout Standard
In addition to the active selection highlighting, when using drag-and-drop
 to place new elements on the test window, an element serving as a reference
 for the new element is highlighted with a blue rectangle.
 The new element will be appended as a child or a next sibling of the reference
 element depending if it is a container or not and the state of the modifier
 key.
\end_layout

\end_body
\end_document