Ayatana Indicators Wiki

Designed by MatthewPaulThomas

{attachment:messaging-menu.png}

The messaging menu provides quick access to global messaging status and individual messaging applications. On the PC, its title should show current messaging and chat status. Inside, there should be a section for global chat status, and/or sections for individual applications, and finally an item for clearing the menu. This specification covers the menu itself, as well as suggestions for applications on integrating with it.

Anyone is welcome to fix bugs and make other improvements. The messaging menu is hosted], and bugs].

Contents

  1. Rationale
  2. PC
    1. User stories
    2. Migration
    3. API
      1. Registration
      2. Shortcut actions
      3. Counts and sources
    4. Presentation
      1. Menu presence
      2. Title
      3. Chat status section
      4. Application sections
      5. Sources
      6. “Clear” item
    5. How applications should integrate with the messaging menu
      1. Recommended behavior for e-mail clients
      2. Recommended behavior for chat or telephony clients
      3. Recommended behavior for social networking clients
      4. Ubuntu One
    6. Session variations
    7. Unresolved issues
  3. Phone

Rationale

The messaging menu exists to simplify communication for people using Ubuntu. It does this first by letting you set chat status quickly and across chat 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.

PC

User stories

Migration

In any version of Ubuntu that installs this version of the messaging menu:

API

An application may be registered to show in the messaging menu. If so, it may be registered to use the global chat status items too.

Registration

An application is registered to show in the menu if both of these are true:

You should be able to manually show or hide a messaging application in the menu using a checkbox in the application’s settings. If you check the checkbox, the application should remove the blacklist file, if it is present, and update the datestamp of the $HOME/.config/indicators/messages/applications/application file. Should this have a convenience API?

An application should automatically register itself only if, and as long as, you have an account or analogous configuration set up in that application (for example, an e-mail account or a feed subscription), and you have not already indicated that you don’t want the application in the menu (for example, by turning it off after setting up a previous account). This avoids the problem where you cannot remove an application installed by another user from your own messaging menu without having to learn its configuration interface (when in the worst case, the application might not even be available in a language you can read).

An application is registered to use the global chat status if… what?

How should an application set the global chat status?

Shortcut actions

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 Desktop].

Counts and sources

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.

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

  2. 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".

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

  4. 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.)

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

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

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

All indicators will get a signal when they are represented visually. That signal will not occur for indicators that are either over the limitations of the applet or if the applet is not functioning in some way.

Presentation

The messaging menu should be present whenever you are logged in (that is, not in the standalone installer session or at the login screen) and any applications are registered.

Test case: Log in to a guest session; the messaging menu should not be present. In Thunderbird, set up an e-mail account; the menu should immediately appear, containing Thunderbird but no chat status items or other applications. Launch Empathy, but close it before setting up an account; the menu should not contain Empathy or chat status items. Relaunch Empathy, and set up an account; the chat status items and Empathy should both be present. Uninstall Empathy; neither the chat status items nor Empathy should be present. Reinstall Empathy; the chat status items and Empathy should reappear in the menu.

{attachment:title-icons.png}

Title

By default, the title of the menu should be a monochrome open envelope icon (indicator-messages), with the accessible name “Messages”.

If any registered application has set draw-attention, that application has not had any of its windows focused since, and you have not subsequently chosen “Clear”, the menu title should instead be a closed and highlighted envelope icon (indicator-messages-new), with the accessible name “New Messages”.

When any applications are registered as using the global chat status, and the global equivalent of the status in all those applications is currently the same — for example, if one application is set to “Away” while another is “Away (on the phone)”, both mapping to “Away” — then the envelope icon, whether in its default or new-messages variant, should be overlaid with a miniature of the color icon for the current status. That status should also be appended in brackets to the accessible label, e.g. “New Messages (Busy)”.

When multiple applications are registered as using the global chat status, and they have different global equivalent statuses — for example, if one application is set to “Available” while another is “Away” — the envelope should be overlaid with a miniature “-” icon evoking the indeterminate radio marks inside the menu itself, and “(various statuses)” should be appended to the accessible label.

