# gnome-triggers

## Name

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

## Synopsis

    #include <libgnome/libgnome.h>

    enum        GnomeTriggerType;
    void        (*GnomeTriggerActionFunction)   (char *msg,
                                                 char *level,
                                                 char *supinfo[]);
    struct      GnomeTrigger;
    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 triggers API provides a way for applications to tell GNOME about interesting events that then cause something to happen (for example, playing a sound). An event can either be a function that is called, a sound that is played or an external command that is run.

Each trigger can optionally have a level associated with it and a section. The section is a list of strings that help to classify the event, which imposes a hierarchy on the trigger system. For example, messages about the hard drive partition /dev/hda1 may come under the section ("system", "device", "disk", "/dev/hda1"). This means that an application could trigger all events for the ("system", "device") sections and include those events, or be more specific and just trigger those for ("system", "device", "disk", "/dev/hda1").

At the present time, triggers are not widely used in GNOME, being mostly used to play sound events in response to certain actions.

## Details

### enum GnomeTriggerType

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

These are the different types of triggers that can be activated by an application.

`GTRIG_NONE` | A null trigger type. Should never be used.
`GTRIG_FUNCTION` | The trigger causes a function to be executed.
`GTRIG_COMMAND` | The trigger causes a command to be executed (using execv()).
`GTRIG_MEDIAPLAY` | The trigger causes a sound to be played.

### GnomeTriggerActionFunction ()

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

The signature of a function that can used as a target for GTRIG_FUNCTION types of GnomeTrigger instances.

`msg` : | The human-readable message that was passed to gnome_triggers_do(). May be `NULL`.
`level` : | The severity level of the event. May be `NULL`.
`supinfo` : | The section in which the event belongs. This is a `NULL` terminated array.

### struct GnomeTrigger

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

This structure stores the information about an action that is triggered for a particular event. A filled in instance of this structure is passed to gnome_triggers_add_trigger() and gnome_triggers_vadd_trigger().

### gnome_triggers_add_trigger ()

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

Adds a new GnomeTrigger instance to the event hierarchy.

`nt` : | Information on the new trigger to be added.
`...` : | The section to add the trigger under.

### gnome_triggers_vadd_trigger ()

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

This does the same as gnome_triggers_add_trigger(), except the section is stored in the `NULL` terminated array `supinfo` instead of as a variable length argument list.

`nt` : | Information on the new trigger to be added.
`supinfo` : | The section to add the trigger under.

### gnome_triggers_do ()

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

Notifies GNOME about an event happening, so that any appropriate handlers can be run.

`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 that any appropriate handlers can be run. This does the same as gnome_trigger_do() except that it takes a `NULL` terminated array instead of a varargs list.

`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).