\section{options.h File Reference}
\label{options_8h}\index{options.h@{options.h}}
Interface to the ROX options system. 

{\tt \#include $<$libxml/parser.h$>$}\par
\subsection*{Data Structures}
\begin{CompactItemize}
\item 
struct {\bf ROXOption}
\end{CompactItemize}
\subsection*{Typedefs}
\begin{CompactItemize}
\item 
typedef {\bf ROXOption} {\bf ROXOption}
\item 
typedef {\bf ROXOption} {\bf Option}
\item 
typedef void {\bf ROXOption\-Notify} (void)
\item 
typedef {\bf ROXOption\-Notify} {\bf Option\-Notify}
\item 
typedef GList $\ast$($\ast$) {\bf ROXOption\-Build\-Fn} ({\bf Option} $\ast$option, xml\-Node $\ast$node, gchar $\ast$label)
\item 
typedef {\bf ROXOption\-Build\-Fn} {\bf Option\-Build\-Fn}
\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
void {\bf rox\_\-options\_\-init} (const char $\ast$project)
\item 
void {\bf rox\_\-options\_\-init\_\-with\_\-domain} (const char $\ast$project, const char $\ast$domain)
\item 
void {\bf rox\_\-option\_\-register\_\-widget} (char $\ast$name, {\bf ROXOption\-Build\-Fn} builder)
\item 
void {\bf rox\_\-option\_\-check\_\-widget} ({\bf ROXOption} $\ast$option)
\item 
void {\bf rox\_\-option\_\-add\_\-int} ({\bf ROXOption} $\ast$option, const gchar $\ast$key, int value)
\item 
void {\bf rox\_\-option\_\-add\_\-string} ({\bf ROXOption} $\ast$option, const gchar $\ast$key, const gchar $\ast$value)
\item 
void {\bf rox\_\-options\_\-notify} (void)
\item 
void {\bf rox\_\-option\_\-add\_\-notify} ({\bf ROXOption\-Notify} $\ast$callback)
\item 
void {\bf rox\_\-option\_\-add\_\-saver} ({\bf ROXOption\-Notify} $\ast$callback)
\item 
Gtk\-Widget $\ast$ {\bf rox\_\-options\_\-show} (void)
\item 
void {\bf options\_\-init} (const char $\ast$project)
\item 
void {\bf options\_\-init\_\-with\_\-domain} (const char $\ast$project, const char $\ast$domain)
\item 
void {\bf option\_\-check\_\-widget} ({\bf Option} $\ast$option)
\item 
void {\bf option\_\-add\_\-int} ({\bf Option} $\ast$option, const gchar $\ast$key, int value)
\item 
void {\bf option\_\-add\_\-string} ({\bf Option} $\ast$option, const gchar $\ast$key, const gchar $\ast$value)
\item 
void {\bf options\_\-notify} (void)
\item 
Gtk\-Widget $\ast$ {\bf options\_\-show} (void)
\end{CompactItemize}


\subsection{Detailed Description}
Interface to the ROX options system. 

Manage a programs options in the same way as ROX-Filer does.

Derived from code written by Thomas Leonard, $<${\tt tal197@users.sourceforge.net}$>$.

How it works:

On startup:

\begin{itemize}
\item The $<$Choices$>$/PROJECT/Options file is read in, which contains a list of name/value pairs, and these are stored in the 'loading' hash table.\end{itemize}


\begin{itemize}
\item Each part of the filer then calls \doxyref{option\_\-add\_\-int()}{p.}{options_8c_153fae0d8a5b1d085bee0e4f4c693a75}, or a related function, supplying the name for each option and a default value. Once an option is registered, it is removed from the loading table.\end{itemize}


\begin{itemize}
\item If things need to happen when values change, modules register with \doxyref{rox\_\-option\_\-add\_\-notify()}{p.}{options_8c_414efd006ff8be46005c2c70d200b06d}.\end{itemize}


\begin{itemize}
\item \doxyref{rox\_\-option\_\-register\_\-widget()}{p.}{options_8c_123cd5242375773d07fc865d70da3477} can be used during initialisation (any time before the ROXOptions box is displayed) to tell the system how to render a particular type of option.\end{itemize}


\begin{itemize}
\item Finally, all notify callbacks are called. Use the \doxyref{ROXOption.has\_\-changed}{p.}{structROXOption_b44770041dfd37f15abcebd3f1fbf951} field to work out what has changed from the defaults.\end{itemize}


When the user opens the Options box:

\begin{itemize}
\item The Options.xml file is read and used to create the Options dialog box. Each element in the file has a key corresponding to an option named above.\end{itemize}


\begin{itemize}
\item For each widget in the box, the current value of the option is used to set the widget's state.\end{itemize}


\begin{itemize}
\item All current values are saved for a possible Revert later.\end{itemize}


When the user changes an option or clicks on Revert:

\begin{itemize}
\item The option values are updated.\end{itemize}


\begin{itemize}
\item All notify callbacks are called. Use the \doxyref{ROXOption.has\_\-changed}{p.}{structROXOption_b44770041dfd37f15abcebd3f1fbf951} field to see what changed.\end{itemize}


When OK is clicked:

\begin{itemize}
\item If anything changed then:\begin{itemize}
\item All the options are written to the filesystem\item The saver\_\-callbacks are called.\end{itemize}
\end{itemize}


\begin{Desc}
\item[Author:]Thomas Leonard, Stephen Watson \end{Desc}
\begin{Desc}
\item[Version:]\begin{Desc}
\item[Id]\doxyref{options.h}{p.}{options_8h},v 1.8 2005/10/15 10:48:49 stephen Exp \end{Desc}
\end{Desc}


\subsection{Typedef Documentation}
\index{options.h@{options.h}!Option@{Option}}
\index{Option@{Option}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}typedef struct {\bf ROXOption} {\bf Option}}\label{options_8h_5f20996b6d6e6b4b94ab8b6cc5d5768d}


