About the Message Menu

The messaging menu aims to make communication easier with other people. It does this first by letting you set IM status quickly and across messaging applications; and secondly by providing quick access to messages, concerning you, that you may not have seen. The exact definition of “concerning you” is application-dependent. For example, e-mail programs often let you distinguish between messages that are important enough to notify you about, and messages that are not. Similarly, IRC clients typically let you specify terms that you should be notified about.

Register your Application

Automatically

A messaging application is automatically registered with the messaging menu if /usr/share/indicators/messages/applications/ or $HOME/.config/indicators/messages/applications/ contains a text file that contains the pathname of the application’s .desktop file, that .desktop file exists, and the program the .desktop file refers to also exists.

In the .desktop file itself, an application may specify shortcut actions that can be invoked regardless of whether the program is running. The syntax of these actions is defined in ApplicationShortcuts.

While Running

For an application to appear in the menu while running it should use libindicate and set the type of the application to messaging.

# get the indicate module, which does all the work
import indicate

# Create a server item
mm = indicate.indicate_server_ref_default()

# If someone clicks your server item in the MM, fire the server-display signal
mm.connect("server-display", show_window_function)

# Set the type of messages that your item uses. It's not at all clear which types
# you're allowed to use, here.
mm.set_type("message.im")

# You must specify a .desktop file: this is where the MM gets the name of your
# app from.
mm.set_desktop_file("/usr/share/applications/myapp.desktop")

# Show the item in the MM.
mm.show()

Adding message count

While running, a registered application can also provide either a single count of new messages, or a set of separate message sources (for example, mail folders or syndicated feeds) with their own counts or times. For example, a Laconica client may provide only the single count, because it presents its updates in a single list and not as separately navigable items. A Usenet newsreader, on the other hand, may provide an item for each newsgroup that has new messages.

When an application provides separate message sources, each source item should have up to six components.

name: The name of the source. For example, a person’s name, a feed title, or a discussion group name. If a single application has multiple sources with the same name, it should disambiguate them if practical.

icon: A vector or bitmap image representing the message source. Ideally, it should be exactly the same icon as the program uses for the same source in the rest of its interface. We request that the icon be provided only where it represents the person who sent the message, for example, the avatar of a person sending an instant message, with other types of client omitting the icon. Applications should specifically not provide "generic" icons, like "mail" or "IM" or "FedEX".

count: The number of new messages concerning you from this source. (Currently count is mutually exclusive with time, though this may change in future.)

time: A timestamp for the most recent instant message from that source, in ISO 8601 format. The messaging menu takes care of presenting this time in an easy-to-read and locale-sensitive format. A string not in ISO 8601 format (e.g. “connected”) will be accepted, but not rendered as a time. (Currently time is mutually exclusive with count, though this may change in future.)

draw-attention: A request that the messaging menu communicate to the user that something important has arrived in the menu. Currently this is displayed as a green dot in the menu title.

signal: A signal that the messaging menu should return to the application when the menu item is selected. When it receives this signal, the application should immediately display the message source represented by the item, and ideally also the first relevant message in that source.

# Create a source item
mm_source = indicate.Indicator()

# Again, it's not clear which subtypes you are allowed to use here.
mm_source.set_property("subtype", "im")

# "Sender" is the text that appears in the source item in the MM
mm_source.set_property("sender", "Unread")

# If someone clicks this source item in the MM, fire the user-display signal
mm_source.connect("user-display", show_window_function)

# Light up the messaging menu so that people know something has changed
mm_source.set_property("draw-attention", "true")

# Set the count of messages in this source.
mm_source.set_property("count", "15")

# If you prefer, you can set the time of the last message from this source,
# rather than the count. (You can't set both.) This means that instead of a
# message count, the MM will show "2m" or similar for the time since this
# message arrived.
# mm_source.set_property_time("time", time.time())
mm_source.show()