gnome-program

gnome-program

Synopsis

#include <libgnome/libgnome.h>

enum                GnomeFileDomain;
struct              GnomeProgram;
struct              GnomeModuleInfo;
struct              GnomeModuleRequirement;
void                (*GnomeModuleInitHook)              (const GnomeModuleInfo *mod_info);
void                (*GnomeModuleClassInitHook)         (GnomeProgramClass *klass,
                                                         const GnomeModuleInfo *mod_info);
void                (*GnomeModuleHook)                  (GnomeProgram *program,
                                                         GnomeModuleInfo *mod_info);
GnomeProgram *      gnome_program_init                  (const char *app_id,
                                                         const char *app_version,
                                                         const GnomeModuleInfo *module_info,
                                                         int argc,
                                                         char **argv,
                                                         const char *first_property_name,
                                                         ...);
GnomeProgram *      gnome_program_initv                 (GType type,
                                                         const char *app_id,
                                                         const char *app_version,
                                                         const GnomeModuleInfo *module_info,
                                                         int argc,
                                                         char **argv,
                                                         const char *first_property_name,
                                                         va_list args);

GnomeProgram *      gnome_program_get                   (void);
const char *        gnome_program_get_human_readable_name
                                                        (GnomeProgram *program);
const char *        gnome_program_get_app_id            (GnomeProgram *program);
const char *        gnome_program_get_app_version       (GnomeProgram *program);
gchar *             gnome_program_locate_file           (GnomeProgram *program,
                                                         GnomeFileDomain domain,
                                                         const gchar *file_name,
                                                         gboolean only_if_exists,
                                                         GSList **ret_locations);

void                gnome_program_module_register       (const GnomeModuleInfo *module_info);
gboolean            gnome_program_module_registered     (const GnomeModuleInfo *module_info);
const GnomeModuleInfo * gnome_program_module_load       (const char *mod_name);
guint               gnome_program_install_property      (GnomeProgramClass *pclass,
                                                         GObjectGetPropertyFunc get_fn,
                                                         GObjectSetPropertyFunc set_fn,
                                                         GParamSpec *pspec);
poptContext         gnome_program_preinit               (GnomeProgram *program,
                                                         const char *app_id,
                                                         const char *app_version,
                                                         int argc,
                                                         char **argv);
void                gnome_program_parse_args            (GnomeProgram *program);
void                gnome_program_postinit              (GnomeProgram *program);

#define             GNOME_PARAM_POPT_TABLE
#define             GNOME_PARAM_POPT_FLAGS
#define             GNOME_PARAM_POPT_CONTEXT
#define             GNOME_PARAM_GOPTION_CONTEXT
#define             GNOME_PARAM_CREATE_DIRECTORIES
#define             GNOME_PARAM_ENABLE_SOUND
#define             GNOME_PARAM_ESPEAKER
#define             GNOME_PARAM_APP_ID
#define             GNOME_PARAM_APP_VERSION
#define             GNOME_PARAM_GNOME_PREFIX
#define             GNOME_PARAM_GNOME_SYSCONFDIR
#define             GNOME_PARAM_GNOME_DATADIR
#define             GNOME_PARAM_GNOME_LIBDIR
#define             GNOME_PARAM_APP_PREFIX
#define             GNOME_PARAM_APP_SYSCONFDIR
#define             GNOME_PARAM_APP_DATADIR
#define             GNOME_PARAM_APP_LIBDIR
#define             GNOME_PARAM_HUMAN_READABLE_NAME
#define             GNOME_PARAM_GNOME_PATH
#define             GNOME_PARAM_NONE
#define             GNOME_PROGRAM_STANDARD_PROPERTIES

Description

Details

enum GnomeFileDomain

