enum MateFileDomain

typedef enum {
    MATE_FILE_DOMAIN_UNKNOWN = 0,

    /* Mate installed files */
    MATE_FILE_DOMAIN_LIBDIR,
    MATE_FILE_DOMAIN_DATADIR,
    MATE_FILE_DOMAIN_SOUND,
    MATE_FILE_DOMAIN_PIXMAP,
    MATE_FILE_DOMAIN_CONFIG,
    MATE_FILE_DOMAIN_HELP,

    /* Application files */
    MATE_FILE_DOMAIN_APP_LIBDIR,
    MATE_FILE_DOMAIN_APP_DATADIR,
    MATE_FILE_DOMAIN_APP_SOUND,
    MATE_FILE_DOMAIN_APP_PIXMAP,
    MATE_FILE_DOMAIN_APP_CONFIG,
    MATE_FILE_DOMAIN_APP_HELP
} MateFileDomain;

Many of the files that a MATE application needs to access will be installed in standard locations. For example, MATE 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 MATE_FILE_DOMAIN_APP_* types, which specify locations relative to MATE_PARAM_APP_DATADIR.

struct MateProgram

struct MateProgram {
    GObject object;

    MateProgramPrivate *_priv;
};

A structure containing information about the current application. Initialised during a call to mate_program_init().

struct MateModuleInfo

struct MateModuleInfo {
    const char *name;
    const char *version;
    const char *description;
    MateModuleRequirement *requirements; /* last element has NULL version */

    MateModuleHook instance_init;
    MateModuleHook pre_args_parse, post_args_parse;

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

    MateModuleInitHook init_pass;

    MateModuleClassInitHook class_init;

    const char *opt_prefix;
    MateModuleGetGOptionGroupFunc get_goption_group_func;
};

A structure containing information about a module. This contains descriptive information about the module, as well as how to initialise it and what its dependencies are (chained via the requirements parameter).

struct MateModuleRequirement

struct MateModuleRequirement {
    const char *required_version;
    const MateModuleInfo *module_info;
};

A structure which allows a module to specify the minimum required versions of modules it depends upon.

MateModuleInitHook ()

void                (*MateModuleInitHook)              (const MateModuleInfo *mod_info);

A function that will be called to allow a module to do any pre-initialisation it might need to do prior to having arguments parsed by the controlling parent module (the parent will do the argument parsing for all modules in the hierarchy).

MateModuleClassInitHook ()

void                (*MateModuleClassInitHook)         (MateProgramClass *klass,
                                                         const MateModuleInfo *mod_info);

A function called to perform any class specific setup that is required by each module.

MateModuleHook ()

void                (*MateModuleHook)                  (MateProgram *program,
                                                         MateModuleInfo *mod_info);

A function that is called to perform some intialisation in a module (which could be either the main init function or the pre or post argument parsing phase).

mate_program_init ()

MateProgram *      mate_program_init                  (const char *app_id,
                                                         const char *app_version,
                                                         const MateModuleInfo *module_info,
                                                         int argc,
                                                         char **argv,
                                                         const char *first_property_name,
                                                         ...);

Initialises the current MATE libraries for use by the application. app_id is used for the following purposes: - to find the programme's help files by mate_help_*() - to load the app-specific gtkrc file from ~/.mate2/$(APPID)rc - to load/save the app's accelerators map from ~/.mate2/accelerators/$(APPID) - to load/save a MateEntry's history from mateconf/apps/mate-settings/$(APPID)/history-$(ENTRYID)

Every MATE application will need to call this function (or mate_program_initv()) early in its lifetime to initialize the various MATE 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 LIBMATE_MODULE or LIBMATEUI_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 MATE_MODULES environment variable.

The following example shows how one might initialise a typical program using a goption table that is defined elsewhere.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

int main(int argc, char **argv) {
    MateProgram *my_app;
    GOptionContext *option_context;
    /* We assume PACKAGE and VERSION are set to the program name and version
     * number respectively. Also, assume that 'options' is a global array of
     * poptOptions.
     */
    option_context = g_option_context_new (PACKAGE);
    g_option_context_add_main_entries (option_context, options, NULL);
    my_app = mate_program_init(PACKAGE, VERSION, LIBMATEUI_MODULE,
                                argc, argv,
                    MATE_PARAM_GOPTION_CONTEXT, option_context,
                    MATE_PARAM_NONE);
    /* Now process any extra args, etc ... */
}

