1 \documentstyle[a4,makeidx,verbatim,texhelp,fancyhea,mysober,mytitle
]{report}%
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}%
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}}%
20 \author{(c) Julian Smart,
2003}%
27 {\large {\bf Version
\ctversion}}
32 \pagestyle{fancyplain
}%
33 \bibliographystyle{plain
}%
34 \pagenumbering{arabic
}%
35 \setheader{{\it CONTENTS
}}{}{}{}{}{{\it CONTENTS
}}%
36 \setfooter{\thepage}{}{}{}{}{\thepage}%
40 \chapter{Welcome to
\ctshortname}%
41 \setheader{{\it Welcome
}}{}{}{}{}{{\it Welcome
}}%
42 \setfooter{\thepage}{}{}{}{}{\thepage}%
44 Welcome to
\ctname, the easy way to configure wxWindows.
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.
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.
58 \setheader{{\it Contacts
}}{}{}{}{}{{\it Contacts
}}%
59 \setfooter{\thepage}{}{}{}{}{\thepage}%
61 The
\ctname home page is at:
65 For help with
\ctshortname or to
report bugs,
66 please go to the wxWindows web site.
71 {\bf (c)
2003 Julian Smart, Anthemion Software
}\hrule
81 {\it Additional programming by
}
83 {\bf The wxWindows development team
}
87 \chapter{Installation
}%
88 \setheader{{\it Installation
}}{}{}{}{}{{\it Installation
}}%
89 \setfooter{\thepage}{}{}{}{}{\thepage}%
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.
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.
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.
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 wxWindows Configuration Tool can find its data files.
116 % tar xvfz wxconfigtool-1.01.tar.gz
117 % export WXCONFIGTOOLDIR=`pwd`/wxconfigtool-1.01
118 % export PATH=$PATH:$WXCONFIGTOOLDIR
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:
128 # Invokes wxWindows Configuration Tool
129 export WXCONFIGTOOLDIR=/home/mydir/wxconfigtool-
1.01
130 $WXCONFIGTOOLDIR/wxconfigtool $*
135 Download and unarchive the HQX file, and drag the wxWindows Configuration Tool folder to an appropriate location
136 on your hard disk. Then double-click on the 'wxconfigtool' executable.
138 \chapter{Release notes
}\label{releasenotes
}%
139 \setheader{{\it CHAPTER
\thechapter}}{}{}{}{}{{\it CHAPTER
\thechapter}}%
140 \setfooter{\thepage}{}{}{}{}{\thepage}%
142 For licencing information, please see
143 the licence files in the installation directory:
145 \begin{itemize
}\itemsep=
0pt
152 \section{What's New?
}\label{whatsnew
}
154 {\bf Version
1.0, June
11th
2003}
156 \begin{itemize
}\itemsep=
10pt
157 \item Initial version.
160 \section{Known issues
}\label{knownissues
}
162 The following problems are known to exist:
164 \begin{itemize
}\itemsep=
10pt
165 \item No issues as yet.
168 \section{To Do
}\label{todo
}
170 There are many things that could be done to make
171 this tool more useful, including the following.
173 \begin{itemize
}\itemsep=
10pt
174 \item Allow full platform-specific dependency specification
175 as mentioned in
\helpref{How to specify platform-specific dependencies
}{platformdependencies
}.
176 \item Allow
\ctshortname to invoke configure and make, with an output
177 window showing build status.
178 \item Distinguish between template files and settings file; allow
179 application of template files to settings files, and vice versa.
180 \item Implement support for string, integer, float settings.
181 \item Write a configuration browser.
182 \item Add description, date and author information to the settings file.
183 \item Command-line mode with ability to change settings from
184 the command-line. Just like configure :-)
185 \item Decide on standard location for settings files.
186 \item Integrate with new (and old?) build systems.
187 \item Allow customization of font and colour.
188 \item Show all calculated dependencies for each config item.
189 \item Add a search facility.
192 \section{Differences between Windows, Linux and Mac versions
}\label{platformdifferences
}
194 Although every effort has been made to make wxWindows Configuration Tool work
195 the same way on different environments, some small differences
198 \begin{itemize
}\itemsep=
10pt
199 \item Screenshots illustrate the Windows version; the Linux
200 and Mac windows and dialogs will be slightly different, but with equivalent
202 \item Dialogs under Windows often have a '?' button on the title
203 bar, for context-sensitive help. Under Linux, this button is
204 on the dialog itself, usually near the OK or Close button.
205 On the Mac, context-sensitive help is not yet supported.
206 \item Under Linux, online help invoked from the
{\bf Help
} button
207 in modal dialogs is itself modal. That is, you have to quit
208 the help window to return to the dialog. On Windows, you can
209 switch back to the dialog without quitting the help viewer.
210 \item On Windows and Linux, context menus are invoked with
211 right-click. On Mac, use control-click.
214 \chapter{\ctshortname user interface
}\label{documentui
}%
215 \setheader{{\it CHAPTER
\thechapter}}{}{}{}{}{{\it CHAPTER
\thechapter}}%
216 \setfooter{\thepage}{}{}{}{}{\thepage}%
218 This section describes the main elements of the
\ctname user interface.
220 The
\ctshortname main window looks like this:
223 \image{}{screen01.png
}
228 %\image{}{menubar.gif}
230 The
\helpref{menubar
}{menubarcommands
} allows you to perform many functions
231 such as loading and saving files, creating new configuration items,
232 undo/redo, invoking help, and so on. Try to remember the keyboard shortcuts that are
233 displayed next to the menu item labels - they can save you a lot of time
234 and make your
\ctshortname experience more natural and enjoyable.
236 \section{Main toolbar
}
238 %\image{}{toolbar.gif}
240 The main toolbar gives quick access to commonly-used commands.
241 If you hold your mouse pointer over the toolbar buttons, a tooltip pops up with a short description
242 of the button's function.
244 You can choose to hide the toolbar altogether
245 using the
{\bf View | Show Toolbar
} menu command.
247 You can find out more about in the
\helpref{toolbar commands
}{toolbarcommands
} topic.
249 \section{Configuration window
}
251 %\image{}{configwindow.gif}
253 The biggest area of
\ctshortname is taken up by the configuration window.
255 On the left is a hierarchy of settings that can be customized.
256 You can check and uncheck most settings, but you will find that
257 many settings are disabled because they depend on other settings
258 being enabled (or disabled).
260 As an end user, you will probably only want to enable or disable
261 options, but it's possible you may wish to update the structure
262 of the settings file itself. In which case you can use the
263 {\bf Edit
} menu to add, remove, or rename items; and you can
264 add custom properties to an item, but this is usually only
265 useful for a developer of the tool to do.
267 Undo/Redo can be applied to most editing commands, but (currently) not
268 enabling and disabling operations.
270 There are three tabs in the main window:
{\bf Properties
},
{\bf Setup.h
},
271 and
{\bf Configure
}. The Properties tab contains the properties
272 for the selected option. Setup.h shows the setup file,
273 and there are buttons to allow you to copy the file to the clipboard
274 and regenerate the file. Similarly, the Configure tab shows
275 the script that will invoke configure.
277 The property editor allows you to show detailed information
278 about the option. A description for each property is shown
279 when you click on the property. You can also edit property values,
280 either by clicking and typing, or by double-clicking or clicking
281 on the
{\bf Edit...
} button. If a special editor is defined for
282 the property type, it will be shown.
284 You can invoke help for the selected option, by clicking
285 on the question mark toolbar button or the
{\bf Help | Configuration Item Help
} menu
286 item. If there is a help topic defined for the option, the
287 wxWindows reference manual will be opened at that topic.
290 \chapter{Getting started: a step-by-step guide
}\label{gettingstarted
}%
291 \setheader{{\it CHAPTER
\thechapter}}{}{}{}{}{{\it CHAPTER
\thechapter}}%
292 \setfooter{\thepage}{}{}{}{}{\thepage}%
294 This section will quickly get you up and running with
\ctshortname. Click
295 on
\helpref{Step
1}{step1
} to start. If you are
296 using a Mac, please interpret 'left-click' to mean 'click', and
297 'right-click' to mean 'control-click'.
299 \section{Step
1: creating a new configuration
}\label{step1
}
301 When you run
\ctshortname for the first time, you are presented with an
302 empty configuration window.
304 Go to
\helpref{Step
2}{step2
} to learn how to do the next thing.
306 \section{Step
2: doing something else
}\label{step2
}
308 Go to
\helpref{Step
3}{step3
} to learn how to do a third thing.
310 \section{Step
3: a third thing
}\label{step3
}
312 Go to
\helpref{Step
4}{step4
} to learn about saving your
document and reloading it.
314 \section{Step
4: saving and loading documents
}\label{step4
}
316 You may wish to save a
document, so you can come back to it later. Click on
{\bf File | Save
} or
317 the
\image{}{save.png
} toolbar button. The first time you save the file, you will be prompted
318 for a filename: you can accept the default one provided, or choose another.
320 To reload the
document, click on
{\bf File | Open...
} or the
\image{}{open.gif
} toolbar button.
321 If you are working on another
document, you will be prompted to save it first.
323 Go to
\helpref{Step
5: generating configurations
}{step5
}
325 \section{Step
5: generating configurations
}\label{step5
}
329 Go to
\helpref{Step
6: where next?
}{step6
}
331 \section{Step
6: where next?
}\label{step6
}
333 Congratulations! You have learnt how to create, edit, save, and load configuration
336 To get to know
\ctshortname more thoroughly, here are some further things you
340 \item Read the
\helpref{How To
}{howto
} section.
341 \item Use the help facilities: most dialogs have a
{\bf Help
} button for a general description, and they
342 also have a
{\bf "?"
} button for getting information on individual controls on a dialog.
343 \item Explore the menubar and the menus that appear when you right-click over
344 the window background and individual cards.
349 \chapter{Using menubar commands
}\label{menubarcommands
}%
350 \setheader{{\it CHAPTER
\thechapter}}{}{}{}{}{{\it CHAPTER
\thechapter}}%
351 \setfooter{\thepage}{}{}{}{}{\thepage}%
353 %\image{}{menubar.gif}
355 This section describes the menubar commands. Commands
356 that are not available in the current context are disabled (shown in grey).
360 The File menu shows commands that are mostly related to working
363 \begin{twocollist
}\itemsep=
0pt
364 \twocolitem{{\bf New...
} (Ctrl+N)
}{Creates a new
\ctshortname document.
}
365 \twocolitem{{\bf Open...
} (Ctrl+O)
}{Opens an existing
document.
}
366 \twocolitem{{\bf Close
} (Ctrl+W)
}{Closes the current
document.
}
367 \twocolitem{\hrule}{\htmlonly{\hrule}}
368 \twocolitem{{\bf Save
} (Ctrl+S)
}{Saves the current
document.
}
369 \twocolitem{{\bf Save As...
}}{Saves the current
document under a new name.
}
370 \twocolitem{\hrule}{\htmlonly{\hrule}}
371 \twocolitem{{\bf Save Setup.h...
} (Ctrl+H)
}{Saves the generated setup.h file in the specified location.
}
372 \twocolitem{{\bf Save Configure Script...
} (Ctrl+G)
}{Saves the generated script containing a configure command in the specified location.
}
373 \twocolitem{\hrule}{\htmlonly{\hrule}}
374 \twocolitem{{\bf Exit
} (Alt+F4)
}{Exits the program.
}
379 The Edit menu shows commands that are related to editing
383 \begin{twocollist
}\itemsep=
0pt
384 \twocolitem{{\bf Undo
} (Ctrl+Z)
}{Undoes the last undoable action.
}
385 \twocolitem{{\bf Redo
} (Ctrl+Y)
}{Redoes the last redoable action.
}
386 \twocolitem{\hrule}{\htmlonly{\hrule}}
387 \twocolitem{{\bf Cut
} (Ctrl+T)
}{Cuts the selected option and places it on the clipboard.
}
388 \twocolitem{{\bf Copy
} (Ctrl+C)
}{Copies the selected option.
}
389 \twocolitem{{\bf Paste
} (Ctrl+V)
}{Pastes an option from the clipboard to the position. Whether the
390 option is pasted as a child or sibling of the selection is determined by whether
391 the selection is a folder or not. If you want finer control, right-click on the
392 item in the tree control and select one of the paste commands.
}
393 \twocolitem{\hrule}{\htmlonly{\hrule}}
394 \twocolitem{{\bf Add Option
}}{Shows a menu for adding one of several option types.
}
395 \twocolitem{\hrule}{\htmlonly{\hrule}}
396 \twocolitem{{\bf Custom Property
}}{Shows a menu for adding, editing or deleting a custom option property.
}
397 \twocolitem{\hrule}{\htmlonly{\hrule}}
398 \twocolitem{{\bf Delete Option
}}{Deletes the selected option.
}
399 \twocolitem{{\bf Rename Option
}}{Shows a dialog for renaming the selected option.
}
404 The View menu gives you commands related to showing or hiding windows
405 and various other preferences.
408 \begin{twocollist
}\itemsep=
0pt
409 \twocolitem{{\bf Show Toolbar
}}{Shows or hides the toolbar, beneath the menubar.
}
410 \twocolitem{\hrule}{\htmlonly{\hrule}}
411 \twocolitem{{\bf Settings...
} (Ctrl+T)
}{Shows the
\helpref{Settings Dialog
}{settingsdialog
}, which
412 relate to application-wide settings.
}
417 The Help menu gives you commands related to getting help.
420 \begin{twocollist
}\itemsep=
0pt
421 \twocolitem{{\bf Contents
}}{Invokes the on-line help, showing the contents page.
}
422 \twocolitem{{\bf wxWindows Help Contents
}}{Invokes the on-line wxWindows reference manual, showing the contents page.
}
423 \twocolitem{\hrule}{\htmlonly{\hrule}}
424 \twocolitem{{\bf Configuration Option Help
} (F1)
}{Invokes the on-line wxWindows reference manual at the topic for the selected option (if a topic
426 \twocolitem{{\bf What's This?
}}{Click to get help on a window or configuration option.
}
427 \twocolitem{\hrule}{\htmlonly{\hrule}}
428 \twocolitem{{\bf About...
}}{Displays a dialog giving a brief description of the program.
}
431 \chapter{Using context menu commands
}\label{contextmenucommands
}%
432 \setheader{{\it CHAPTER
\thechapter}}{}{}{}{}{{\it CHAPTER
\thechapter}}%
433 \setfooter{\thepage}{}{}{}{}{\thepage}%
435 This section describes the context menu commands available when you right-click.
436 On the Mac, this is achieved with control-click.
438 \section{Configuration tree context menu
}
440 This menu is shown when you right-click over the configuration tree window background.
441 On the Mac, this is achieved with control-click.
444 \begin{twocollist
}\itemsep=
0pt
445 \twocolitem{{\bf Paste before this option
}}{Pastes the clipboard option before the clicked-on option.
}
446 \twocolitem{{\bf Paste after this option
}}{Pastes the clipboard option after the clicked-on option.
}
447 \twocolitem{{\bf Paste as child of this option
}}{Pastes the clipboard option as a child of the clicked-on option,
448 if it is a group option.
}
449 \twocolitem{\hrule}{\htmlonly{\hrule}}
450 \twocolitem{{\bf C&opy
}}{Copies the clicked-on option to the internal clipboard.
}
451 \twocolitem{{\bf Cu&t
}}{Copies the clicked-on option to the internal clipboard, and
452 deletes the option from the tree.
}
455 \chapter{Using toolbar commands
}\label{toolbarcommands
}%
456 \setheader{{\it CHAPTER
\thechapter}}{}{}{}{}{{\it CHAPTER
\thechapter}}%
457 \setfooter{\thepage}{}{}{}{}{\thepage}%
459 This section describes the toolbar commands.
461 %\image{}{toolbar.gif}
463 The toolbar provides quick access to commonly-used
467 \begin{twocollist
}\itemsep=
0pt
468 \twocolitem{\image{}{new.png
}{\bf New Document
}}{Creates a new
document.
}
469 \twocolitem{\image{}{open.png
}{\bf Open Document
}}{Opens an existing
document, closing the currently open
document.
}
470 \twocolitem{\image{}{save.png
}{\bf Save Document
}}{Saves the current
document.
}
471 \twocolitem{\hrule}{\htmlonly{\hrule}}
472 \twocolitem{\image{}{undo.png
}{\bf Undo
}}{Undoes the last command.
}
473 \twocolitem{\image{}{redo.png
}{\bf Redo
}}{Redoes the last command.
}
474 \twocolitem{\hrule}{\htmlonly{\hrule}}
475 \twocolitem{\image{}{copy.png
}{\bf Copy
}}{Copies the selected option to an internal clipboard.
}
476 \twocolitem{\image{}{cut.png
}{\bf Cut
}}{Cuts the selected option and copies it to the internal clipboard..
}
477 \twocolitem{\image{}{paste.png
}{\bf Paste
}}{Pastes the option from the clipboard to the configuration tree.
}
478 \twocolitem{\hrule}{\htmlonly{\hrule}}
479 \twocolitem{\image{}{help.png
}{\bf Help
}}{Shows the wxWindows manual topic for the
480 \twocolitem{\image{}{helpcs.png
}{\bf Context Help
}}{Shows a context-sensitive help
481 cursor; click on a window to show brief help about that window.
}
482 selected configuration item.
}
485 \chapter{Using dialogs
}\label{dialogs
}%
486 \setheader{{\it CHAPTER
\thechapter}}{}{}{}{}{{\it CHAPTER
\thechapter}}%
487 \setfooter{\thepage}{}{}{}{}{\thepage}%
489 Most dialogs have a
{\bf "?"
} button on their caption to provide context-sensitive help.
490 Click on this and then on a control
491 in a dialog to get quick help on that control. You can also click on the
{\bf Help
} button
492 for more detailed help on the dialog.
494 \section{Settings dialog
}\label{settingsdialog
}
496 This dialog has a number of tabs to allow you to
497 edit different categories of settings that are applicable
498 to the application as a whole.
500 \subsection{General settings dialog
}\label{generalapplicationsettingsdialog
}
502 The General Settings Dialog allows you to set a variety of
\ctshortname options.
505 \begin{twocollist
}\itemsep=
0pt
506 \twocolitem{{\bf Load last
document on startup
}}{If checked, the last viewed
document will
507 be reloaded when
\ctshortname starts up.
}
508 % If the application terminated abnormally, this
509 %option will be switched off the next time \ctshortname runs in case there was a problem with
511 %\twocolitem{{\bf Auto-save document}}{If checked, \ctshortname will regularly
512 %save the document to a temporary file. If \ctshortname or the operating system
513 %should terminate abnormally, the next time \ctshortname is run it will
514 %check for an auto-save file and ask if you wish to open that file.}
515 %\twocolitem{{\bf Show welcome dialog on startup}}{If checked, the \helpref{Welcome Dialog}{welcomedialog} will
516 %be shown on startup.}
517 \twocolitem{{\bf Show tooltips
}}{If checked, tooltips will be shown in most dialogs, when you hover
518 the mouse pointer over a control.
}
521 \subsection{Location settings dialog
}\label{locationsettingsdialog
}
523 The Location Settings Dialog allows you to choose various locations.
526 \begin{twocollist
}\itemsep=
0pt
527 \twocolitem{{\bf wxWindows hierarchy
}}{This determines where
\ctshortname will look
528 when prompting for filenames.
}
529 \twocolitem{{\bf Use WXWIN environment variable
}}{Check this to use
530 the value of the WXWIN variable instead of the path entered in the text field.
}
533 \chapter{Using keyboard shortcuts
}\label{keyboardshortcuts
}%
534 \setheader{{\it CHAPTER
\thechapter}}{}{}{}{}{{\it CHAPTER
\thechapter}}%
535 \setfooter{\thepage}{}{}{}{}{\thepage}%
537 You can make your
\ctshortname experience even smoother by
538 using handy keyboard shortcuts. Note that some shortcuts are
539 dependent on context: that is, which control has the focus.
542 \begin{twocollist
}\itemsep=
0pt
543 \twocolitem{{\bf Ctrl + C
}}{Copies the selected option to the clipboard.
}
544 \twocolitem{{\bf Ctrl + H
}}{Saves the setup.h file.
}
545 \twocolitem{{\bf Ctrl + G
}}{Saves the configure script file.
}
546 \twocolitem{{\bf Ctrl + N
}}{Creates a new
\ctshortname file.
}
547 \twocolitem{{\bf Ctrl + O
}}{Opens a
\ctshortname file.
}
548 \twocolitem{{\bf Ctrl + S
}}{Saves the current
\ctshortname document.
}
549 \twocolitem{{\bf Ctrl + T
}}{Shows the
\helpref{Settings Dialog
}{settingsdialog
}.
}
550 \twocolitem{{\bf Ctrl + V
}}{Pastes the option on the clipboard (if any) to the configuration tree.
}
551 \twocolitem{{\bf Ctrl + W
}}{Closes the current
\ctshortname document.
}
552 \twocolitem{{\bf Ctrl + X
}}{Cuts the selected option and copies it to the clipboard.
}
553 \twocolitem{{\bf Ctrl + Y
}}{Redoes the previously undone edit.
}
554 \twocolitem{{\bf Ctrl + Z
}}{Undoes the previous edit.
}
555 \twocolitem{{\bf F1
}}{Shows the online help for the selected item.
}
556 \twocolitem{{\bf Alt + F4
}}{Closes
\ctshortname.
}
559 \chapter{Reference
}\label{reference
}%
560 \setheader{{\it CHAPTER
\thechapter}}{}{}{}{}{{\it CHAPTER
\thechapter}}%
561 \setfooter{\thepage}{}{}{}{}{\thepage}%
563 \section{The dependency evaluation algorithm
}
565 \ctshortname pre-calculates a list of all dependencies
566 for each option -- this is a kind of reverse-pointer version
567 of all the dependencies associated with each item. So
568 if option
{\bf a
} has a
{\bf requires
} option specifying
569 {\bf b
}, then
{\bf b
} will end up with a dependency list
570 containing
{\bf a
} and any other options that refer to it.
572 When the user enables or disables an option (
{\bf b
}),
573 the list of dependencies for that option is visited,
574 and for each mentioned option (
{\bf a
}), all its dependency information
575 is evaluated. This may result in the option
{\bf a
} being
576 (de)selected and perhaps deactivated (made insensitive).
578 The results of this change are propagated to dependents of
579 {\bf a
}, recursively, so several options may flip state
580 as the result of checking the original option.
582 The parent-child relationship of a check or radio
583 group and its children is considered to be a virtual
584 'requires' dependency. Mutual exclusivity is also
585 taken into account if the option is a radio option
586 or group. For each radio option, all other mutually
587 exclusive options need to be listed. See the
588 {\bf Platform
} group for an example of this.
590 \section{How
\ctshortname generates the configure commands
}
592 If the
{\bf configure
} property isn't empty,
593 \ctshortname will output the string as a parameter
596 The configure command is taken to be the command to
597 use if the option is checked. If the option is
598 unchecked, the 'enable' or 'with' is replaced with
599 'disable' or 'without'.
601 TODO: should we distinguish between the case
602 where a setting is not passed to configure (using
603 the default), versus the case where it's specified but disabled?
604 It's probably a good idea to make all the options
605 explicit, but on the other hand it makes for a very long
608 \ctshortname checks for the presence of a
609 {\bf builtin
} custom boolean property and appends 'builtin' or
610 'sys' to the configure command depending on where
611 the
{\bf builtin
} setting is checked or unchecked.
612 We also allow for passing strings, e.g. for --with-rpath=DIR,
613 by using the
{\bf value
} custom string property.
615 \section{How
\ctshortname generates the setup.h file
}
617 The
{\bf Platforms
} group is ignored. In all other
618 cases, if the setting is prefixed by wxUSE_...
619 and it's a boolean setting,
\ctshortname will
620 output
1 or
0 depending on the setting state.
622 A few settings that don't have the wxUSE_...
623 convention are also checked for and processed.
626 \chapter{How To...
}\label{howto
}%
627 \setheader{{\it CHAPTER
\thechapter}}{}{}{}{}{{\it CHAPTER
\thechapter}}%
628 \setfooter{\thepage}{}{}{}{}{\thepage}%
630 A variety of topics to help you get the best from
\ctshortname.
632 \section{How to specify dependencies
}\label{dependencies
}
634 To ensure consistency throughout the configuration,
635 \ctshortname allows specification of dependencies, essentially
636 a list of option names that should be considered in evaluating
637 whether an option should be enabled or disabled. In addition,
638 if the option is constrained to always be disabled
639 or enabled in the current context, then it is greyed out
640 (deactivated) to prevent the user from changing the state.
642 There are four kinds of dependencies: requires, precludes,
643 enabled-if, and enabled-if-not. Each one represents a
644 relationship between the current option (a) and one
645 or more named options (b). For the sake of argument
646 we will consider only one other option, but multiple
647 options are taken to mean (b1 or b2 or b3 or ...)
648 Below the allowed combined states of a and b are
649 listed for each kind of dependency.
651 1. a
{\bf requires
} b
653 For example, wxUSE_DRAG_AND_DROP requires wxUSE_OLE.
663 2. a
{\bf precludes
} b
665 For example, wxUSE_ODBC precludes wxUSE_UNICODE.
676 3. a
{\bf enabled-if
} b
678 For example, __WXUNIVERSAL__ enabled-if X11 or MGL
688 4. a
{\bf enabled-if-not
} b
690 For example, wxUSE_TOOLBAR_SIMPLE enabled-if-not wxUSE_TOOLBAR_NATIVE.
700 \section{How to specify platform-specific dependencies
}\label{platformdependencies
}
702 You can associate one or more options as part of the
703 option's
{\bf context
}. In the case of wxUSE_OLE,
704 the context contains __WXMSW__, because it's a Windows-specific
705 option. This is used when calculating dependencies, as
706 follows. If either option involved in a dependency
707 relationship is not part of the current context, that
708 is, none of the options in its
{\bf context
} property is currently
709 enabled, then it is ignored in the dependency calculation.
711 This allows the dependency 'wxUSE_DRAG_AND_DROP requires wxUSE_OLE'
712 to only be evaluated when __WXMSW__ is enabled.
714 It doesn't quite cover all bases, however, because
715 it cannot express that the
{\it dependency
} itself
716 is platform specific. You might have a platform-specific
717 dependency that exists between two options that are
718 perfectly valid for any platform. For example, we
719 can't capture the notion that wxUSE_LISTBOX
720 should be required if wxUSE_COMBOBOX is set,
721 but only for __WXUNIVERSAL__. We could do it
722 by complicating the dependency syntax, for example:
724 wxUSE_COMBOBOX requires wxUSE_LISTBOX:__WXUNIVERSAL__
726 This means that the dependency should only be
727 evaluated if __WXUNIVERSAL__ is enabled.
728 This has not been implemented yet.
730 \section{How to specify custom properties
}\label{customproperties
}
732 You can add custom properties to any option, but
733 currently only
{\bf option
} and
{\bf value
} are
734 recognised by
\ctshortname.
736 \ctshortname checks for the presence of a
737 {\bf builtin
} boolean custom property and appends 'builtin' or
738 'sys' to the configure command depending on where
739 the
{\bf builtin
} setting is checked or unchecked.
740 We also allow for passing strings, e.g. for --with-rpath=DIR,
741 by using the
{\bf value
} string custom property.
747 \gloss{thing
}\label{thing
}
755 \addcontentsline{toc
}{chapter
}{Index
}
757 \setheader{{\it INDEX
}}{}{}{}{}{{\it INDEX
}}%
758 \setfooter{\thepage}{}{}{}{}{\thepage}%
761 \chapter{Popups
}\label{popups
}