\begin{Desc}
\item[{\bf Deprecated}]use \doxyref{ROXOption}{p.}{structROXOption} \end{Desc}
\index{options.h@{options.h}!OptionBuildFn@{OptionBuildFn}}
\index{OptionBuildFn@{OptionBuildFn}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}typedef {\bf ROXOption\-Build\-Fn} {\bf Option\-Build\-Fn}}\label{options_8h_c8efd5f31217fa3618c06d7c23ec3d24}


\begin{Desc}
\item[{\bf Deprecated}]use \doxyref{ROXOption\-Build\-Fn}{p.}{options_8h_f65724879daa272fb06d2d5e0f48e28d} \end{Desc}
\index{options.h@{options.h}!OptionNotify@{OptionNotify}}
\index{OptionNotify@{OptionNotify}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}typedef {\bf ROXOption\-Notify} {\bf Option\-Notify}}\label{options_8h_b55e88fbb58f9a84c74fd77ced379298}


\begin{Desc}
\item[{\bf Deprecated}]use \doxyref{ROXOption\-Notify}{p.}{options_8h_1afbfce8b3a868225fa9a742c8639548} \end{Desc}
\index{options.h@{options.h}!ROXOption@{ROXOption}}
\index{ROXOption@{ROXOption}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}typedef struct {\bf ROXOption} {\bf ROXOption}}\label{options_8h_238d32af11d8e470dfe779bf8e87127a}


An option, stored as a string. It may have an integer value \index{options.h@{options.h}!ROXOptionBuildFn@{ROXOptionBuildFn}}
\index{ROXOptionBuildFn@{ROXOptionBuildFn}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}typedef GList$\ast$($\ast$) {\bf ROXOption\-Build\-Fn}({\bf Option} $\ast$option, xml\-Node $\ast$node, gchar $\ast$label)}\label{options_8h_f65724879daa272fb06d2d5e0f48e28d}


Type of function used to build custom option widgets

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftrightarrow$} {\em option}]option being constructed \item[\mbox{$\leftarrow$} {\em node}]element of the Options.xml file to use in construction \item[\mbox{$\leftarrow$} {\em label}]label to attach to the widget \end{description}
\end{Desc}
\index{options.h@{options.h}!ROXOptionNotify@{ROXOptionNotify}}
\index{ROXOptionNotify@{ROXOptionNotify}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}typedef void {\bf ROXOption\-Notify}(void)}\label{options_8h_1afbfce8b3a868225fa9a742c8639548}


