utils/dialoged/docs/body.tex

   1 \chapter{Introduction}\label{introduction}
   2 \pagenumbering{arabic}%
   3 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
   4 \setfooter{\thepage}{}{}{}{}{\thepage}%
   5
   6 The wxWindows Dialog Editor is a tool for creating dialog resource files, in {\tt .wxr} format.
   7 It differs from wxBuilder in the following respectes:
   8
   9 \begin{enumerate}\itemsep=0pt
  10 \item Scope. It is written for dialog editing only, and is therefore more convenient than wxBuilder for this purpose.
  11 \item File format. Dialog editor reads and writes wxWindows resource files (extension {\tt .wxr}) and has
  12 no independent file format.
  13 \item Robustness. It is written in a more principled way than wxBuilder, and is less ambitious.
  14 \item Ease of use. Windows are edited using the mouse or via consistent {\it property editors}, which
  15 provide immediate visual feedback of changed properties.
  16 \end{enumerate}
  17
  18 Dialog Editor 2.0 should be compiled and used with wxWindows 2.0.
  19
  20 \section{Current status}
  21
  22 Dialog Editor currently runs under wxMSW and wxGTK. It has yet to
  23 be tested under wxMotif.
  24
  25 \section{Future developments}
  26
  27 \begin{itemize}\itemsep=0pt
  28 \item Motif compilation.
  29 \item It would be nice to have a dialog browser, showing thumbnails of
  30 all dialogs in a particular directory.
  31 \item Maybe add a menubar editor (from wxBuilder).
  32 \item Maybe convert Windows .rc files.
  33 \end{itemize}
  34
  35 \chapter{Commands}\label{commands}
  36 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
  37 \setfooter{\thepage}{}{}{}{}{\thepage}%
  38
  39 \section{Dialog editor menu bar}
  40
  41 \subsection{File menu}
  42
  43 \begin{twocollist}\itemsep=0pt
  44 \twocolitem{New dialog}{Creates a new dialog resource.}
  45 \twocolitem{New project}{Creates a new project (clears index and resets project name).}
  46 \twocolitem{Open}{Opens an existing resource file.}
  47 \twocolitem{Save}{Saves the current resources.}
  48 \twocolitem{Save As...}{Saves the current resources in a named file.}
  49 \twocolitem{Clear}{Clears the current resources.}
  50 \twocolitem{Exit}{Exits the program.}
  51 \end{twocollist}
  52
  53 \subsection{Edit menu}
  54
  55 \begin{twocollist}\itemsep=0pt
  56 \twocolitem{Test Dialog}{Creates the current dialog for test purposes.}
  57 \twocolitem{Recreate}{Recreates the currently selected control from the underlying resource. This may be necessary
  58 to regenerate items that cannot be changed dynamically, and which have got out of sync with the displayed
  59 item.}
  60 \twocolitem{Delete}{Deletes the currently selected resource.}
  61 \end{twocollist}
  62
  63 \subsection{Help menu}
  64
  65 \begin{twocollist}\itemsep=0pt
  66 \twocolitem{Help topics}{Displays on-line help at the contents page.}
  67 \twocolitem{About}{Displays an dialog showing the Dialog Editor version and author.}
  68 \end{twocollist}
  69
  70 \latexonly{\newpage}
  71 \section{Command toolbar}
  72
  73 The command toolbar consists of the following tools:
  74
  75 \begin{twocollist}%\itemsep=0pt
  76 \twocolitem{\icon{new.eps}{New}}{Clears the project.}
  77 \twocolitem{\icon{open.eps}{Open}}{Opens an existing resource file.}
  78 \twocolitem{\icon{save.eps}{Save}}{Saves the current resources.}
  79 \twocolitem{\icon{vert.eps}{Horizontal align}}{Aligns the centre of the selected items horizontally.}
  80 \twocolitem{\icon{alignt.eps}{Horizontal top-align}}{Aligns the top sides of the selected items horizontally.}
  81 \twocolitem{\icon{alignb.eps}{Horizontal bottom-align}}{Aligns the bottom sides of the selected items horizontally.}
  82 \twocolitem{\icon{horiz.eps}{Vertical align}}{Aligns the centre of the selected items vertically.}
  83 \twocolitem{\icon{alignl.eps}{Vertical left-align}}{Aligns the left sides of the selected items vertically.}
  84 \twocolitem{\icon{alignr.eps}{Vertical right-align}}{Aligns the right sides of the selected items vertically.}
  85 \twocolitem{\icon{copysize.eps}{Copy size}}{Copies the size of the first selected item to the subsequently selected item(s).}
  86 \twocolitem{\icon{tofront.eps}{To front}}{Puts the selected item(s) to the front of the display list.}
  87 \twocolitem{\icon{toback.eps}{To back}}{Puts the selected item(s) to the back of the display list.}
  88 \twocolitem{\icon{help.eps}{Help}}{Invokes Dialog Editor help.}
  89 \end{twocollist}
  90
  91 \latexonly{\newpage}
  92 \section{Tool palette}
  93
  94 The tool palette is used to select a type of control to create on the dialog.
  95 To create a new control, select a tool with left-click, then left-click on the dialog.
  96 Select the pointer tool to use left-click for selecting and deselecting
  97 items.
  98
  99 \section{Resource tree}
 100
 101 The resource tree shows a list of the dialogs, controls and bitmaps currently loaded
 102 in Dialog Editor. Double-clicking on an item shows the associated resource.
 103
 104 \chapter{Procedures}\label{procedures}
 105 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
 106 \setfooter{\thepage}{}{}{}{}{\thepage}%
 107
 108 \section{Running Dialog Editor}
 109
 110 To run Dialog Editor under Windows, click on the Program Manager or Explorer icon.
 111 Under UNIX, run from the command line.
 112
 113 The main window shows a menu bar, command toolbar, tool palette, resource list, and
 114 status line.
 115
 116 \section{Creating a dialog}
 117
 118 To create a new dialog, click on the {\bf File: New} menu item, or equivalent
 119 toolbar button. A dialog will appear. To put a control on the dialog, left-click
 120 on the appropriate palette icon and then left-click on the dialog. A new item
 121 will appear at the place you clicked.
 122
 123 You can edit any control or dialog by control-left clicking. A property editor
 124 will appear, allowing any property to be selected and edited (see \helpref{Using property editors}{propeditors}).
 125 You can also edit items by right-clicking to show a menu, and then selecting {\it Edit properties}.
 126
 127 To move a control, drag the item with the left mouse button, or edit
 128 the position values in the property editor. To resize a control, you
 129 can either select it by left-clicking and then dragging on a selection
 130 handle, or edit the size values in the property editor.
 131
 132 You can delete items from the right-click menu, or by selecting the item and
 133 choosing {\bf Edit: Delete} from the menu bar.
 134
 135 \section{Using property editors}\label{propeditors}
 136
 137 Property editors consist of a list of properties and current values, plus controls at the top of
 138 the editor. If the property is of an appropriate type, you can edit the value directly in the
 139 text field, and confirm or cancel the value using the two buttons to the left of it.
 140 If the property has a predefined range of values, such as labelFontFamily, you can
 141 see a list of permissable values by clicking on the button labelled with an ellipsis symbol ({\bf ...}).
 142 This will show a listbox with possible values and current selection. You may also be able
 143 to cycle through values by double-clicking the value in the listbox.
 144
 145 Properties may have special editors appropriate to the type. Filename properties invoke
 146 the file selector, and properties containing list of user-definable strings use a
 147 string editor.
 148
 149 When you change a property value, this value is immediately reflected in
 150 the dialog or control.  If the item allows this value to be changed
 151 dynamically, the relevant wxWindows function will be called internally
 152 to effect the change.  If the value cannot be changed dynamically, the
 153 item will be destroyed and re-created, which means that there will be
 154 more flickering associated with some kinds of property changes than
 155 others.
 156
 157 \section{Saving and loading files}
 158
 159 Use {\it File: Save} and {\it File: Save as} or the equivalent toolbar button
 160 to save the current dialog(s) in a wxWindows resource file (extension {\tt .wxr}).
 161
 162 The {\tt .wxr} file can be used directly in a wxWindows program, if
 163 wxWindows resources have been enabled when building the wxWindows library.
 164 These files can be loaded dynamically, or included directly into program source
 165 with a \verb$#include$ directive. See the wxWindows user manual for further details.
 166
 167 \section{Working with identifiers}
 168
 169 Dialog Editor keeps track of identifiers in your resources, and reads and writes an include file of the
 170 form {\tt name.h} where 'name' is the root name of your {\tt .wxr} file. Dialog Editor
 171 knows about the predefined identifiers such as wxID\_OK.
 172
 173 When you create a dialog or control, the identifier is initially generated. When you
 174 edit the identifier via a property editor, you can choose a new name, such as a predefined
 175 symbol and optionally change the integer assigned to the name (assuming it's not a
 176 predefined symbol).
 177
 178 When you save the project, the identifier include file is saved as well. Include this file
 179 in your project so that you can refer to controls and dialogs by identifier rather than
 180 obscure integers. Note that the {\tt .wxr} file itself can only contain integer ids and not the symbols,
 181 due to way in which the resource file is loaded.
 182
 183 \section{Multi-platform development}
 184
 185 {\tt .wxr} files generated on one environment (e.g. Windows) can be used in another (e.g. GTK).
 186 If you use default fonts and colouring (set {\bf useSystemDefaults} to True in the dialog properties)
 187 then the dialog fonts and colours will take on the native values, rather than ones specified in the
 188 resource. Without this, colours in the dialog resource may not match system colours.
 189
 190 Also, set {\bf useDialogUnits} to True whenever possible since this will cause the dialog
 191 to be created using a scale based on the current system font size, and will result in dialogs that are
 192 portable between screen resolutions as well as platforms.
 193
 194 Because the same control can have different sizes on different GUIs,
 195 the user should be cautious in assuming that one resource file will work for all
 196 platforms. It may be better to plan to conditionally include or load different
 197 resource files for different platforms, with spacing modified to suit each
 198 environment. The best thing is to try your dialog resource on several platforms
 199 and see whether tweaking is required for some platforms.
 200