%vim:set tw=68:
% $Source: /home/bricks/source/greater/cvs/greaterrepository/sciparam/doc/sciparam-manual.tex,v $
% $Id: sciparam-manual.tex,v 1.18 2005-11-16 11:12:03 frank Exp $

%begin{latexonly}
\documentclass[a4paper,twoside,BCOR19mm]{scrbook}
%end{latexonly}
\usepackage{html}
\begin{htmlonly}
\documentclass[a4paper,oneside]{book}
\end{htmlonly}
\usepackage[latin1]{inputenc}
\usepackage{times}
\usepackage{graphicx}

%begin{latexonly}
\usepackage{parskip}
\usepackage{fancyhdr}
\usepackage{mdwlist}

\def\CVS$#1: #2 ${\expandafter\def\csname CVS#1\endcsname{#2}}
\CVS$Id: sciparam-manual.tex,v 1.18 2005-11-16 11:12:03 frank Exp $
%end{latexonly}

%----------------------------------------------
% Document DATE and VERSION
% set these values when releasing a new version

\newcommand{\documentdate}{16 November 2005}
\newcommand{\documentversion}{1.1.0+cvs}
\newcommand{\documentID}{\CVSId}
\newcommand{\softwareversion}{1.1.0+cvs}

\begin{htmlonly}
\newenvironment{basedescript}[1]{\begin{description}}{\end{description}}
\end{htmlonly}


%----------------------------------------------

% Makros:
%       \Fig{figure}{text}      : creates an mbox around 'figure' and
%                                 writes 'text' at the bottom with leading
%                                 'Fig. section.figno:'.
%                                 Example:
%                                 \Fig{\epsfxsize30mm \epsffile{x.eps}}{the x}\\%       \FigNoEntry{}{}         : same as above, no entry in figures list
%
%       \FigCaption{}           : line with figure caption, setting figure
%                                 counter and figures list
%

%****************************************************************************
%       Figure makro for graphics continously enumerated.
%

