MessagingMenuApp

MessagingMenuApp — An application section in the messaging menu

Synopsis

                    MessagingMenuApp;
typedef             MessagingMenuAppClass;
enum                MessagingMenuStatus;
void                messaging_menu_app_append_source    (MessagingMenuApp *app,
                                                         const gchar *id,
                                                         GIcon *icon,
                                                         const gchar *label);
void                messaging_menu_app_append_source_with_count
                                                        (MessagingMenuApp *app,
                                                         const gchar *id,
                                                         GIcon *icon,
                                                         const gchar *label,
                                                         guint count);
void                messaging_menu_app_append_source_with_string
                                                        (MessagingMenuApp *app,
                                                         const gchar *id,
                                                         GIcon *icon,
                                                         const gchar *label,
                                                         const gchar *str);
void                messaging_menu_app_append_source_with_time
                                                        (MessagingMenuApp *app,
                                                         const gchar *id,
                                                         GIcon *icon,
                                                         const gchar *label,
                                                         gint64 time);
void                messaging_menu_app_draw_attention   (MessagingMenuApp *app,
                                                         const gchar *source_id);
gboolean            messaging_menu_app_has_source       (MessagingMenuApp *app,
                                                         const gchar *source_id);
void                messaging_menu_app_insert_source    (MessagingMenuApp *app,
                                                         gint position,
                                                         const gchar *id,
                                                         GIcon *icon,
                                                         const gchar *label);
void                messaging_menu_app_insert_source_with_count
                                                        (MessagingMenuApp *app,
                                                         gint position,
                                                         const gchar *id,
                                                         GIcon *icon,
                                                         const gchar *label,
                                                         guint count);
void                messaging_menu_app_insert_source_with_string
                                                        (MessagingMenuApp *app,
                                                         gint position,
                                                         const gchar *id,
                                                         GIcon *icon,
                                                         const gchar *label,
                                                         const gchar *str);
void                messaging_menu_app_insert_source_with_time
                                                        (MessagingMenuApp *app,
                                                         gint position,
                                                         const gchar *id,
                                                         GIcon *icon,
                                                         const gchar *label,
                                                         gint64 time);
MessagingMenuApp *  messaging_menu_app_new              (const gchar *desktop_id);
void                messaging_menu_app_register         (MessagingMenuApp *app);
void                messaging_menu_app_remove_attention (MessagingMenuApp *app,
                                                         const gchar *source_id);
void                messaging_menu_app_remove_source    (MessagingMenuApp *app,
                                                         const gchar *source_id);
void                messaging_menu_app_set_source_count (MessagingMenuApp *app,
                                                         const gchar *source_id,
                                                         guint count);
void                messaging_menu_app_set_source_string
                                                        (MessagingMenuApp *app,
                                                         const gchar *source_id,
                                                         const gchar *str);
void                messaging_menu_app_set_source_time  (MessagingMenuApp *app,
                                                         const gchar *source_id,
                                                         gint64 time);
void                messaging_menu_app_set_status       (MessagingMenuApp *app,
                                                         MessagingMenuStatus status);
void                messaging_menu_app_unregister       (MessagingMenuApp *app);

Object Hierarchy

  GObject
   +----MessagingMenuApp

Properties

  "desktop-id"               gchar*                : Write / Construct Only

Signals

  "activate-source"                                : Has Details
  "status-changed"                                 : Run First

Description

A MessagingMenuApp represents an application section in the Messaging Menu. An application section is tied to an installed application through a desktop file id, which must be passed to messaging_menu_app_new().

To register the appliction with the Messaging Menu, call messaging_menu_app_register(). This signifies that the application should be present in the menu and be marked as "running".

The first menu item in an application section represents the application itself, using the name and icon found in the associated desktop file. Activating this item starts the application.

Following the application item, the Messaging Menu inserts all shortcuts actions found in the desktop file which are marked as appearing in the Messaging Menu (the TargetEnvironment or OnlyShowIn keywords contains "Messaging Menu"). The desktop file specification contains a detailed explanation of shortcut actions [1]. An application cannot add, remove, or change these shortcut items while it is running.

Next, an application section contains menu items for message sources. What exactly constitutes a message source depends on the type of application: an email client's message sources are folders containing new messages, while those of a chat program are persons that have contacted the user.