Even though many applications still use popt for command-line option parsing, it has been deprecated in Mate-2.14 and its use is discouraged for newly-written code. MATE applications should aim to use the new GOption API. Here an example that shows how one might initialize a typical program using a GOptionEntry table (see the GLib documentation for a more elaborate example of an option entry table):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

int main(int argc, char **argv) {
    gchar **remaining_args = NULL;
    GOptionEntry option_entries[] = {
        /* ... your application's command line options go here ... */
        /* last but not least a special option that collects filenames */
        { G_OPTION_REMAINING, 0, 0, G_OPTION_ARG_FILENAME_ARRAY,
          &remaining_args,
          "Special option that collects any remaining arguments for us" },
        { NULL }
    };
    GOptionContext *option_context;
    MateProgram *my_app;
    option_context = g_option_context_new ("my-app");
    /* if you are using any libraries that have command line options
     * of their own and provide a GOptionGroup with them, you can
     * add them here as well using g_option_context_add_group()
     */
    /* now add our own application's command-line options. If you
     * are using gettext for translations, you should be using
     * GETTEXT_PACKAGE here instead of NULL
     */
    g_option_context_add_main_entries (option_context, option_entries, NULL);
    /* We assume PACKAGE and VERSION are set to the program name and version
     * number respectively. Also, assume that 'option_entries' is a global
     * array of GOptionEntry structures.
     */
    my_app = mate_program_init(PACKAGE, VERSION,
                                LIBMATEUI_MODULE, argc, argv,
                                MATE_PARAM_GOPTION_CONTEXT, option_context,
                                MATE_PARAM_NONE);
    /* parse remaining command-line arguments that are not
     * options (e.g. filenames or URIs or whatever), if any
     */
    if (remaining_args != NULL) {
        gint i, num_args;
        num_args = g_strv_length (remaining_args);
        for (i = 0; i < num_args; ++i) {
            /* process remaining_args[i] here */
        }
        g_strfreev (remaining_args);
        remaining_args = NULL;
    }

mate_program_initv ()

MateProgram *      mate_program_initv                 (GType type,
                                                         const char *app_id,
                                                         const char *app_version,
                                                         const MateModuleInfo *module_info,
                                                         int argc,
                                                         char **argv,
                                                         const char *first_property_name,
                                                         va_list args);

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

mate_program_get ()

MateProgram *      mate_program_get                   (void);

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

mate_program_get_human_readable_name ()

const char *        mate_program_get_human_readable_name
                                                        (MateProgram *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 MATE_PARAM_HUMAN_READABLE_NAME init argument. Returns NULL if no name was set.

mate_program_get_app_id ()

const char *        mate_program_get_app_id            (MateProgram *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.

mate_program_get_app_version ()

const char *        mate_program_get_app_version       (MateProgram *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.

mate_program_locate_file ()

gchar *             mate_program_locate_file           (MateProgram *program,
                                                         MateFileDomain 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 MATE_FILE_DOMAIN_APP_* domains. However you MUST set the correct attributes for MateProgram 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.

mate_program_module_register ()

void                mate_program_module_register       (const MateModuleInfo *module_info);

This function is used to register a module to be initialized by the MATE 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.

mate_program_module_registered ()

gboolean            mate_program_module_registered     (const MateModuleInfo *module_info);

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

mate_program_module_load ()

const MateModuleInfo * mate_program_module_load       (const char *mod_name);

Loads a shared library that contains a MateModuleInfo dynamic_module_info structure.

mate_program_install_property ()

guint               mate_program_install_property      (MateProgramClass *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.

mate_program_preinit ()

poptContext         mate_program_preinit               (MateProgram *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.

mate_program_parse_args ()

void                mate_program_parse_args            (MateProgram *program);

Parses the command line arguments for the application

mate_program_postinit ()

void                mate_program_postinit              (MateProgram *program);

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

MATE_PARAM_POPT_TABLE

#define MATE_PARAM_POPT_TABLE          "popt-table"

This parameter contains the table of options to be passed to popt (write on init only). Mutually exclusive with using MATE_PARAM_GOPTION_CONTEXT parameter.

MATE_PARAM_POPT_FLAGS

#define MATE_PARAM_POPT_FLAGS          "popt-flags"

This parameter contains the flags to use for popt (write on init only).

MATE_PARAM_POPT_CONTEXT

#define MATE_PARAM_POPT_CONTEXT        "popt-context"

This parameter contains the context pointer that MateProgram is using for popt parsing (readable).

MATE_PARAM_GOPTION_CONTEXT

#define MATE_PARAM_GOPTION_CONTEXT     "goption-context"

This parameter contains the GOptionContext pointer that MateProgram is using for GOption parsing (write on init only). The MateProgram will assume ownership of the passed GOptionContext. Mutually exclusive with using the MATE_PARAM_POPT_TABLE parameter.

Since 2.14

MATE_PARAM_CREATE_DIRECTORIES

#define MATE_PARAM_CREATE_DIRECTORIES  "create-directories"

This parameter contains TRUE if the standard MATE directories should be created on startup.

MATE_PARAM_ENABLE_SOUND

#define MATE_PARAM_ENABLE_SOUND        "enable-sound"

This parameter determines whether or not to enable sound on startup.

MATE_PARAM_ESPEAKER

#define MATE_PARAM_ESPEAKER            "espeaker"

This parameter describes how to connect to esd.

MATE_PARAM_APP_ID

#define MATE_PARAM_APP_ID              "app-id"

This parameter contains the ID string to use for the application (readable).

MATE_PARAM_APP_VERSION

#define MATE_PARAM_APP_VERSION         "app-version"

This parameter contains the application version (readable).

MATE_PARAM_MATE_PREFIX

#define MATE_PARAM_MATE_PREFIX        "mate-prefix"

This parameter contains the prefix where the main MATE system is installed (readable, writable on init only).

MATE_PARAM_MATE_SYSCONFDIR

#define MATE_PARAM_MATE_SYSCONFDIR    "mate-sysconfdir"

This parameter contains the prefix where the MATE configuration files are installed (readable, writable on init only).

MATE_PARAM_MATE_DATADIR

#define MATE_PARAM_MATE_DATADIR       "mate-datadir"

This parameter contains the prefix where the MATE data files are installed (readable, writable on init only).

MATE_PARAM_MATE_LIBDIR

#define MATE_PARAM_MATE_LIBDIR        "mate-libdir"

This parameter contains the prefix where the MATE library files are installed (readable, writable on init only).

MATE_PARAM_APP_PREFIX

#define MATE_PARAM_APP_PREFIX          "app-prefix"

This parameter contains the prefix where this application was installed (read / write).

MATE_PARAM_APP_SYSCONFDIR

#define MATE_PARAM_APP_SYSCONFDIR      "app-sysconfdir"

This parameter contains the prefix where this application's configuration files are installed (read / write).

MATE_PARAM_APP_DATADIR

#define MATE_PARAM_APP_DATADIR         "app-datadir"

This parameter contains the prefix where this application's data files are installed (read / write).

MATE_PARAM_APP_LIBDIR

#define MATE_PARAM_APP_LIBDIR          "app-libdir"

This parameter contains the prefix where this application's library files are installed (read / write).

MATE_PARAM_HUMAN_READABLE_NAME

#define MATE_PARAM_HUMAN_READABLE_NAME "human-readable-name"

This parameter contains the human readable name of the application (readable).

MATE_PARAM_MATE_PATH

#define MATE_PARAM_MATE_PATH          "mate-path"

This parameter contains the path in which to look for installed files (taken from the MATE2_PATH environment variable).

MATE_PARAM_NONE

#define MATE_PARAM_NONE                NULL

Used to terminate a list of parameters and their values.

MATE_PROGRAM_STANDARD_PROPERTIES

#define             MATE_PROGRAM_STANDARD_PROPERTIES

When PREFIX, SYSCONFDIR, DATADIR and LIBDIR are defined during the build process, this macro can be used to assign these values to MATE_PARAM_APP_PREFIX, MATE_PARAM_APP_SYSCONFDIR, MATE_PARAM_APP_DATADIR and MATE_PARAM_APP_LIBDIR respectively so that the MATE libraries automatically know where to fetch application specific data from.

Every respectable MATE application should set these variables and use MATE_PROGRAM_STANDARD_PROPERTIES in the call to mate_program_init().