#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{tabular}{ccc} & 
\backslash
textbf{wxGTK and wxMSW} & 
\backslash
textbf{wxMac}
\backslash

\backslash

\end_layout

\begin_layout Standard

Tool button & Ctrl & Alt
\backslash

\backslash

\end_layout

\begin_layout Standard

Pulldown menu & Ctrl & Alt
\backslash

\backslash

\end_layout

\begin_layout Standard

Ctrl+V or Control+V shortcut & Alt & Alt
\backslash

\backslash

\end_layout

\begin_layout Standard


\backslash
end{tabular} 
\end_layout

\end_inset


\end_layout

\begin_layout Section
Defining attributes
\end_layout

\begin_layout Standard
Attributes are edited using the attribute panel.
 The upper part has the class field and, if applicable, the object 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

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

Style
\begin_inset Quotes erd
\end_inset

 with styles grouped in two columns - 
\series bold
Generic
\series default
 and 
\series bold
Specific,
\series default
 then there may be 
\begin_inset Quotes eld
\end_inset

ExStyle
\begin_inset Quotes erd
\end_inset

 page for extra styles and if there is a hidden node a page with its attributes.
\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 Section
Component plugins
\end_layout

\begin_layout Standard
Each interface element available in XRCed is defined using a component plugin.
 This permits easy extension to include new XRC format features and classes
 and using custom application-specific components.
\end_layout

\begin_layout Standard
A component plugin is actually a (singleton) object of 
\series bold
Component
\series default
 class or one of derived classes, containing the data essential for constructing
 the visual interface for editing element attributes and defining its behaviour
 with respect to other components.
 Components must be registered with the component manager 
\series bold
Manager
\series default
 object.
\end_layout

\begin_layout Subsection*
Defining component plugins
\end_layout

\begin_layout Standard
There are two ways to define component plugins.
\end_layout

\begin_layout Itemize
Creating an object of one of component classes in a Python module (optionally
 defining a new class if a specific behaviour which cannot be provided by
 the standard classes) is needed.
 XRCed looks in standard 
\family typewriter
plugins
\family default
 directory (in 
\family typewriter
XRCed
\family default
 installation directory) and in each of the directories in 
\family typewriter
XRCEDPATH
\family default
 environment variable.
 It tries to import all Python files, except with names starting with underscore
 ('_').
 It then looks in sub-directories which contain 
\family typewriter
__init__.py
\family default
 and imports them using *-mode (so it's possible to group plugins by directory
 without listing too many in 
\family typewriter
XRCEDPATH
\family default
).
\end_layout

\begin_layout Itemize
Another option to define a plugin is to use an XML 
\emph on
manifest
\emph default
 file.
 This can be used for simple plugins which do not require defining new component
 classes or component groups.
 The structure of this CRX file is very similar to a flat XRC file having
 only top-level nodes defined using 
\series bold
component
\series default
 tag instead of 
\series bold
object
\series default
 (that's why it is called CRX and uses .crx extention).
 This is done so that CRX files can be edited using XRCed, if you don't
 want to edit XML by hand.
 A special command-line options 
\family typewriter
-m
\family default
 or 
\family typewriter
--meta
\family default
 should be used when starting XRCed to include support for so-called 
\emph on
meta-components.
 
\emph default
Attributes of meta-components correspond to the constructor parameters of
 Component classes (class name must be one of known component classes).
 It is possible to include normal interface elements in the same CRX file,
 for easy testing of new plugins.
\end_layout

\begin_layout Standard
Please refer to the wxPyWiki documentation for further information and examples
 about component plugins.
\end_layout

\end_body
\end_document