Hello everyone, In the past few months in KDE we worked on a new way to represent the systemtray icons to overcome the following limitations: -lack of communication between the systemtray area and the items, that mean we don't know about their status, their importance of if they are being used or not -the xembed process is quite slow and doesn't give control to the systray on the paining -it's not possible to have more than one systray (useful in multi monitor setups)
The new protocol is based upon D-Bus, and separates the presentation of the items from the logic, in our case the painting is completely controlled by Plasma and the applications registers via D-bus (with a small clien library shared across KDE) to a central server, while there can be zero or more instances of the systemtray. if either the serve or no instances of systemtrays that supports this protocol are registered the system will fall back using the old freedesktop.org systray specification. KDE has already a complete and working implementation of the protocol, usedby several core applications the draft specification is attached and on gitorious: http://gitorious.org/~notmart/xdg-specs/notmart-xdg-specs/commits/notificationitem questions and comments are more than welcome Cheers, Marco Martin
<?xml version="1.0"?> <!DOCTYPE article PUBLIC "-//OASIS/DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd";> <article id="index"> <articleinfo> <title>Notification Item Specification</title> </articleinfo> <sect1 id="introduction"> <title>Introduction</title> <para> This is a draft standard for the management of visual items used to report the status of an application to the user or provide quick access to common actions performed by that application. It is intended to be complementary but not directly related with the freedesktop.org Desktop Notifications specification and is aimed as a replacement to the freedesktop.org Systemtray specification. </para> <para> </para> <para> This specification does not define what the presentation of the Noticication Items to the user should be. It only defines the communication protocol used between the applications. </para> <para> Example use cases may include: </para> <itemizedlist> <listitem> <para>Volume and sound mixer control.</para> </listitem> <listitem> <para>Battery indicator.</para> </listitem> <listitem> <para>Instant messager online status.</para> </listitem> <listitem> <para>Generic application information and actions, such as media player controls.</para> </listitem> </itemizedlist> </sect1> <sect1 id="basic-design"> <title>Basic Design</title> <para> The Notification Item system relies on inter-process communication via D-BUS and is composed of three parts: </para> <itemizedlist> <listitem> <para> Notification Item: each application that wants to utilize the system registers its own Notification Item on the session bus. Properties, methods and signals that must be provided by all Notification Item instances are described in <xref linkend="Notification Item"/>. </para> </listitem> <listitem> <para> Notification Item Watcher: a D-Bus service used to keep track of every active instance of Notification Item, used by Notification Host to get the list of all items. It also notifies it when items are added and removed. Only one Notification Item Watcher is active in the user session at a time. The detailed specification of Notification ItemWatcher is described in <xref linkend="Notification ItemWatcher"/>. </para> </listitem> <listitem> <para> Notification Host: an application that provides a visualization of the existing Notification Item instances. A Notification Host must register itself on the session bus and there may be zero or more Notification Hosts active at once. The detailed specification of Notification Host is described in <xref linkend="Notification Host"/>. </para> </listitem> </itemizedlist> </sect1> <sect1 id="Notification Item"> <title>Notification Item</title> <para> Each application may register an arbitrary number of Notification Items by registering an object implementing the <literal>org.freedesktop.NotificationItem-PID-ID</literal> service on the session bus, where the PID is the process id of the application and ID is an arbitrary numeric unique identifier between different Notification Item instances registered by the same application. This ensures that a unique identifier exists for each instance of a Notification Item on the bus. </para> <para> As soon as a new instance of a Notification Item is created, the application must then register the unique identifier to the Notification Item Watcher as described in <xref linkend="NotificationItemWatcher"/> </para> <para> Each instance of Notification Item must provide an object called <literal>NotificationItem</literal> with the following properties, methods and signals: </para> <sect2 id="NotificationItemProperties"> <title>Properties</title> <sect3 id="category"> <title><literal>org.freedesktop.NotificationItem.Category</literal></title> <funcsynopsis> <funcprototype> <funcdef>STRING <function>org.freedesktop.NotificationItem.Category</function> </funcdef> <paramdef/> </funcprototype> </funcsynopsis> <para>Describes the category of this item.</para> <para>The allowed values for the Category property are:</para> <itemizedlist> <listitem> <para><literal>ApplicationStatus</literal>: The item describes the status of a generic application, for instance the current state of a media player.</para> </listitem> <listitem> <para><literal>Communications</literal>: The item describes the status of communication oriented applications, like an instant messager or an email client.</para> </listitem> <listitem> <para><literal>SystemServices</literal>: 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.</para> </listitem> <listitem> <para><literal>Hardware</literal>: The item describes the state and control of a particular hardware device, such as an indicator of the battery charge or sound card volume control.</para> </listitem> </itemizedlist> </sect3> <sect3 id="id"> <title><literal>org.freedesktop.NotificationItem.Id</literal></title> <funcsynopsis> <funcprototype> <funcdef>STRING <function>org.freedesktop.NotificationItem.Id</function> </funcdef> <paramdef/> </funcprototype> </funcsynopsis> <para>A name that should be unique for this application and consistent between sessions, such as the application name itself.</para> </sect3> <sect3 id="title"> <title><literal>org.freedesktop.NotificationItem.Title</literal></title> <funcsynopsis> <funcprototype> <funcdef>STRING <function>org.freedesktop.NotificationItem.Title</function> </funcdef> <paramdef/> </funcprototype> </funcsynopsis> <para>A name that describes the application, it can be more descriptive than Id.</para> </sect3> <sect3 id="status"> <title><literal>org.freedesktop.NotificationItem.Status</literal></title> <funcsynopsis> <funcprototype> <funcdef>STRING <function>org.freedesktop.NotificationItem.Status</function> </funcdef> <paramdef/> </funcprototype> </funcsynopsis> <para>Describes the status of this item or of the associated application.</para> <para>The allowed values for the Status property are:</para> <itemizedlist> <listitem> <para><literal>Passive</literal>: The item doesn't convey important information to the user, it can be considered an <quote>idle</quote> status and is likely that visualizations will chose to hide it.</para> </listitem> <listitem> <para><literal>Active</literal>: The item is active, is more important that the item will be shown in some way to the user.</para> </listitem> <listitem> <para><literal>NeedsAttention</literal>: The item carries really important information for the user, such as battery charge running out and is wants to incentivate the direct user intervention. Visualizations should emphasize in some way the items with NeedsAttention status.</para> </listitem> </itemizedlist> </sect3> <sect3 id="WindowId"> <title><literal>org.freedesktop.NotificationItem.WindowId</literal></title> <funcsynopsis> <funcprototype> <funcdef>UINT32 <function>org.freedesktop.NotificationItem.WindowId</function> </funcdef> <paramdef/> </funcprototype> </funcsynopsis> <para>The windowing system dependent identifier for a window (e.g. a WID), the application can chose one of its windows to be available through this property or set 0 if no window is associated with the Notification Item.</para> </sect3> <sect3 id="IconName"> <title><literal>org.freedesktop.NotificationItem.IconName</literal></title> <funcsynopsis> <funcprototype> <funcdef>STRING <function>org.freedesktop.NotificationItem.IconName</function> </funcdef> <paramdef/> </funcprototype> </funcsynopsis> <para>The Notification Item may include an icon that can be used by the Notification Host to identify the item visually to the user.</para> <para>An icon can either be identified by its freedesktop.org-compliant icon name using this property, or by raw pixmap data carried by the property <literal>IconPixmap</literal>. Visualizations are encouraged to prefer icon names over icon pixmaps if both are available to allow for better theming and integration by a Notification Host.</para> </sect3> <sect3 id="IconPixmap"> <title><literal>org.freedesktop.NotificationItem.IconPixmap</literal></title> <funcsynopsis> <funcprototype> <funcdef>ARRAY(INT, INT, ARRAY BYTE) <function>org.freedesktop.NotificationItem.IconPixmap</function> </funcdef> <paramdef/> </funcprototype> </funcsynopsis> <para>Carries an ARGB32 binary representation of the icon, the format of icon data used in this specification is described in Section <xref linkend="icons"/></para> </sect3> <sect3 id="OverlayIconName"> <title><literal>org.freedesktop.NotificationItem.OverlayIconName</literal></title> <funcsynopsis> <funcprototype> <funcdef>STRING <function>org.freedesktop.NotificationItem.OverlayIconName</function> </funcdef> <paramdef/> </funcprototype> </funcsynopsis> <para>The freedesktop.org-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.</para> </sect3> <sect3 id="OverlayIconPixmap"> <title><literal>org.freedesktop.NotificationItem.OverlayIconPixmap</literal></title> <funcsynopsis> <funcprototype> <funcdef>ARRAY(INT, INT, ARRAY BYTE) <function>org.freedesktop.NotificationItem.OverlayIconPixmap</function> </funcdef> <paramdef/> </funcprototype> </funcsynopsis> <para>ARGB32 binary representation of the overlay icon described in the previous paragraph.</para> </sect3> <sect3 id="AttentionIconName"> <title><literal>org.freedesktop.NotificationItem.AttentionIconName</literal></title> <funcsynopsis> <funcprototype> <funcdef>STRING <function>org.freedesktop.NotificationItem.AttentionIconName</function> </funcdef> <paramdef/> </funcprototype> </funcsynopsis> <para>The freedesktop.org-compliant name of an icon. this can be used by the visualization to indicate that the item is in <literal>RequestingAttention</literal> state.</para> </sect3> <sect3 id="AttentionIconPixmap"> <title><literal>org.freedesktop.NotificationItem.AttentionIconPixmap</literal></title> <funcsynopsis> <funcprototype> <funcdef>ARRAY(INT, INT, ARRAY BYTE) <function>org.freedesktop.NotificationItem.AttentionIconPixmap</function> </funcdef> <paramdef/> </funcprototype> </funcsynopsis> <para>ARGB32 binary representation of the requesting attention icon describen in the previous paragraph.</para> </sect3> <sect3 id="AttentionMovie"> <title><literal>org.freedesktop.NotificationItem.AttentionMovie</literal></title> <funcsynopsis> <funcprototype> <funcdef>ARRAY(INT, INT, ARRAY BYTE) <function>org.freedesktop.NotificationItem.AttentionMovie</function> </funcdef> <paramdef/> </funcprototype> </funcsynopsis> <para>An item can also specify an animation associated to the <literal>RequestingAttention</literal> state. The format is identical to single icons, as described in Section <xref linkend="icons"/>. The visualization can chose between the movie or AttentionIconPixmap (or using neither of those) at its discrection.</para> </sect3> <sect3 id="ToolTip"> <title><literal>org.freedesktop.NotificationItem.ToolTip</literal></title> <funcsynopsis> <funcprototype> <funcdef>(STRING, ARRAY(INT, INT, ARRAY BYTE), STRING, STRING) <function>org.freedesktop.NotificationItem.ToolTip</function> </funcdef> <paramdef/> </funcprototype> </funcsynopsis> <para>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:</para> <itemizedlist> <listitem> <para>STRING: freedesktop.org-compliant name for an icon. An empty string may be passed for no icon.</para> </listitem> <listitem> <para>ARRAY(INT, INT, ARRAY BYTE): optional icon ARGB32 pixmap data</para> </listitem> <listitem> <para>STRING: title for this tooltip</para> </listitem> <listitem> <para>STRING: optional descriptive text for this tooltip. It can contain also a subset of the HTML markup language, for a list of allowed tags see Section <xref linkend="markup"/>.</para> </listitem> </itemizedlist> </sect3> </sect2> <sect2 id="Notification ItemMethods"> <title>Methods</title> <sect3 id="ContextMenu"> <title>ContextMenu</title> <funcsynopsis> <funcprototype> <funcdef>VOID <function>org.freedesktop.NotificationItem.ContextMenu</function> </funcdef> <paramdef>INT <parameter>x</parameter></paramdef> <paramdef>INT <parameter>y</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Asks the notification item to show a context menu, this is typically a consequence of user input, such as a mouse right click over the graphical representation of the item.</para> <para>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.</para> </sect3> <sect3 id="Activate"> <title>Activate</title> <funcsynopsis> <funcprototype> <funcdef>VOID <function>org.freedesktop.NotificationItem.Activate</function> </funcdef> <paramdef>INT <parameter>x</parameter></paramdef> <paramdef>INT <parameter>y</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Asks the notification item for activation, this is typically a consequence of user input, such as a mouse left click over the graphical representation of the item. The application will perform any task is considered appropriate as an activation request.</para> <para>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).</para> </sect3> <sect3 id="SecondaryActivate"> <title>SecondaryActivate</title> <funcsynopsis> <funcprototype> <funcdef>VOID <function>org.freedesktop.NotificationItem.SecondaryActivate</function> </funcdef> <paramdef>INT <parameter>x</parameter></paramdef> <paramdef>INT <parameter>y</parameter></paramdef> </funcprototype> </funcsynopsis> <para>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 a mouse middle click over the graphical representation of the item. The application will perform any task is considered appropriate as an activation request.</para> <para>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).</para> </sect3> <sect3 id="Scroll"> <title>Scroll</title> <funcsynopsis> <funcprototype> <funcdef>VOID <function>org.freedesktop.NotificationItem.Scroll</function> </funcdef> <paramdef>INT <parameter>delta</parameter></paramdef> <paramdef>STRING <parameter>orientation</parameter></paramdef> </funcprototype> </funcsynopsis> <para>The user asked for a scroll action. This is caused from input such as mouse wheel over the graphical representation of the item.</para> <para>The <literal>delta</literal> paramenter represent the amount of scroll, the <literal>orientation</literal> paramenter represent the horizontal or vertical orientation of the scroll request and its legal values are <literal>horizontal</literal> and <literal>vertical</literal>.</para> </sect3> </sect2> <sect2 id="Notification ItemSignals"> <title>Signals</title> <sect3 id="NewTitle"> <title>NewTitle</title> <funcsynopsis> <funcprototype> <funcdef>VOID <function>org.freedesktop.NotificationItem.NewTitle</function> </funcdef> <paramdef/> </funcprototype> </funcsynopsis> <para>The item has a new title: the graphical representation should read it again immediately.</para> </sect3> <sect3 id="NewIcon"> <title>NewIcon</title> <funcsynopsis> <funcprototype> <funcdef>VOID <function>org.freedesktop.NotificationItem.NewIcon</function> </funcdef> <paramdef/> </funcprototype> </funcsynopsis> <para>The item has a new icon: the graphical representation should read it again immediately.</para> </sect3> <sect3 id="NewAttentionIcon"> <title>NewAttentionIcon</title> <funcsynopsis> <funcprototype> <funcdef>VOID <function>org.freedesktop.NotificationItem.NewAttentionIcon</function> </funcdef> <paramdef/> </funcprototype> </funcsynopsis> <para>The item has a new attention icon: the graphical representation should read it again immediately.</para> </sect3> <sect3 id="NewToolTip"> <title>NewToolTip</title> <funcsynopsis> <funcprototype> <funcdef>VOID <function>org.freedesktop.NotificationItem.NewToolTip</function> </funcdef> <paramdef/> </funcprototype> </funcsynopsis> <para>The item has a new tooltip: the graphical representation should read it again immediately.</para> </sect3> <sect3 id="NewStatus"> <title>NewStatus</title> <funcsynopsis> <funcprototype> <funcdef>VOID <function>org.freedesktop.NotificationItem.NewStatus</function> </funcdef> <paramdef>STRING <parameter>status</parameter></paramdef> </funcprototype> </funcsynopsis> <para>The item has a new status, that is passed as an argument of the signal.</para> </sect3> </sect2> </sect1> <sect1 id="NotificationItemWatcher"> <title>NotificationItemWatcher</title> <para>There will be a single <literal>org.freedesktop.NotificationItemWatcher</literal> service instance registered on the session but at any given time. The <literal>Notification ItemWatcher</literal> service is used to keep track of <literal>Notification Item</literal> instances, enumerate them and notify when new ones are registered or old ones are unregistered.</para> <para>It is also used to keep track of <literal>org.freedesktop.NotificationHost</literal> instances, to have an easy way to know if there is at least one service registered as the visualization host for the notification items.</para> <sect2> <title>Methods</title> <sect3 id="RegisterService"> <title>RegisterService</title> <funcsynopsis> <funcprototype> <funcdef>VOID <function>org.freedesktop.NotificationItemWatcher.RegisterService</function> </funcdef> <paramdef>STRING <parameter>service</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Register a <literal>Notification Item</literal> with the <literal>Notification Item Watcher</literal> on the session bus. The unique identifier of the Notification Item is used, for instance <literal>org.freedesktop.NotificationItem-4077-1</literal>. A Notification Item instance must be registered with the watcher in order to be noticed by both the watcher and any <literal>Notification Host</literal> instances that may exist. If the registered Notification Item is removed from the session bus, the Notification Item Watcher must remove it from the list of registered services.</para> </sect3> <sect3 id="RegisteredServices"> <title>RegisteredServices</title> <funcsynopsis> <funcprototype> <funcdef>ARRAY(STRING) <function>org.freedesktop.NotificationItemWatcher.RegisteredServices</function> </funcdef> <paramdef/> </funcprototype> </funcsynopsis> <para>A list of all registered <literal>Notification Items</literal>. All elements of the array should correspond to services actually running on the session bus at the moment of the method call.</para> </sect3> <sect3 id="ProtocolVersion"> <title>ProtocolVersion</title> <funcsynopsis> <funcprototype> <funcdef>STRING <function>org.freedesktop.NotificationItemWatcher.ProtocolVersion</function> </funcdef> <paramdef/> </funcprototype> </funcsynopsis> <para>Returns the version of the protocol the <literal>Notification Item Watcher</literal> instance implements.</para> </sect3> <sect3 id="RegisterNotificationHost"> <title>RegisterNotificationHost</title> <funcsynopsis> <funcprototype> <funcdef>VOID <function>org.freedesktop.NotificationItemWatcher.RegisterService</function> </funcdef> <paramdef>STRING <parameter>service</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Register a <literal>Notification Host</literal> with the <literal>Notification Item Watcher</literal> on the session bus. Its unique identifier is used for this, for instance <literal>org.freedesktop.NotificationHost-4005</literal>. Every Notfication Host instance that intends to display Notification Item representations should register with the Notification Item Watcher using this method. The Notification Item Watcher must automatically notice if an instance of NotificationHost goes away.</para> </sect3> <sect3 id="IsNotificationHostRegistered"> <title>IsNotificationHostRegistered</title> <funcsynopsis> <funcprototype> <funcdef>BOOL <function>org.freedesktop.NotificationItemWatcher.IsNotificationHostRegistered</function> </funcdef> <paramdef/> </funcprototype> </funcsynopsis> <para>Returns true if at least one <literal>Notification Host</literal> has been registered with <xref linkend="RegisterNotificationHost"/> and is currently running. If no Notification Hosts are registered and running, all Notification Item instances should fall back to using the freedesktop.org system tray specification.</para> </sect3> </sect2> <sect2> <title>SIGNALS</title> <sect3 id="ServiceRegistered"> <title>ServiceRegistered</title> <funcsynopsis> <funcprototype> <funcdef>BOOL <function>org.freedesktop.NotificationItemWatcher.ServiceRegistered</function> </funcdef> <paramdef>STRING <parameter>service</parameter></paramdef> </funcprototype> </funcsynopsis> <para>A new <literal>Notification Item</literal> has been registered, the argument of the signal is the session bus name of the instance. Notification Host implementations should listen this signal to know when they should update their representation of the items. Notification Hosts are not required to show all Notification Items that are registered, however; which Notification Items to show in a given Notification Host may be implementation specific.</para> </sect3> <sect3 id="ServiceUnregistered"> <title>ServiceUnregistered</title> <funcsynopsis> <funcprototype> <funcdef>BOOL <function>org.freedesktop.NotificationItemWatcher.ServiceUnregistered</function> </funcdef> <paramdef>STRING <parameter>service</parameter></paramdef> </funcprototype> </funcsynopsis> <para>A <literal>Notification Item</literal> instance has disappeared from the bus, the argument of the signal is the session bus name of the instance. Notification Host implementations should listen this signal to know when they should update their representation of the items.</para> </sect3> <sect3 id="NotificationHostRegistered"> <title>NotificationHostRegistered</title> <funcsynopsis> <funcprototype> <funcdef>BOOL <function>org.freedesktop.NotificationItemWatcher.NotificationHostRegistered</function> </funcdef> <paramdef/> </funcprototype> </funcsynopsis> <para>A new <literal>Notification Host</literal> has been registered. At this point the Notification Item instances know that they can use this protocol instead of the freedesktop.org system tray protocol.</para> </sect3> </sect2> </sect1> <sect1 id="NotificationHost"> <title>Notification Host</title> <para>A <literal>Notification Host</literal> corresponds to an object in an application that provides a representation of <literal>Notification Item</literal> instances. The representation will often be visual, but could also take the form of audio, a text display, file logging, etc.</para> <para>Instances of this service are registered on the D-Bus session bus, under a name on the form <literal>org.freedesktop.NotificationHost-id</literal> where <literal>id</literal> is a unique identifier which keeps the names unique on the bus. The process-id of the application or another type of identifier combined with the process id if more that one Notification Host is registered by the same process should be used.</para> <para><literal>Notification Host</literal> instances do not need any particular property, method or signal registered on the bus. What is important is the presence of the service, to inform <literal>Notification Item Watchers</literal> that a Notification Item representation is currently running on the system.</para> </sect1> <sect1 id="backwards-compatibility"> <title>Backwards Compatibility</title> <para> Implementers of Notification Item may also support the freedesktop.org system tray specification for compatibility purposes. If they do so, Notification Items should use the freedesktop.org system tray specification instead of the Notification Item protocol in one of the following scenarios: </para> <itemizedlist> <listitem> <para>The service <literal>org.freedesktop.NotificationItemWatcher</literal> is not registered on the session bus</para> </listitem> <listitem> <para>The service <literal>org.freedesktop.NotificationItemWatcher</literal> is registered on the session bus, but the method <literal>org.freedesktop.NotificationItemWatcher.IsNotificationHostRegistered</literal> returns <literal>FALSE</literal>.</para> </listitem> </itemizedlist> <para> As soon as <literal>org.freedesktop.NotificationItemWatcher</literal> appears on the session bus and <literal>org.freedesktop.NotificationItemWatcher.IsNotificationHostRegistered</literal> returns true the Freedesktop Systemtray item should be deleted and the NotificationItem should be registered instead. </para> <para> In the same way a NotificationItem should be registered when arrives the signal <literal>org.freedesktop.NotificationItemWatcher.NotificationHostRegistered</literal> and no NotificationHost were registered before. </para> </sect1> <sect1 id="markup" xreflabel="Markup"> <title>Markup</title> <para> The sub text of a tooltip may contain markup. The markup is XML-based, and consists of a small subset of HTML. </para> <para> The following tags should be supported by the NotificationHost visualization. Though it is optional, it is recommended. NotificationHost that do not support these tags should filter them out. </para> <informaltable> <tgroup cols="2"> <tbody valign="top"> <row> <entry> <sgmltag class="starttag">b</sgmltag> ... <sgmltag class="endtag">b</sgmltag> </entry> <entry>Bold</entry> </row> <row> <entry> <sgmltag class="starttag">i</sgmltag> ... <sgmltag class="endtag">i</sgmltag> </entry> <entry>Italic</entry> </row> <row> <entry> <sgmltag class="starttag">u</sgmltag> ... <sgmltag class="endtag">u</sgmltag> </entry> <entry>Underline</entry> </row> <row> <entry> <sgmltag class="starttag">a href="..."</sgmltag> ... <sgmltag class="endtag">a</sgmltag> </entry> <entry>Hyperlink</entry> </row> <row> <entry> <sgmltag class="emptytag">img src="..." alt="..."</sgmltag> </entry> <entry>Image</entry> </row> </tbody> </tgroup> </informaltable> <para> 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. </para> <para> 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. </para> <para> 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. </para> </sect1> <sect1 id="icons" xreflabel="Icons"> <title>Icons</title> <para> 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. </para> <para> 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. </para> </sect1> <sect1 id="scenario" xreflabel="Use case scenario"> <title>Use case scenario</title> <para> Here we show in pseudocode a typical 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. </para> <para> The function getDBusConnection() returns an object with all of the methods, properties and signals of a service registered on the bus. </para> <sect2 id="NotificationItemScenario"> <title>NotificationItem</title> <para> An application that wants to register a new NotificationItem has to do the following steps (providing we have a class, here called NotificationItem 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. </para> <programlisting> NotificationItem notificationItem = new NotificationItem(); String notificationItemBusName = "org.freedesktop.NotificationItem-" + pid() + "-" + uniqueId(); registerToDBus(notificationItemBusName); //setting the properties the NotificationItem notificationItem.setId("Mixer"); //no signal emitted: Id is not supposed to change again notificationItem.setTitle("Volume control"); //at this point notificationItem emitted the NewTitle signal notificationItem.setCategory(Hardware); //no signal emitted: Category is not supposed to change notificationItem.setStatus(Active); //notificationItem emitted NewStatus signal //here we use just icon names and not icon pixmaps notificationItem.setIconName("mixer"); //NewIcon emitted notificationItem.setTooltipIconName("mixer"); notificationItem.setTooltipTitle("Sound mixer"); notificationItem.setTooltipText("Control your soundcard volume"); //NewToolTip emitted: implementations are encouraged to emit this signal //just one time after all changes are done NotificationItemWatcherConnection watcher = getDBusConnection("org.freedesktop.NotificationItemWatcher"); watcher.RegisterService(notificationItemBusName); </programlisting> <para> At this point the item should be visualized in any NotificationHost that displays items of <literal>Hardware</literal> type. </para> <para> Each time a new property will be setted, the NotificationItem implementation must emit the proper signal. </para> </sect2> <sect2 id="NotificationItemWarcherScenario"> <title>NotificationItemWatcher</title> <para> The NotificationItemWatcher has to emit the ServiceRegistered signal every time somebdy calls RegisterService on it and emit ServiceUnRegistered when that service disappear on the session bus. </para> <para> The RegisateredServices method must return a list composed of only names that are actually registered on the session bus. </para> <para> When RegisterNotificationHost is register, the NotificationHostRegistered signal must be emitted. Below there is the pseudocode for the RegisterService method, here the m_services sontains a list of all the registered NotificationItem instances. </para> <programlisting> 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 ServiceRegistered(serviceName); } } </programlisting> </sect2> <sect2 id="NotificationHostScenario"> <title>NotificationHost</title> <para> When a NotificationHost instance starts it must register itself on NotificationItemWatcher and then fetch from it the list of registered NotificationItems and listen for new one registered or old ones going away. </para> <para> It should also keep in sync all properties like icons, states and tooltips. </para> <programlisting> String notificationHostName = "org.freedesktop.NotificationHost-" + pid() + "-" + uniqueId(); registerToDBus(notificationHostName); NotificationItemWatcherConnection watcher = getDBusConnection("org.freedesktop.NotificationItemWatcher"); watcher.registerNotificationHost(notificationHostName); connect(watcher, SIGNAL(ServiceRegistered()), this, SLOT(ServiceRegistered())); connect(watcher, SIGNAL(ServiceUnregistered()), this, SLOT(ServiceUnRegistered())); m_itemList = watcher.RegisteredServices(); foreach (string service, m_itemList) { NotificationItemConnection 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(); } </programlisting> </sect2> </sect1> </article>
_______________________________________________ Plasma-devel mailing list Plasma-devel@kde.org https://mail.kde.org/mailman/listinfo/plasma-devel
