gnome-program

Name

gnome-program -- Initialize and retrieve information about a GNOME application.

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);
#define     GNOME_PROGRAM_STANDARD_PROPERTIES

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

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


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 this enum. User applications make use of the GNOME_FILE_DOMAIN_APP_* types, which specify locations relative to GNOME_PARAM_APP_DATADIR.


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;

    struct poptOption *options;

    GnomeModuleInitHook init_pass;

    GnomeModuleClassInitHook class_init;

    const char *opt_prefix;
    gpointer    expansion1;
};


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

Every GNOME application will need to call this function (or gnome_program_initv()) early in its lifetime to initialize the various GNOME libraries in a consistent fashion. This function is very flexible in allowing the user to specify which modules should be initialised and any special paramter values that should be passed to these modules (along with processing commandline options).

It loads the specified module_info, which is normally LIBGNOME_MODULE or LIBGNOMEUI_MODULE and pulls in all the dependencies. Programs that are not running in setuid or setgid mode will also load modules specified in the --load-modules and also in the GNOME_MODULES environment variable.

After setting up the module loading, this function then calls (in order) gnome_program_preinit(), gnome_program_parse_args() and gnome_program_postinit().

The following example shows how one might initialise a typical program using a popt table that is defined elsewhere (in other words, this is how to remove the use of the deprecated gnome_init_with_popt_table() from code).


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.


GNOME_PROGRAM_STANDARD_PROPERTIES

#define     GNOME_PROGRAM_STANDARD_PROPERTIES


gnome_program_get ()

GnomeProgram* gnome_program_get             (void);


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.


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.


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.


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.


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


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.


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.


gnome_program_install_property ()

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


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.


gnome_program_parse_args ()

void        gnome_program_parse_args        (GnomeProgram *program);

Parses the command line arguments for the application


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