Chat status section

{attachment:im-section.png}

The chat status section should appear only when any applications are registered to use it. The section should consist of one radio item each for “Available”, “Away”, “Busy”, “Hidden”, and “Offline”. Each item should use the standard (color) icon for that status.

As usual with radio items, if registered applications are using different statuses, the items representing each of the statuses being used should be in the - indeterminate state instead of the single • state.

Application sections

The menu should have these sections, with separators between them:

{attachment:application-section.png}
Erratum: minutes should be abbreviated as “min”, not “m”.

Within each section, first should be an application item representing the application as a whole, using the application’s own icon and Name.

{attachment:application-running.png}

If the application is currently running, this should be indicated by an inward-pointing triangle at the leading edge of the application item, and an accessible name consisting of the application name plus “ (running)”, e.g. “Evolution (running)”. If the application has not provided message source items, its count should be shown as part of the application item, and appended in brackets to its accessible name, e.g. “Evolution (running) (46)”. And if the application has set draw-attention, the triangle, application name, and any count should all be the same color as the envelope (bug Bug:906043).

Activating the application item should (re-)launch the application; the application can then decide whether it is most appropriate to open a new window, focus an existing window, or do something else. (For example, if the only Evolution window currently open is a Calendar window, choosing “Evolution” from the messaging menu should open and focus an Evolution Mail window.)

All other items (“non-launcher items”) in an application section should be indented such that the leading edge of all non-launcher items in the menu are both lined up with each other, and lined up with the leading edge of the text of every launcher item in the menu.

Next should be presented the shortcut items for the application, if any, in whatever order the application specifies, up to a limit of the six first items. Activating any of these menu items should (re-)launch the application with the appropriate options; the application can then decide whether it is most appropriate to open a new window, focus an existing window, or do something else.

If the application has provided message source sub-items, any count for the application as a whole should be ignored. Up to six of the sub-items should be presented in the menu, in whatever order the application specifies, below the application item and any shortcut items. They should use name as their text, and icon (if any) as their icon. The count or time for each item should be presented as part of the menu item. If it has neither count nor time, the time at which the item was registered should be presented as its time. The item’s accessible name should consist of its name, and its count or unabbreviated time in brackets, separated by a space: for example, “Henrietta (17 minutes ago)”.

Selecting an item from the menu should send the associated signal, and also remove the item from the menu.

All application items should be limited to a single line of text (with non-space whitespace rendered as a space). Neither the menu nor any of its items should have a tooltip.

Sources

{attachment:count.png}

If a source has a non-zero count, this should be presented as a lozenge at the trailing end of the menu item, with its trailing edge horizontally aligned with the trailing edge of the menu contents area.

{attachment:time.png}
Erratum: minutes should be abbreviated as “min”, not “m”.

Otherwise, if the source has a time, that should be displayed in small print, with its baseline aligned with the baseline of the main menu text, and with its trailing edge horizontally aligned with the trailing edge of the menu contents area.

A time less than an hour ago should be presented as relative minutes — for example, “4 min” or “58 min” (bug Bug:652845). As part of an accessible name, it should be presented as whole words — for example, “4 minutes ago” or “58 minutes ago”.

A time greater than or equal to an hour ago, but from today, should be presented as absolute hours and minutes, in either 12-hour or 24-hour format the same as chosen in the clock settings, but without date or seconds.

A time both great than or equal to an hour ago, and from before today, but from less than six days before the most recent midnight, should be presented the same way, but preceded by the day in abbreviated form — for example, “Thu 4:11 AM” or “Sat 20:07”. As part of an accessible name, the day should be presented as a whole word — for example, “Thursday 4:11 AM” or “Saturday 20:07”.

A time from more than six days before the most recent midnight should be preceded by the date instead of the day. For example, “Aug 8 4:11 AM” or “Oct 11 20:07”. In an accessible name, month names should be unabbreviated.

A time that is not a timestamp, e.g. “connected”, should be presented verbatim.

If a source has neither a non-zero count nor a time, it should not be shown at all.

