IndicateIndicator

IndicateIndicator — A representation of state for applications

Stability Level

Unstable, unless otherwise indicated

Functions

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── IndicateIndicator

Includes

#include <libindicate/indicator.h>

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.

Functions

indicate_indicator_get_id ()

guint
indicate_indicator_get_id (IndicateIndicator *indicator);

Gets the ID value of the indicator .

Parameters

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.

Parameters

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.

Parameters

indicator

a IndicateIndicator to act on

 

indicate_indicator_is_visible ()

gboolean
indicate_indicator_is_visible (IndicateIndicator *indicator);

Checkes the visibility status of indicator .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

indicator

a IndicateIndicator to act on

 

timestamp

The time that the event happened

 

Types and Values

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.

Members

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

 

Signal Details

The “displayed” signal

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

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.

Parameters

arg0

The IndicateIndicator object

 

arg1

Whether the indicator has been displayed

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “hide” signal

void
user_function (IndicateIndicator *arg0,
               gpointer           user_data)

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

Typically this results in an emition of “indicator-removed”.

Parameters

arg0

The IndicateIndicator object

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “modified” signal

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

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

Typically this results in an emition of “indicator-modified”.

Parameters

arg0

The IndicateIndicator object

 

arg1

The name of the property that changed.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “show” signal

void
user_function (IndicateIndicator *arg0,
               gpointer           user_data)

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

Typically this results in an emition of “indicator-added”.

Parameters

arg0

The IndicateIndicator object

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “user-display” signal

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

Parameters

indicateindicator

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last