configtool.tex

Wxpython Implemented on Windows CE, Source code

\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}