“Clear” item

The “Clear” item should be sensitive whenever there is at least one application with a draw_attention request. Activating the item should restore the menu title to the no-new-messages state, but should keep any message sources, counts, and times in the menu.

How applications should integrate with the messaging menu

See the] for how applications should let you specify whether they are present in the menu at all.

A mail client should register itself automatically when you set up any mail account (unless you previously turned it off), and unregister itself when you remove the last account. It should also provide settings of the form “Show {type of message} in the messaging menu” or “Show {Name of Program} in the messaging menu”.

For the purpose of the messaging menu, a new message is an unread message that the program discovered since the last time you (a) performed any action in that mailbox or (b) selected the corresponding item in the messaging menu. Whether a new message concerns you may be configurable within the program, perhaps by sender, by folder, or by mail filters.

A mail program should provide one message source item for each mailbox that contains new messages concerning you. (It should do this for all mailboxes even though a maximum of six will be shown, because that maximum may change in the future.)

name should be set to to the name of the mailbox. If (and only if) there is more than one mailbox with the same name, the mail program should disambiguate them using the account name if possible, e.g. “Inbox (Home)” vs. “Inbox (Yoyodyne)”.

signal should be set such that selecting an item from the menu focuses the most relevant window to display that mailbox (for example a window that is already displaying that mailbox, if one is open), and switches to the mailbox if necessary.

A chat client should register itself automatically when you set up any accounts (unless you previously turned it off), and unregister itself when you remove its last account. It should also provide a “Show {Name of Program} in the messaging menu” checkbox in its settings.

For the purpose of the messaging menu, a new message is a message concerning you that was posted at a time when the tab or window in which it appeared was not focused. “Concerning you” for a private chat means every message, and for a public chat means every message that the program highlights (for example, because it mentions your name).

A chat client should provide one message source item for each person who, or group chat containing someone, who, has sent you new messages. (It should do this for all relevant people or chats even though a maximum of six will be shown, because that maximum may change in the future.)

Optionally, it may also provide a message source item for each person in your contact list who has not sent you new messages, but who has connected in the past minute and is still online. It should not do this unless it is also configured to display a notification bubble notifying you that the person has connected.

For a group conversation, name should be set to the name of the channel or chat room. If only one person has sent highlighted messages, this should be followed by the name of that person in brackets. Otherwise, it should be followed by the number of people who have sent highlighted messages in brackets.

For an individual conversation, name should be set to the name of the person if known, otherwise their instant messaging ID or IRC nickname.

time should be set to the time of the earliest unseen message from that group or individual, if there is one. For someone who has connected in the past minute but not sent you new messages, time should be set to “connected”.

signal should be set such that selecting an item from the menu brings the relevant window to the front, and switches to the relevant tab in that window if necessary.

Telephony clients should not use the messaging menu to show incoming calls. It is not nearly noticable enough or quick enough to be accessed in time. Use a morphing window instead.

Useful messaging menu behavior for a Twitter, Facebook, or similar client depends greatly on how many messages someone receives. For a typical user, most updates are not addressed directly to them, and it would not be useful for the menu to be highlighted most of the time. So it is inappropriate to draw-attention on every update by default.

For example, a Twitter client might have source items for “Updates”, “Replies”, and “Direct Messages”; settings checkboxes for which of those highlight the menu; and default to highlighting the menu on replies and direct messages only.

Ubuntu One

Ubuntu One should not be in the messaging menu: while it does occasionally present file share invitations, most of the time people spend seeing or using Ubuntu One is not related to communicating with people.

Instead, it should be in the sync menu if it exists, or its own application indicator menu otherwise.

Session variations

This is a summary only; the specifications of individual items are authoritative.

In the guest session and the live session, the indicator and menu should be present as normal.

In the standalone installer session and the login screen, the indicator should not be present at all.

Unresolved issues

Phone

On the phone, the header for the menu should be “Incoming”.

Ayatana Indicators Wiki: AyatanaIndicatorMessages (last edited 2021-02-09 14:03:03 by localhost)