Type of function called when the options change 

\subsection{Function Documentation}
\index{options.h@{options.h}!option_add_int@{option\_\-add\_\-int}}
\index{option_add_int@{option\_\-add\_\-int}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void option\_\-add\_\-int ({\bf ROXOption} $\ast$ {\em option}, const gchar $\ast$ {\em key}, int {\em value})}\label{options_8h_6555d9ceda2c7ba28be7e78636720ba9}


Initialise and register a new integer option

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftrightarrow$} {\em option}]option to initialize \item[\mbox{$\leftarrow$} {\em key}]name of the option \item[\mbox{$\leftarrow$} {\em value}]default value\end{description}
\end{Desc}
\begin{Desc}
\item[{\bf Deprecated}]Use \doxyref{rox\_\-option\_\-add\_\-int()}{p.}{options_8c_a065a76696dc2f13259eb2b4f2fdc912}. \end{Desc}
\index{options.h@{options.h}!option_add_string@{option\_\-add\_\-string}}
\index{option_add_string@{option\_\-add\_\-string}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void option\_\-add\_\-string ({\bf ROXOption} $\ast$ {\em option}, const gchar $\ast$ {\em key}, const gchar $\ast$ {\em value})}\label{options_8h_a50077cbeb46c8b197e2ca0e7f354ef0}


Initialise and register a new string option

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftrightarrow$} {\em option}]option to initialize \item[\mbox{$\leftarrow$} {\em key}]name of the option \item[\mbox{$\leftarrow$} {\em value}]default value\end{description}
\end{Desc}
\begin{Desc}
\item[{\bf Deprecated}]Use \doxyref{rox\_\-option\_\-add\_\-int()}{p.}{options_8c_a065a76696dc2f13259eb2b4f2fdc912}. \end{Desc}
\index{options.h@{options.h}!option_check_widget@{option\_\-check\_\-widget}}
\index{option_check_widget@{option\_\-check\_\-widget}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void option\_\-check\_\-widget ({\bf ROXOption} $\ast$ {\em option})}\label{options_8h_2b98d265e7f7c5d6f2ea57c203ae5a61}


This is called when the widget's value is modified by the user. Reads the new value of the widget into the option and calls the notify callbacks.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftrightarrow$} {\em option}]option to be updated.\end{description}
\end{Desc}
\begin{Desc}
\item[{\bf Deprecated}]Use \doxyref{rox\_\-option\_\-check\_\-widget()}{p.}{options_8c_92e54d4b425bc44c9bdd0b33bcedddf6}. \end{Desc}
\index{options.h@{options.h}!options_init@{options\_\-init}}
\index{options_init@{options\_\-init}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void options\_\-init (const char $\ast$ {\em project})}\label{options_8h_4cd427d03d72d2ff846fb42d94067a4d}


Initialize the options system, normally called by \doxyref{rox\_\-init()}{p.}{rox_8c_afe930e2bcbe2cf1dd0834fafe43a1a3}. \begin{Desc}
\item[{\bf Deprecated}]Use \doxyref{rox\_\-options\_\-init\_\-with\_\-domain()}{p.}{options_8c_34fabc8853fc5d174635c3719728a70b} instead.\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftarrow$} {\em project}]name of program \end{description}
\end{Desc}
\index{options.h@{options.h}!options_init_with_domain@{options\_\-init\_\-with\_\-domain}}
\index{options_init_with_domain@{options\_\-init\_\-with\_\-domain}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void options\_\-init\_\-with\_\-domain (const char $\ast$ {\em project}, const char $\ast$ {\em domain})}\label{options_8h_07b3271cd763892a539ac715cd1a299a}


