IndicateIndicator: libindicate Reference Manual

IndicateIndicator

IndicateIndicator — A representation of state for applications

Stability Level

Unstable, unless otherwise indicated

Functions

guint	indicate_indicator_get_id ()
const gchar *	indicate_indicator_get_property ()
void	indicate_indicator_hide ()
gboolean	indicate_indicator_is_visible ()
GPtrArray *	indicate_indicator_list_properties ()
IndicateIndicator *	indicate_indicator_new ()
void	indicate_indicator_set_property ()
void	indicate_indicator_set_property_time ()
void	indicate_indicator_show ()
void	indicate_indicator_user_display ()

Signals

void	displayed	Run Last
void	hide	Run Last
void	modified	Run Last
void	show	Run Last
void	user-display	Run Last

Types and Values

struct	IndicateIndicator
struct	IndicateIndicatorClass

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