Gnome Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# gnome-triggers

## Name

gnome-triggers -- Hierarchical signal mechanism for application events.

## Synopsis

    #include <gnome.h>

    enum        GnomeTriggerType;
    void        (*GnomeTriggerActionFunction)   (char *msg,
                                                 char *level,
                                                 char *supinfo[]);
    struct      GnomeTrigger;
    void        gnome_triggers_init             (void);
    gint        gnome_triggers_readfile         (const char *infilename);
    void        gnome_triggers_add_trigger      (GnomeTrigger *nt,
                                                 ...);
    void        gnome_triggers_vadd_trigger     (GnomeTrigger *nt,
                                                 char *supinfo[]);
    void        gnome_triggers_do               (const char *msg,
                                                 const char *level,
                                                 ...);
    void        gnome_triggers_vdo              (const char *msg,
                                                 const char *level,
                                                 const char *supinfo[]);

## Description

The GNOME triggers API was intended to provide a general way for the application to tell GNOME about "interesting events". Most of it is presently deprecated - at the present time, the application writer should only use gnome_triggers_do and gnome_triggers_vdo for the purpose of firing application sound events (in conjunction with .soundlist files).

Please see the "GNOME configuration files" white paper for more information on .soundlist files.

## Details

### enum GnomeTriggerType

    typedef enum {
    	GTRIG_NONE,
    	GTRIG_FUNCTION,
    	GTRIG_COMMAND,
    	GTRIG_MEDIAPLAY
    }  GnomeTriggerType;

Deprecated.

### GnomeTriggerActionFunction ()

    void        (*GnomeTriggerActionFunction)   (char *msg,
                                                 char *level,
                                                 char *supinfo[]);

Deprecated.

`msg` : |
`level` : |
`supinfo` : |

### struct GnomeTrigger

    struct GnomeTrigger {
    	GnomeTriggerType type;
    	union {
    		/*
    		 * These will be passed the same info as
    		 * gnome_triggers_do got
    		 */
    		GnomeTriggerActionFunction function;
    		gchar *command;
    		struct {
    			gchar *file;
    			int cache_id;
    		} media;
    	} u;
            gchar *level;
    };

Deprecated.

### gnome_triggers_init ()

    void        gnome_triggers_init             (void);

Deprecated.

### gnome_triggers_readfile ()

    gint        gnome_triggers_readfile         (const char *infilename);

The file should be of the format:

level section type params

Where 'level' indicates the message severity at which this trigger should be activated, 'section' is a colon-separated list indicating which part of the "message classification tree" this trigger will be activated for, 'type' is either "command" (run the command specified in 'params') or 'play' (play the esd sound sample named 'params').

Deprecated.

`infilename` : | A file listing triggers to install in the currently running program.
Returns : | 0 on success. 1 otherwise.

### gnome_triggers_add_trigger ()

    void        gnome_triggers_add_trigger      (GnomeTrigger *nt,
                                                 ...);

Similar to gnome_triggers_readfile(), but gets the trigger information from the file 'nt' structure and the varargs, instead of from a file.

Deprecated.

`nt` : | Information on the new trigger to be added.
`...` : | the 'section' to add the trigger under (see gnome_triggers_readfile())

### gnome_triggers_vadd_trigger ()

    void        gnome_triggers_vadd_trigger     (GnomeTrigger *nt,
                                                 char *supinfo[]);

Similar to gnome_triggers_readfile(), but gets the trigger information from the file 'nt' structure and 'supinfo', instead of from a file.

Deprecated.

`nt` : | Information on the new trigger to be added.
`supinfo` : | the 'section' to add the trigger under (see gnome_triggers_readfile())

### gnome_triggers_do ()

    void        gnome_triggers_do               (const char *msg,
                                                 const char *level,
                                                 ...);

Notifies GNOME about an event happening, so GNOME can do cool things.

This function tells the GNOME framework that an event has occurred inside the application that GNOME might be interested in. Currently this is just used to trigger user-configurable sound events.

`msg` : | The human-readable message describing the event. (Can be NULL).
`level` : | The level of severity of the event, or NULL.
`...` : | The classification of the event.

### gnome_triggers_vdo ()

    void        gnome_triggers_vdo              (const char *msg,
                                                 const char *level,
                                                 const char *supinfo[]);

Notifies GNOME about an event happening, so GNOME can do cool things.

This function is the same as gnome_triggers_do, except the supinfo is passed as an array of strings, rather than as a variable number of arguments.

`msg` : | The human-readable message describing the event. (Can be NULL).
`level` : | The level of severity of the event, or NULL.
`supinfo` : | The classification of the event (NULL terminated array).

<<< Previous Page | Home | Up | Next Page >>>
gnome-sound | gnome-url