typedef enum {
    GNOME_FILE_DOMAIN_UNKNOWN = 0,

    /* Gnome installed files */
    GNOME_FILE_DOMAIN_LIBDIR,
    GNOME_FILE_DOMAIN_DATADIR,
    GNOME_FILE_DOMAIN_SOUND,
    GNOME_FILE_DOMAIN_PIXMAP,
    GNOME_FILE_DOMAIN_CONFIG,
    GNOME_FILE_DOMAIN_HELP,

    /* Application files */
    GNOME_FILE_DOMAIN_APP_LIBDIR,
    GNOME_FILE_DOMAIN_APP_DATADIR,
    GNOME_FILE_DOMAIN_APP_SOUND,
    GNOME_FILE_DOMAIN_APP_PIXMAP,
    GNOME_FILE_DOMAIN_APP_CONFIG,
    GNOME_FILE_DOMAIN_APP_HELP
} GnomeFileDomain;

struct GnomeProgram

struct GnomeProgram {
    GObject object;

    GnomeProgramPrivate *_priv;
};

struct GnomeModuleInfo

struct GnomeModuleInfo {
    const char *name;
    const char *version;
    const char *description;
    GnomeModuleRequirement *requirements; /* last element has NULL version */

    GnomeModuleHook instance_init;
    GnomeModuleHook pre_args_parse, post_args_parse;

#ifdef GNOME_DISABLE_DEPRECATED
    void *_options;
#else
    struct poptOption *options;
#endif

    GnomeModuleInitHook init_pass;

    GnomeModuleClassInitHook class_init;

    const char *opt_prefix;
    GnomeModuleGetGOptionGroupFunc get_goption_group_func;
};

struct GnomeModuleRequirement

struct GnomeModuleRequirement {
    const char *required_version;
    const GnomeModuleInfo *module_info;
};

GnomeModuleInitHook ()

void                (*GnomeModuleInitHook)              (const GnomeModuleInfo *mod_info);

GnomeModuleClassInitHook ()

void                (*GnomeModuleClassInitHook)         (GnomeProgramClass *klass,
                                                         const GnomeModuleInfo *mod_info);

GnomeModuleHook ()

void                (*GnomeModuleHook)                  (GnomeProgram *program,
                                                         GnomeModuleInfo *mod_info);

gnome_program_init ()

GnomeProgram *      gnome_program_init                  (const char *app_id,
                                                         const char *app_version,
                                                         const GnomeModuleInfo *module_info,
                                                         int argc,
                                                         char **argv,
                                                         const char *first_property_name,
                                                         ...);

Initialises the current GNOME libraries for use by the application. app_id is used for the following purposes:

  • to find the programme's help files by gnome_help_*()

  • to load the app-specific gtkrc file from ~/.gnome2/$(APPID)rc

  • to load/save the app's accelerators map from ~/.gnome2/accelerators/$(APPID)

  • to load/save a GnomeEntry's history from gconf/apps/gnome-settings/$(APPID)/history-$(ENTRYID)

app_id :

Application ID string.

app_version :

Application version string.

module_info :

The module to init with this program.

argc :

The number of commmand line arguments contained in argv.

argv :

A string array of command line arguments.

first_property_name :

The first item in a NULL-terminated list of attribute name and value pairs (so this will be an attribute name or NULL).

... :

The continuation of a NULL-terminated list of attribute name/value pairs.

Returns :

A new GnomeProgram instance representing the current application. Unref the returned reference right before exiting your application.

gnome_program_initv ()

GnomeProgram *      gnome_program_initv                 (GType type,
                                                         const char *app_id,
                                                         const char *app_version,
                                                         const GnomeModuleInfo *module_info,
                                                         int argc,
                                                         char **argv,
                                                         const char *first_property_name,
                                                         va_list args);

Provides a non-varargs form of gnome_program_init(). Users will rarely need to call this function directly.

type :

The type of application to be initialized (usually GNOME_TYPE_PROGRAM).

app_id :

Application ID string.

app_version :

Application version string.

module_info :

The modules to init with the application.

argc :

The number of command line arguments contained in argv.

argv :

A string array of command line arguments.

first_property_name :

The first item in a NULL-terminated list of attribute name/value.

args :

The remaining elements in the NULL terminated list (of which first_property_name is the first element).

Returns :

A GnomeProgram instance representing the current application.

gnome_program_get ()

GnomeProgram *      gnome_program_get                   (void);

