ROX-CLib: choices.c File Reference

- Main Page
- Data Structures
- Files
- Related Pages

- File List
- Globals

# choices.c File Reference

Code for handling loading and saving of user choices. More...

`#include "rox-clib.h"`
`#include <stdio.h>`
`#include <stdlib.h>`
`#include <sys/param.h>`
`#include <sys/stat.h>`
`#include <fcntl.h>`
`#include <errno.h>`
`#include <glib.h>`
`#include "rox_debug.h"`
`#include "choices.h"`
`#include "basedir.h"`

## Functions
void | choices_init (void)
GPtrArray * | choices_list_dirs (const char *dir)
void | choices_free_list (GPtrArray *list)
gchar * | choices_find_path_load (const char *leaf, const char *dir)
gchar * | choices_find_path_save (const char *leaf, const char *dir, gboolean create)
void | rox_choices_init (void)
gchar * | rox_choices_save (const char *leaf, const char *dir, const char *domain)
gchar * | rox_choices_load (const char *leaf, const char *dir, const char *domain)
GPtrArray * | rox_choices_list_dirs (const char *domain, const char *dir)
void | rox_choices_free_list (GPtrArray *list)

## Detailed Description

Code for handling loading and saving of user choices.

The current versions use a parameter "domain" to ensure that two programs from different sources but with the same name do not clash. domain is optional and may be NULL. If given it should be a domain name identifying the software, i.e. I use kerofin.demon.co.uk. If you don't have a domain name, use an email address, e.g. me@my-isp.org

These functions are deprecated and should not be used in new code:

- choices_init()
- choices_list_dirs()
- choices_free_list()
- choices_find_path_load()
- choices_find_path_save()

Version:
  Id
    choices.c,v 1.13 2006/11/06 20:22:42 stephen Exp

Author:
  Thomas Leonard, Stephen Watson. Borrowed from: ROX-Filer, filer for the ROX desktop project Copyright (C) 2000, Thomas Leonard, <tal197@users.sourceforge.net>.

Version:
  Id
    choices.c,v 1.13 2006/11/06 20:22:42 stephen Exp

Author:
  Thomas Leonard, Stephen Watson.

## Function Documentation

gchar* choices_find_path_load | ( | const char * | leaf,
|  | const char * | dir |
| ) |  |  |

Get the pathname of a choices file to load. Eg:

choices_find_path_load("menus", "ROX-Filer") -> "/usr/local/share/Choices/ROX-Filer/menus".

The return values may be NULL - use built-in defaults - otherwise g_free() the result.

Deprecated:
  Use rox_choices_load() instead.

Parameters:

  `[in]` | leaf | last part of file name (may include a relative directory part)
  `[in]` | dir | directory to locate in $CHOICESPATH, normally the name of the program

Returns:
  path to file (pass to g_free() when done) or NULL

gchar* choices_find_path_save | ( | const char * | leaf,
|  | const char * | dir,
|  | gboolean | create |
| ) |  |  |

Returns the pathname of a file to save to, or NULL if saving is disabled. If 'create' is TRUE then intermediate directories will be created (set this to FALSE if you just want to find out where a saved file would go without actually altering the filesystem).

g_free() the result.

Deprecated:
  Use rox_choices_save() instead

Parameters:

  `[in]` | leaf | last part of file name (may include a relative directory part)
  `[in]` | dir | directory to locate in $CHOICESPATH, normally the name of the program
  `[in]` | create | if non-zero create missing directories

Returns:
  path to file (pass to g_free() when done) or NULL

void choices_free_list | ( | GPtrArray * | list | ) |

Free the data returned by choices_list_dirs().

Parameters:

  `[in,out]` | list | Return value from choices_list_dirs().

Deprecated:
  use rox_choices_free_list() instead.

void choices_init | ( | void |  | ) |

Checks $CHOICESPATH to construct the directory list table for the old choices_system. You must call this before using any other choices_* functions.

If the environment variable does not exist then the defaults are used.

Deprecated:
  This is called by rox_init_with_domain() and you should call that in preference to this.

GPtrArray* choices_list_dirs | ( | const char * | dir | ) |

Returns an array of the directories in CHOICESPATH which contain a subdirectory called 'dir'.

Lower-indexed results should override higher-indexed ones.

Free the list using choices_free_list().

Parameters:

  `[in]` | dir | directory to search for.

Returns:
  pointer array of results.

Deprecated:
  use rox_choices_list_dirs() instead.

void rox_choices_free_list | ( | GPtrArray * | list | ) |

Free the data returned by rox_choices_list_dirs().

Parameters:

  `[in,out]` | list | Return value from rox_choices_list_dirs().

void rox_choices_init | ( | void |  | ) |

Checks $CHOICESPATH to construct the directory list table for the old choices_system. This is called to support the old choices system and should not be used in new code.

If the environment variable does not exist then the defaults are used.

Deprecated:
  This is called by rox_init_with_domain() and you should call that in preference to this.

GPtrArray* rox_choices_list_dirs | ( | const char * | domain,
|  | const char * | dir |
| ) |  |  |

Returns an array of the directories in XDG_CONFIG_DIRS which contain a subdirectory called 'domain/dir'.

Lower-indexed results should override higher-indexed ones.

Free the list using rox_choices_free_list().

Parameters:

  `[in]` | dir | directory to search for.
  `[in]` | domain | domain of the programs author, or email address. Used to uniquely identify programs with similar names.

Returns:
  pointer array of results.

gchar* rox_choices_load | ( | const char * | leaf,
|  | const char * | dir,
|  | const char * | domain |
| ) |  |  |

Get the pathname of a choices file to load. Eg:

`rox_choices_load("menus", "ROX-Filer", "rox.sourceforge.net") -> "/etc/xdg/rox.sourceforge.net/ROX-Filer/menus"` or `"/home/user/.config/rox.sourceforge.net/ROX-Filer/menus".`

The return values may be NULL - use built-in defaults - otherwise g_free() the result.

This uses rox_basedir_load_config_path(), falling back on choices_find_path_load() if that does not return a result.

Parameters:

  `[in]` | leaf | last part of file name (may include a relative directory part)
  `[in]` | dir | directory to locate in $XDG_CONFIG_HOME, $XDG_CONFIG_DIRS or $CHOICESPATH, normally the name of the program
  `[in]` | domain | domain of the programs author, or email address. Used to uniquely identify programs with similar names.

Returns:
  path to file (pass to g_free() when done) or NULL

gchar* rox_choices_save | ( | const char * | leaf,
|  | const char * | dir,
|  | const char * | domain |
| ) |  |  |

Returns the pathname of a file to save to, or NULL if saving is disabled.

g_free() the result.

Parameters:

  `[in]` | leaf | last part of file name (may include a relative directory part)
  `[in]` | dir | directory to locate in $XDG_CONFIG_HOME or $XDG_CONFIG_DIRS, normally the name of the program
  `[in]` | domain | domain of the programs author, or email address. Used to uniquly identify programs with similar names.

Returns:
  path to file (pass to g_free() when done) or NULL