MessagingMenuApp: Messaging Menu Reference Manual

## MessagingMenuApp MessagingMenuApp — An application section in the messaging menu |

## Functions

MessagingMenuApp * | messaging_menu_app_new ()
void | messaging_menu_app_register ()
void | messaging_menu_app_unregister ()
void | messaging_menu_app_set_status ()
void | messaging_menu_app_insert_source ()
void | messaging_menu_app_append_source ()
void | messaging_menu_app_insert_source_with_count ()
void | messaging_menu_app_append_source_with_count ()
void | messaging_menu_app_insert_source_with_time ()
void | messaging_menu_app_append_source_with_time ()
void | messaging_menu_app_append_source_with_string ()
void | messaging_menu_app_insert_source_with_string ()
void | messaging_menu_app_remove_source ()
gboolean | messaging_menu_app_has_source ()
void | messaging_menu_app_set_source_label ()
void | messaging_menu_app_set_source_icon ()
void | messaging_menu_app_set_source_count ()
void | messaging_menu_app_set_source_time ()
void | messaging_menu_app_set_source_string ()
void | messaging_menu_app_draw_attention ()
void | messaging_menu_app_remove_attention ()
void | messaging_menu_app_append_message ()
MessagingMenuMessage * | messaging_menu_app_get_message ()
void | messaging_menu_app_remove_message ()
void | messaging_menu_app_remove_message_by_id ()

## Properties

char * | desktop-id | Write / Construct Only

## Signals

void | activate-source | Has Details
void | status-changed | Run First

## Types and Values

enum | MessagingMenuStatus
typedef | MessagingMenuAppClass
| MessagingMenuApp

## Object Hierarchy

        GObject
        ╰── MessagingMenuApp

## Includes

    #include <messaging-menu.h>

## 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 application 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 shortcut actions found in the desktop file. Actions whose

`NotShowIn` keyword contains "Messaging Menu" or whose `OnlyShowIn` keyword does not contain "Messaging Menu"

will not appear (the desktop file specification contains a detailed explanation of shortcut actions.) 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.

## Functions

### 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()`.

#### Parameters

app | a MessagingMenuApp |

### 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.

#### Parameters

app | a MessagingMenuApp |

### 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.

#### Parameters

app | a MessagingMenuApp |
status | a MessagingMenuStatus |

### 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.

#### Parameters

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_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.

#### Parameters

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_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.

#### Parameters

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_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.

#### Parameters

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_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` . Use `messaging_menu_app_insert_source()` to insert a source with the current 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.

#### Parameters

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, in microseconds |

### 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` . Use `messaging_menu_app_append_source()` to append a source with the current 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.

#### Parameters

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, in microseconds |

### 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.

#### Parameters

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_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.

#### Parameters

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_remove_source ()

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

Removes the source corresponding to `source_id` from the menu.

#### Parameters

app | a MessagingMenuApp |
source_id | the id of the source to remove |

### messaging_menu_app_has_source ()

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

#### Parameters

app | a MessagingMenuApp |
source_id | a source id |

#### Returns

TRUE if there is a source associated with `source_id`

### messaging_menu_app_set_source_label ()

    void
    messaging_menu_app_set_source_label (MessagingMenuApp *app,
                                         const gchar *source_id,
                                         const gchar *label);

Changes the label of `source_id` to `label` .

#### Parameters

app | a MessagingMenuApp |
source_id | a source id |
label | the new label for the source |

### messaging_menu_app_set_source_icon ()

    void
    messaging_menu_app_set_source_icon (MessagingMenuApp *app,
                                        const gchar *source_id,
                                        GIcon *icon);

Changes the icon of `source_id` to `icon` .

#### Parameters

app | a MessagingMenuApp |
source_id | a source id |
icon | the new icon for the source. | [allow-none]

### 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` .

#### Parameters

app | a MessagingMenuApp |
source_id | a source id |
count | the new count 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` .

#### Parameters

app | a MessagingMenuApp |
source_id | a source id |
time | the new time for the source, in microseconds |

### 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` .

#### Parameters

app | a MessagingMenuApp |
source_id | a source id |
str | the new string for the source |

### 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.

#### Parameters

app | a MessagingMenuApp |
source_id | a source id |

### 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.

#### Parameters

app | a MessagingMenuApp |
source_id | a source id |

### messaging_menu_app_append_message ()

    void
    messaging_menu_app_append_message (MessagingMenuApp *app,
                                       MessagingMenuMessage *msg,
                                       const gchar *source_id,
                                       gboolean notify);

Appends `msg` to the source with id `source_id` of `app` . The messaging menu might not display this message immediately if other messages are queued before this one.

If `source_id` has a count associated with it, that count will be increased by one.

If `source_id` is `NULL`, `msg` won't be associated with a source.

#### Parameters

app | a MessagingMenuApp |
msg | the MessagingMenuMessage to append |
source_id | the source id to which `msg` is added, or NULL. | [allow-none]
notify | whether a notification bubble should be shown for this message |

### messaging_menu_app_get_message ()

    MessagingMenuMessage *
    messaging_menu_app_get_message (MessagingMenuApp *app,
                                    const gchar *id);

Retrieves the message with `id` , that was added with `messaging_menu_app_append_message()`.

#### Parameters

app | a MessagingMenuApp |
id | id of the message to retrieve |

#### Returns

the MessagingMenuApp with `id` , or `NULL`.

[transfer none][allow-none]

### messaging_menu_app_remove_message ()

    void
    messaging_menu_app_remove_message (MessagingMenuApp *app,
                                       MessagingMenuMessage *msg);

Removes `msg` from `app` .

If `source_id` has a count associated with it, that count will be decreased by one.

#### Parameters

app | a MessagingMenuApp |
msg | the MessagingMenuMessage to remove |

### messaging_menu_app_remove_message_by_id ()

    void
    messaging_menu_app_remove_message_by_id
                                   (MessagingMenuApp *app,
                                    const gchar *id);

Removes the message with the id `id` from `app` .

If `source_id` has a count associated with it, that count will be decreased by one.

#### Parameters

app | a MessagingMenuApp |
id | the unique id of `msg` |

## Types and Values

### enum MessagingMenuStatus

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

#### Members

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 |

### MessagingMenuAppClass

    typedef GObjectClass             MessagingMenuAppClass;

### MessagingMenuApp

    typedef struct _MessagingMenuApp MessagingMenuApp;

MessagingMenuApp is an opaque structure.

## Property Details

### The `“desktop-id”` property

      “desktop-id”               char *

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

Owner: MessagingMenuApp

Flags: Write / Construct Only

Default value: NULL

## Signal Details

### The `“activate-source”` signal

    void
    user_function (MessagingMenuApp *mmapp,
                   char             *source_id,
                   gpointer          user_data)

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()`.

#### Parameters

mmapp | the MessagingMenuApp |
source_id | the source id that was activated |
user_data | user data set when the signal handler was connected. |

Flags: Has Details

### The `“status-changed”` signal

    void
    user_function (MessagingMenuApp *mmapp,
                   int               status,
                   gpointer          user_data)

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.

#### Parameters

mmapp | the MessagingMenuApp |
status | a MessagingMenuStatus |
user_data | user data set when the signal handler was connected. |

Flags: Run First