A message source is represented in the menu by a label and optionally also an icon. It can be associated with either a count, a time, or an arbitrary string, which will appear on the right side of the menu item.

When the user activates a source, the source is immediately removed from the menu and the "activate-source" signal is emitted.

Applications should always expose all the message sources available. However, the Messaging Menu might limit the amount of sources it displays to the user.

The Messaging Menu offers users a way to set their chat status (available, away, busy, invisible, or offline) for multiple applications at once. Applications that appear in the Messaging Menu can integrate with this by setting the "X-MessagingMenu-UsesChatSection" key in their desktop file to True. Use messaging_menu_app_set_status() to signify that the application's chat status has changed. When the user changes status through the Messaging Menu, the ::status-changed signal will be emitted.

If the application stops running without calling messaging_menu_app_unregister(), it will be marked as "not running". Its application and shortcut items stay in the menu, but all message sources are removed. If messaging_menu_app_unregister() is called, the application section is removed completely.

More information about the design and recommended usage of the Messaging Menu is available at https://wiki.ubuntu.com/MessagingMenu.

Details

MessagingMenuApp

typedef struct _MessagingMenuApp MessagingMenuApp;

MessagingMenuApp is an opaque structure.

MessagingMenuAppClass

typedef GObjectClass             MessagingMenuAppClass;

enum MessagingMenuStatus

typedef enum {
  MESSAGING_MENU_STATUS_AVAILABLE,
  MESSAGING_MENU_STATUS_AWAY,
  MESSAGING_MENU_STATUS_BUSY,
  MESSAGING_MENU_STATUS_INVISIBLE,
  MESSAGING_MENU_STATUS_OFFLINE
} MessagingMenuStatus;

An enumeration for the possible chat statuses the messaging menu can be in.

MESSAGING_MENU_STATUS_AVAILABLE

 available

MESSAGING_MENU_STATUS_AWAY

 away

MESSAGING_MENU_STATUS_BUSY

 busy

MESSAGING_MENU_STATUS_INVISIBLE

 invisible

MESSAGING_MENU_STATUS_OFFLINE

 offline

messaging_menu_app_append_source ()

void                messaging_menu_app_append_source    (MessagingMenuApp *app,
                                                         const gchar *id,
                                                         GIcon *icon,
                                                         const gchar *label);

Appends a new message source to the end of the section representing app. Equivalent to calling messaging_menu_app_append_source_with_time() with the current time.

It is an error to add a source with an id which already exists. Use messaging_menu_app_has_source() to find out whether there is such a source.

app :

 a MessagingMenuApp

id :

 a unique identifier for the source to be added

icon :

 the icon associated with the source. [allow-none]

label :

 a user-visible string best describing the source

messaging_menu_app_append_source_with_count ()

void                messaging_menu_app_append_source_with_count
                                                        (MessagingMenuApp *app,
                                                         const gchar *id,
                                                         GIcon *icon,
                                                         const gchar *label,
                                                         guint count);

Appends a new message source to the end of the section representing app and initializes it with count.

To update the count, use messaging_menu_app_set_source_count().

It is an error to add a source with an id which already exists. Use messaging_menu_app_has_source() to find out whether there is such a source.

app :

 a MessagingMenuApp

id :

 a unique identifier for the source to be added

icon :

 the icon associated with the source. [allow-none]

label :

 a user-visible string best describing the source

count :

 the count for the source

messaging_menu_app_append_source_with_string ()

void                messaging_menu_app_append_source_with_string
                                                        (MessagingMenuApp *app,
                                                         const gchar *id,
                                                         GIcon *icon,
                                                         const gchar *label,
                                                         const gchar *str);

Appends a new message source to the end of the section representing app and initializes it with str.

To update the string, use messaging_menu_app_set_source_string().

It is an error to insert a source with an id which already exists. Use messaging_menu_app_has_source() to find out whether there is such a source.

app :

 a MessagingMenuApp

id :

 a unique identifier for the source to be added

icon :

 the icon associated with the source. [allow-none]

label :

 a user-visible string best describing the source

str :

 a string associated with the source

messaging_menu_app_append_source_with_time ()