Retrieves an object that stored information about the application's state. Other functions assume this will always return a GnomeProgram object which (if not NULL) has already been initialized.

Returns :

The application's GnomeProgram instance, or NULL if it does not exist.

gnome_program_get_human_readable_name ()

const char *        gnome_program_get_human_readable_name
                                                        (GnomeProgram *program);

This function returns a pointer to a static string that the application has provided as a human readable name. The app should provide the name with the GNOME_PARAM_HUMAN_READABLE_NAME init argument. Returns NULL if no name was set.

program :

The application object

Returns :

Application human-readable name string.

gnome_program_get_app_id ()

const char *        gnome_program_get_app_id            (GnomeProgram *program);

This function returns a pointer to a static string that the application has provided as an identifier. This is not meant as a human-readable identifier so much as a unique identifier for programs and libraries.

program :

The program object

Returns :

Application ID string.

gnome_program_get_app_version ()

const char *        gnome_program_get_app_version       (GnomeProgram *program);

This function returns a pointer to a static string that the application has provided as a version number. This is not meant as a human-readable identifier so much as a unique identifier for programs and libraries.

program :

The application object

Returns :

Application version string.

gnome_program_locate_file ()

gchar *             gnome_program_locate_file           (GnomeProgram *program,
                                                         GnomeFileDomain domain,
                                                         const gchar *file_name,
                                                         gboolean only_if_exists,
                                                         GSList **ret_locations);

This function finds a full path to the file_name located in the specified "domain". A domain is a name for a collection of related files. For example, common domains are "libdir", "pixmap", and "config".

If ret_locations is NULL, only one pathname is returned. Otherwise, alternative paths are returned in ret_locations.

User applications should store files in the GNOME_FILE_DOMAIN_APP_* domains. However you MUST set the correct attributes for GnomeProgram for the APP specific prefixes (during the initialization part of the application).

The ret_locations list and its contents should be freed by the caller, as should the returned string.

program :

A valid GnomeProgram object or NULL (in which case the current application is used).

domain :

A GnomeFileDomain.

file_name :

A file name or path inside the 'domain' to find.

only_if_exists :

Only return a full pathname if the specified file actually exists

ret_locations :

If this is not NULL, a list of all the possible locations of the file will be returned.

Returns :

The full path to the file (if it exists or only_if_exists is FALSE) or NULL.

gnome_program_module_register ()

void                gnome_program_module_register       (const GnomeModuleInfo *module_info);

This function is used to register a module to be initialized by the GNOME library framework. The memory pointed to by module_info must be valid during the whole application initialization process, and the module described by module_info must only use the module_info pointer to register itself.

module_info :

A pointer to a GnomeModuleInfo structure describing the module to be initialized

gnome_program_module_registered ()

gboolean            gnome_program_module_registered     (const GnomeModuleInfo *module_info);

This method checks to see whether a specific module has been initialized in the specified program.

module_info :

A pointer to a GnomeModuleInfo structure describing the module to be queried

Returns :

A value indicating whether the specified module has been registered/initialized in the current program

gnome_program_module_load ()

const GnomeModuleInfo * gnome_program_module_load       (const char *mod_name);

Loads a shared library that contains a GnomeModuleInfo dynamic_module_info structure.

mod_name :

module name

Returns :

The GnomeModuleInfo structure that was loaded, or NULL if the module could not be loaded.

gnome_program_install_property ()

guint               gnome_program_install_property      (GnomeProgramClass *pclass,
                                                         GObjectGetPropertyFunc get_fn,
                                                         GObjectSetPropertyFunc set_fn,
                                                         GParamSpec *pspec);

Install a collection of available properties, their default values and the functions to set and retrieve these properties.

Normal applications will never need to call this function, it is mostly for use by other platform library authors.

pclass :

A GnomeProgramClass.

get_fn :

A function to get property values.

set_fn :

A function to set property values.

pspec :

A collection of properties.

Returns :

The number of properties installed.

gnome_program_preinit ()

