Status Notifier Specification
Prev 

Use case scenario

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.

StatusNotifierItem

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.

StatusNotifierWatcher

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);
          }
      }

StatusNotifierHost

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();
      }
PrevHome 
Icons