void                messaging_menu_app_append_source_with_time
                                                        (MessagingMenuApp *app,
                                                         const gchar *id,
                                                         GIcon *icon,
                                                         const gchar *label,
                                                         gint64 time);

Appends a new message source to the end of the section representing app and initializes it with time.

To change the time, use messaging_menu_app_set_source_time().

It is an error to insert a source with an id which already exists. Use messaging_menu_app_has_source() to find out whether there is such a source.

app :

 a MessagingMenuApp

id :

 a unique identifier for the source to be added

icon :

 the icon associated with the source. [allow-none]

label :

 a user-visible string best describing the source

time :

 the time when the source was created

messaging_menu_app_draw_attention ()

void                messaging_menu_app_draw_attention   (MessagingMenuApp *app,
                                                         const gchar *source_id);

Indicates that source_id has important unread messages. Currently, this means that the messaging menu's envelope icon will turn blue.

Use messaging_menu_app_remove_attention() to stop indicating that the source needs attention.

app :

 a MessagingMenuApp

source_id :

 a source id

messaging_menu_app_has_source ()

gboolean            messaging_menu_app_has_source       (MessagingMenuApp *app,
                                                         const gchar *source_id);

app :

 a MessagingMenuApp

source_id :

 a source id

Returns :

 TRUE if there is a source associated with source_id

messaging_menu_app_insert_source ()

void                messaging_menu_app_insert_source    (MessagingMenuApp *app,
                                                         gint position,
                                                         const gchar *id,
                                                         GIcon *icon,
                                                         const gchar *label);

Inserts a new message source into the section representing app. Equivalent to calling messaging_menu_app_insert_source_with_time() with the current time.

It is an error to insert a source with an id which already exists. Use messaging_menu_app_has_source() to find out whether there is such a source.

app :

 a MessagingMenuApp

position :

 the position at which to insert the source

id :

 a unique identifier for the source to be added

icon :

 the icon associated with the source

label :

 a user-visible string best describing the source

messaging_menu_app_insert_source_with_count ()

void                messaging_menu_app_insert_source_with_count
                                                        (MessagingMenuApp *app,
                                                         gint position,
                                                         const gchar *id,
                                                         GIcon *icon,
                                                         const gchar *label,
                                                         guint count);

Inserts a new message source into the section representing app and initializes it with count.

To update the count, use messaging_menu_app_set_source_count().

It is an error to insert a source with an id which already exists. Use messaging_menu_app_has_source() to find out whether there is such a source.

app :

 a MessagingMenuApp

position :

 the position at which to insert the source

id :

 a unique identifier for the source to be added

icon :

 the icon associated with the source. [allow-none]

label :

 a user-visible string best describing the source

count :

 the count for the source

messaging_menu_app_insert_source_with_string ()

void                messaging_menu_app_insert_source_with_string
                                                        (MessagingMenuApp *app,
                                                         gint position,
                                                         const gchar *id,
                                                         GIcon *icon,
                                                         const gchar *label,
                                                         const gchar *str);

Inserts a new message source into the section representing app and initializes it with str.

To update the string, use messaging_menu_app_set_source_string().

It is an error to insert a source with an id which already exists. Use messaging_menu_app_has_source() to find out whether there is such a source.

app :

 a MessagingMenuApp

position :

 the position at which to insert the source

id :

 a unique identifier for the source to be added

icon :

 the icon associated with the source. [allow-none]

label :

 a user-visible string best describing the source

str :

 a string associated with the source

messaging_menu_app_insert_source_with_time ()

void                messaging_menu_app_insert_source_with_time
                                                        (MessagingMenuApp *app,
                                                         gint position,
                                                         const gchar *id,
                                                         GIcon *icon,
                                                         const gchar *label,
                                                         gint64 time);

Inserts a new message source into the section representing app and initializes it with time.

To change the time, use messaging_menu_app_set_source_time().

It is an error to insert a source with an id which already exists. Use messaging_menu_app_has_source() to find out whether there is such a source.

app :

 a MessagingMenuApp

position :

 the position at which to insert the source

id :

 a unique identifier for the source to be added

icon :

 the icon associated with the source. [allow-none]

label :

 a user-visible string best describing the source

time :

 the time when the source was created

messaging_menu_app_new ()

MessagingMenuApp *  messaging_menu_app_new              (const gchar *desktop_id);