Initialize the options system, normally called by \doxyref{rox\_\-init\_\-with\_\-domain()}{p.}{rox_8c_74e2d8a486c8aedc955851dc7b71b660} if it detects {\tt Options.xml} in {\em \$APP\_\-DIR\/}.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftarrow$} {\em project}]name of program \item[\mbox{$\leftarrow$} {\em domain}]domain under the control of the programmer.\end{description}
\end{Desc}
\begin{Desc}
\item[{\bf Deprecated}]Use \doxyref{rox\_\-options\_\-init\_\-with\_\-domain()}{p.}{options_8c_34fabc8853fc5d174635c3719728a70b} instead. \end{Desc}
\index{options.h@{options.h}!options_notify@{options\_\-notify}}
\index{options_notify@{options\_\-notify}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void options\_\-notify (void)}\label{options_8h_d8728b3f9c832cd986df564ff08bdefa}


Call all the notify callbacks. This should happen after any options have their values changed. Set each option-$>$has\_\-changed flag before calling this function.

\begin{Desc}
\item[{\bf Deprecated}]Use \doxyref{rox\_\-options\_\-notify()}{p.}{options_8c_24d960d63799708bc23a4a1add0a711d}. \end{Desc}
\index{options.h@{options.h}!options_show@{options\_\-show}}
\index{options_show@{options\_\-show}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}Gtk\-Widget$\ast$ options\_\-show (void)}\label{options_8h_b2ab08afe9b6876c6ff6502697582c4c}


Allow the user to edit the options. Returns the window widget (you don't normally need this). NULL if already open.

\begin{Desc}
\item[Returns:]the options window\end{Desc}
\begin{Desc}
\item[{\bf Deprecated}]Use \doxyref{rox\_\-options\_\-show()}{p.}{options_8c_7275e7234c6f9ca8804b6b3a8af94415}. \end{Desc}
\index{options.h@{options.h}!rox_option_add_int@{rox\_\-option\_\-add\_\-int}}
\index{rox_option_add_int@{rox\_\-option\_\-add\_\-int}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void rox\_\-option\_\-add\_\-int ({\bf ROXOption} $\ast$ {\em option}, const gchar $\ast$ {\em key}, int {\em value})}\label{options_8h_a065a76696dc2f13259eb2b4f2fdc912}


Initialise and register a new integer option

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftrightarrow$} {\em option}]option to initialize \item[\mbox{$\leftarrow$} {\em key}]name of the option \item[\mbox{$\leftarrow$} {\em value}]default value \end{description}
\end{Desc}
\index{options.h@{options.h}!rox_option_add_notify@{rox\_\-option\_\-add\_\-notify}}
\index{rox_option_add_notify@{rox\_\-option\_\-add\_\-notify}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void rox\_\-option\_\-add\_\-notify ({\bf ROXOption\-Notify} $\ast$ {\em callback})}\label{options_8h_414efd006ff8be46005c2c70d200b06d}


Add a callback which will be called after any options have changed their values. If several options change at once, this is called after all changes.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftarrow$} {\em callback}]funtion to call if options change \end{description}
\end{Desc}
\index{options.h@{options.h}!rox_option_add_saver@{rox\_\-option\_\-add\_\-saver}}
\index{rox_option_add_saver@{rox\_\-option\_\-add\_\-saver}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void rox\_\-option\_\-add\_\-saver ({\bf ROXOption\-Notify} $\ast$ {\em callback})}\label{options_8h_e622c3cc9911ad2da9c17757cd8847f7}


Call 'callback' after all the options have been saved

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftarrow$} {\em callback}]funtion to call when options have been saved \end{description}
\end{Desc}
\index{options.h@{options.h}!rox_option_add_string@{rox\_\-option\_\-add\_\-string}}
\index{rox_option_add_string@{rox\_\-option\_\-add\_\-string}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void rox\_\-option\_\-add\_\-string ({\bf ROXOption} $\ast$ {\em option}, const gchar $\ast$ {\em key}, const gchar $\ast$ {\em value})}\label{options_8h_1aac46d5b6fe041013ece225b1b278ef}


Initialise and register a new string option

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftrightarrow$} {\em option}]option to initialize \item[\mbox{$\leftarrow$} {\em key}]name of the option \item[\mbox{$\leftarrow$} {\em value}]default value \end{description}
\end{Desc}
\index{options.h@{options.h}!rox_option_check_widget@{rox\_\-option\_\-check\_\-widget}}
\index{rox_option_check_widget@{rox\_\-option\_\-check\_\-widget}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void rox\_\-option\_\-check\_\-widget ({\bf ROXOption} $\ast$ {\em option})}\label{options_8h_92e54d4b425bc44c9bdd0b33bcedddf6}