poptContext         gnome_program_preinit               (GnomeProgram *program,
                                                         const char *app_id,
                                                         const char *app_version,
                                                         int argc,
                                                         char **argv);

Warning

gnome_program_preinit is deprecated and should not be used in newly-written code.

This function performs the portion of application initialization that needs to be done prior to command line argument parsing. The poptContext returned can be used for getopt()-style option processing.

program :

Application object

app_id :

application ID string

app_version :

application version string

argc :

The number of commmand line arguments contained in 'argv'

argv :

A string array of command line arguments

Returns :

A poptContext representing the argument parsing state, or NULL if using GOption argument parsing.

gnome_program_parse_args ()

void                gnome_program_parse_args            (GnomeProgram *program);

Warning

gnome_program_parse_args is deprecated and should not be used in newly-written code.

Parses the command line arguments for the application

program :

Application object

gnome_program_postinit ()

void                gnome_program_postinit              (GnomeProgram *program);

Warning

gnome_program_postinit is deprecated and should not be used in newly-written code.

Called after gnome_program_parse_args(), this function takes care of post-parse initialization and cleanup

program :

Application object

GNOME_PARAM_POPT_TABLE

#define GNOME_PARAM_POPT_TABLE          "popt-table"

Warning

GNOME_PARAM_POPT_TABLE is deprecated and should not be used in newly-written code.


GNOME_PARAM_POPT_FLAGS

#define GNOME_PARAM_POPT_FLAGS          "popt-flags"

Warning

GNOME_PARAM_POPT_FLAGS is deprecated and should not be used in newly-written code.


GNOME_PARAM_POPT_CONTEXT

#define GNOME_PARAM_POPT_CONTEXT        "popt-context"

Warning

GNOME_PARAM_POPT_CONTEXT is deprecated and should not be used in newly-written code.


GNOME_PARAM_GOPTION_CONTEXT

#define GNOME_PARAM_GOPTION_CONTEXT     "goption-context"

GNOME_PARAM_CREATE_DIRECTORIES

#define GNOME_PARAM_CREATE_DIRECTORIES  "create-directories"

GNOME_PARAM_ENABLE_SOUND

#define GNOME_PARAM_ENABLE_SOUND        "enable-sound"

GNOME_PARAM_ESPEAKER

#define GNOME_PARAM_ESPEAKER            "espeaker"

GNOME_PARAM_APP_ID

#define GNOME_PARAM_APP_ID              "app-id"

GNOME_PARAM_APP_VERSION

#define GNOME_PARAM_APP_VERSION         "app-version"

GNOME_PARAM_GNOME_PREFIX

#define GNOME_PARAM_GNOME_PREFIX        "gnome-prefix"

GNOME_PARAM_GNOME_SYSCONFDIR

#define GNOME_PARAM_GNOME_SYSCONFDIR    "gnome-sysconfdir"

GNOME_PARAM_GNOME_DATADIR

#define GNOME_PARAM_GNOME_DATADIR       "gnome-datadir"

GNOME_PARAM_GNOME_LIBDIR

#define GNOME_PARAM_GNOME_LIBDIR        "gnome-libdir"

GNOME_PARAM_APP_PREFIX

#define GNOME_PARAM_APP_PREFIX          "app-prefix"

GNOME_PARAM_APP_SYSCONFDIR

#define GNOME_PARAM_APP_SYSCONFDIR      "app-sysconfdir"

GNOME_PARAM_APP_DATADIR

#define GNOME_PARAM_APP_DATADIR         "app-datadir"

GNOME_PARAM_APP_LIBDIR

#define GNOME_PARAM_APP_LIBDIR          "app-libdir"

GNOME_PARAM_HUMAN_READABLE_NAME

#define GNOME_PARAM_HUMAN_READABLE_NAME "human-readable-name"

GNOME_PARAM_GNOME_PATH

#define GNOME_PARAM_GNOME_PATH          "gnome-path"

GNOME_PARAM_NONE

#define GNOME_PARAM_NONE                NULL

GNOME_PROGRAM_STANDARD_PROPERTIES

#define             GNOME_PROGRAM_STANDARD_PROPERTIES