## IndicateIndicator

IndicateIndicator — A representation of state for applications

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libindicate/indicator.h>

    struct              IndicateIndicator;
    struct              IndicateIndicatorClass;
    guint               indicate_indicator_get_id           (IndicateIndicator *indicator);
    const gchar *       indicate_indicator_get_property     (IndicateIndicator *indicator,
                                                             const gchar *key);
    void                indicate_indicator_hide             (IndicateIndicator *indicator);
    gboolean            indicate_indicator_is_visible       (IndicateIndicator *indicator);
    GPtrArray *         indicate_indicator_list_properties  (IndicateIndicator *indicator);
    IndicateIndicator * indicate_indicator_new              (void);
    void                indicate_indicator_set_property     (IndicateIndicator *indicator,
                                                             const gchar *key,
                                                             const gchar *data);
    void                indicate_indicator_set_property_time
                                                            (IndicateIndicator *indicator,
                                                             const gchar *key,
                                                             GTimeVal *time);
    void                indicate_indicator_show             (IndicateIndicator *indicator);
    void                indicate_indicator_user_display     (IndicateIndicator *indicator,
                                                             guint timestamp);

## Object Hierarchy

      GObject
       +----IndicateIndicator

## Signals

      "displayed"                                      : Run Last
      "hide"                                           : Run Last
      "modified"                                       : Run Last
      "show"                                           : Run Last
      "user-display"                                   : Run Last

## Description

An indicator is designed to represent a single instance of something in your application. So this might be an IM or an e-mail mail box or any other thing that is a small unit of information to pass on to the user.

Indicators make no promises about how they are preceived by the user, it's up to the listener to represent them in an intutive and visually appealling way. But, what we can do is provide information on the indicator to provide enough information for the listener to do that.

Mostly this is done through properties.

It may be that some users don't want to create objects for every indicator as it could be a lot of overhead if there are large numbers and there is already a data structure representing them all. In that case it is recommended that you ignore the IndicateIndicator object tree in general and move to subclassing IndicateServer directly.

## Details

### struct IndicateIndicator

    struct IndicateIndicator;

The indicator object represents a single item that is shared over the indicator bus. This could be something like one IM, one e-mail or a single system update. It should be accessed only through its accessors.

### struct IndicateIndicatorClass

    struct IndicateIndicatorClass {
    	/* Parents */
    	GObjectClass parent_class;

    	/* Signals */
    	void (*hide) (IndicateIndicator * indicator, gpointer data);
    	void (*show) (IndicateIndicator * indicator, gpointer data);
    	void (*user_display) (IndicateIndicator * indicator, guint timestamp, gpointer data);
    	void (*modified) (IndicateIndicator * indicator, gchar * property, gpointer data);
    	void (*displayed) (IndicateIndicator * indicator, gboolean displayed);

    	/* Subclassable functions */
    	void (*set_property) (IndicateIndicator * indicator, const gchar * key, GVariant * data);
    	GVariant * (*get_property) (IndicateIndicator * indicator, const gchar * key);
    	indicate_indicator_list_properties_slot_t list_properties;

    	/* Reserver for future use */
    	void (*indicate_indicator_reserved1)(void);
    	void (*indicate_indicator_reserved2)(void);
    	void (*indicate_indicator_reserved3)(void);
    	void (*indicate_indicator_reserved4)(void);
    };

All of the functions that are used to modify or change data that is in the indicator. Typically gets subclassed by other types of indicators, for example IndicateIndicatorMessages.

GObjectClass `parent_class`; | Parent class GObjectClass.
`hide` () | Slot for "hide".
`show` () | Slot for "show".
`user_display` () | Slot for "user-display".
`modified` () | Slot for "modified".
`displayed` () | Slot for "displayed".
`set_property` () | Called when `indicate_indicator_set_property()` is called and should set the value. While typically it is overridden by subclasses they usually handle special properties themselves and then call the superclass for storage.
`get_property` () | Called when `indicate_indicator_get_property()` is called and should return the value requested. Many times this is left alone.
indicate_indicator_list_properties_slot_t `list_properties`; | Called when `indicate_indicator_list_properties()` is called and returns a list of the properties available. Again this can be overridden by subclasses to handle special properties.
`indicate_indicator_reserved1` () | Reserved for future use
`indicate_indicator_reserved2` () | Reserved for future use
`indicate_indicator_reserved3` () | Reserved for future use
`indicate_indicator_reserved4` () | Reserved for future use

### indicate_indicator_get_id ()

    guint               indicate_indicator_get_id           (IndicateIndicator *indicator);

Gets the ID value of the `indicator`.

`indicator` : | a IndicateIndicator to act on
Returns : | The ID of the indicator. Can not be zero. Zero represents an error.

