]> git.saurik.com Git - wxWidgets.git/blob - utils/configtool/docs/manual/configtool.tex
Added SetFocus and SetFocusIgnoringChildren to wx.Panel
[wxWidgets.git] / utils / configtool / docs / manual / configtool.tex
1 \documentstyle[a4,makeidx,verbatim,texhelp,fancyhea,mysober,mytitle]{report}%
2 \twocolwidtha{4cm}%
3 \definecolour{black}{0}{0}{0}%
4 \definecolour{cyan}{0}{255}{255}%
5 \definecolour{green}{0}{255}{0}%
6 \definecolour{magenta}{255}{0}{255}%
7 \definecolour{red}{255}{0}{0}%
8 \definecolour{blue}{0}{0}{200}%
9 \definecolour{yellow}{255}{255}{0}%
10 \definecolour{white}{255}{255}{255}%
11 %\input{psbox.tex}
12 \newcommand{\commandref}[2]{\helpref{{\tt $\backslash$#1}}{#2}}%
13 \newcommand{\commandrefn}[2]{\helprefn{{\tt $\backslash$#1}}{#2}\index{#1}}%
14 \newcommand{\commandpageref}[2]{\latexignore{\helprefn{{\tt $\backslash$#1}}{#2}}\latexonly{{\tt $\backslash$#1} {\it page \pageref{#2}}}\index{#1}}%
15 \newcommand{\indexit}[1]{#1\index{#1}}%
16 \newcommand{\inioption}[1]{{\tt #1}\index{#1}}%
17 \parskip=10pt%
18 \parindent=0pt%
19 \title{\cttitle}%
20 \author{(c) Julian Smart, 2003}%
21 \makeindex%
22 \begin{document}%
23 %\maketitle%
24 \begin{center}
25 \image{}{logo.gif}
26
27 {\large {\bf Version \ctversion}}
28
29 (c) Julian Smart
30 \end{center}
31
32 \pagestyle{fancyplain}%
33 \bibliographystyle{plain}%
34 \pagenumbering{arabic}%
35 \setheader{{\it CONTENTS}}{}{}{}{}{{\it CONTENTS}}%
36 \setfooter{\thepage}{}{}{}{}{\thepage}%
37 \tableofcontents%
38
39
40 \chapter{Welcome to \ctshortname}%
41 \setheader{{\it Welcome}}{}{}{}{}{{\it Welcome}}%
42 \setfooter{\thepage}{}{}{}{}{\thepage}%
43
44 Welcome to \ctname, the easy way to configure wxWidgets.
45 Instead of tweaking a setup.h file, or typing a long configure
46 command, you can now check and uncheck options in a convenient
47 GUI tool, read the relevant reference document for each
48 option, and save the setup.h file or configure command file.
49
50 \begin{itemize}\itemsep=0pt
51 \item For release information, please see \helpref{Release Notes}{releasenotes}.
52 \item For a tour of the main windows in \ctshortname, please see the \helpref{User Interface}{documentui} section.
53 %\item For a quick tutorial, go straight to \helpref{Getting Started}{gettingstarted}.
54 \item For tips and troubleshooting, see the \helpref{How To}{howto} section.
55 \end{itemize}
56
57 \chapter{Contacts}%
58 \setheader{{\it Contacts}}{}{}{}{}{{\it Contacts}}%
59 \setfooter{\thepage}{}{}{}{}{\thepage}%
60
61 The \ctname home page is at:
62
63 {\tt \cturl}
64
65 For help with \ctshortname or to report bugs,
66 please go to the wxWidgets web site.
67
68 \section{Credits}
69
70 \begin{center}
71 {\bf (c) 2003 Julian Smart, Anthemion Software}\hrule
72
73 {\it Designed by}
74
75 {\bf Julian Smart}
76
77 {\it Programmed by}
78
79 {\bf Julian Smart}
80
81 {\it Additional programming by}
82
83 {\bf The wxWidgets development team}
84
85 \end{center}
86
87 \chapter{Installation}%
88 \setheader{{\it Installation}}{}{}{}{}{{\it Installation}}%
89 \setfooter{\thepage}{}{}{}{}{\thepage}%
90
91 {\bf On Windows:}
92
93 Please run the installation program. This will create a program
94 folder called \ctname (or other name if you have chosen a different name). This
95 folder can be accessed via the Start menu under Programs. The
96 folder contains shortcuts to the program, help file, and Uninstall program.
97
98 You can uninstall \ctshortname either by double-clicking the Uninstall \ctshortname icon
99 in the \ctname group, or by invoking the Windows Control Panel,
100 double-clicking on Add/Remove Programs, and then choosing the \ctshortname item.
101
102 {\bf On Linux:}
103
104 Unarchive wxconfigtool-x.xx.tar.gz to a suitable location
105 in your filesystem. A directory of the form wxconfigtool-x.xx
106 (where x.xx is the version number) will be created.
107
108 Add the location to your PATH and run the application with
109 'wxconfigtool'. You may wish to set the environment variable
110 WXCONFIGTOOLDIR so that wxWidgets Configuration Tool can find its data files.
111
112 For example:
113
114 \begin{verbatim}
115 % cd ~
116 % tar xvfz wxconfigtool-1.01.tar.gz
117 % export WXCONFIGTOOLDIR=`pwd`/wxconfigtool-1.01
118 % export PATH=$PATH:$WXCONFIGTOOLDIR
119 % wxconfigtool
120 \end{verbatim}
121
122 If you don't want to change your PATH, you could place a
123 script in a location already on your PATH, such as
124 /usr/local/bin. For example:
125
126 \begin{verbatim}
127 #!/bin/sh
128 # Invokes wxWidgets Configuration Tool
129 export WXCONFIGTOOLDIR=/home/mydir/wxconfigtool-1.01
130 $WXCONFIGTOOLDIR/wxconfigtool $*
131 \end{verbatim}
132
133 {\bf On Mac:}
134
135 Download and unarchive the HQX file, and drag the wxWidgets Configuration Tool folder to an appropriate location
136 on your hard disk. Then double-click on the 'wxconfigtool' executable.
137
138 \chapter{Release notes}\label{releasenotes}%
139 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
140 \setfooter{\thepage}{}{}{}{}{\thepage}%
141
142 For licencing information, please see
143 the licence files in the installation directory:
144
145 \begin{itemize}\itemsep=0pt
146 \item licendoc.txt
147 \item gpl.txt
148 \item lgpl.txt
149 \item preamble.txt
150 \end{itemize}
151
152 \section{What's New?}\label{whatsnew}
153
154 {\bf Version 1.02, June 16th 2003}
155
156 \begin{itemize}\itemsep=10pt
157 \item The <b>Platform</b> group has been renamed
158 <b>Target</b>, since there can be multiple targets
159 per platform.
160 \item The Windows/Universal target has been added.
161 \end{itemize}
162
163 {\bf Version 1.01, June 14th 2003}
164
165 \begin{itemize}\itemsep=10pt
166 \item Added Find facility.
167 \end{itemize}
168
169 {\bf Version 1.0, June 11th 2003}
170
171 \begin{itemize}\itemsep=10pt
172 \item Initial version.
173 \end{itemize}
174
175 \section{Known issues}\label{knownissues}
176
177 The following problems are known to exist:
178
179 \begin{itemize}\itemsep=10pt
180 \item No issues as yet.
181 \end{itemize}
182
183 \section{To Do}\label{todo}
184
185 There are many things that could be done to make
186 this tool more useful, including the following.
187
188 \begin{itemize}\itemsep=10pt
189 \item Allow full platform-specific dependency specification
190 as mentioned in \helpref{How to specify platform-specific dependencies}{platformdependencies}.
191 \item Allow \ctshortname to invoke configure and make, with an output
192 window showing build status.
193 \item Distinguish between template files and settings file; allow
194 application of template files to settings files, and vice versa.
195 \item Implement support for string, integer, float settings.
196 \item Write a configuration browser.
197 \item Add description, date and author information to the settings file.
198 \item Command-line mode with ability to change settings from
199 the command-line. Just like configure :-)
200 \item Decide on standard location for settings files.
201 \item Integrate with new (and old?) build systems.
202 \item Allow customization of font and colour.
203 \item Show all calculated dependencies for each config item.
204 \item Add a search facility.
205 \end{itemize}
206
207 \section{Differences between Windows, Linux and Mac versions}\label{platformdifferences}
208
209 Although every effort has been made to make wxWidgets Configuration Tool work
210 the same way on different environments, some small differences
211 are inevitable.
212
213 \begin{itemize}\itemsep=10pt
214 \item Screenshots illustrate the Windows version; the Linux
215 and Mac windows and dialogs will be slightly different, but with equivalent
216 functionality.
217 \item Dialogs under Windows often have a '?' button on the title
218 bar, for context-sensitive help. Under Linux, this button is
219 on the dialog itself, usually near the OK or Close button.
220 On the Mac, context-sensitive help is not yet supported.
221 \item Under Linux, online help invoked from the {\bf Help} button
222 in modal dialogs is itself modal. That is, you have to quit
223 the help window to return to the dialog. On Windows, you can
224 switch back to the dialog without quitting the help viewer.
225 \item On Windows and Linux, context menus are invoked with
226 right-click. On Mac, use control-click.
227 \end{itemize}
228
229 \chapter{\ctshortname user interface}\label{documentui}%
230 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
231 \setfooter{\thepage}{}{}{}{}{\thepage}%
232
233 This section describes the main elements of the \ctname user interface.
234
235 The \ctshortname main window looks like this:
236
237 \begin{center}
238 \image{}{screen01.png}
239 \end{center}
240
241 \section{Menubar}
242
243 %\image{}{menubar.gif}
244
245 The \helpref{menubar}{menubarcommands} allows you to perform many functions
246 such as loading and saving files, creating new configuration items,
247 undo/redo, invoking help, and so on. Try to remember the keyboard shortcuts that are
248 displayed next to the menu item labels - they can save you a lot of time
249 and make your \ctshortname experience more natural and enjoyable.
250
251 \section{Main toolbar}
252
253 %\image{}{toolbar.gif}
254
255 The main toolbar gives quick access to commonly-used commands.
256 If you hold your mouse pointer over the toolbar buttons, a tooltip pops up with a short description
257 of the button's function.
258
259 You can choose to hide the toolbar altogether
260 using the {\bf View | Show Toolbar} menu command.
261
262 You can find out more about in the \helpref{toolbar commands}{toolbarcommands} topic.
263
264 \section{Configuration window}
265
266 %\image{}{configwindow.gif}
267
268 The biggest area of \ctshortname is taken up by the configuration window.
269
270 On the left is a hierarchy of settings that can be customized.
271 You can check and uncheck most settings, but you will find that
272 many settings are disabled because they depend on other settings
273 being enabled (or disabled).
274
275 As an end user, you will probably only want to enable or disable
276 options, but it's possible you may wish to update the structure
277 of the settings file itself. In which case you can use the
278 {\bf Edit} menu to add, remove, or rename items; and you can
279 add custom properties to an item, but this is usually only
280 useful for a developer of the tool to do.
281
282 Undo/Redo can be applied to most editing commands, but (currently) not
283 enabling and disabling operations.
284
285 There are three tabs in the main window: {\bf Properties}, {\bf Setup.h},
286 and {\bf Configure}. The Properties tab contains the properties
287 for the selected option. Setup.h shows the setup file,
288 and there are buttons to allow you to copy the file to the clipboard
289 and regenerate the file. Similarly, the Configure tab shows
290 the script that will invoke configure.
291
292 The property editor allows you to show detailed information
293 about the option. A description for each property is shown
294 when you click on the property. You can also edit property values,
295 either by clicking and typing, or by double-clicking or clicking
296 on the {\bf Edit...} button. If a special editor is defined for
297 the property type, it will be shown.
298
299 You can invoke help for the selected option, by clicking
300 on the question mark toolbar button or the {\bf Help | Configuration Item Help} menu
301 item. If there is a help topic defined for the option, the
302 wxWidgets reference manual will be opened at that topic.
303
304 \begin{comment}
305 \chapter{Getting started: a step-by-step guide}\label{gettingstarted}%
306 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
307 \setfooter{\thepage}{}{}{}{}{\thepage}%
308
309 This section will quickly get you up and running with \ctshortname. Click
310 on \helpref{Step 1}{step1} to start. If you are
311 using a Mac, please interpret 'left-click' to mean 'click', and
312 'right-click' to mean 'control-click'.
313
314 \section{Step 1: creating a new configuration}\label{step1}
315
316 When you run \ctshortname for the first time, you are presented with an
317 empty configuration window.
318
319 Go to \helpref{Step 2}{step2} to learn how to do the next thing.
320
321 \section{Step 2: doing something else}\label{step2}
322
323 Go to \helpref{Step 3}{step3} to learn how to do a third thing.
324
325 \section{Step 3: a third thing}\label{step3}
326
327 Go to \helpref{Step 4}{step4} to learn about saving your document and reloading it.
328
329 \section{Step 4: saving and loading documents}\label{step4}
330
331 You may wish to save a document, so you can come back to it later. Click on {\bf File | Save} or
332 the \image{}{save.png} toolbar button. The first time you save the file, you will be prompted
333 for a filename: you can accept the default one provided, or choose another.
334
335 To reload the document, click on {\bf File | Open...} or the \image{}{open.gif} toolbar button.
336 If you are working on another document, you will be prompted to save it first.
337
338 Go to \helpref{Step 5: generating configurations}{step5}
339
340 \section{Step 5: generating configurations}\label{step5}
341
342 Todo.
343
344 Go to \helpref{Step 6: where next?}{step6}
345
346 \section{Step 6: where next?}\label{step6}
347
348 Congratulations! You have learnt how to create, edit, save, and load configuration
349 files.
350
351 To get to know \ctshortname more thoroughly, here are some further things you
352 can do.
353
354 \begin{itemize}
355 \item Read the \helpref{How To}{howto} section.
356 \item Use the help facilities: most dialogs have a {\bf Help} button for a general description, and they
357 also have a {\bf "?"} button for getting information on individual controls on a dialog.
358 \item Explore the menubar and the menus that appear when you right-click over
359 the window background and individual cards.
360 \end{itemize}
361
362 \end{comment}
363
364 \chapter{Using menubar commands}\label{menubarcommands}%
365 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
366 \setfooter{\thepage}{}{}{}{}{\thepage}%
367
368 %\image{}{menubar.gif}
369
370 This section describes the menubar commands. Commands
371 that are not available in the current context are disabled (shown in grey).
372
373 \section{File menu}
374
375 The File menu shows commands that are mostly related to working
376 with files.
377
378 \begin{twocollist}\itemsep=0pt
379 \twocolitem{{\bf New...} (Ctrl+N)}{Creates a new \ctshortname document.}
380 \twocolitem{{\bf Open...} (Ctrl+O)}{Opens an existing document.}
381 \twocolitem{{\bf Close} (Ctrl+W)}{Closes the current document.}
382 \twocolitem{\hrule}{\htmlonly{\hrule}}
383 \twocolitem{{\bf Save} (Ctrl+S)}{Saves the current document.}
384 \twocolitem{{\bf Save As...}}{Saves the current document under a new name.}
385 \twocolitem{\hrule}{\htmlonly{\hrule}}
386 \twocolitem{{\bf Save Setup.h...} (Ctrl+H)}{Saves the generated setup.h file in the specified location.}
387 \twocolitem{{\bf Save Configure Script...} (Ctrl+G)}{Saves the generated script containing a configure command in the specified location.}
388 \twocolitem{\hrule}{\htmlonly{\hrule}}
389 \twocolitem{{\bf Go} (F5)}{Saves the generated setup.h file or configurewx.sh script (according to the default setting) in the last-saved.}
390 \twocolitem{\hrule}{\htmlonly{\hrule}}
391 \twocolitem{{\bf Exit} (Alt+F4)}{Exits the program.}
392 \end{twocollist}
393
394 \section{Edit menu}
395
396 The Edit menu shows commands that are related to editing
397 document elements.
398
399 \twocolwidtha{5cm}
400 \begin{twocollist}\itemsep=0pt
401 \twocolitem{{\bf Undo} (Ctrl+Z)}{Undoes the last undoable action.}
402 \twocolitem{{\bf Redo} (Ctrl+Y)}{Redoes the last redoable action.}
403 \twocolitem{\hrule}{\htmlonly{\hrule}}
404 \twocolitem{{\bf Cut} (Ctrl+T)}{Cuts the selected option and places it on the clipboard.}
405 \twocolitem{{\bf Copy} (Ctrl+C)}{Copies the selected option.}
406 \twocolitem{{\bf Paste} (Ctrl+V)}{Pastes an option from the clipboard to the position. Whether the
407 option is pasted as a child or sibling of the selection is determined by whether
408 the selection is a folder or not. If you want finer control, right-click on the
409 item in the tree control and select one of the paste commands.}
410 \twocolitem{\hrule}{\htmlonly{\hrule}}
411 \twocolitem{{\bf Add Option}}{Shows a menu for adding one of several option types.}
412 \twocolitem{\hrule}{\htmlonly{\hrule}}
413 \twocolitem{{\bf Custom Property}}{Shows a menu for adding, editing or deleting a custom option property.}
414 \twocolitem{\hrule}{\htmlonly{\hrule}}
415 \twocolitem{{\bf Delete Option}}{Deletes the selected option.}
416 \twocolitem{{\bf Rename Option}}{Shows a dialog for renaming the selected option.}
417 \twocolitem{\hrule}{\htmlonly{\hrule}}
418 \twocolitem{{\bf Find...}}{Shows the Find dialog, allowing you to search for text
419 within name, description and notes for each item.}
420 \end{twocollist}
421
422 \section{View menu}
423
424 The View menu gives you commands related to showing or hiding windows
425 and various other preferences.
426
427 \twocolwidtha{5cm}
428 \begin{twocollist}\itemsep=0pt
429 \twocolitem{{\bf Show Toolbar}}{Shows or hides the toolbar, beneath the menubar.}
430 \twocolitem{\hrule}{\htmlonly{\hrule}}
431 \twocolitem{{\bf Settings...} (Ctrl+T)}{Shows the \helpref{Settings Dialog}{settingsdialog}, which
432 relate to application-wide settings.}
433 \end{twocollist}
434
435 \section{Help menu}
436
437 The Help menu gives you commands related to getting help.
438
439 \twocolwidtha{5cm}
440 \begin{twocollist}\itemsep=0pt
441 \twocolitem{{\bf Contents}}{Invokes the on-line help, showing the contents page.}
442 \twocolitem{{\bf wxWidgets Help Contents}}{Invokes the on-line wxWidgets reference manual, showing the contents page.}
443 \twocolitem{\hrule}{\htmlonly{\hrule}}
444 \twocolitem{{\bf Configuration Option Help} (F1)}{Invokes the on-line wxWidgets reference manual at the topic for the selected option (if a topic
445 is defined).}
446 \twocolitem{{\bf What's This?}}{Click to get help on a window or configuration option.}
447 \twocolitem{\hrule}{\htmlonly{\hrule}}
448 \twocolitem{{\bf About...}}{Displays a dialog giving a brief description of the program.}
449 \end{twocollist}
450
451 \chapter{Using context menu commands}\label{contextmenucommands}%
452 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
453 \setfooter{\thepage}{}{}{}{}{\thepage}%
454
455 This section describes the context menu commands available when you right-click.
456 On the Mac, this is achieved with control-click.
457
458 \section{Configuration tree context menu}
459
460 This menu is shown when you right-click over the configuration tree window background.
461 On the Mac, this is achieved with control-click.
462
463 \twocolwidtha{5cm}
464 \begin{twocollist}\itemsep=0pt
465 \twocolitem{{\bf Paste before this option}}{Pastes the clipboard option before the clicked-on option.}
466 \twocolitem{{\bf Paste after this option}}{Pastes the clipboard option after the clicked-on option.}
467 \twocolitem{{\bf Paste as child of this option}}{Pastes the clipboard option as a child of the clicked-on option,
468 if it is a group option.}
469 \twocolitem{\hrule}{\htmlonly{\hrule}}
470 \twocolitem{{\bf C&opy}}{Copies the clicked-on option to the internal clipboard.}
471 \twocolitem{{\bf Cu&t}}{Copies the clicked-on option to the internal clipboard, and
472 deletes the option from the tree.}
473 \end{twocollist}
474
475 \chapter{Using toolbar commands}\label{toolbarcommands}%
476 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
477 \setfooter{\thepage}{}{}{}{}{\thepage}%
478
479 This section describes the toolbar commands.
480
481 %\image{}{toolbar.gif}
482
483 The toolbar provides quick access to commonly-used
484 commands.
485
486 \twocolwidtha{5cm}
487 \begin{twocollist}\itemsep=0pt
488 \twocolitem{\image{}{new.png}{\bf New Document}}{Creates a new document.}
489 \twocolitem{\image{}{open.png}{\bf Open Document}}{Opens an existing document, closing the currently open document.}
490 \twocolitem{\image{}{save.png}{\bf Save Document}}{Saves the current document.}
491 \twocolitem{\hrule}{\htmlonly{\hrule}}
492 \twocolitem{\image{}{undo.png}{\bf Undo}}{Undoes the last command.}
493 \twocolitem{\image{}{redo.png}{\bf Redo}}{Redoes the last command.}
494 \twocolitem{\hrule}{\htmlonly{\hrule}}
495 \twocolitem{\image{}{copy.png}{\bf Copy}}{Copies the selected option to an internal clipboard.}
496 \twocolitem{\image{}{cut.png}{\bf Cut}}{Cuts the selected option and copies it to the internal clipboard..}
497 \twocolitem{\image{}{paste.png}{\bf Paste}}{Pastes the option from the clipboard to the configuration tree.}
498 \twocolitem{\hrule}{\htmlonly{\hrule}}
499 \twocolitem{\image{}{go.png}{\bf Go}}{Saves the generated setup.h file or configurewx.sh script (according to the default setting) in the last-saved.}
500 \twocolitem{\hrule}{\htmlonly{\hrule}}
501 \twocolitem{\image{}{help.png}{\bf Help}}{Shows the wxWidgets manual topic for the
502 \twocolitem{\image{}{helpcs.png}{\bf Context Help}}{Shows a context-sensitive help
503 cursor; click on a window to show brief help about that window.}
504 selected configuration item.}
505 \end{twocollist}
506
507 \chapter{Using dialogs}\label{dialogs}%
508 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
509 \setfooter{\thepage}{}{}{}{}{\thepage}%
510
511 Most dialogs have a {\bf "?"} button on their caption to provide context-sensitive help.
512 Click on this and then on a control
513 in a dialog to get quick help on that control. You can also click on the {\bf Help} button
514 for more detailed help on the dialog.
515
516 \section{Settings dialog}\label{settingsdialog}
517
518 This dialog has a number of tabs to allow you to
519 edit different categories of settings that are applicable
520 to the application as a whole.
521
522 \subsection{General settings dialog}\label{generalapplicationsettingsdialog}
523
524 The General Settings Dialog allows you to set a variety of \ctshortname options.
525
526 \twocolwidtha{5cm}
527 \begin{twocollist}\itemsep=0pt
528 \twocolitem{{\bf Load last document on startup}}{If checked, the last viewed document will
529 be reloaded when \ctshortname starts up.}
530 % If the application terminated abnormally, this
531 %option will be switched off the next time \ctshortname runs in case there was a problem with
532 %the document file.}
533 %\twocolitem{{\bf Auto-save document}}{If checked, \ctshortname will regularly
534 %save the document to a temporary file. If \ctshortname or the operating system
535 %should terminate abnormally, the next time \ctshortname is run it will
536 %check for an auto-save file and ask if you wish to open that file.}
537 %\twocolitem{{\bf Show welcome dialog on startup}}{If checked, the \helpref{Welcome Dialog}{welcomedialog} will
538 %be shown on startup.}
539 \twocolitem{{\bf Show tooltips}}{If checked, tooltips will be shown in most dialogs, when you hover
540 the mouse pointer over a control.}
541 \end{twocollist}
542
543 \subsection{Location settings dialog}\label{locationsettingsdialog}
544
545 The Location Settings Dialog allows you to choose various locations.
546
547 \twocolwidtha{5cm}
548 \begin{twocollist}\itemsep=0pt
549 \twocolitem{{\bf wxWidgets hierarchy}}{This determines where \ctshortname will look
550 when prompting for filenames.}
551 \twocolitem{{\bf Use WXWIN environment variable}}{Check this to use
552 the value of the WXWIN variable instead of the path entered in the text field.}
553 \end{twocollist}
554
555 \chapter{Using keyboard shortcuts}\label{keyboardshortcuts}%
556 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
557 \setfooter{\thepage}{}{}{}{}{\thepage}%
558
559 You can make your \ctshortname experience even smoother by
560 using handy keyboard shortcuts. Note that some shortcuts are
561 dependent on context: that is, which control has the focus.
562
563 \twocolwidtha{3cm}
564 \begin{twocollist}\itemsep=0pt
565 \twocolitem{{\bf Ctrl + C}}{Copies the selected option to the clipboard.}
566 \twocolitem{{\bf Ctrl + H}}{Saves the setup.h file.}
567 \twocolitem{{\bf Ctrl + G}}{Saves the configure script file.}
568 \twocolitem{{\bf Ctrl + N}}{Creates a new \ctshortname file.}
569 \twocolitem{{\bf Ctrl + O}}{Opens a \ctshortname file.}
570 \twocolitem{{\bf Ctrl + S}}{Saves the current \ctshortname document.}
571 \twocolitem{{\bf Ctrl + T}}{Shows the \helpref{Settings Dialog}{settingsdialog}.}
572 \twocolitem{{\bf Ctrl + V}}{Pastes the option on the clipboard (if any) to the configuration tree.}
573 \twocolitem{{\bf Ctrl + W}}{Closes the current \ctshortname document.}
574 \twocolitem{{\bf Ctrl + X}}{Cuts the selected option and copies it to the clipboard.}
575 \twocolitem{{\bf Ctrl + Y}}{Redoes the previously undone edit.}
576 \twocolitem{{\bf Ctrl + Z}}{Undoes the previous edit.}
577 \twocolitem{{\bf F1}}{Shows the online help for the selected item.}
578 \twocolitem{{\bf Alt + F4}}{Closes \ctshortname.}
579 \end{twocollist}
580
581 \chapter{Reference}\label{reference}%
582 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
583 \setfooter{\thepage}{}{}{}{}{\thepage}%
584
585 \section{The dependency evaluation algorithm}
586
587 \ctshortname pre-calculates a list of all dependencies
588 for each option -- this is a kind of reverse-pointer version
589 of all the dependencies associated with each item. So
590 if option {\bf a} has a {\bf requires} option specifying
591 {\bf b}, then {\bf b} will end up with a dependency list
592 containing {\bf a} and any other options that refer to it.
593
594 When the user enables or disables an option ({\bf b}),
595 the list of dependencies for that option is visited,
596 and for each mentioned option ({\bf a}), all its dependency information
597 is evaluated. This may result in the option {\bf a} being
598 (de)selected and perhaps deactivated (made insensitive).
599
600 The results of this change are propagated to dependents of
601 {\bf a}, recursively, so several options may flip state
602 as the result of checking the original option.
603
604 The parent-child relationship of a check or radio
605 group and its children is considered to be a virtual
606 'requires' dependency. Mutual exclusivity is also
607 taken into account if the option is a radio option
608 or group. For each radio option, all other mutually
609 exclusive options need to be listed. See the
610 {\bf Target} group for an example of this.
611
612 The results of these dependencies can be overridden by
613 indeterminate-if, which is done last of all and can
614 make the option user-selectable when otherwise it
615 would be constrained to be enabled or disabled.
616
617 \section{How \ctshortname generates the configure commands}
618
619 If the {\bf configure} property isn't empty,
620 \ctshortname will output the string as a parameter
621 to configure.
622
623 The configure command is taken to be the command to
624 use if the option is checked. If the option is
625 unchecked, the 'enable' or 'with' is replaced with
626 'disable' or 'without'.
627
628 TODO: should we distinguish between the case
629 where a setting is not passed to configure (using
630 the default), versus the case where it's specified but disabled?
631 It's probably a good idea to make all the options
632 explicit, but on the other hand it makes for a very long
633 command line.
634
635 \ctshortname checks for the presence of a
636 {\bf builtin} custom boolean property and appends 'builtin' or
637 'sys' to the configure command depending on where
638 the {\bf builtin} setting is checked or unchecked.
639 We also allow for passing strings, e.g. for --with-rpath=DIR,
640 by using the {\bf value} custom string property.
641
642 \section{How \ctshortname generates the setup.h file}
643
644 The {\bf Target} group is ignored. In all other
645 cases, if the setting is prefixed by wxUSE_...
646 and it's a boolean setting, \ctshortname will
647 output 1 or 0 depending on the setting state.
648
649 A few settings that don't have the wxUSE_...
650 convention are also checked for and processed.
651
652
653 \chapter{How To...}\label{howto}%
654 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
655 \setfooter{\thepage}{}{}{}{}{\thepage}%
656
657 A variety of topics to help you get the best from \ctshortname.
658
659 \section{How to specify dependencies}\label{dependencies}
660
661 To ensure consistency throughout the configuration,
662 \ctshortname allows specification of dependencies, essentially
663 a list of option names that should be considered in evaluating
664 whether an option should be enabled or disabled. In addition,
665 if the option is constrained to always be disabled
666 or enabled in the current context, then it is greyed out
667 (deactivated) to prevent the user from changing the state.
668
669 There are five kinds of dependencies: requires, precludes,
670 enabled-if, enabled-if-not, and indeterminate-if. Each one represents a
671 relationship between the current option (a) and one
672 or more named options (b). For the sake of argument
673 we will consider only one other option, but multiple
674 options are taken to mean (b1 or b2 or b3 or ...)
675 Below the allowed combined states of a and b are
676 listed for each kind of dependency.
677
678 1. a {\bf requires} b
679
680 For example, wxUSE_DRAG_AND_DROP requires wxUSE_OLE.
681
682 \begin{verbatim}
683 a b
684
685 1 1
686 0 1
687 0 0
688 \end{verbatim}
689
690 2. a {\bf precludes} b
691
692 For example, wxUSE_ODBC precludes wxUSE_UNICODE.
693
694 \begin{verbatim}
695 a b
696
697 1 0
698 0 0
699 0 1
700 \end{verbatim}
701
702
703 3. a {\bf enabled-if} b
704
705 For example, __WXUNIVERSAL__ enabled-if X11 or MGL
706
707 \begin{verbatim}
708 a b
709
710 1 1
711 1 0
712 0 0
713 \end{verbatim}
714
715 4. a {\bf enabled-if-not} b
716
717 For example, wxUSE_TOOLBAR_SIMPLE enabled-if-not wxUSE_TOOLBAR_NATIVE.
718
719 \begin{verbatim}
720 a b
721
722 1 0
723 0 1
724 1 1
725 \end{verbatim}
726
727 5. a {\bf indeterminate-if} b
728
729 For example, wxUSE_UNICODE indeterminate-if Custom.
730
731 \begin{verbatim}
732 a b
733
734 ? 1
735 \end{verbatim}
736
737 This overrides all the other dependencies, and allows you
738 to make an option user-choosable in some circumstances,
739 when otherwise it would be constrained to be either enabled or
740 disabled. You may need to use an intermediate option to
741 make sensible use of this: for example make the intermediate
742 option dependent on a number of factors, such as Unicode not being
743 available on some platforms.
744
745 \section{How to specify platform-specific dependencies}\label{platformdependencies}
746
747 You can associate one or more options as part of the
748 option's {\bf context}. In the case of wxUSE_OLE,
749 the context contains __WXMSW__, because it's a Windows-specific
750 option. This is used when calculating dependencies, as
751 follows. If either option involved in a dependency
752 relationship is not part of the current context, that
753 is, none of the options in its {\bf context} property is currently
754 enabled, then it is ignored in the dependency calculation.
755
756 This allows the dependency 'wxUSE_DRAG_AND_DROP requires wxUSE_OLE'
757 to only be evaluated when __WXMSW__ is enabled.
758
759 It doesn't quite cover all bases, however, because
760 it cannot express that the {\it dependency} itself
761 is platform specific. You might have a platform-specific
762 dependency that exists between two options that are
763 perfectly valid for any platform. For example, we
764 can't capture the notion that wxUSE_LISTBOX
765 should be required if wxUSE_COMBOBOX is set,
766 but only for __WXUNIVERSAL__. We could do it
767 by complicating the dependency syntax, for example:
768
769 wxUSE_COMBOBOX requires wxUSE_LISTBOX:__WXUNIVERSAL__
770
771 This means that the dependency should only be
772 evaluated if __WXUNIVERSAL__ is enabled.
773 This has not been implemented yet.
774
775 \section{How to specify custom properties}\label{customproperties}
776
777 You can add custom properties to any option, but
778 currently only {\bf option} and {\bf value} are
779 recognised by \ctshortname.
780
781 \ctshortname checks for the presence of a
782 {\bf builtin} boolean custom property and appends 'builtin' or
783 'sys' to the configure command depending on where
784 the {\bf builtin} setting is checked or unchecked.
785 We also allow for passing strings, e.g. for --with-rpath=DIR,
786 by using the {\bf value} string custom property.
787
788 \begin{comment}
789
790 \begin{helpglossary}
791
792 \gloss{thing}\label{thing}
793
794 A glossary entry.
795
796 \end{helpglossary}
797 \end{comment}
798
799 \rtfonly{%
800 \addcontentsline{toc}{chapter}{Index}
801 \printindex%
802 \setheader{{\it INDEX}}{}{}{}{}{{\it INDEX}}%
803 \setfooter{\thepage}{}{}{}{}{\thepage}%
804 }
805 \winhelponly{
806 \chapter{Popups}\label{popups}
807
808 } % WinHelp only
809
810 \end{document}