GnomeProgram

Name

GnomeProgram -- 

Synopsis


#include <libgnome/libgnome.h>


enum        GnomeFileDomain;
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);
#define     GNOME_PARAM_MODULE_INFO
#define     GNOME_PARAM_MODULES
#define     GNOME_PARAM_POPT_TABLE
#define     GNOME_PARAM_POPT_FLAGS
#define     GNOME_PARAM_POPT_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_TYPE_MODULE_INFO
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);
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_PROGRAM_STANDARD_PROPERTIES
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);


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;

Many of the files that a GNOME application needs to access will be installed in standard locations. For example, GNOME help files will be in one location, while help files specific to the current application might be in another location.

The different types of files are given in the GnomeFileDomain enum. User applications make use of the GNOME_FILE_DOMAIN_APP_* types, which specify locations relative to GNOME_PARAM_APP_DATADIR.


gnome_program_get ()

GnomeProgram* gnome_program_get             (void);

Returns : An object that stores information on the GNOME application's state. If the object does not exist, NULL is returned. Other functions assume that this will always return a GnomeProgram object which (if not NULL) has already been initialized.


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 the full path to a file 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, there is no other return value.

The GNOME_FILE_DOMAIN_APP_* domains are ones for your own application. 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.

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_PARAM_MODULE_INFO

#define GNOME_PARAM_MODULE_INFO         "module-info"


GNOME_PARAM_MODULES

#define GNOME_PARAM_MODULES             "modules"


GNOME_PARAM_POPT_TABLE

#define GNOME_PARAM_POPT_TABLE          "popt-table"


GNOME_PARAM_POPT_FLAGS

#define GNOME_PARAM_POPT_FLAGS          "popt-flags"


GNOME_PARAM_POPT_CONTEXT

#define GNOME_PARAM_POPT_CONTEXT        "popt-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_TYPE_MODULE_INFO

#define GNOME_TYPE_MODULE_INFO          (gnome_module_info_get_type ())


struct GnomeModuleInfo

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

    GnomeModuleHook instance_init;
    GnomeModuleHook pre_args_parse, post_args_parse;

    struct poptOption *options;

    GnomeModuleInitHook init_pass; /* This gets run before the preinit
				      function to allow the module to
				      register other modules as needed. The
				      module cannot assume its required
				      modules are initialized (they aren't). */

    GnomeModuleClassInitHook class_init;

    gpointer expansion1, expansion2;
};


struct GnomeModuleRequirement

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


GnomeModuleInitHook ()

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

mod_info : 


GnomeModuleClassInitHook ()

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

klass : 
mod_info : 


GnomeModuleHook ()

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

program : 
mod_info : 


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 : 


gnome_program_install_property ()

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

pclass : 
get_fn : 
set_fn : 
pspec : 
Returns : 


gnome_program_preinit ()

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

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.


gnome_program_parse_args ()

void        gnome_program_parse_args        (GnomeProgram *program);

Parses the command line arguments for the application

program : 


gnome_program_postinit ()

void        gnome_program_postinit          (GnomeProgram *program);

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

program : Application object


GNOME_PROGRAM_STANDARD_PROPERTIES

#define     GNOME_PROGRAM_STANDARD_PROPERTIES


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,
                                             ...);

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/value.
... : The continuation of a NULL-terminated list of attribute name/value pairs.
Returns : A GnomeProgram instance representing the current 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.