This specification defines the management of visual items, usually icons used for reporting the status of an application to the user or provide a quick access to common actions performed by that application. It is intended to be complementary but not directly related with the Freedesktop's Desktop Notifications specification and is aimed as a replacement to the Freedesktop System tray specification. This specification does not define what the aspect of the Notification Items will be, this is strictly implementation specific. Example use cases will include: Mixer volume control. Battery indicator. Instant messenger on-line status. Generic application information and actions, like a media player controls. The Status Notifier Item system relies on inter-process communication via D-BUS and is composed by three parts: StatusNotifierItem: each application that wants to utilize the system registers its own StatusNotifierItem to the session bus. Properties, methods and signals that must be provided by all StatusNotifierItem instances are described in . StatusNotifierWatcher: service used to keep track of every active instance of StatusNotifierItem, used by StatusNotifierHost to get the list of all items. It also notifies it when items are added and removed. The detailed specification of StatusNotifierWatcher is described in . StatusNotifierHost: an application that wants to provide a visualization of the existing StatusNotifierItem instances must register a StatusNotifierHost in the session bus. The detailed specification of StatusNotifierHost is described in . Each application can register an arbitrary number of Status Notifier Items by registering on the session bus the service org.freedesktop.StatusNotifierItem-PID-ID, where PID is the process id of the application and ID is an arbitrary numeric unique identifier between different instances registered by the same application. As soon as a new instance of a StatusNotifierItem is created, the application must register the unique instance name to the StatusNotifierWatcher as described in Each instance of StatusNotifierItem must provide an object called StatusNotifierItem with the following properties, methods and signals described in the following sections. STRING org.freedesktop.StatusNotifierItem.Category Describes the category of this item. The allowed values for the Category property are: ApplicationStatus: The item describes the status of a generic application, for instance the current state of a media player. Communications: The item describes the status of communication oriented applications, like an instant messenger or an email client. SystemServices: The item describes services of the system not seen as a stand alone application by the user, such as an indicator for the activity of a disk indexing service. Hardware: The item describes the state and control of a particular hardware, such as an indicator of the battery charge or sound card volume control. STRING org.freedesktop.StatusNotifierItem.Id It's a name that should be unique for this application and consistent between sessions, such as the application name itself. STRING org.freedesktop.StatusNotifierItem.Title It's a name that describes the application, it can be more descriptive than Id. STRING org.freedesktop.StatusNotifierItem.Status Describes the status of this item or of the associated application. The allowed values for the Status property are: Passive: The item doesn't convey important information to the user, it can be considered an idle status and is likely that visualizations will chose to hide it. Active: The item is active, is more important that the item will be shown in some way to the user. NeedsAttention: The item carries really important information for the user, such as battery charge running out and is wants to incentive the direct user intervention. Visualizations should emphasize in some way the items with NeedsAttention status. UINT32 org.freedesktop.StatusNotifierItem.WindowId It's the windowing-system dependent identifier for a window, the application can chose one of its windows to be available trough this property or just set 0 if it's not interested. STRING org.freedesktop.StatusNotifierItem.IconName The StatusNotifierItem can carry an icon that can be used by the visualization to identify the item. An icon can either be identified by its Freedesktop-compliant icon name, carried by this property of by the icon data itself, carried by the property IconPixmap. Visualizations are encouraged to prefer icon names over icon pixmaps if both are available (FIXME: still not very defined: could e the pixmap used as fallback if an icon name is not found?) ARRAY(INT, INT, ARRAY BYTE) org.freedesktop.StatusNotifierItem.IconPixmap Carries an ARGB32 binary representation of the icon, the format of icon data used in this specification is described in Section STRING org.freedesktop.StatusNotifierItem.OverlayIconName The Freedesktop-compliant name of an icon. This can be used by the visualization to indicate extra state information, for instance as an overlay for the main icon. ARRAY(INT, INT, ARRAY BYTE) org.freedesktop.StatusNotifierItem.OverlayIconPixmap ARGB32 binary representation of the overlay icon described in the previous paragraph. STRING org.freedesktop.StatusNotifierItem.AttentionIconName The Freedesktop-compliant name of an icon. this can be used by the visualization to indicate that the item is in RequestingAttention state. ARRAY(INT, INT, ARRAY BYTE) org.freedesktop.StatusNotifierItem.AttentionIconPixmap ARGB32 binary representation of the requesting attention icon describe in the previous paragraph. STRING org.freedesktop.StatusNotifierItem.AttentionMovieName An item can also specify an animation associated to the RequestingAttention state. This should be either a Freedesktop-compliant icon name or a full path. The visualization can chose between the movie or AttentionIconPixmap (or using neither of those) at its discretion. (STRING, ARRAY(INT, INT, ARRAY BYTE), STRING, STRING) org.freedesktop.StatusNotifierItem.ToolTip Data structure that describes extra information associated to this item, that can be visualized for instance by a tooltip (or by any other mean the visualization consider appropriate. Components are: STRING: Freedesktop-compliant name for an icon. ARRAY(INT, INT, ARRAY BYTE): icon data STRING: title for this tooltip STRING: descriptive text for this tooltip. It can contain also a subset of the HTML markup language, for a list of allowed tags see Section . VOID org.freedesktop.StatusNotifierItem.ContextMenu INT x INT y Asks the status notifier item to show a context menu, this is typically a consequence of user input, such as mouse right click over the graphical representation of the item. the x and y parameters are in screen coordinates and is to be considered an hint to the item about where to show the context menu. VOID org.freedesktop.StatusNotifierItem.Activate INT x INT y Asks the status notifier item for activation, this is typically a consequence of user input, such as mouse left click over the graphical representation of the item. The application will perform any task is considered appropriate as an activation request. the x and y parameters are in screen coordinates and is to be considered an hint to the item where to show eventual windows (if any). VOID org.freedesktop.StatusNotifierItem.SecondaryActivate INT x INT y Is to be considered a secondary and less important form of activation compared to Activate. This is typically a consequence of user input, such as mouse middle click over the graphical representation of the item. The application will perform any task is considered appropriate as an activation request. the x and y parameters are in screen coordinates and is to be considered an hint to the item where to show eventual windows (if any). VOID org.freedesktop.StatusNotifierItem.Scroll INT delta STRING orientation The user asked for a scroll action. This is caused from input such as mouse wheel over the graphical representation of the item. The delta parameter represent the amount of scroll, the orientation parameter represent the horizontal or vertical orientation of the scroll request and its legal values are horizontal and vertical. VOID org.freedesktop.StatusNotifierItem.NewTitle The item has a new title: the graphical representation should read it again immediately. VOID org.freedesktop.StatusNotifierItem.NewIcon The item has a new icon: the graphical representation should read it again immediately. VOID org.freedesktop.StatusNotifierItem.NewAttentionIcon The item has a new attention icon: the graphical representation should read it again immediately. VOID org.freedesktop.StatusNotifierItem.NewOverlayIcon The item has a new overlay icon: the graphical representation should read it again immediately. VOID org.freedesktop.StatusNotifierItem.NewToolTip The item has a new tooltip: the graphical representation should read it again immediately. VOID org.freedesktop.StatusNotifierItem.NewStatus STRING status The item has a new status, that is passed as an argument of the signal. There will be a single org.freedesktop.StatusNotifierWatcher service instance registered on the session but at any given time. The StatusNotifierWatcher service is used to keep track of StatusNotifierItem instances, enumerate them and notify when new ones are registered or old ones are unregistered. It is also used to keep track of org.freedesktop.StatusNotifierHost instances, to have an easy way to know if there is at least one service registered as the visualization host for the status notifier items. VOID org.freedesktop.StatusNotifierWatcher.RegisterStatusNotifierItem STRING service Register a StatusNotifierItem into the StatusNotifierWatcher, in the form of its full name on the session bus, for instance org.freedesktop.StatusNotifierItem-4077-1. A StatusNotifierItem instance must be registered to the watcher in order to be noticed from both the watcher and the StatusNotifierHost instances. If the registered StatusNotifierItem goes away from the session bus, the StatusNotifierWatcher should automatically notice it and remove it from the list of registered services. VOID org.freedesktop.StatusNotifierWatcher.RegisterStatusNotifierHost STRING service Register a StatusNotifierHost into the StatusNotifierWatcher, in the form of its full name on the session bus, for instance org.freedesktop.StatusNotifierHost-4005. Every NotficationHost instance that intends to display StatusNotifierItem representations should register to StatusNotifierWatcher with this method. The StatusNotifierWatcher should automatically notice if an instance of StatusNotifierHost goes away. ARRAY(STRING) org.freedesktop.StatusNotifierWatcher.RegisteredStatusNotifierItems List containing all the registered instances of StatusNotifierItem. All elements of the array should correspond to services actually running on the session bus at the moment of the method call. BOOL org.freedesktop.StatusNotifierWatcher.IsStatusNotifierHostRegistered True if at least one StatusNotifierHost has been registered with and is currently running. If no StatusNotifierHost are registered and running, all StatusNotifierItem instances should fall back using the Freedesktop System tray specification. INT org.freedesktop.StatusNotifierWatcher.ProtocolVersion The version of the protocol the StatusNotifierWatcher instance implements. BOOL org.freedesktop.StatusNotifierWatcher.StatusNotifierItemRegistered STRING service A new StatusNotifierItem has been registered, the argument of the signal is the session bus name of the instance. StatusNotifierHost implementation should listen this signal to know when they should update their representation of the items. BOOL org.freedesktop.StatusNotifierWatcher.StatusNotifierItemUnregistered STRING service A StatusNotifierItem instance has disappeared from the bus, the argument of the signal is the session bus name of the instance. StatusNotifierHost implementation should listen this signal to know when they should update their representation of the items. BOOL org.freedesktop.StatusNotifierWatcher.StatusNotifierHostRegistered A new StatusNotifierHost has been registered, the StatusNotifierItem instances knows that they can use this protocol instead of the Freedesktop System tray protocol. StatusNotifierHost corresponds an object in an application that does the actual graphical representation of StatusNotifierItem instances. Instances of this service are registered on the Dbus session bus, under a name on the form org.freedesktop.StatusNotifierHost-id where id is an unique identifier, that keeps the names unique on the bus, such as the process-id of the application or another type of identifier if more that one StatusNotifierHost is registered by the same process. StatusNotifierHost instances don't need any particular property, method or signal registered to the bus. What is important is the presence of the service on the bus, to inform StatusNotifierWatcher that a StatusNotifierItem representation is currently running on the system. Implementers of StatusNotifierItem should support the Freedesktop Systemtray specification too, and should use that instead of the Status notifier protocol in one of the following scenarios: The service org.freedesktop.StatusNotifierWatcher is not registered on the session bus The service org.freedesktop.StatusNotifierWatcher is registered on the session bus, but the method org.freedesktop.StatusNotifierWatcher.IsStatusNotifierHostRegistered returns FALSE. As soon as org.freedesktop.StatusNotifierWatcher appears on the session bus and org.freedesktop.StatusNotifierWatcher.IsStatusNotifierHostRegistered returns true the Freedesktop Systemtray item should be deleted and the StatusNotifierItem should be registered instead. In the same way a StatusNotifierItem should be registered when arrives the signal org.freedesktop.StatusNotifierWatcher.StatusNotifierHostRegistered and no StatusNotifierHost were registered before. The sub text of a tooltip may contain markup. The markup is XML-based, and consists of a small subset of XHTML. The following tags should be supported by the StatusNotifierHost visualization. Though it is optional, it is recommended. StatusNotifierHost that do not support these tags should filter them out. b ... b Bold i ... i Italic u ... u Underline a href="..." ... a Hyperlink img src="..." alt="..." Image Images can be used with absolute pathnames as image source. The alt tab is mandatory. A full-blown HTML implementation is not required of this spec, and notifications should never take advantage of tags that are not listed above. As tooltips are not a substitute for complex dialogs, advanced layout is not necessary, and may in fact limit the number of systems where this system can run on, due to memory usage and screen space. Such examples are PDAs, certain cell phones, and slow PCs or laptops with little memory. For the same reason, a full XML or XHTML implementation using XSLT or CSS stylesheets is not part of this specification. Information that must be presented in a more complex form should use an application-specific dialog, a web browser, or some other display mechanism. The tags specified above mark up the content in a way that allows them to be stripped out on some implementations without impacting the actual content. All the icons can be transferred over the bus by a particular serialization of their data, capabe of representing multiple resolutions of the same image or a brief aimation of images of the same size. Icons are transferred in an array of raw image data structures of signature a(iiay) whith each one describing the width, height, and image data respectively. The data is represented in ARGB32 format and is in the network byte order, to make easy the communication over the network between little and big endian machines. Here we show in pseudocode a tipical usage scenario of the three components. In this examples a service is registered to DBus by registering a class with the registerToDBus() function call. the function pid() returns the process-id of the application and uniqueId() returns each an unique id in the application (it can just be a progressive integer). Those are used to generate an unique name on the session bus. The function getDBusConnection() returns an object with all of the methods, properties and signals of a service registered on the bus. An application that wants to register a new StatusNotifierItem has to do the following steps (providing we have a class, here called StatusNotifierItem with methods to set its properties, any other programming paradigm can be used in implementations). The applicatin in this example is an hypothetical sound mixer application. StatusNotifierItem statusNotifierItem = new StatusNotifierItem(); String statusNotifierItemBusName = "org.freedesktop.StatusNotifierItem-" + pid() + "-" + uniqueId(); registerToDBus(statusNotifierItemBusName); //setting the properties the StatusNotifierItem statusNotifierItem.setId("Mixer"); //no signal emitted: Id is not supposed to change again statusNotifierItem.setTitle("Volume control"); //at this point statusNotifierItem emitted the NewTitle signal statusNotifierItem.setCategory(Hardware); //no signal emitted: Category is not supposed to change statusNotifierItem.setStatus(Active); //statusNotifierItem emitted NewStatus signal //here we use just icon names and not icon pixmaps statusNotifierItem.setIconName("mixer"); //NewIcon emitted statusNotifierItem.setTooltipIconName("mixer"); statusNotifierItem.setTooltipTitle("Sound mixer"); statusNotifierItem.setTooltipText("Control your soundcard volume"); //NewToolTip emitted: implementations are encouraged to emit this signal //just one time after all changes are done StatusNotifierWatcherConnection watcher = getDBusConnection("org.freedesktop.StatusNotifierWatcher"); watcher.RegisterService(statusNotifierItemBusName); At this point the item should be visualized in any StatusNotifierHost that displays items of Hardware type. Each time a new property will be setted, the StatusNotifierItem implementation must emit the proper signal. The StatusNotifierWatcher has to emit the StatusNotifierItemRegistered signal every time somebdy calls RegisterService on it and emit ServiceUnRegistered when that service disappear on the session bus. The RegisateredServices method must return a list composed of only names that are actually registered on the session bus. When RegisterStatusNotifierHost is register, the StatusNotifierHostRegistered signal must be emitted. Below there is the pseudocode for the RegisterService method, here the m_services sontains a list of all the registered StatusNotifierItem instances. void RegisterService(string serviceName) { //we try to connect to find out if the name is valid if (getDBusConnection(serviceName).isValid()) { m_services.append(serviceName); emit StatusNotifierItemRegistered(serviceName); } } When a StatusNotifierHost instance starts it must register itself on StatusNotifierWatcher and then fetch from it the list of registered StatusNotifierItems and listen for new one registered or old ones going away. It should also keep in sync all properties like icons, states and tooltips. String statusNotifierHostName = "org.freedesktop.StatusNotifierHost-" + pid() + "-" + uniqueId(); registerToDBus(statusNotifierHostName); StatusNotifierWatcherConnection watcher = getDBusConnection("org.freedesktop.StatusNotifierWatcher"); watcher.registerStatusNotifierHost(statusNotifierHostName); connect(watcher, SIGNAL(StatusNotifierItemRegistered()), this, SLOT(StatusNotifierItemRegistered())); connect(watcher, SIGNAL(StatusNotifierItemUnregistered()), this, SLOT(ServiceUnRegistered())); m_itemList = watcher.RegisteredStatusNotifierItems(); foreach (string service, m_itemList) { StatusNotifierItemConnection item = getDBusConnection(service); //we will have a slot called when the asyncronous GetAll() is done //it will create or update the actual visual representation of the item item.GetAll(); }