| 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{Convert Old Resources...}{Takes a directory of wxWindows 1.68 dialog resources, |
| 51 | and converts them to wxWindows 2 resources, in a separate directory. See |
| 52 | \helpref{Converting old files}{convertingoldfiles}.} |
| 53 | \twocolitem{Exit}{Exits the program.} |
| 54 | \end{twocollist} |
| 55 | |
| 56 | \subsection{Edit menu} |
| 57 | |
| 58 | \begin{twocollist}\itemsep=0pt |
| 59 | \twocolitem{Test Dialog}{Creates the current dialog for test purposes.} |
| 60 | \twocolitem{Recreate}{Recreates the currently selected control from the underlying resource. This may be necessary |
| 61 | to regenerate items that cannot be changed dynamically, and which have got out of sync with the displayed |
| 62 | item.} |
| 63 | \twocolitem{Delete}{Deletes the currently selected resource.} |
| 64 | \end{twocollist} |
| 65 | |
| 66 | \subsection{Help menu} |
| 67 | |
| 68 | \begin{twocollist}\itemsep=0pt |
| 69 | \twocolitem{Help Topics}{Displays on-line help at the contents page.} |
| 70 | \twocolitem{About}{Displays an dialog showing the Dialog Editor version and author.} |
| 71 | \end{twocollist} |
| 72 | |
| 73 | \latexonly{\newpage} |
| 74 | \section{Command toolbar} |
| 75 | |
| 76 | The command toolbar consists of the following tools: |
| 77 | |
| 78 | \begin{twocollist}%\itemsep=0pt |
| 79 | \twocolitem{\icon{new.eps}{New}}{Clears the project.} |
| 80 | \twocolitem{\icon{open.eps}{Open}}{Opens an existing resource file.} |
| 81 | \twocolitem{\icon{save.eps}{Save}}{Saves the current resources.} |
| 82 | \twocolitem{\icon{vert.eps}{Horizontal align}}{Aligns the centre of the selected controls horizontally.} |
| 83 | \twocolitem{\icon{alignt.eps}{Horizontal top-align}}{Aligns the top sides of the selected controls horizontally.} |
| 84 | \twocolitem{\icon{alignb.eps}{Horizontal bottom-align}}{Aligns the bottom sides of the selected controls horizontally.} |
| 85 | \twocolitem{\icon{horiz.eps}{Vertical align}}{Aligns the centre of the selected controls vertically.} |
| 86 | \twocolitem{\icon{alignl.eps}{Vertical left-align}}{Aligns the left sides of the selected controls vertically.} |
| 87 | \twocolitem{\icon{alignr.eps}{Vertical right-align}}{Aligns the right sides of the selected controls vertically.} |
| 88 | \twocolitem{\icon{copysize.eps}{Copy size}}{Copies the size of the first selected control to the subsequently selected control(s).} |
| 89 | \twocolitem{\icon{copywdth.eps}{Copy width}}{Copies the width of the first selected control to the subsequently selected control(s).} |
| 90 | \twocolitem{\icon{copyhght.eps}{Copy height}}{Copies the height of the first selected control to the subsequently selected control(s).} |
| 91 | \twocolitem{\icon{disthor.eps}{Distribute horizontally}}{Evenly distributes the space between the selected controls, horizontally. Note that the controls |
| 92 | should be selected in order from left to right.} |
| 93 | \twocolitem{\icon{distvert.eps}{Distribute vertically}}{Evenly distributes the space between the selected controls, vertically. Note that the controls |
| 94 | should be selected in order from top to bottom.} |
| 95 | \twocolitem{\icon{tofront.eps}{To front}}{Puts the selected control(s) to the front of the display list.} |
| 96 | \twocolitem{\icon{toback.eps}{To back}}{Puts the selected control(s) to the back of the display list.} |
| 97 | \twocolitem{\icon{help.eps}{Help}}{Invokes Dialog Editor help.} |
| 98 | \end{twocollist} |
| 99 | |
| 100 | \latexonly{\newpage} |
| 101 | \section{Tool palette} |
| 102 | |
| 103 | The tool palette is used to select a type of control to create on the dialog. |
| 104 | To create a new control, select a tool with left-click, then left-click on the dialog. |
| 105 | Select the pointer tool to use left-click for selecting and deselecting |
| 106 | items. |
| 107 | |
| 108 | \section{Resource tree} |
| 109 | |
| 110 | The resource tree shows a list of the dialogs, controls and bitmaps currently loaded |
| 111 | in Dialog Editor. Double-clicking on an item shows the associated resource. |
| 112 | |
| 113 | \chapter{Procedures}\label{procedures} |
| 114 | \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}% |
| 115 | \setfooter{\thepage}{}{}{}{}{\thepage}% |
| 116 | |
| 117 | \section{Running Dialog Editor} |
| 118 | |
| 119 | To run Dialog Editor under Windows, click on the Program Manager or Explorer icon. |
| 120 | Under UNIX, run from the command line. |
| 121 | |
| 122 | The main window shows a menu bar, command toolbar, tool palette, resource list, and |
| 123 | status line. |
| 124 | |
| 125 | \section{Creating a dialog} |
| 126 | |
| 127 | To create a new dialog, click on the {\bf File: New} menu item, or equivalent |
| 128 | toolbar button. A dialog will appear. To put a control on the dialog, left-click |
| 129 | on the appropriate palette icon and then left-click on the dialog. A new item |
| 130 | will appear at the place you clicked. |
| 131 | |
| 132 | You can edit any control or dialog by control-left clicking. A property editor |
| 133 | will appear, allowing any property to be selected and edited (see \helpref{Using property editors}{propeditors}). |
| 134 | You can also edit items by right-clicking to show a menu, and then selecting {\it Edit properties}. |
| 135 | |
| 136 | To move a control, drag the item with the left mouse button, or edit |
| 137 | the position values in the property editor. To resize a control, you |
| 138 | can either select it by left-clicking and then dragging on a selection |
| 139 | handle, or edit the size values in the property editor. |
| 140 | |
| 141 | You can delete items from the right-click menu, or by selecting the item and |
| 142 | choosing {\bf Edit: Delete} from the menu bar. |
| 143 | |
| 144 | \section{Using property editors}\label{propeditors} |
| 145 | |
| 146 | Property editors consist of a list of properties and current values, plus controls at the top of |
| 147 | the editor. If the property is of an appropriate type, you can edit the value directly in the |
| 148 | text field, and confirm or cancel the value using the two buttons to the left of it. |
| 149 | If the property has a predefined range of values, such as labelFontFamily, you can |
| 150 | see a list of permissable values by clicking on the button labelled with an ellipsis symbol ({\bf ...}). |
| 151 | This will show a listbox with possible values and current selection. You may also be able |
| 152 | to cycle through values by double-clicking the value in the listbox. |
| 153 | |
| 154 | Properties may have special editors appropriate to the type. Filename properties invoke |
| 155 | the file selector, and properties containing list of user-definable strings use a |
| 156 | string editor. |
| 157 | |
| 158 | When you change a property value, this value is immediately reflected in |
| 159 | the dialog or control. If the item allows this value to be changed |
| 160 | dynamically, the relevant wxWindows function will be called internally |
| 161 | to effect the change. If the value cannot be changed dynamically, the |
| 162 | item will be destroyed and re-created, which means that there will be |
| 163 | more flickering associated with some kinds of property changes than |
| 164 | others. |
| 165 | |
| 166 | \section{Saving and loading files} |
| 167 | |
| 168 | Use {\it File: Save} and {\it File: Save as} or the equivalent toolbar button |
| 169 | to save the current dialog(s) in a wxWindows resource file (extension {\tt .wxr}). |
| 170 | |
| 171 | The {\tt .wxr} file can be used directly in a wxWindows program, if |
| 172 | wxWindows resources have been enabled when building the wxWindows library. |
| 173 | These files can be loaded dynamically, or included directly into program source |
| 174 | with a \verb$#include$ directive. See the wxWindows user manual for further details. |
| 175 | |
| 176 | \section{Working with identifiers} |
| 177 | |
| 178 | Dialog Editor keeps track of identifiers in your resources, and reads and writes an include file of the |
| 179 | form {\tt name.h} where 'name' is the root name of your {\tt .wxr} file. Dialog Editor |
| 180 | knows about the predefined identifiers such as wxID\_OK. |
| 181 | |
| 182 | When you create a dialog or control, the identifier is initially generated. When you |
| 183 | edit the identifier via a property editor, you can choose a new name, such as a predefined |
| 184 | symbol and optionally change the integer assigned to the name (assuming it's not a |
| 185 | predefined symbol). |
| 186 | |
| 187 | When you save the project, the identifier include file is saved as well. Include this file |
| 188 | in your project so that you can refer to controls and dialogs by identifier rather than |
| 189 | obscure integers. Note that the {\tt .wxr} file itself can only contain integer ids and not the symbols, |
| 190 | due to way in which the resource file is loaded. |
| 191 | |
| 192 | \section{Multi-platform development} |
| 193 | |
| 194 | {\tt .wxr} files generated on one environment (e.g. Windows) can be used in another (e.g. GTK). |
| 195 | If you use default fonts and colouring (set {\bf useSystemDefaults} to True in the dialog properties) |
| 196 | then the dialog fonts and colours will take on the native values, rather than ones specified in the |
| 197 | resource. Without this, colours in the dialog resource may not match system colours. |
| 198 | |
| 199 | Also, set {\bf useDialogUnits} to True whenever possible since this will cause the dialog |
| 200 | to be created using a scale based on the current system font size, and will result in dialogs that are |
| 201 | portable between screen resolutions as well as platforms. |
| 202 | |
| 203 | Because the same control can have different sizes on different GUIs, |
| 204 | the user should be cautious in assuming that one resource file will work for all |
| 205 | platforms. It may be better to plan to conditionally include or load different |
| 206 | resource files for different platforms, with spacing modified to suit each |
| 207 | environment. The best thing is to try your dialog resource on several platforms |
| 208 | and see whether tweaking is required for some platforms. |
| 209 | |
| 210 | \section{Converting old files}\label{convertingoldfiles} |
| 211 | |
| 212 | Dialog Editor can make an attempt at converting dialog resources created with Dialog Editor for wxWindows 1.68. |
| 213 | The command is {\bf Convert Old Resources...} on the {\bf File} menu. |
| 214 | |
| 215 | You need to specify two directories, an input and an output directory. Dialog Editor will |
| 216 | do the following conversions: |
| 217 | |
| 218 | \begin{enumerate}\itemsep=0pt |
| 219 | \item wxMultiText becomes a wxTextCtrl with wxTE\_MULTILINE style. |
| 220 | \item wxText becomes a wxTextCtrl. |
| 221 | \item wxMessage becomes either a wxStaticText or wxStaticBitmap. |
| 222 | \item wxButton becomes a wxBitmapButton if necessary. |
| 223 | \item wxGroupBox becomes wxStaticBox. |
| 224 | \item Controls that no longer have labels, such as wxTextCtrl and wxListBox, |
| 225 | have a separate wxStaticText control created for them at approximately the correct |
| 226 | position. The label's window name becomes ControlName_Label where ControlName is |
| 227 | the name of the control that formerly had the label. |
| 228 | \item Identifiers are allocated. |
| 229 | \item Font sizes are reduced to counter the decreased font size now created by wxWindows |
| 230 | for a given point size. |
| 231 | \item The dialog height is reduced slightly to compensate for the fact that the dialog caption |
| 232 | is no longer included in the size. |
| 233 | \end{enumerate} |
| 234 | |