fix for crash on 64 bit platforms (patch 1028942)

[wxWidgets.git] / utils / configtool / docs / manual / configtool.tex

\documentstyle[a4,makeidx,verbatim,texhelp,fancyhea,mysober,mytitle]{report}%
\twocolwidtha{4cm}%
\definecolour{black}{0}{0}{0}%
\definecolour{cyan}{0}{255}{255}%
\definecolour{green}{0}{255}{0}%
\definecolour{magenta}{255}{0}{255}%
\definecolour{red}{255}{0}{0}%
\definecolour{blue}{0}{0}{200}%
\definecolour{yellow}{255}{255}{0}%
\definecolour{white}{255}{255}{255}%
%\input{psbox.tex}
\newcommand{\commandref}[2]{\helpref{{\tt $\backslash$#1}}{#2}}%
\newcommand{\commandrefn}[2]{\helprefn{{\tt $\backslash$#1}}{#2}\index{#1}}%
\newcommand{\commandpageref}[2]{\latexignore{\helprefn{{\tt $\backslash$#1}}{#2}}\latexonly{{\tt $\backslash$#1} {\it page \pageref{#2}}}\index{#1}}%
\newcommand{\indexit}[1]{#1\index{#1}}%
\newcommand{\inioption}[1]{{\tt #1}\index{#1}}%
\parskip=10pt%
\parindent=0pt%
\title{\cttitle}%
\author{(c) Julian Smart, 2003}%
\makeindex%
\begin{document}%
%\maketitle%
\begin{center}
\image{}{logo.gif}

{\large {\bf Version \ctversion}}

(c) Julian Smart
\end{center}

\pagestyle{fancyplain}%
\bibliographystyle{plain}%
\pagenumbering{arabic}%
\setheader{{\it CONTENTS}}{}{}{}{}{{\it CONTENTS}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%
\tableofcontents%


\chapter{Welcome to \ctshortname}%
\setheader{{\it Welcome}}{}{}{}{}{{\it Welcome}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

Welcome to \ctname, the easy way to configure wxWidgets.
Instead of tweaking a setup.h file, or typing a long configure
command, you can now check and uncheck options in a convenient
GUI tool, read the relevant reference document for each
option, and save the setup.h file or configure command file.

\begin{itemize}\itemsep=0pt
\item For release information, please see \helpref{Release Notes}{releasenotes}.
\item For a tour of the main windows in \ctshortname, please see the \helpref{User Interface}{documentui} section.
%\item For a quick tutorial, go straight to \helpref{Getting Started}{gettingstarted}.
\item For tips and troubleshooting, see the \helpref{How To}{howto} section.
\end{itemize}

\chapter{Contacts}%
\setheader{{\it Contacts}}{}{}{}{}{{\it Contacts}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

The \ctname home page is at:

{\tt \cturl}

For help with \ctshortname or to report bugs,
please go to the wxWidgets web site.

\section{Credits}

\begin{center}
{\bf (c) 2003 Julian Smart, Anthemion Software}\hrule

{\it Designed by}

{\bf Julian Smart}

{\it Programmed by}

{\bf Julian Smart}

{\it Additional programming by}

{\bf The wxWidgets development team}

\end{center}

\chapter{Installation}%
\setheader{{\it Installation}}{}{}{}{}{{\it Installation}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

{\bf On Windows:}

Please run the installation program. This will create a program
folder called \ctname (or other name if you have chosen a different name). This
folder can be accessed via the Start menu under Programs. The
folder contains shortcuts to the program, help file, and Uninstall program.

You can uninstall \ctshortname either by double-clicking the Uninstall \ctshortname icon
in the \ctname group, or by invoking the Windows Control Panel,
double-clicking on Add/Remove Programs, and then choosing the \ctshortname item.

{\bf On Linux:}

Unarchive wxconfigtool-x.xx.tar.gz to a suitable location
in your filesystem. A directory of the form wxconfigtool-x.xx
(where x.xx is the version number) will be created.

Add the location to your PATH and run the application with
'wxconfigtool'. You may wish to set the environment variable
WXCONFIGTOOLDIR so that wxWidgets Configuration Tool can find its data files.

For example:

\begin{verbatim}
  % cd ~
  % tar xvfz wxconfigtool-1.01.tar.gz
  % export WXCONFIGTOOLDIR=`pwd`/wxconfigtool-1.01
  % export PATH=$PATH:$WXCONFIGTOOLDIR
  % wxconfigtool
\end{verbatim}

If you don't want to change your PATH, you could place a
script in a location already on your PATH, such as
/usr/local/bin. For example:

\begin{verbatim}
  #!/bin/sh
  # Invokes wxWidgets Configuration Tool
  export WXCONFIGTOOLDIR=/home/mydir/wxconfigtool-1.01
  $WXCONFIGTOOLDIR/wxconfigtool $*
\end{verbatim}

{\bf On Mac:}

Download and unarchive the HQX file, and drag the wxWidgets Configuration Tool folder to an appropriate location
on your hard disk. Then double-click on the 'wxconfigtool' executable.

\chapter{Release notes}\label{releasenotes}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

For licencing information, please see
the licence files in the installation directory:

\begin{itemize}\itemsep=0pt
\item licendoc.txt
\item gpl.txt
\item lgpl.txt
\item preamble.txt
\end{itemize}

\section{What's New?}\label{whatsnew}

{\bf Version 1.02, June 16th 2003}

\begin{itemize}\itemsep=10pt
\item The <b>Platform</b> group has been renamed
<b>Target</b>, since there can be multiple targets
per platform.
\item The Windows/Universal target has been added.
\end{itemize}

{\bf Version 1.01, June 14th 2003}

\begin{itemize}\itemsep=10pt
\item Added Find facility.
\end{itemize}

{\bf Version 1.0, June 11th 2003}

\begin{itemize}\itemsep=10pt
\item Initial version.
\end{itemize}

\section{Known issues}\label{knownissues}

The following problems are known to exist:

\begin{itemize}\itemsep=10pt
\item No issues as yet.
\end{itemize}

\section{To Do}\label{todo}

There are many things that could be done to make
this tool more useful, including the following.

\begin{itemize}\itemsep=10pt
\item Allow full platform-specific dependency specification
as mentioned in \helpref{How to specify platform-specific dependencies}{platformdependencies}.
\item Allow \ctshortname to invoke configure and make, with an output
window showing build status.
\item Distinguish between template files and settings file; allow
application of template files to settings files, and vice versa.
\item Implement support for string, integer, float settings.
\item Write a configuration browser.
\item Add description, date and author information to the settings file.
\item Command-line mode with ability to change settings from
the command-line. Just like configure :-)
\item Decide on standard location for settings files.
\item Integrate with new (and old?) build systems.
\item Allow customization of font and colour.
\item Show all calculated dependencies for each config item.
\item Add a search facility.
\end{itemize}

\section{Differences between Windows, Linux and Mac versions}\label{platformdifferences}

Although every effort has been made to make wxWidgets Configuration Tool work
the same way on different environments, some small differences
are inevitable.

\begin{itemize}\itemsep=10pt
\item Screenshots illustrate the Windows version; the Linux
and Mac windows and dialogs will be slightly different, but with equivalent
functionality.
\item Dialogs under Windows often have a '?' button on the title
bar, for context-sensitive help. Under Linux, this button is
on the dialog itself, usually near the OK or Close button.
On the Mac, context-sensitive help is not yet supported.
\item Under Linux, online help invoked from the {\bf Help} button
in modal dialogs is itself modal. That is, you have to quit
the help window to return to the dialog. On Windows, you can
switch back to the dialog without quitting the help viewer.
\item On Windows and Linux, context menus are invoked with
right-click. On Mac, use control-click.
\end{itemize}

\chapter{\ctshortname user interface}\label{documentui}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

This section describes the main elements of the \ctname user interface.

The \ctshortname main window looks like this:

\begin{center}
\image{}{screen01.png}
\end{center}

\section{Menubar}

%\image{}{menubar.gif}

The \helpref{menubar}{menubarcommands} allows you to perform many functions
such as loading and saving files, creating new configuration items,
undo/redo, invoking help, and so on. Try to remember the keyboard shortcuts that are
displayed next to the menu item labels - they can save you a lot of time
and make your \ctshortname experience more natural and enjoyable.

\section{Main toolbar}

%\image{}{toolbar.gif}

The main toolbar gives quick access to commonly-used commands.
If you hold your mouse pointer over the toolbar buttons, a tooltip pops up with a short description
of the button's function.

You can choose to hide the toolbar altogether
using the {\bf View | Show Toolbar} menu command.

You can find out more about in the \helpref{toolbar commands}{toolbarcommands} topic.

\section{Configuration window}

%\image{}{configwindow.gif}

The biggest area of \ctshortname is taken up by the configuration window.

On the left is a hierarchy of settings that can be customized.
You can check and uncheck most settings, but you will find that
many settings are disabled because they depend on other settings
being enabled (or disabled).

As an end user, you will probably only want to enable or disable
options, but it's possible you may wish to update the structure
of the settings file itself. In which case you can use the
{\bf Edit} menu to add, remove, or rename items; and you can
add custom properties to an item, but this is usually only
useful for a developer of the tool to do.

Undo/Redo can be applied to most editing commands, but (currently) not
enabling and disabling operations.

There are three tabs in the main window: {\bf Properties}, {\bf Setup.h},
and {\bf Configure}. The Properties tab contains the properties
for the selected option. Setup.h shows the setup file,
and there are buttons to allow you to copy the file to the clipboard
and regenerate the file. Similarly, the Configure tab shows
the script that will invoke configure.

The property editor allows you to show detailed information
about the option. A description for each property is shown
when you click on the property. You can also edit property values,
either by clicking and typing, or by double-clicking or clicking
on the {\bf Edit...} button. If a special editor is defined for
the property type, it will be shown.

You can invoke help for the selected option, by clicking
on the question mark toolbar button or the {\bf Help | Configuration Item Help} menu
item. If there is a help topic defined for the option, the
wxWidgets reference manual will be opened at that topic.

\begin{comment}
\chapter{Getting started: a step-by-step guide}\label{gettingstarted}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

This section will quickly get you up and running with \ctshortname. Click
on \helpref{Step 1}{step1} to start. If you are
using a Mac, please interpret 'left-click' to mean 'click', and
'right-click' to mean 'control-click'.

\section{Step 1: creating a new configuration}\label{step1}

When you run \ctshortname for the first time, you are presented with an
empty configuration window.

Go to \helpref{Step 2}{step2} to learn how to do the next thing.

\section{Step 2: doing something else}\label{step2}

Go to \helpref{Step 3}{step3} to learn how to do a third thing.

\section{Step 3: a third thing}\label{step3}

Go to \helpref{Step 4}{step4} to learn about saving your document and reloading it.

\section{Step 4: saving and loading documents}\label{step4}

You may wish to save a document, so you can come back to it later. Click on {\bf File | Save} or
the \image{}{save.png} toolbar button. The first time you save the file, you will be prompted
for a filename: you can accept the default one provided, or choose another.

To reload the document, click on {\bf File | Open...} or the \image{}{open.gif} toolbar button.
If you are working on another document, you will be prompted to save it first.

Go to \helpref{Step 5: generating configurations}{step5}

\section{Step 5: generating configurations}\label{step5}

Todo.

Go to \helpref{Step 6: where next?}{step6}

\section{Step 6: where next?}\label{step6}

Congratulations! You have learnt how to create, edit, save, and load configuration
files.

To get to know \ctshortname more thoroughly, here are some further things you
can do.

\begin{itemize}
\item Read the \helpref{How To}{howto} section.
\item Use the help facilities: most dialogs have a {\bf Help} button for a general description, and they
also have a {\bf "?"} button for getting information on individual controls on a dialog.
\item Explore the menubar and the menus that appear when you right-click over
the window background and individual cards.
\end{itemize}

\end{comment}

\chapter{Using menubar commands}\label{menubarcommands}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

%\image{}{menubar.gif}

This section describes the menubar commands. Commands
that are not available in the current context are disabled (shown in grey).

\section{File menu}

The File menu shows commands that are mostly related to working
with files.

\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf New...} (Ctrl+N)}{Creates a new \ctshortname document.}
\twocolitem{{\bf Open...} (Ctrl+O)}{Opens an existing document.}
\twocolitem{{\bf Close} (Ctrl+W)}{Closes the current document.}
\twocolitem{\hrule}{\htmlonly{\hrule}}
\twocolitem{{\bf Save} (Ctrl+S)}{Saves the current document.}
\twocolitem{{\bf Save As...}}{Saves the current document under a new name.}
\twocolitem{\hrule}{\htmlonly{\hrule}}
\twocolitem{{\bf Save Setup.h...} (Ctrl+H)}{Saves the generated setup.h file in the specified location.}
\twocolitem{{\bf Save Configure Script...} (Ctrl+G)}{Saves the generated script containing a configure command in the specified location.}
\twocolitem{\hrule}{\htmlonly{\hrule}}
\twocolitem{{\bf Go} (F5)}{Saves the generated setup.h file or configurewx.sh script (according to the default setting) in the last-saved.}
\twocolitem{\hrule}{\htmlonly{\hrule}}
\twocolitem{{\bf Exit} (Alt+F4)}{Exits the program.}
\end{twocollist}

\section{Edit menu}

The Edit menu shows commands that are related to editing
document elements.

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf Undo} (Ctrl+Z)}{Undoes the last undoable action.}
\twocolitem{{\bf Redo} (Ctrl+Y)}{Redoes the last redoable action.}
\twocolitem{\hrule}{\htmlonly{\hrule}}
\twocolitem{{\bf Cut} (Ctrl+T)}{Cuts the selected option and places it on the clipboard.}
\twocolitem{{\bf Copy} (Ctrl+C)}{Copies the selected option.}
\twocolitem{{\bf Paste} (Ctrl+V)}{Pastes an option from the clipboard to the position. Whether the
option is pasted as a child or sibling of the selection is determined by whether
the selection is a folder or not. If you want finer control, right-click on the
item in the tree control and select one of the paste commands.}
\twocolitem{\hrule}{\htmlonly{\hrule}}
\twocolitem{{\bf Add Option}}{Shows a menu for adding one of several option types.}
\twocolitem{\hrule}{\htmlonly{\hrule}}
\twocolitem{{\bf Custom Property}}{Shows a menu for adding, editing or deleting a custom option property.}
\twocolitem{\hrule}{\htmlonly{\hrule}}
\twocolitem{{\bf Delete Option}}{Deletes the selected option.}
\twocolitem{{\bf Rename Option}}{Shows a dialog for renaming the selected option.}
\twocolitem{\hrule}{\htmlonly{\hrule}}
\twocolitem{{\bf Find...}}{Shows the Find dialog, allowing you to search for text
within name, description and notes for each item.}
\end{twocollist}

\section{View menu}

The View menu gives you commands related to showing or hiding windows
and various other preferences.

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf Show Toolbar}}{Shows or hides the toolbar, beneath the menubar.}
\twocolitem{\hrule}{\htmlonly{\hrule}}
\twocolitem{{\bf Settings...} (Ctrl+T)}{Shows the \helpref{Settings Dialog}{settingsdialog}, which
relate to application-wide settings.}
\end{twocollist}

\section{Help menu}

The Help menu gives you commands related to getting help.

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf Contents}}{Invokes the on-line help, showing the contents page.}
\twocolitem{{\bf wxWidgets Help Contents}}{Invokes the on-line wxWidgets reference manual, showing the contents page.}
\twocolitem{\hrule}{\htmlonly{\hrule}}
\twocolitem{{\bf Configuration Option Help} (F1)}{Invokes the on-line wxWidgets reference manual at the topic for the selected option (if a topic
is defined).}
\twocolitem{{\bf What's This?}}{Click to get help on a window or configuration option.}
\twocolitem{\hrule}{\htmlonly{\hrule}}
\twocolitem{{\bf About...}}{Displays a dialog giving a brief description of the program.}
\end{twocollist}

\chapter{Using context menu commands}\label{contextmenucommands}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

This section describes the context menu commands available when you right-click.
On the Mac, this is achieved with control-click.

\section{Configuration tree context menu}

This menu is shown when you right-click over the configuration tree window background.
On the Mac, this is achieved with control-click.

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf Paste before this option}}{Pastes the clipboard option before the clicked-on option.}
\twocolitem{{\bf Paste after this option}}{Pastes the clipboard option after the clicked-on option.}
\twocolitem{{\bf Paste as child of this option}}{Pastes the clipboard option as a child of the clicked-on option,
if it is a group option.}
\twocolitem{\hrule}{\htmlonly{\hrule}}
\twocolitem{{\bf C&opy}}{Copies the clicked-on option to the internal clipboard.}
\twocolitem{{\bf Cu&t}}{Copies the clicked-on option to the internal clipboard, and
deletes the option from the tree.}
\end{twocollist}

\chapter{Using toolbar commands}\label{toolbarcommands}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

This section describes the toolbar commands.

%\image{}{toolbar.gif}

The toolbar provides quick access to commonly-used
commands.

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\image{}{new.png}{\bf  New Document}}{Creates a new document.}
\twocolitem{\image{}{open.png}{\bf  Open Document}}{Opens an existing document, closing the currently open document.}
\twocolitem{\image{}{save.png}{\bf  Save Document}}{Saves the current document.}
\twocolitem{\hrule}{\htmlonly{\hrule}}
\twocolitem{\image{}{undo.png}{\bf  Undo}}{Undoes the last command.}
\twocolitem{\image{}{redo.png}{\bf  Redo}}{Redoes the last command.}
\twocolitem{\hrule}{\htmlonly{\hrule}}
\twocolitem{\image{}{copy.png}{\bf  Copy}}{Copies the selected option to an internal clipboard.}
\twocolitem{\image{}{cut.png}{\bf  Cut}}{Cuts the selected option and copies it to the internal clipboard..}
\twocolitem{\image{}{paste.png}{\bf  Paste}}{Pastes the option from the clipboard to the configuration tree.}
\twocolitem{\hrule}{\htmlonly{\hrule}}
\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.}
\twocolitem{\hrule}{\htmlonly{\hrule}}
\twocolitem{\image{}{help.png}{\bf  Help}}{Shows the wxWidgets manual topic for the
\twocolitem{\image{}{helpcs.png}{\bf  Context Help}}{Shows a context-sensitive help
cursor; click on a window to show brief help about that window.}
selected configuration item.}
\end{twocollist}

\chapter{Using dialogs}\label{dialogs}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

Most dialogs have a {\bf "?"} button on their caption to provide context-sensitive help.
Click on this and then on a control
in a dialog to get quick help on that control. You can also click on the {\bf Help} button
for more detailed help on the dialog.

\section{Settings dialog}\label{settingsdialog}

This dialog has a number of tabs to allow you to
edit different categories of settings that are applicable
to the application as a whole.

\subsection{General settings dialog}\label{generalapplicationsettingsdialog}

The General Settings Dialog allows you to set a variety of \ctshortname options.

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf Load last document on startup}}{If checked, the last viewed document will
be reloaded when \ctshortname starts up.}
% If the application terminated abnormally, this
%option will be switched off the next time \ctshortname runs in case there was a problem with
%the document file.}
%\twocolitem{{\bf Auto-save document}}{If checked, \ctshortname will regularly
%save the document to a temporary file. If \ctshortname or the operating system
%should terminate abnormally, the next time \ctshortname is run it will
%check for an auto-save file and ask if you wish to open that file.}
%\twocolitem{{\bf Show welcome dialog on startup}}{If checked, the \helpref{Welcome Dialog}{welcomedialog} will
%be shown on startup.}
\twocolitem{{\bf Show tooltips}}{If checked, tooltips will be shown in most dialogs, when you hover
the mouse pointer over a control.}
\end{twocollist}

\subsection{Location settings dialog}\label{locationsettingsdialog}

The Location Settings Dialog allows you to choose various locations.

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf wxWidgets hierarchy}}{This determines where \ctshortname will look
when prompting for filenames.}
\twocolitem{{\bf Use WXWIN environment variable}}{Check this to use
the value of the WXWIN variable instead of the path entered in the text field.}
\end{twocollist}

\chapter{Using keyboard shortcuts}\label{keyboardshortcuts}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

You can make your \ctshortname experience even smoother by
using handy keyboard shortcuts. Note that some shortcuts are
dependent on context: that is, which control has the focus.

\twocolwidtha{3cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf Ctrl + C}}{Copies the selected option to the clipboard.}
\twocolitem{{\bf Ctrl + H}}{Saves the setup.h file.}
\twocolitem{{\bf Ctrl + G}}{Saves the configure script file.}
\twocolitem{{\bf Ctrl + N}}{Creates a new \ctshortname file.}
\twocolitem{{\bf Ctrl + O}}{Opens a \ctshortname file.}
\twocolitem{{\bf Ctrl + S}}{Saves the current \ctshortname document.}
\twocolitem{{\bf Ctrl + T}}{Shows the \helpref{Settings Dialog}{settingsdialog}.}
\twocolitem{{\bf Ctrl + V}}{Pastes the option on the clipboard (if any) to the configuration tree.}
\twocolitem{{\bf Ctrl + W}}{Closes the current \ctshortname document.}
\twocolitem{{\bf Ctrl + X}}{Cuts the selected option and copies it to the clipboard.}
\twocolitem{{\bf Ctrl + Y}}{Redoes the previously undone edit.}
\twocolitem{{\bf Ctrl + Z}}{Undoes the previous edit.}
\twocolitem{{\bf F1}}{Shows the online help for the selected item.}
\twocolitem{{\bf Alt + F4}}{Closes \ctshortname.}
\end{twocollist}

\chapter{Reference}\label{reference}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

\section{The dependency evaluation algorithm}

\ctshortname pre-calculates a list of all dependencies
for each option -- this is a kind of reverse-pointer version
of all the dependencies associated with each item. So
if option {\bf a} has a {\bf requires} option specifying
{\bf b}, then {\bf b} will end up with a dependency list
containing {\bf a} and any other options that refer to it.

When the user enables or disables an option ({\bf b}),
the list of dependencies for that option is visited,
and for each mentioned option ({\bf a}), all its dependency information
is evaluated. This may result in the option {\bf a} being
(de)selected and perhaps deactivated (made insensitive).

The results of this change are propagated to dependents of
{\bf a}, recursively, so several options may flip state
as the result of checking the original option.

The parent-child relationship of a check or radio
group and its children is considered to be a virtual
'requires' dependency. Mutual exclusivity is also
taken into account if the option is a radio option
or group. For each radio option, all other mutually
exclusive options need to be listed. See the
{\bf Target} group for an example of this.

The results of these dependencies can be overridden by
indeterminate-if, which is done last of all and can
make the option user-selectable when otherwise it
would be constrained to be enabled or disabled.

\section{How \ctshortname generates the configure commands}

If the {\bf configure} property isn't empty,
\ctshortname will output the string as a parameter
to configure.

The configure command is taken to be the command to
use if the option is checked. If the option is
unchecked, the 'enable' or 'with' is replaced with
'disable' or 'without'.

TODO: should we distinguish between the case
where a setting is not passed to configure (using
the default), versus the case where it's specified but disabled?
It's probably a good idea to make all the options
explicit, but on the other hand it makes for a very long
command line.

\ctshortname checks for the presence of a
{\bf builtin} custom boolean property and appends 'builtin' or
'sys' to the configure command depending on where
the {\bf builtin} setting is checked or unchecked.
We also allow for passing strings, e.g. for --with-rpath=DIR,
by using the {\bf value} custom string property.

\section{How \ctshortname generates the setup.h file}

The {\bf Target} group is ignored. In all other
cases, if the setting is prefixed by wxUSE_...
and it's a boolean setting, \ctshortname will
output 1 or 0 depending on the setting state.

A few settings that don't have the wxUSE_...
convention are also checked for and processed.


\chapter{How To...}\label{howto}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

A variety of topics to help you get the best from \ctshortname.

\section{How to specify dependencies}\label{dependencies}

To ensure consistency throughout the configuration,
\ctshortname allows specification of dependencies, essentially
a list of option names that should be considered in evaluating
whether an option should be enabled or disabled. In addition,
if the option is constrained to always be disabled
or enabled in the current context, then it is greyed out
(deactivated) to prevent the user from changing the state.

There are five kinds of dependencies: requires, precludes,
enabled-if, enabled-if-not, and indeterminate-if. Each one represents a
relationship between the current option (a) and one
or more named options (b). For the sake of argument
we will consider only one other option, but multiple
options are taken to mean (b1 or b2 or b3 or ...)
Below the allowed combined states of a and b are
listed for each kind of dependency.

1. a {\bf requires} b

For example, wxUSE_DRAG_AND_DROP requires wxUSE_OLE.

\begin{verbatim}
    a        b

    1        1
    0        1
    0        0
\end{verbatim}

2. a {\bf precludes} b

For example, wxUSE_ODBC precludes wxUSE_UNICODE.

\begin{verbatim}
    a        b

    1        0
    0        0
    0        1
\end{verbatim}


3. a {\bf enabled-if} b

For example, __WXUNIVERSAL__ enabled-if X11 or MGL

\begin{verbatim}
    a        b

    1        1
    1        0
    0        0
\end{verbatim}

4. a {\bf enabled-if-not} b

For example, wxUSE_TOOLBAR_SIMPLE enabled-if-not wxUSE_TOOLBAR_NATIVE.

\begin{verbatim}
    a        b

    1        0
    0        1
    1        1
\end{verbatim}

5. a {\bf indeterminate-if} b

For example, wxUSE_UNICODE indeterminate-if Custom.

\begin{verbatim}
    a        b

    ?        1
\end{verbatim}

This overrides all the other dependencies, and allows you
to make an option user-choosable in some circumstances,
when otherwise it would be constrained to be either enabled or
disabled. You may need to use an intermediate option to
make sensible use of this: for example make the intermediate
option dependent on a number of factors, such as Unicode not being
available on some platforms.

\section{How to specify platform-specific dependencies}\label{platformdependencies}

You can associate one or more options as part of the
option's {\bf context}. In the case of wxUSE_OLE,
the context contains __WXMSW__, because it's a Windows-specific
option. This is used when calculating dependencies, as
follows. If either option involved in a dependency
relationship is not part of the current context, that
is, none of the options in its {\bf context} property is currently
enabled, then it is ignored in the dependency calculation.

This allows the dependency 'wxUSE_DRAG_AND_DROP requires wxUSE_OLE'
to only be evaluated when __WXMSW__ is enabled.

It doesn't quite cover all bases, however, because
it cannot express that the {\it dependency} itself
is platform specific. You might have a platform-specific
dependency that exists between two options that are
perfectly valid for any platform. For example, we
can't capture the notion that wxUSE_LISTBOX
should be required if wxUSE_COMBOBOX is set,
but only for __WXUNIVERSAL__. We could do it
by complicating the dependency syntax, for example:

wxUSE_COMBOBOX requires wxUSE_LISTBOX:__WXUNIVERSAL__

This means that the dependency should only be
evaluated if __WXUNIVERSAL__ is enabled.
This has not been implemented yet.

\section{How to specify custom properties}\label{customproperties}

You can add custom properties to any option, but
currently only {\bf option} and {\bf value} are
recognised by \ctshortname.

\ctshortname checks for the presence of a
{\bf builtin} boolean custom property and appends 'builtin' or
'sys' to the configure command depending on where
the {\bf builtin} setting is checked or unchecked.
We also allow for passing strings, e.g. for --with-rpath=DIR,
by using the {\bf value} string custom property.

\begin{comment}

\begin{helpglossary}

\gloss{thing}\label{thing}

A glossary entry.

\end{helpglossary}
\end{comment}

\rtfonly{%
\addcontentsline{toc}{chapter}{Index}
\printindex%
\setheader{{\it INDEX}}{}{}{}{}{{\it INDEX}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%
}
\winhelponly{
\chapter{Popups}\label{popups}

} % WinHelp only

\end{document}