\newcounter{FigCnt}[chapter]
\newcommand{\Fig}[3]%
{
        \refstepcounter{FigCnt}
        \addcontentsline{lof}{figure}%
                {\protect\numberline{\thechapter.\arabic{FigCnt}}{#2}}
        \mbox{#1}
\nopagebreak

        {Fig. \thechapter.\arabic{FigCnt}: #3}
}

\newcommand{\FigNoEntry}[2]%
{
        \refstepcounter{FigCnt}
        \mbox{#1}
\nopagebreak

        {Fig. \thechapter.\arabic{FigCnt}: #2}
}

\newcommand{\FigCaption}[1]%
{
        \refstepcounter{FigCnt}
        \addcontentsline{lof}{figure}%
                {\protect\numberline{\thechapter.\arabic{FigCnt}}{#1}}

        %{Figure \thechapter.\arabic{FigCnt}: #1}
}

\begin{document}

%begin{latexonly}
%-----------------------------------
% define header/footer
% The settings here are for single page documents (only odd page set)

% for some pages latex switches back to pagestyle plain :-(
\fancypagestyle{plain}{%
	\fancyhf{} % clear all header and footer fields
	\fancyhead[LO,RE]{\footnotesize SciParam Manual\\ \leftmark}
	\fancyfoot[RO,LE]{\footnotesize Intevation GmbH} % Author
	\fancyfoot[CO,CE]{\footnotesize \thepage/\pageref{theverylastpage}}
	% set the document title for the footer here!
	\fancyfoot[LO,RE]{\footnotesize \documentdate 
	\\\documentID}
	\renewcommand{\footrulewidth}{0.4pt}
}

% and now define pagestyle fancy
\fancyhead{} % clear all fields
\fancyhead[LO,RE]{\footnotesize SciParam Manual\\ \leftmark}

\fancyfoot{}% clear all fields
\fancyfoot[RO,LE]{\footnotesize Intevation GmbH} % Author
\fancyfoot[CO,CE]{\footnotesize \thepage/\pageref{theverylastpage}}
% set the document title for the footer here!
\fancyfoot[LO,RE]{\footnotesize \documentdate 
\\\documentID}

%end{latexonly}

\renewcommand{\footrulewidth}{0.4pt}

%begin{latexonly}
\newcommand{\imagescale}{0.67}
%end{latexonly}
\begin{htmlonly}
\newcommand{\imagescale}{1}
\end{htmlonly}

\pagestyle{fancy}

%-----------------------------------

\parindent0cm

%-----------------------------------
% TITLE PAGE

%begin{latexonly}
{
	\includegraphics[width=0.3\textwidth]{./images/intevation-logo.eps}\\[0.1cm]

	 {\tt http://intevation.net}\\[2.0cm] 
}

% reenter the TITLE here
{
	\sffamily\bfseries\Large 
	SciParam \softwareversion\\[0.5cm]
	\huge SciParam Manual\\[4cm]

}
%end{latexonly}

\begin{htmlonly}
	{\huge Manual for SciParam \softwareversion{}}
\end{htmlonly}


% a possible SUBTITLE
\begin{flushleft}
	\sffamily\bfseries\large 
	Scientific Parameter Dialogs in wxPython based user interfaces.\\
%	by Intevation GmbH\\[0.5cm]
\end{flushleft}

\thispagestyle{empty}


\vfill

{\sffamily\small
	\htmladdnormallink{Intevation GmbH}{http://intevation.net/}\\
	Georgstraße 4\\
	D-49074 Osnabrück\\
	Germany\\
	\\
	Date: \documentdate
}


\newpage


\vfill

This document has been designed with \LaTeX{}.
It is available as source code and PDF.\\
The HTML version is generated with \latextohtml.\\

\begin{tabular}{l l}
Version:	& \documentversion \\
Date:		& \documentdate \\
Author:		& Thomas Arendsen Hein \\
		& \small (Before my wedding on July 30th, 2003
			my name was Thomas Köster) \\
\end{tabular}

\vfill

\begin{center}Copyright (c) 2002, 2003 \htmladdnormallink{Intevation GmbH}{http://intevation.net/}.\end{center}

    Permission is granted to copy, distribute and/or modify this document
    under the terms of the GNU Free Documentation License, Version 1.2
    or any later version published by the Free Software Foundation;
    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
    A copy of the license is included in the section entitled ``GNU
    Free Documentation License''.

\tableofcontents

%-------------------------Chapter-------------------------------------

\chapter{Introduction}

SciParam is a Python package to easily add additional quality control for
entering scientific parameters in wxPython-based user interfaces.
SciParam is the basis for the parameter dialogs of GREAT-ER II
(Geo-referenced Regional Exposure Assessment Tool for European Rivers).

\section{Links}

\begin{tabular}{l l}
Homepage	& {\tt \htmladdnormallink{http://great-er.intevation.org/sciparam/}{http://great-er.intevation.org/sciparam/}} \\
Bug Tracker	& {\tt \htmladdnormallink{http://intevation.de/rt/webrt?q\_queue=great-er}{http://intevation.de/rt/webrt?q\_queue=great-er}} \\
CVS		& {\tt \htmladdnormallink{http://intevation.de/cgi-bin/viewcvs-greater.cgi/sciparam/}{http://intevation.de/cgi-bin/viewcvs-greater.cgi/sciparam/}} \\
Mailing List	& {\tt \htmladdnormallink{http://intevation.de/mailman/listinfo/great-er-list}{http://intevation.de/mailman/listinfo/great-er-list}} \\
\end{tabular}


\section{License}

SciParam - Scientific Parameter Dialogs\\
Copyright (C) 2002, 2003  Intevation GmbH\\
Georgstraße 4, D-49074 Osnabrück, Germany

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

%-------------------------Chapter-------------------------------------

\chapter{Installing SciParam}

\section{Requirements}

\begin{basedescript}{\desclabelwidth{7mm}\desclabelstyle{\nextlinelabel}}
\item [Python from {\tt \htmladdnormallink{http://python.org/}{http://python.org/}}]
Tested with version 2.1 and 2.2, but should work with newer versions.

\item [wxPython from {\tt \htmladdnormallink{http://wxPython.org/}{http://wxPython.org/}}]
  Tested with version 2.2.9 and current 2.4.0 branch.\\
  Later versions of SciParam may require at least wxPython 2.4 branch.

\end{basedescript}


\section{Installation}

To install SciParam, just make sure the SciParam-\softwareversion
directory is in the PYTHONPATH environment variable.
For example, if you extracted SciParam-\softwareversion.tar.bz2 or \\
SciParam-\softwareversion.zip to /home/fred/, then you would have
something like:

{\tt export PYTHONPATH=\$PYTHONPATH:/home/fred/SciParam-\softwareversion/}

in your \~{}/.bash\_profile, etc.

If you use Windows NT, 2000, or XP, then
set your environment variables by right-clicking on My Computer and
selecting Properties. If you use some other version of windows, you'll
need to set the variable at a command prompt, or in autoexec.bat, with
the 'set' command.

If you'd like to install SciParam system-wide on your machine and into the
default PYTHONPATH, you can use setup.py to do so:

{\tt \# python ./setup.py install}

Be sure to run setup.py with appropriate privileges (root under Unix).

For Windows there is a self-installing package:
``SciParam-\softwareversion.win32.exe''

%-------------------------Chapter-------------------------------------

\include{sciparam-manual-gui}

%-------------------------Chapter-------------------------------------

\chapter{Developer Documentation}

\section{Creating Parameters}

\subsection{Import of Parameter Classes}

The package SciParam contains the following parameter classes:

\begin{itemize}
\item FloatParam
\item DistParam
\item IntParam
\item StringParam
\item FilenameParam
\item ChoiceParam
\end{itemize}

SciParam supports accessing them in several ways, as shown here with
StringParam:

\begin{itemize}

\item \begin{verbatim}
import SciParam
param = SciParam.StringParam('Name')
\end{verbatim}

\item \begin{verbatim}
import SciParam.parameter
param = SciParam.parameter.StringParam('Name')
\end{verbatim}

\item \begin{verbatim}
from SciParam import StringParam
param = StringParam('Name')
\end{verbatim}

\end{itemize}

This one is deprecated, except for saving keystrokes in interactive sessions:

\begin{itemize}

\item \begin{verbatim}
from SciParam import *
param = StringParam('Name')
\end{verbatim}

\end{itemize}

Every parameter instance must have a name and can have a description,
a unit, a default value, a current value and a comment.
Additionally there are some boolean flags (required, notunknown,
ui\_disabled, ui\_locked)
and method hooks (hook\_isvalid, hook\_isusual, hook\_updated,
hook\_estimate, hook\_can\_estimate).

\subsection{Import of Classes Range and Distribution}

The parameter classes can build ranges and distributions from a string,
therefore you don't need to import these classes very often.
If you want to import them, use one of these methods:

\begin{itemize}

\item \begin{verbatim}
import SciParam
range1 = SciParam.Range()
dist1 = SciParam.Distribution()
\end{verbatim}

\item \begin{verbatim}
import SciParam.range
import SciParam.distribution
range1 = SciParam.range.Range()
dist1 = SciParam.distribution.Distribution()
\end{verbatim}

\item \begin{verbatim}
from SciParam import Range, Distribution
range1 = Range()
dist1 = Distribution()
\end{verbatim}

\end{itemize}

This one is deprecated, except for saving keystrokes in interactive sessions:

\begin{itemize}

\item \begin{verbatim}
from SciParam import *
range1 = Range()
dist1 = Distribution()
\end{verbatim}

\end{itemize}

\subsection{Using Parameters with Ranges and Distributions}

\begin{verbatim}
parameters = [
    StringParam('Name', 'a unique identifier', value='Silicon',
                required=1, maxlength=20, comment='A comment.'),
    IntParam('Atomic No', value=14, wrange='[1;260]', erange='[1;oo['
             description='Number in the periodic table of elements'),
    FloatParam('Atomic Mass', None, value=28.0855, erange='[0;oo['),
    ChoiceParam('Crystal', 'crystal structure',
                choices=[None, 'simple cubic', 'face centered cubic',
                         'body centered cubic', 'diamond cubic',
                         'tetragonal', 'orthorombic', 'monoclinc'],
                value='face centered cubic',
                default='face centered cubic', long=1),
    DistParam('Temperature', 'temperature of samples', '°C',
              value='17.5;3.7/normal', erange='[-273.15;oo['),
    ChoiceParam('Verified', 'Have these values been checked?',
                choices=ChoiceParam.yes_no, value=0, default=1),
]
\end{verbatim}

\clearpage
\section{Creating Dialogs and Notebooks}

\subsection{Import of Dialog Classes}

The package SciParam.UI contains the following dialog classes:

\begin{itemize}
\item ParameterDialog
\item ParameterNotebookDialog
\end{itemize}

SciParam supports accessing them in several ways:

\begin{itemize}

\item \begin{verbatim}
import SciParam.UI
dialog = SciParam.UI.ParameterDialog(...)
notebook = SciParam.UI.ParameterNotebookDialog(...)
\end{verbatim}

\item \begin{verbatim}
from SciParam.UI.dialog import ParameterDialog
from SciParam.UI.notebook import ParameterNotebookDialog
dialog = ParameterDialog(...)
notebook = ParameterNotebookDialog(...)
\end{verbatim}

\item \begin{verbatim}
from SciParam.UI import ParameterDialog, ParameterNotebookDialog
dialog = ParameterDialog(...)
notebook = ParameterNotebookDialog(...)
\end{verbatim}

\end{itemize}

This one is deprecated, except for saving keystrokes in interactive sessions:

\begin{itemize}

\item \begin{verbatim}
from SciParam.UI import *
dialog = ParameterDialog(...)
notebook = ParameterNotebookDialog(...)
\end{verbatim}

\end{itemize}

\clearpage
\subsection{Using Dialogs}

Using a ParameterDialog works much like using any other dialog in wxPython.
Additionally you have to specify a list of parameters and optionally a
number of columns (defaults to one) to use:

\begin{verbatim}
 parameters = [parameter1, parameter2, parameter3]
 dialog = ParameterDialog(parent, -1, 'Dialog Title',
                          parameters, columns=2)
 if dialog.ShowModal() == wxID_OK:
     print "OK"
 else:
     print "Cancel"
 for par in dialog.get_parameters():
     print "%s = %s (%s)" % (par.name, par, par.value)
     print " comment = %s" % par.comment
 dialog.Destroy()
\end{verbatim}

ParameterNotebookDialog takes a list of pages instead of parameters as
argument. Each page is a 2-tuple consisting of page name and parameter
list for this page:
\begin{verbatim}
 parameters1 = [parameter1, parameter2, parameter3]
 parameters2 = [parameter4, parameter5, parameter6]
 parameters3 = [parameter7, parameter8, parameter9]
 parameters = [('Page 1', page1),
               ('Page 2', page2),
               ('Page 3', page3)]
 dialog = ParameterNotebookDialog(parent, -1, 'Notebook Title',
                                  parameters, columns=2)
 if dialog.ShowModal() == wxID_OK:
     print "OK"
 else:
     print "Cancel"
 for par in dialog.get_parameters():
     print "%s = %s (%s)" % (par.name, par, par.value)
     print " comment = %s" % par.comment
 dialog.Destroy()
\end{verbatim}

%-------------------------Appendix-------------------------------------

\begin{appendix}

\chapter{Keyboard Shortcuts}

Keyboard shortcuts depend on your graphical environment, but here is a list
shortcuts known to work in MS Windows and GTK+:

\begin{center}
\begin{tabular}{|p{4cm}|p{9cm}|}
\hline
\tt <Tab> & Move to the next control.\\
\tt <Shift-Tab> & Move to the previous control.\\
\tt <Ctrl-Tab> & Move to the next notebook page.\\
\tt <Shift-Ctrl-Tab> & Move to the previous notebook page.\\
\tt <Enter> & Equivalent to clicking the OK button. \\
\tt <Escape> & Equivalent to clicking the Cancel button.\\
\tt <Space> & Equivalent to clicking the current button or radio button.\\
\tt <Alt-Down> & Drop down the list box of a selection list.\\
\tt <Cursor> & Change the current item in a selection list.\\
\tt <Alt-D> & Toggle the input focus between a parameter and its details box.\\
\hline
\end{tabular}
\end{center}


\include{gnufdl}


\chapter*{References}
\addcontentsline{toc}{chapter}{References}

\begin{description}

\item Sachs L. (1997)\\
    Angewandte Statistik\\
    Achte Auflage\\
    Springer, Berlin

\end{description}

\end{appendix}

\label{theverylastpage}
\end{document}