messaging_menu_app_register ()

void                messaging_menu_app_register         (MessagingMenuApp *app);

Registers app with the Messaging Menu.

If the application doesn't already have a section in the Messaging Menu, one will be created for it. The application will also be marked as "running".

The application will be marked as "not running" as soon as app is destroyed. The application launcher as well as shortcut actions will remain in the menu. To completely remove the application section from the Messaging Menu, call messaging_menu_app_unregister().

app :

 a MessagingMenuApp

messaging_menu_app_remove_attention ()

void                messaging_menu_app_remove_attention (MessagingMenuApp *app,
                                                         const gchar *source_id);

Stop indicating that source_id needs attention.

This function does not need to be called when the source is removed with messaging_menu_app_remove_source() or the user has activated the source.

Use messaging_menu_app_draw_attention() to make source_id draw attention again.

app :

 a MessagingMenuApp

source_id :

 a source id

messaging_menu_app_remove_source ()

void                messaging_menu_app_remove_source    (MessagingMenuApp *app,
                                                         const gchar *source_id);

Removes the source corresponding to source_id from the menu.

app :

 a MessagingMenuApp

source_id :

 the id of the source to remove

messaging_menu_app_set_source_count ()

void                messaging_menu_app_set_source_count (MessagingMenuApp *app,
                                                         const gchar *source_id,
                                                         guint count);

Updates the count of source_id to count.

app :

 a MessagingMenuApp

source_id :

 a source id

count :

 the new count for the source

messaging_menu_app_set_source_string ()

void                messaging_menu_app_set_source_string
                                                        (MessagingMenuApp *app,
                                                         const gchar *source_id,
                                                         const gchar *str);

Updates the string displayed next to source_id to str.

Note that the string is only displayed if the source does not also have a count or time associated with it.

app :

 a MessagingMenuApp

source_id :

 a source id

str :

 the new string for the source

messaging_menu_app_set_source_time ()

void                messaging_menu_app_set_source_time  (MessagingMenuApp *app,
                                                         const gchar *source_id,
                                                         gint64 time);

Updates the time of source_id to time.

Note that the time is only displayed if the source does not also have a count associated with it.

app :

 a MessagingMenuApp

source_id :

 a source id

time :

 the new time for the source

messaging_menu_app_set_status ()

void                messaging_menu_app_set_status       (MessagingMenuApp *app,
                                                         MessagingMenuStatus status);

Notify the Messaging Menu that the chat status of app has changed to status.

Connect to the ::status-changed signal to receive notification about the user changing their global chat status through the Messaging Menu.

This function does nothing for applications whose desktop file does not include X-MessagingMenu-UsesChatSection.

app :

 a MessagingMenuApp

status :

 a MessagingMenuStatus

messaging_menu_app_unregister ()

void                messaging_menu_app_unregister       (MessagingMenuApp *app);

Completely removes the app from the Messaging Menu. If the application's launcher and shortcut actions should remain in the menu, destroying app with g_object_unref() suffices.

Note: app will remain valid and usable after this call.

app :

 a MessagingMenuApp

Property Details

The "desktop-id" property

  "desktop-id"               gchar*                : Write / Construct Only

The desktop id of the application associated with this application section. Must be given when the MessagingMenuApp is created.

Default value: NULL

Signal Details

The "activate-source" signal

void                user_function                      (MessagingMenuApp *mmapp,
                                                        gchar            *source_id,
                                                        gpointer          user_data)      : Has Details

Emitted when the user has activated the message source with id source_id. The source is immediately removed from the menu, handlers of this signal do not need to call messaging_menu_app_remove_source().

mmapp :

 the MessagingMenuApp

source_id :

 the source id that was activated

user_data :

 user data set when the signal handler was connected.

The "status-changed" signal

void                user_function                      (MessagingMenuApp *mmapp,
                                                        gint              status,
                                                        gpointer          user_data)      : Run First

Emitted when the chat status is changed through the messaging menu.

Applications which are registered to use the chat status should change their status to status upon receiving this signal. Call messaging_menu_app_set_status() to acknowledge that the application changed its status.

mmapp :

 the MessagingMenuApp

status :

 a MessagingMenuStatus

user_data :

 user data set when the signal handler was connected.
Generated by GTK-Doc V1.18