aboutsummaryrefslogtreecommitdiff
path: root/libmessaging-menu
diff options
context:
space:
mode:
Diffstat (limited to 'libmessaging-menu')
-rw-r--r--libmessaging-menu/messaging-menu.c132
-rw-r--r--libmessaging-menu/messaging-menu.h5
2 files changed, 125 insertions, 12 deletions
diff --git a/libmessaging-menu/messaging-menu.c b/libmessaging-menu/messaging-menu.c
index b090352..5bce20b 100644
--- a/libmessaging-menu/messaging-menu.c
+++ b/libmessaging-menu/messaging-menu.c
@@ -27,6 +27,71 @@
* SECTION:messagingmenuapp
* @title: MessagingMenuApp
* @short_description: An application section in the messaging menu
+ *
+ * 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
+ *
+ * [1] http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-1.1.html#extra-actions
+ */
+
+/**
+ * MessagingMenuApp:
+ *
+ * #MessagingMenuApp is an opaque structure.
*/
struct _MessagingMenuApp
{
@@ -157,6 +222,12 @@ messaging_menu_app_class_init (MessagingMenuAppClass *class)
object_class->finalize = messaging_menu_app_finalize;
object_class->dispose = messaging_menu_app_dispose;
+ /**
+ * MessagingMenuApp:desktop-id:
+ *
+ * The desktop id of the application associated with this application
+ * section. Must be given when the #MessagingMenuApp is created.
+ */
properties[PROP_DESKTOP_ID] = g_param_spec_string ("desktop-id",
"Desktop Id",
"The desktop id of the associated application",
@@ -167,6 +238,16 @@ messaging_menu_app_class_init (MessagingMenuAppClass *class)
g_object_class_install_properties (object_class, N_PROPERTIES, properties);
+ /**
+ * MessagingMenuApp::activate-source:
+ * @mmapp: the #MessagingMenuApp
+ * @source_id: the source id that was activated
+ *
+ * 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
+ * mesaging_menu_app_remove().
+ */
signals[ACTIVATE_SOURCE] = g_signal_new ("activate-source",
MESSAGING_MENU_TYPE_APP,
G_SIGNAL_RUN_FIRST |
@@ -176,6 +257,18 @@ messaging_menu_app_class_init (MessagingMenuAppClass *class)
g_cclosure_marshal_VOID__STRING,
G_TYPE_NONE, 1, G_TYPE_STRING);
+ /**
+ * MessagingMenuApp::status-changed:
+ * @mmapp: the #MessagingMenuApp
+ * @status: a #MessagingMenuStatus
+ *
+ * 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.
+ */
signals[STATUS_CHANGED] = g_signal_new ("status-changed",
MESSAGING_MENU_TYPE_APP,
G_SIGNAL_RUN_FIRST,
@@ -321,11 +414,8 @@ messaging_menu_app_init (MessagingMenuApp *app)
* Creates a new #MessagingMenuApp for the application associated with
* @desktop_id.
*
- * If the application is already registered with the messaging menu, it will be
- * marked as "running". Otherwise, call messaging_menu_app_register().
- *
- * The messaging menu will return to marking the application as not running as
- * soon as the returned #MessagingMenuApp is destroyed.
+ * The application will not show up (nor be marked as "running") in the
+ * Messaging Menu before messaging_menu_app_register() has been called.
*
* Returns: (transfer full): a new #MessagingMenuApp
*/
@@ -341,13 +431,16 @@ messaging_menu_app_new (const gchar *desktop_id)
* messaging_menu_app_register:
* @app: a #MessagingMenuApp
*
- * Registers @app with the messaging menu.
+ * Registers @app with the Messaging Menu.
*
- * The messaging menu will add a section with an app launcher and the shortcuts
- * defined in its desktop file.
+ * 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 "running" as long as @app is alive or
- * messaging_menu_app_unregister() is called.
+ * 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().
*/
void
messaging_menu_app_register (MessagingMenuApp *app)
@@ -371,8 +464,9 @@ messaging_menu_app_register (MessagingMenuApp *app)
* messaging_menu_app_unregister:
* @app: a #MessagingMenuApp
*
- * Completely removes the application associated with @desktop_id from the
- * messaging menu.
+ * 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.
*/
@@ -397,6 +491,16 @@ messaging_menu_app_unregister (MessagingMenuApp *app)
* messaging_menu_app_set_status:
* @app: a #MessagingMenuApp
* @status: a #MessagingMenuStatus
+ *
+ * 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.
*/
void
messaging_menu_app_set_status (MessagingMenuApp *app,
@@ -876,6 +980,10 @@ messaging_menu_app_draw_attention (MessagingMenuApp *app,
*
* 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.
*/
diff --git a/libmessaging-menu/messaging-menu.h b/libmessaging-menu/messaging-menu.h
index e767099..4668319 100644
--- a/libmessaging-menu/messaging-menu.h
+++ b/libmessaging-menu/messaging-menu.h
@@ -29,6 +29,11 @@ G_BEGIN_DECLS
#define MESSAGING_MENU_APP_CLASS(c) (G_TYPE_CHECK_CLASS_CAST ((c), MESSAGING_MENU_TYPE_APP, MessagingMenuAppClass))
#define MESSAGING_MENU_IS_APP(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), MESSAGING_MENU_TYPE_APP))
+/**
+ * MessagingMenuStatus:
+ *
+ * An enumeration for the possible chat statuses the messaging menu can be in.
+ */
typedef enum {
MESSAGING_MENU_STATUS_AVAILABLE,
MESSAGING_MENU_STATUS_AWAY,