This is called when the widget's value is modified by the user. Reads the new value of the widget into the option and calls the notify callbacks.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftrightarrow$} {\em option}]option to be updated \end{description}
\end{Desc}
\index{options.h@{options.h}!rox_option_register_widget@{rox\_\-option\_\-register\_\-widget}}
\index{rox_option_register_widget@{rox\_\-option\_\-register\_\-widget}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void rox\_\-option\_\-register\_\-widget (char $\ast$ {\em name}, {\bf ROXOption\-Build\-Fn} {\em builder})}\label{options_8h_123cd5242375773d07fc865d70da3477}


When parsing the XML file, process an element named 'name' by calling 'builder(option, xml\_\-node, label)'. builder returns the new widgets to add to the options box. {\em name\/} should be a static string. Call \doxyref{rox\_\-option\_\-check\_\-widget()}{p.}{options_8c_92e54d4b425bc44c9bdd0b33bcedddf6} when the widget's value is modified.

Functions to set or get the widget's state can be stored in 'option'. If the option doesn't have a name attribute in Options.xml then ui will be {\tt NULL} on entry (this is used for buttons).

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftarrow$} {\em name}]name of the type of widget as used in the Options.xml element \item[\mbox{$\leftarrow$} {\em builder}]function called to build the option \end{description}
\end{Desc}
\index{options.h@{options.h}!rox_options_init@{rox\_\-options\_\-init}}
\index{rox_options_init@{rox\_\-options\_\-init}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void rox\_\-options\_\-init (const char $\ast$ {\em project})}\label{options_8h_fa5bf165c38f199457ce53c94a4ba789}


Initialize the options system, normally called by \doxyref{rox\_\-init()}{p.}{rox_8c_afe930e2bcbe2cf1dd0834fafe43a1a3}. \begin{Desc}
\item[{\bf Deprecated}]Use \doxyref{rox\_\-options\_\-init\_\-with\_\-domain()}{p.}{options_8c_34fabc8853fc5d174635c3719728a70b} instead.\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftarrow$} {\em project}]name of program \end{description}
\end{Desc}
\index{options.h@{options.h}!rox_options_init_with_domain@{rox\_\-options\_\-init\_\-with\_\-domain}}
\index{rox_options_init_with_domain@{rox\_\-options\_\-init\_\-with\_\-domain}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void rox\_\-options\_\-init\_\-with\_\-domain (const char $\ast$ {\em project}, const char $\ast$ {\em domain})}\label{options_8h_34fabc8853fc5d174635c3719728a70b}


Initialize the options system, normally called by \doxyref{rox\_\-init\_\-with\_\-domain()}{p.}{rox_8c_74e2d8a486c8aedc955851dc7b71b660} if it detects {\tt Options.xml} in {\em \$APP\_\-DIR\/}.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftarrow$} {\em project}]name of program \item[\mbox{$\leftarrow$} {\em domain}]domain under the control of the programmer. \end{description}
\end{Desc}
\index{options.h@{options.h}!rox_options_notify@{rox\_\-options\_\-notify}}
\index{rox_options_notify@{rox\_\-options\_\-notify}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void rox\_\-options\_\-notify (void)}\label{options_8h_24d960d63799708bc23a4a1add0a711d}


Call all the notify callbacks. This should happen after any options have their values changed. Set each option-$>$has\_\-changed flag before calling this function. \index{options.h@{options.h}!rox_options_show@{rox\_\-options\_\-show}}
\index{rox_options_show@{rox\_\-options\_\-show}!options.h@{options.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}Gtk\-Widget$\ast$ rox\_\-options\_\-show (void)}\label{options_8h_7275e7234c6f9ca8804b6b3a8af94415}


Allow the user to edit the options. Returns the window widget (you don't normally need this).

\begin{Desc}
\item[Returns:]the options window or {\tt NULL} if already open. \end{Desc}