### indicate_indicator_get_property ()

    const gchar *       indicate_indicator_get_property     (IndicateIndicator *indicator,
                                                             const gchar *key);

Returns the value that is set for a property or `NULL` if that property is not set.

`indicator` : | a IndicateIndicator to act on
`key` : | name of the property
Returns : | A constant string or NULL.

### indicate_indicator_hide ()

    void                indicate_indicator_hide             (IndicateIndicator *indicator);

Hides the indicator from the bus. Does not effect the indicator's IndicateServer in any way.

`indicator` : | a IndicateIndicator to act on

### indicate_indicator_is_visible ()

    gboolean            indicate_indicator_is_visible       (IndicateIndicator *indicator);

Checkes the visibility status of `indicator`.

`indicator` : | a IndicateIndicator to act on
Returns : | `TRUE` if the indicator is visible else `FALSE`.

### indicate_indicator_list_properties ()

    GPtrArray *         indicate_indicator_list_properties  (IndicateIndicator *indicator);

This function gets a list of all the properties that exist on a `indicator`. The array may have zero entries.

`indicator` : | a IndicateIndicator to act on. [in]
Returns : | An array of strings that is the keys of all the properties on this indicator. [transfer full][array][element-type utf8]

### indicate_indicator_new ()

    IndicateIndicator * indicate_indicator_new              (void);

Builds a new indicator object using `g_object_new()`.

Returns : | A pointer to a new IndicateIndicator object.

### indicate_indicator_set_property ()

    void                indicate_indicator_set_property     (IndicateIndicator *indicator,
                                                             const gchar *key,
                                                             const gchar *data);

Sets a simple string property on `indicator`. If the property had previously been set it will replace it with the new value, otherwise it will create the property. This will include an emition of "modified" if the property value was changed.

`indicator` : | a IndicateIndicator to act on
`key` : | name of the property
`data` : | value of the property

### indicate_indicator_set_property_time ()

    void                indicate_indicator_set_property_time
                                                            (IndicateIndicator *indicator,
                                                             const gchar *key,
                                                             GTimeVal *time);

This is a helper function that wraps around indicate_indicator_set_property but takes an GTimeVal parameter. It then takes the `data` parameter converts it to an ISO 8601 time string and uses that data to call indicate_indicator_set_property.

`indicator` : | a IndicateIndicator to act on
`key` : | name of the property
`time` : | time to set property with

### indicate_indicator_show ()

    void                indicate_indicator_show             (IndicateIndicator *indicator);

Shows this indicator on the bus. If the IndicateServer that it's connected to is not shown itself this function will show the server as well using indicate_server_show.

`indicator` : | a IndicateIndicator to act on

### indicate_indicator_user_display ()

    void                indicate_indicator_user_display     (IndicateIndicator *indicator,
                                                             guint timestamp);

Emits the "user-display" signal simliar to a user clicking on `indicator` over the bus. Signal will not be sent if the `indicator` is not visible.

`indicator` : | a IndicateIndicator to act on
`timestamp` : | The time that the event happened

## Signal Details

### The `"displayed"` signal

    void                user_function                      (IndicateIndicator *arg0,
                                                            gboolean           arg1,
                                                            gpointer           user_data)      : Run Last

This is the signal that the indicator has been displayed, or hidden by a listener. In most cases, the signal will be that it has been displayed as most folks don't go hiding it later.

`arg0` : | The IndicateIndicator object
`arg1` : | Whether the indicator has been displayed
`user_data` : | user data set when the signal handler was connected.

### The `"hide"` signal

    void                user_function                      (IndicateIndicator *arg0,
                                                            gpointer           user_data)      : Run Last

Emitted every time this indicator is hidden. This is mostly used by IndicateServer.

Typically this results in an emition of "indicator-removed".

`arg0` : | The IndicateIndicator object
`user_data` : | user data set when the signal handler was connected.

### The `"modified"` signal

    void                user_function                      (IndicateIndicator *arg0,
                                                            gchar             *arg1,
                                                            gpointer           user_data)      : Run Last

Emitted every time an indicator property is changed. This is mostly used by IndicateServer.

Typically this results in an emition of "indicator-modified".

`arg0` : | The IndicateIndicator object
`arg1` : | The name of the property that changed.
`user_data` : | user data set when the signal handler was connected.

### The `"show"` signal

    void                user_function                      (IndicateIndicator *arg0,
                                                            gpointer           user_data)      : Run Last

Emitted every time this indicator is shown. This is mostly used by IndicateServer.

Typically this results in an emition of "indicator-added".

`arg0` : | The IndicateIndicator object
`user_data` : | user data set when the signal handler was connected.

### The `"user-display"` signal

    void                user_function                      (IndicateIndicator *indicateindicator,
                                                            guint              arg1,
                                                            gpointer           user_data)              : Run Last

`indicateindicator` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.