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 should be compiled and used with wxWindows 1.65 or later.
  19
  20 \section{Current status}
  21
  22 Dialog Editor currently runs under MS Windows. It has yet to
  23 be tested under Motif and XView: see \helpref{Technical notes}{technotes} for a discussion
  24 of what needs to be done.
  25
  26 \section{Future developments}
  27
  28 \begin{itemize}\itemsep=0pt
  29 \item XView and Motif versions.
  30 \item It would be nice to have a dialog browser, showing thumbnails of
  31 all dialogs in a particular directory.
  32 \item Maybe add a menubar editor (from wxBuilder).
  33 \item Maybe convert Windows .rc files.
  34 \end{itemize}
  35
  36 \chapter{Commands}\label{commands}
  37 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
  38 \setfooter{\thepage}{}{}{}{}{\thepage}%
  39
  40 \section{Dialog editor menu bar}
  41
  42 \subsection{File menu}
  43
  44 \begin{twocollist}\itemsep=0pt
  45 \twocolitem{New project}{Creates a new project (clears index and resets project name).}
  46 \twocolitem{New dialog}{Creates a new dialog resource.}
  47 \twocolitem{Open}{Opens an existing resource file.}
  48 \twocolitem{Save}{Saves the current resources.}
  49 \twocolitem{Save as}{Saves the current resources in a named file.}
  50 \twocolitem{Clear}{Clears the current resources.}
  51 \twocolitem{Exit}{Exit the program.}
  52 \end{twocollist}
  53
  54 \subsection{Edit menu}
  55
  56 \begin{twocollist}\itemsep=0pt
  57 \twocolitem{Recreate}{Recreates the currently selected panel item 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 \twocolitem{Toggle edit/test mode}{Toggles from edit to test mode, and vice versa. Edit mode is used for editing
  62 dialogs, test mode allows panel items to be manipulated as they will appear to the user.}
  63 \end{twocollist}
  64
  65 \subsection{Help menu}
  66
  67 \begin{twocollist}\itemsep=0pt
  68 \twocolitem{Help topics}{Displays on-line help at the contents page.}
  69 \twocolitem{About}{Displays an dialog showing the Dialog Editor version and author.}
  70 \end{twocollist}
  71
  72 \latexonly{\newpage}
  73 \section{Command toolbar}
  74
  75 The command toolbar consists of the following tools:
  76
  77 \begin{twocollist}%\itemsep=0pt
  78 \twocolitem{\icon{new.eps}{New}}{Clears the project.}
  79 \twocolitem{\icon{open.eps}{Open}}{Opens an existing resource file.}
  80 \twocolitem{\icon{save.eps}{Save}}{Saves the current resources.}
  81 \twocolitem{\icon{vert.eps}{Horizontal align}}{Aligns the centre of the selected items horizontally.}
  82 \twocolitem{\icon{alignt.eps}{Horizontal top-align}}{Aligns the top sides of the selected items horizontally.}
  83 \twocolitem{\icon{alignb.eps}{Horizontal bottom-align}}{Aligns the bottom sides of the selected items horizontally.}
  84 \twocolitem{\icon{horiz.eps}{Vertical align}}{Aligns the centre of the selected items vertically.}
  85 \twocolitem{\icon{alignl.eps}{Vertical left-align}}{Aligns the left sides of the selected items vertically.}
  86 \twocolitem{\icon{alignr.eps}{Vertical right-align}}{Aligns the right sides of the selected items vertically.}
  87 \twocolitem{\icon{copysize.eps}{Copy size}}{Copies the size of the first selected item to the subsequently selected item(s).}
  88 \twocolitem{\icon{tofront.eps}{To front}}{Puts the selected item(s) to the front of the display list.}
  89 \twocolitem{\icon{toback.eps}{To back}}{Puts the selected item(s) to the back of the display list.}
  90 \twocolitem{\icon{help.eps}{Help}}{Invokes Dialog Editor help.}
  91 \end{twocollist}
  92
  93 \latexonly{\newpage}
  94 \section{Tool palette}
  95
  96 The tool palette is used to select a type of panel item to create on the dialog.
  97 To create a new panel item, select a tool with left-click, then left-click on the dialog to
  98 window. Select the pointer tool to use left-click for selecting and deselecting
  99 items.
 100
 101 The tool palette consists of the following tools.
 102
 103 \begin{twocollist}%\itemsep=0pt
 104 \twocolitem{\icon{arrow.eps}{Pointer}}{Click this to select/deselect items on a dialog.}
 105 \twocolitem{\icon{message.eps}{Message}}{Text message item.}
 106 \twocolitem{\icon{picture.eps}{Bitmap message}}{Bitmap message item.}
 107 \twocolitem{\icon{button.eps}{Button}}{Text button item.}
 108 \twocolitem{\icon{bmpbuttn.eps}{Bitmap button}}{Bitmap button item.}
 109 \twocolitem{\icon{check.eps}{Checkbox}}{Checkbox item.}
 110 \twocolitem{\icon{radio.eps}{Radiobox}}{Radiobox item.}
 111 \twocolitem{\icon{listbox.eps}{Listbox}}{Listbox item.}
 112 \twocolitem{\icon{choice.eps}{Choice}}{Choice item.}
 113 \twocolitem{\icon{text.eps}{Text}}{Single-line text item.}
 114 \twocolitem{\icon{mtext.eps}{Multitext}}{Multi-line text item.}
 115 \twocolitem{\icon{slider.eps}{Slider}}{Slider item.}
 116 \twocolitem{\icon{group.eps}{Groupbpx}}{Groupbox item.}
 117 \twocolitem{\icon{gauge.eps}{Gauge}}{Gauge item.}
 118 \twocolitem{\icon{scroll.eps}{Scrollbar}}{Scrollbar item.}
 119 \end{twocollist}
 120
 121 \section{Resource list}
 122
 123 The resource list shows a list of the dialogs, panel items and bitmaps currently loaded
 124 in Dialog Editor. Double-clicking on a dialog item shows the associated dialog box.
 125
 126 \chapter{Procedures}\label{procedures}
 127 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
 128 \setfooter{\thepage}{}{}{}{}{\thepage}%
 129
 130 \section{Running Dialog Editor}
 131
 132 To run Dialog Editor under Windows, click on the Program Manager or Explorer icon.
 133 Under UNIX, run from the command line.
 134
 135 The main window shows a menu bar, command toolbar, tool palette, resource list, and
 136 status line.
 137
 138 \section{Creating a dialog}
 139
 140 To create a new dialog, click on the {\bf File: New} menu item, or equivalent
 141 toolbar button. A dialog will appear. To put a panel item on the dialog, left-click
 142 on the appropriate palette icon and then left-click on the dialog. A new item
 143 will appear at the place you clicked.
 144
 145 You can edit any panel item or dialog by control-left clicking. A property editor
 146 will appear, allowing any property to be selected and edited (see \helpref{Using property editors}{propeditors}).
 147 You can also edit items by right-clicking to show a menu, and then selecting {\it Edit properties}.
 148
 149 To move a panel item, drag the item with the left mouse button, or edit
 150 the position values in the property editor. To resize a panel item, you
 151 can either select it by left-clicking and then dragging on a selection
 152 handle, or edit the size values in the property editor.
 153
 154 You can delete items from the right-click menu, or by selecting the item and
 155 choosing {\bf Edit: Delete} from the menu bar.
 156
 157 \section{Using property editors}\label{propeditors}
 158
 159 Property editors consist of a list of properties and current values, plus controls at the top of
 160 the editor. If the property is of an appropriate type, you can edit the value directly in the
 161 text field, and confirm or cancel the value using the two buttons to the left of it.
 162 If the property has a predefined range of values, such as labelFontFamily, you can
 163 see a list of permissable values by clicking on the button labelled with an ellipsis symbol ({\bf ...}).
 164 This will show a listbox with possible values and current selection. You may also be able
 165 to cycle through values by double-clicking the value in the listbox.
 166
 167 Properties may have special editors appropriate to the type. Filename properties invoke
 168 the file selector, and properties containing list of user-definable strings use a
 169 string editor.
 170
 171 When you change a property value, this value is immediately reflected in
 172 the dialog or panel item.  If the item allows this value to be changed
 173 dynamically, the relevant wxWindows function will be called internally
 174 to effect the change.  If the value cannot be changed dynamically, the
 175 item will be destroyed and re-created, which means that there will be
 176 more flickering associated with some kinds of property changes than
 177 others.
 178
 179 \section{Saving and loading files}
 180
 181 Use {\it File: Save} and {\it File: Save as} or the equivalent toolbar button
 182 to save the current dialog(s) in a wxWindows resource file (extension {\tt .wxr}).
 183
 184 The {\tt .wxr} file can be used directly in a wxWindows program, if
 185 wxWindows resources have been enabled when building the wxWindows library.
 186 These files can be loaded dynamically, or included directly into program source
 187 with a \verb$#include$ directive. See the wxWindows user manual for further details.
 188
 189 \section{Multi-platform development}
 190
 191 {\tt .wxr} files generated on one environment (e.g. Windows) can be used in another (e.g. Motif).
 192 However, because the same panel item can have different sizes on different GUIs,
 193 the user should be cautious in assuming that one resource file will work for all
 194 platforms. It may be better to plan to conditionally include or load different
 195 resource files for different platforms, with spacing modified to suit each
 196 environment.
 197