''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 [[[https://launchpad.net/indicator-messages|hosted|on Launchpad]]], and [[[https://bugs.launchpad.net/ubuntu/+source/indicator-messages|bugs|are reported there too]]]. <> == 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 === * Tillie uses a Telstra Big``Pond e-mail account in Thunderbird. She is subscribed to the [[[http://lists.rootsweb.ancestry.com/index/other/Ethnic-Scots/AUS-SCOTTISH.html|AUS-Scottish]]] mailing list, which receives about five messages per month. Any other messages are usually from her nieces and nephews and their children, so receiving one is the highlight of Tillie’s day. When a message arrives she hears the “ding-dong!” from the computer, and stops whatever she’s doing to read it. Her nephew has taught her to look for the “Inbox” item under the envelope menu at the top of the screen. * Claude uses Gmail through Prism (with the `prism-google-mail` package), with cGmail to notify him of new messages. He receives about 80 messages a day, most of which are from mailing lists and get tagged automatically. The new message count appears in the messaging menu, along with status updates from his friends on Identica. He goes through e-mail daily at 9.15 a.m., except for messages from his girlfriend, which he reads as soon as they arrive. === Migration === In any version of Ubuntu that installs this version of the messaging menu: * the Me menu (`indicator-me`) should not be installed by default * the installer slide show should not mention the Me menu * the only help page mentioning the Me menu should explain that it is no longer present; you can now use Gwibber or similar to post to Twitter etc, the messaging menu to change your IM status, and System Settings to change your password and account details. === 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: * `$HOME/.config/indicators/messages/applications-blacklist/` does not contain a text file that contains the pathname of the application’s `.desktop` file; * `$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. 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?'' ## The link to the desktop file at the system level should exist as a file containing only the path to the file in ''/etc/indicators/messages/applications/''. The name of the file should be unique, but will not be displayed to the user in any form. Usually the name of package in the distribution's package manager will suffice, as it is unique and descriptive for people wanting to hand edit their computer's setup. If, on a per user basis, a user would like to remove or add an application they can do so by adding a file with the same name in ''~/.config/indicators/messages/applications-blacklist'' or ''~/.config/indicators/messages/applications''. ==== 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 [[[http://standards.freedesktop.org/desktop-entry-spec/latest/ar01s08.html|Desktop|Entry Specification]]]. ==== 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 [[[https://launchpad.net/libindicate|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 === ==== Menu presence ==== 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: * in Ubuntu for Android, a section for the “Phone” application, if it is registered; * in Ubuntu for Android, a section for the “SMS” application, if it is registered; * a section for Ubuntu’s default chat client, if it is registered; * a section for Ubuntu’s default mail client, if it is registered; * a section for any other registered application, sorted alphabetically by the application `Name`. {{{{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 [[TimeAndDate#settings|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 [[[#API|the|API section]]] for how applications should let you specify whether they are present in the menu at all. <> ==== Recommended behavior for e-mail clients ==== 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. <> ==== Recommended behavior for chat or telephony clients ==== 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 [[NotificationDesignGuidelines#Morphing_window|morphing window]] instead. <> ==== Recommended behavior for social networking clients ==== 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 [[SyncMenu|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 === * We need to survey messaging applications for (a) what custom items they'd want when not running ([[[http://standards.freedesktop.org/desktop-entry-spec/latest/ar01s08.html|Desktop|Entry Specification]]]), and (b) what custom items they’d want when running. That way we can work out whether it is necessary to provide a separate API for custom items while running. * [from Brian Curtis] How to run programs in the background so they're accessible only from the messaging menu? * How to configure appearance, length of display, etc ?? * Should the menu try to enforce limitations on how `draw-attention` is used? * Should the number of subitems be limited to prevent abuse? How many? And how should the excess case be displayed? == Phone == On the phone, the header for the menu should be “Incoming”.