ROX-CLib: options.c File Reference

- Main Page
- Data Structures
- Files
- Related Pages

- File List
- Globals

# options.c File Reference

Interface to the ROX options system. More...

`#include "rox-clib.h"`
`#include <stdio.h>`
`#include <stdlib.h>`
`#include <string.h>`
`#include <errno.h>`
`#include <ctype.h>`
`#include <gtk/gtk.h>`
`#include <libxml/parser.h>`
`#include "rox.h"`
`#include "options.h"`

## Functions
void | rox_options_init_with_domain (const char *project, const char *domain)
void | options_init_with_domain (const char *project, const char *domain)
void | rox_options_init (const char *project)
void | options_init (const char *project)
void | rox_option_register_widget (char *name, ROXOptionBuildFn builder)
void | option_register_widget (char *name, ROXOptionBuildFn builder)
void | rox_option_check_widget (ROXOption *option)
void | option_check_widget (ROXOption *option)
void | rox_options_notify (void)
void | options_notify (void)
GtkWidget * | rox_options_show (void)
GtkWidget * | options_show (void)
void | rox_option_add_int (ROXOption *option, const gchar *key, int value)
void | option_add_int (ROXOption *option, const gchar *key, int value)
void | rox_option_add_string (ROXOption *option, const gchar *key, const gchar *value)
void | option_add_string (ROXOption *option, const gchar *key, const gchar *value)
void | rox_option_add_notify (ROXOptionNotify *callback)
void | option_add_notify (ROXOptionNotify *callback)
void | rox_option_add_saver (ROXOptionNotify *callback)
void | option_add_saver (ROXOptionNotify *callback)

## 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, <tal197@users.sourceforge.net>.

How it works:

On startup:

- 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.

- Each part of the filer then calls rox_option_add_int(), 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.

- If things need to happen when values change, modules register with rox_option_add_notify().

- rox_option_register_widget() can be used during initialisation (any time before the Options box is displayed) to tell the system how to render a particular type of option.

- Finally, all notify callbacks are called. Use the ROXOption.has_changed field to work out what has changed from the defaults.

When the user opens the Options box:

- 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.

- For each widget in the box, the current value of the option is used to set the widget's state.

- All current values are saved for a possible Revert later.

When the user changes an option or clicks on Revert:

- The option values are updated.

- All notify callbacks are called. Use the ROXOption.has_changed field to see what changed.

When OK is clicked:

- If anything changed then:
  - All the options are written to the filesystem
  - The saver_callbacks are called.

## Function Documentation

void option_add_int | ( | ROXOption * | option,
|  | const gchar * | key,
|  | int | value |
| ) |  |  |

Initialise and register a new integer option

Parameters:

  `[in,out]` | option | option to initialize
  `[in]` | key | name of the option
  `[in]` | value | default value

Deprecated:
  Use rox_option_add_int().

void option_add_notify | ( | ROXOptionNotify * | callback | ) |

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.

Parameters:

  `[in]` | callback | funtion to call if options change

Deprecated:
  Use rox_option_add_notify().

void option_add_saver | ( | ROXOptionNotify * | callback | ) |

Call 'callback' after all the options have been saved

Parameters:

  `[in]` | callback | funtion to call when options have been saved

Deprecated:
  Use rox_option_add_save().

void option_add_string | ( | ROXOption * | option,
|  | const gchar * | key,
|  | const gchar * | value |
| ) |  |  |

Initialise and register a new string option

Parameters:

  `[in,out]` | option | option to initialize
  `[in]` | key | name of the option
  `[in]` | value | default value

Deprecated:
  Use rox_option_add_int().

void option_check_widget | ( | ROXOption * | option | ) |

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.

Parameters:

  `[in,out]` | option | option to be updated.

Deprecated:
  Use rox_option_check_widget().

void option_register_widget | ( | char * | name,
|  | ROXOptionBuildFn | builder |
| ) |  |  |

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. 'name' should be a static string. Call rox_option_check_widget 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 NULL on entry (this is used for buttons).

Parameters:

  `[in]` | name | name of the type of widget as used in the Options.xml element
  `[in]` | builder | function called to build the option

Deprecated:
  Use rox_option_register_widget().

void options_init | ( | const char * | project | ) |

Initialize the options system, normally called by rox_init().

Deprecated:
  Use rox_options_init_with_domain() instead.

Parameters:

  `[in]` | project | name of program

void options_init_with_domain | ( | const char * | project,
|  | const char * | domain |
| ) |  |  |

Initialize the options system, normally called by rox_init_with_domain() if it detects `Options.xml` in $APP_DIR.

Parameters:

  `[in]` | project | name of program
  `[in]` | domain | domain under the control of the programmer.

Deprecated:
  Use rox_options_init_with_domain() instead.

void options_notify | ( | void |  | ) |

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.

Deprecated:
  Use rox_options_notify().

GtkWidget* options_show | ( | void |  | ) |

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

Returns:
  the options window

Deprecated:
  Use rox_options_show().

void rox_option_add_int | ( | ROXOption * | option,
|  | const gchar * | key,
|  | int | value |
| ) |  |  |

Initialise and register a new integer option

Parameters:

  `[in,out]` | option | option to initialize
  `[in]` | key | name of the option
  `[in]` | value | default value

void rox_option_add_notify | ( | ROXOptionNotify * | callback | ) |

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.

Parameters:

  `[in]` | callback | funtion to call if options change

void rox_option_add_saver | ( | ROXOptionNotify * | callback | ) |

Call 'callback' after all the options have been saved

Parameters:

  `[in]` | callback | funtion to call when options have been saved

void rox_option_add_string | ( | ROXOption * | option,
|  | const gchar * | key,
|  | const gchar * | value |
| ) |  |  |

Initialise and register a new string option

Parameters:

  `[in,out]` | option | option to initialize
  `[in]` | key | name of the option
  `[in]` | value | default value

void rox_option_check_widget | ( | ROXOption * | option | ) |

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.

Parameters:

  `[in,out]` | option | option to be updated

void rox_option_register_widget | ( | char * | name,
|  | ROXOptionBuildFn | builder |
| ) |  |  |

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. name should be a static string. Call rox_option_check_widget() 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 `NULL` on entry (this is used for buttons).

Parameters:

  `[in]` | name | name of the type of widget as used in the Options.xml element
  `[in]` | builder | function called to build the option

void rox_options_init | ( | const char * | project | ) |

Initialize the options system, normally called by rox_init().

Deprecated:
  Use rox_options_init_with_domain() instead.

Parameters:

  `[in]` | project | name of program

void rox_options_init_with_domain | ( | const char * | project,
|  | const char * | domain |
| ) |  |  |

Initialize the options system, normally called by rox_init_with_domain() if it detects `Options.xml` in $APP_DIR.

Parameters:

  `[in]` | project | name of program
  `[in]` | domain | domain under the control of the programmer.

void rox_options_notify | ( | void |  | ) |

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.

GtkWidget* rox_options_show | ( | void |  | ) |

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

Returns:
  the options window or `NULL` if already open.