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.
Generated by GTK-Doc V1.18