<<Include(Ayatana/PageTemplate/Header)>>
= Application Panel Indicators =

<<TableOfContents(3)>>

== Summary ==

For the Lucid cycle, the DX team is focusing on a part of the desktop that has become a problem-area:

{{{{attachment:disaster.png}}}}

The current notification area is more and more difficult for users to interact with. Each application behaves differently, they're not accessible, and they're even sometime styled differently.

We propose to migrate the different applets to using simple menus. This change should provide a more consistent interface and be an important step to improve the user experience with the right hand side of the panel.

To implement that change, we're proposing to use a set of dbus APIs. These protocols are based on current technologies, some already used in Ubuntu, others also discussed by members of the FreeDesktop.org group. This includes an implementation already validated by the KDE project.

We are providing a set of libraries compatible with the 2 major desktop environments, along with tools and documentation to help porting applications to use the new protocols.

This effort is managed as part of the Ayatana project group on Launchpad, joining other cross-desktop projects that were delivered during the last Ubuntu development cycles. See resources below.

 * Jono Bacon's [[[http://www.jonobacon.org/2010/02/10/kde-application-indicators-in-gnome/|blog|post]]] on progress.
 * Jorge Castro's [[[http://castrojo.wordpress.com/2010/02/06/application-indicator-update/|blog|post]]] on progress.
 * Sense Hofstede's experience [[[http://qense.nl/giving-transmission-the-indicator-application|porting|Transmission]]] to app indicators.

== Notification area usage analysis ==

The panel indicator area was introduced in an early version of Gnome, on the model of the Microsoft '95 design, as an area dedicated to notifications. It is often called the systray or the notification area.

=== Use cases ===

Generally it allows users to very quickly access important application features. For application developers, there are thus certain occasions were it's interesting to host some of the user interface directly on the panel:

 * Someone using Last.fm wants quick access to play, pause, skip, love, and ban tracks. Some of these actions are specific to Last.fm, and not relevant to any other music player.
 * Someone using Ubuntu One to sync files wants to see whether it is currently syncing, and wants quick access to pause and resume functions. These tasks would not make sense in any other menu.
 * Someone using Tomboy wants a menu to let them quickly create new notes and access recent notes. Eventually these tasks may be integrated into a more generic document-creation interface, but for now, these tasks do not make sense in any other menu.
 * A software developer testing visual bugs in her software wants quick access to start and stop recording of the screen.

=== Issues with the current situation ===

Over time the notification area grew organically and somewhat inconsistently, for example, by including various applets which, according to the Guidelines, do not properly belong in the panel indicators area.

{{{{attachment:panel-suck.png}}}}

1.   The areas of the panel are not clearly defined or identifiable at a glance because items are no longer organised visually, behaviorally and logically.  Each item seems to have an independent purpose and, when clicked, behaves very differently one from the other. We have buttons, menu-ish panel, menu-ish slider and menus. This makes it almost impossible for users to gain a clear overall picture of the function of that area.

2.  Users expect items close to each other to behave similarly.  They rely on the proximity of applets/applications/menus to predict their behaviours and explain their functions (Usability principles: 1) proximity compatibility (Barnett & Wickens, 1988; Wickens & Carswell, 1995) and 2) consistency (Universal Principle of Design; Nielsen Norman; Bastien & Scapin). The unpredictability of behaviours of items in the panel indicator generates some confusion since users are not always in a position to interpret what the system is doing in response to their actions.  

Recommendations:  Decisions have to be made about the role of the panel indicators area and items have to be grouped and organized with consistency as to goal, function and behavior in order to offer users a consistent, predictable and therefore intuitive experience.

=== Proposed changes ===

We propose to define 2 main areas on the panel:

 * a "system indicator" area at the far right of the panel, gathering system features like sound, power or session management
 * an "application indicator" area, just before it, grouping icons and menus from applications that wish to host a part of their interface on the panel 

Additionaly, we propose to turn all of the elements on the right side of the panel into regular menus.

{{{{attachment:panel-suck-less.png}}}}

This way, users will not have to worry about whether a function is accessible with a left or right click, or be suprised when a click on a panel icon suddenly hides or shows a full application window. Additionally, that will help provide:
 * an accessible interface: icons and menus will be introspectable by screen readers
 * style consistency: as the menus will be rendered by the same toolkit as the panel, the context menus of KDE applications will be rendered in the same style as other applications running on a Gnome desktop, and vice versa
 * constant layout: being integrated in a common menubar (as opposed to a collection of applets), icons and menus shouldn't be disturbed by resolution changes, like when doing a presentation and then returning to the desktop to see all applets totally disorganized
 * menu scrubbing: users frequently browse menus in search of a feature; by turning the notification area into a set of menus, the users will be able to search the interface more easily

Note: for compatibility reasons, we'll maintain a notification area zone for a while, to let application developers gradually migrate to the new protocol. Eventually, the old notification area should disappear and applications being able to inject generic/common functions in the system area, while the application-specific features will stay in the "application indicator" zone.

== Software Architecture ==

During the Jaunty and Karmic cycles, we initiated a process to connect the panel and parts of the system using dbus. Traditionally the panel communicates with the rest of the system through a variety of technologies like: Orbit, X properties or Xembed. That flexibility has allowed a lot of applications to use the panel, but the general result is that this starts to show its age.

Using dbus for the panel. We've started with some menus (that we call indicators). We want to continue with all systray/notification-area applications. We call these application-indicators.

There are different parts composing the architecture required to implement the proposed solution.

 1. A ''panel applet'' to host the variety of application icons: the applet should display the icons or menu titles, render the content of menus/sub-menus and dialog with the application once the user activates a menu entry.
 2. A ''library to let applications register a status icon'' in the panel area; the library should be similar to the existing API, namely gtk_status_icon_new on a Gnome desktop.
 3. A ''"signaling protocol"'' between the panel and applications, to maintain that bi-directional link between applications and their icons and menus.
 4. A ''library to export the context menus'', their content and structure, between an application and the panel applet. Trying hard to make that as transparent as possible.
 5. A corresponding ''protocol to transport the menus'' and allow for rapid content-related signals to be propagated between the application and the applet, across a dbus link.

We want to do this in a cross-desktop friendly manner that uses existing standards and is easy to migrate to. Therefore we propose this new method of application panel indicators.

In the implementation we developed for the Gnome desktop, we're reusing some existing technologies and introducing a new library.

 * '''dbusmenu''' is the library implementing the transport protocol between the applications and the panel (#5). dbusmenu has already been used for developing the session menu, and is a building block also for implementing some new system menus in Lucid

 * '''indicator-applet''' is the panel applet that will host the application indicator area. indicator-applet was developed as part of the messaging menu project and is meant to be a generic container for panel indicators

 * '''libappindicator''' is a new library introduced to help with application side changes; it does register icons and menus and internally uses dbusmenu to publish context menus over dbus. While its a new library for the Gnome desktop, it is based on a protocol (the "signaling protocol" part above) that was designed in the KDE project to renovate the systray protocol. libappindicator adopts and extends this protocol, and connects it with dbusmenu to provide the full set of service that an application will require to migrate its code

Note: the extensions to KDE's KStatusNotifier API have been discussed with upstream developers in order to have cross-desktop compatible protocols. This way a KDE application running on a Gnome desktop will have its icon and context menu properly rendered in the Gnome panel. Similarly, a Gnome application running under KDE, should see its icon and menu rendered in the new systray plasmoïd.

== Technical Resources ==

=== Design Guidelines ===

Currently applications set how they behave in the notification area. Some use it as a fancy minimize function, others shouldn't have icons in the first place, etc. The design team have put together a design document on how your application should behave.

  * [[[https://wiki.ubuntu.com/CustomStatusMenuDesignGuidelines|Design|Guidelines]]]

=== Libraries ===

 * [[[http://developer.ubuntu.com/api/ubuntu-11.04/python/AppIndicator-0.1.html|API|Documentation for Python]]]
 * [[[http://developer.ubuntu.com/api/ubuntu-11.04/c/appindicator/|libappindicator|Reference Manual]]]
 * [[[http://hackage.haskell.org/package/happindicator|happindicator|- Haskell bindings for libappindicator]]]

Get the code here or ([[[http://bazaar.launchpad.net/~indicator-applet-developers/indicator-application/trunk/files|browse]]]):
{{{
bzr branch lp:indicator-application
}}}

We are providing sample implementations in C, C#, and Python using three applications: Rhythmbox, Tomboy, and jockey.
 * [[[#Typical|usage (C version)|C code sample]]] below
 * C# patch for Tomboy: see [[[https://bugs.edge.launchpad.net/ubuntu/+source/tomboy/+bug/497058/comments/1]]]
 * [[[#Python|version|Python code sample]]] below (thanks to JonoBacon)
 * Python patch for jockey: see [[[https://code.launchpad.net/~cjcurran/jockey/app-indicator-support]]]

As of 2010-01-14, libappindicator now provides automatic fallback support in the absence of the application indicator area, ie you don't have to check for the presence of the applet in your code, the library will do that for you automatically. If the area is not present on the user desktop, the library will automatically rewrite "app indicator" calls to use the old gtk_status_icon / systray API.
Also, libappindicator now provides transparent menu updates. This means that there's no need to do anything when changing a menu content elsewhere in an application: the library connects to gtk signals to trigger dbusmenu updates on the fly and refresh the icons and menus on the panel.

=== Automake fu ===

libappindicator is not yet a blessed dependency for Gnome (and won't be for the time being). So here is how third-party application developers can conditionally build for Ubuntu and use the new app. indicators.

'''WARNING''': When using the Mono bindings for libappindicator, you have to check for 'appindicator-sharp-0.1' rather than 'appindicator-0.1'!

1. Test for the existence of libappindicator on the build system
{{{
APPINDICATOR_REQUIRED=0.0.7

AC_ARG_ENABLE(appindicator,
                        AS_HELP_STRING([--enable-appindicator[=@<:@no/auto/yes@:>@]],[Build support for application indicators ]),
                        [enable_appindicator=$enableval],
                        [enable_appindicator="auto"])

if test x$enable_appindicator = xauto ; then
        PKG_CHECK_EXISTS([appindicator-0.1 >= $APPINDICATOR_REQUIRED],
                         enable_appindicator="yes",
                         enable_appindicator="no")
fi

if test x$enable_appindicator = xyes ; then
        PKG_CHECK_EXISTS([appindicator-0.1 >= $APPINDICATOR_REQUIRED],,
                         AC_MSG_ERROR([appindicator-0.1 is not installed]))
        PKG_CHECK_MODULES(APP_INDICATOR,
                        appindicator-0.1 >= $APPINDICATOR_REQUIRED)
        AC_SUBST(APP_INDICATOR_CFLAGS)
        AC_SUBST(APP_INDICATOR_LIBS)
        AC_DEFINE(HAVE_APP_INDICATOR, 1, [Have AppIndicator])
fi
AM_CONDITIONAL(HAVE_APP_INDICATOR, test x"$enable_appindicator" = xyes)
}}}

2. Enjoy libappindicator!


=== Public Package Archive(s) ===

We have set up [[[https://edge.launchpad.net/~indicator-applet-developers/+archive/indicator-core-ppa|a|PPA]]] with the core libraries needed for you to install and test libappindicator for Ubuntu Karmic. For Lucid users the libraries will be included in the distro by default. Adding this PPA, upgrading, and running rhythmbox will show you how it works.

If you are interested in porting and getting applications tested, we have set up [[[https://edge.launchpad.net/~application-indicator-upstream/+archive/ppa|an|upstream applications PPA]]] as a service to upstreams who want to get their applications tested. If you need help with this please contact JorgeCastro.

=== Bug reports, lists and IRC ===

 * File bugs here: https://launchpad.net/indicator-application
 * dbusmenu-list, for discussing the protocol, its optimization and potential extensions: https://edge.launchpad.net/~dbusmenu-list
 * #ayatana on freenode.org
 * [[[https://launchpad.net/~ayatana-dev|Mailing|List]]]
 * [[[https://bugs.edge.launchpad.net/ubuntu/+bugs?field.tag=indicator-application|Current|List of Bugs]]] in Launchpad of applications that need to be ported. These currently just cover what is main right now. If you want to port an application in universe, file a wishlist bug on it and tag it with "indicator-application". Then when you're done porting it attach a patch and then send the patch upstream.


== Priority Applications ==
Below is a list of applications that need porting to the new API.

[[[https://bugs.edge.launchpad.net/ubuntu/+bugs?field.tag=indicator-application|List|of applications]]] - Applications should also have a corresponding upstream bug report (Feel free to file and link them). When your patch is ready for review please submit it to the upstream bug tracker attached to the corresponding bug.

||'''Name'''||'''Current behavior'''||'''Description of neccessary change'''||'''Blueprint?/Bug Report?'''||'''Blocking Bugs?'''||
|| gnome-display-properties || Can provide a tray icon if the option is set in the main dialog. It provides a list of radio items and some (cairo drawn?) headers. The menu is the same for left and right click. || Just port the menu over (don't know if the headers can be ported over without an addition of functionality in libdbusmenu. || None || None ||

== Porting Guide for Applications ==

The application indicators API is similar to the GtkStatusIcon API in some ways, but [[[http://developer.ubuntu.com/api/ubuntu-11.04/libappindicator/|simpler|and more opinionated]]] in its design.

Indicators are grouped together by category, so it's important for the application to accurately specify its category.  Possible categories for indicators include:
 * APP_INDICATOR_CATEGORY_APPLICATION_STATUS: used to tell the user the current state of the application and    allow users to act on that.
 * APP_INDICATOR_CATEGORY_COMMUNICATIONS: might be used by applications such as IM clients to let the user know they have received new messages.
 * APP_INDICATOR_CATEGORY_SYSTEM_SERVICES: inform the user about system-related events. Maybe there are updates available?
 * APP_INDICATOR_CATEGORY_HARDWARE: used for hardware-related tasks, for example Bluetooth.
 * APP_INDICATOR_CATEGORY_OTHER: if the app doesn't belong in one of the other categories but needs an indicator, it should use other.

The category is set when the indicator is created and isn't changed.

Application indicators fall into one of three states:
 * APP_INDICATOR_STATUS_PASSIVE: the indicator should be hidden from the user
 * APP_INDICATOR_STATUS_ACTIVE: the indicator should be shown normally
 * APP_INDICATOR_STATUS_ATTENTION: the application wants the user's attention

The indicator status can be set using app_indicator_set_status().

The icons need to use icon names from themes, direct paths to icon files are not supported. For example, icon names used with gtk_status_icon_new_from_file() won't work.

=== Typical usage (C version) ===

Indicators should typically be created using the helper function app_indicator_new().  This returns a pointer to a newly created AppIndicator object, which is may be unref'd normally when it is no longer needed.  This function expects three parameters:
{{{
  AppIndicator* app_indicator_new (const gchar          *id,
                                   const gchar          *icon_name,
                                   AppIndicatorCategory  category);
}}}
The id parameter should be unique to your application.  Because app indicators are cross-desktop, the icon_name parameter expects an icon name according to the usual icon naming spec.  The category parameter is the indicator category as described above.

Once an indicator object is created, the application may decide to set an attention icon using app_indicator_set_attention_icon().

Lastly, the indicator should be given a GtkMenu object.  This can be either created manually or using some other method such as GtkUIManager. Below is an example using GtkUIManager.

{{{#!highlight c
#include <gtk/gtk.h>
#include <libappindicator/app-indicator.h>

static void activate_action (GtkAction *action);

static GtkActionEntry entries[] = {
  { "FileMenu", NULL, "_File" },
  { "New",      "document-new", "_New", "<control>N",
    "Create a new file", G_CALLBACK (activate_action) },
  { "Open",     "document-open", "_Open", "<control>O",
    "Open a file", G_CALLBACK (activate_action) },
  { "Save",     "document-save", "_Save", "<control>S",
    "Save file", G_CALLBACK (activate_action) },
  { "Quit",     "application-exit", "_Quit", "<control>Q",
    "Exit the application", G_CALLBACK (gtk_main_quit) },
};
static guint n_entries = G_N_ELEMENTS (entries);

static const gchar *ui_info =
"<ui>"
"  <menubar name='MenuBar'>"
"    <menu action='FileMenu'>"
"      <menuitem action='New'/>"
"      <menuitem action='Open'/>"
"      <menuitem action='Save'/>"
"      <separator/>"
"      <menuitem action='Quit'/>"
"    </menu>"
"  </menubar>"
"  <popup name='IndicatorPopup'>"
"    <menuitem action='New' />"
"    <menuitem action='Open' />"
"    <menuitem action='Save' />"
"    <menuitem action='Quit' />"
"  </popup>"
"</ui>";

static void
activate_action (GtkAction *action)
{
        const gchar *name = gtk_action_get_name (action);
        GtkWidget *dialog;

        dialog = gtk_message_dialog_new (NULL,
                                         GTK_DIALOG_DESTROY_WITH_PARENT,
                                         GTK_MESSAGE_INFO,
                                         GTK_BUTTONS_CLOSE,
                                         "You activated action: \"%s\"",
                                         name);

        g_signal_connect (dialog, "response",
                          G_CALLBACK (gtk_widget_destroy), NULL);

        gtk_widget_show (dialog);
}

int main (int argc, char **argv)
{
  GtkWidget *window;
  GtkWidget *menubar;
  GtkWidget *table;
  GtkWidget *sw;
  GtkWidget *contents;
  GtkWidget *statusbar;
  GtkWidget *indicator_menu;
  GtkActionGroup *action_group;
  GtkUIManager *uim;
  AppIndicator *indicator;
  GError *error = NULL;

  gtk_init (&argc, &argv);

  /* main window */
  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  gtk_window_set_title (GTK_WINDOW (window), "Indicator Demo");
  gtk_window_set_icon_name (GTK_WINDOW (window), "indicator-messages-new");
  g_signal_connect (G_OBJECT (window),
                    "destroy",
                    G_CALLBACK (gtk_main_quit),
                    NULL);

  table = gtk_table_new (1, 5, FALSE);
  gtk_container_add (GTK_CONTAINER (window), table);

  /* Menus */
  action_group = gtk_action_group_new ("AppActions");
  gtk_action_group_add_actions (action_group,
                                entries, n_entries,
                                window);

  uim = gtk_ui_manager_new ();
  g_object_set_data_full (G_OBJECT (window),
                          "ui-manager", uim,
                          g_object_unref);
  gtk_ui_manager_insert_action_group (uim, action_group, 0);
  gtk_window_add_accel_group (GTK_WINDOW (window),
                              gtk_ui_manager_get_accel_group (uim));

  if (!gtk_ui_manager_add_ui_from_string (uim, ui_info, -1, &error))
    {
      g_message ("Failed to build menus: %s\n", error->message);
      g_error_free (error);
      error = NULL;
    }

  menubar = gtk_ui_manager_get_widget (uim, "/ui/MenuBar");
  gtk_widget_show (menubar);
  gtk_table_attach (GTK_TABLE (table),
                    menubar,
                    0, 1,                    0, 1,
                    GTK_EXPAND | GTK_FILL,   0,
                    0,                       0);

  /* Document */
  sw = gtk_scrolled_window_new (NULL, NULL);

  gtk_scrolled_window_set_policy (GTK_SCROLLED_WINDOW (sw),
                                  GTK_POLICY_AUTOMATIC,
                                  GTK_POLICY_AUTOMATIC);

  gtk_scrolled_window_set_shadow_type (GTK_SCROLLED_WINDOW (sw),
                                       GTK_SHADOW_IN);

  gtk_table_attach (GTK_TABLE (table),
                    sw,
                    /* X direction */       /* Y direction */
                    0, 1,                   3, 4,
                    GTK_EXPAND | GTK_FILL,  GTK_EXPAND | GTK_FILL,
                    0,                      0);

  gtk_window_set_default_size (GTK_WINDOW (window),
                               200, 200);

  contents = gtk_text_view_new ();
  gtk_widget_grab_focus (contents);

  gtk_container_add (GTK_CONTAINER (sw),
                     contents);


  /* Create statusbar */
  statusbar = gtk_statusbar_new ();
  gtk_table_attach (GTK_TABLE (table),
                    statusbar,
                    /* X direction */       /* Y direction */
                    0, 1,                   4, 5,
                    GTK_EXPAND | GTK_FILL,  0,
                    0,                      0);

  /* Show the window */
  gtk_widget_show_all (window);

  /* Indicator */
  indicator = app_indicator_new ("example-simple-client",
                                 "indicator-messages",
                                 APP_INDICATOR_CATEGORY_APPLICATION_STATUS);

  indicator_menu = gtk_ui_manager_get_widget (uim, "/ui/IndicatorPopup");

  app_indicator_set_status (indicator, APP_INDICATOR_STATUS_ACTIVE);
  app_indicator_set_attention_icon (indicator, "indicator-messages-new");

  app_indicator_set_menu (indicator, GTK_MENU (indicator_menu));

  gtk_main ();

  return 0;
}
}}}

=== Python version ===

==== PyGI ====

{{{#!highlight python
#!/usr/bin/env python
#
# Copyright 2009-2012 Canonical Ltd.
#
# Authors: Neil Jagdish Patel <neil.patel@canonical.com>
#          Jono Bacon <jono@ubuntu.com>
#          David Planella <david.planella@ubuntu.com>
#
# This program is free software: you can redistribute it and/or modify it 
# under the terms of either or both of the following licenses:
#
# 1) the GNU Lesser General Public License version 3, as published by the 
# Free Software Foundation; and/or
# 2) the GNU Lesser General Public License version 2.1, as published by 
# the Free Software Foundation.
#
# This program is distributed in the hope that it will be useful, but 
# WITHOUT ANY WARRANTY; without even the implied warranties of 
# MERCHANTABILITY, SATISFACTORY QUALITY or FITNESS FOR A PARTICULAR 
# PURPOSE.  See the applicable version of the GNU Lesser General Public 
# License for more details.
#
# You should have received a copy of both the GNU Lesser General Public 
# License version 3 and version 2.1 along with this program.  If not, see 
# <http://www.gnu.org/licenses/>
#

from gi.repository import Gtk
from gi.repository import AppIndicator3 as appindicator


def menuitem_response(w, buf):
  print buf

if __name__ == "__main__":
  ind = appindicator.Indicator.new (
                        "example-simple-client",
                        "indicator-messages",
                        appindicator.IndicatorCategory.APPLICATION_STATUS)
  ind.set_status (appindicator.IndicatorStatus.ACTIVE)
  ind.set_attention_icon ("indicator-messages-new")

  # create a menu
  menu = Gtk.Menu()

  # create some 
  for i in range(3):
    buf = "Test-undermenu - %d" % i

    menu_items = Gtk.MenuItem(buf)

    menu.append(menu_items)

    # this is where you would connect your menu item up with a function:
    
    # menu_items.connect("activate", menuitem_response, buf)

    # show the items
    menu_items.show()

  ind.set_menu(menu)

  Gtk.main()
}}}

==== PyGTK ====

{{{#!highlight python
#!/usr/bin/env python
#
# Copyright 2009 Canonical Ltd.
#
# Authors: Neil Jagdish Patel <neil.patel@canonical.com>
#          Jono Bacon <jono@ubuntu.com>
#
# This program is free software: you can redistribute it and/or modify it 
# under the terms of either or both of the following licenses:
#
# 1) the GNU Lesser General Public License version 3, as published by the 
# Free Software Foundation; and/or
# 2) the GNU Lesser General Public License version 2.1, as published by 
# the Free Software Foundation.
#
# This program is distributed in the hope that it will be useful, but 
# WITHOUT ANY WARRANTY; without even the implied warranties of 
# MERCHANTABILITY, SATISFACTORY QUALITY or FITNESS FOR A PARTICULAR 
# PURPOSE.  See the applicable version of the GNU Lesser General Public 
# License for more details.
#
# You should have received a copy of both the GNU Lesser General Public 
# License version 3 and version 2.1 along with this program.  If not, see 
# <http://www.gnu.org/licenses/>
#

import gobject
import gtk
import appindicator


def menuitem_response(w, buf):
  print buf

if __name__ == "__main__":
  ind = appindicator.Indicator ("example-simple-client",
                              "indicator-messages",
                              appindicator.CATEGORY_APPLICATION_STATUS)
  ind.set_status (appindicator.STATUS_ACTIVE)
  ind.set_attention_icon ("indicator-messages-new")

  # create a menu
  menu = gtk.Menu()

  # create some 
  for i in range(3):
    buf = "Test-undermenu - %d" % i

    menu_items = gtk.MenuItem(buf)

    menu.append(menu_items)

    # this is where you would connect your menu item up with a function:
    
    # menu_items.connect("activate", menuitem_response, buf)

    # show the items
    menu_items.show()

  ind.set_menu(menu)

  gtk.main()

}}}

=== C# Example ===
{{{#!highlight csharp
using Gtk;
using AppIndicator;

public class IndicatorExample
{
        public static void Main ()
        {
                Application.Init ();

                Window win = new Window ("Test");
                win.Resize (200, 200);

                Label label = new Label ();
                label.Text = "Hello, world!";

                win.Add (label);

                ApplicationIndicator indicator = new ApplicationIndicator ("my-id",
                                                                           "my-name",
                                                                           Category.ApplicationStatus);

                indicator.Status = Status.Attention;

                /*
                Menu menu = new Menu ();
                menu.Append (new MenuItem ("Foo"));
                menu.Append (new MenuItem ("Bar"));

                indicator.Menu = menu;
                */

                win.ShowAll ();

                Application.Run ();
        }
}
}}}

=== Vala Example ===
{{{#!highlight vala
/*
 * Copyright 2011-2013 Canonical Ltd.
 *
 * This program is free software: you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 3, as published
 * by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranties of
 * MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR
 * PURPOSE.  See the GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 * Compile with:
 *  valac --pkg appindicator3-0.1 --pkg gtk+-3.0 app-indicator.vala
 *
 * Authors:
 *   Marco Trevisan (Treviño) <mail@3v1n0.net>
 */

using AppIndicator;

public class IndicatorExample {
        public static int main(string[] args) {
                Gtk.init(ref args);

                var win = new Gtk.Window();
                win.title = "Indicator Test";
                win.resize(200, 200);
                win.destroy.connect(Gtk.main_quit);

                var label = new Gtk.Label("Hello, world!");
                win.add(label);

                var indicator = new Indicator(win.title, "indicator-messages",
                                              IndicatorCategory.APPLICATION_STATUS);

                indicator.set_status(IndicatorStatus.ACTIVE);
                indicator.set_attention_icon("indicator-messages-new");

                var menu = new Gtk.Menu();

                var item = new Gtk.MenuItem.with_label("Foo");
                item.activate.connect(() => {
                        indicator.set_status(IndicatorStatus.ATTENTION);
                });
                item.show();
                menu.append(item);

                item = new Gtk.MenuItem.with_label("Bar");
                item.show();
                item.activate.connect(() => {
                        indicator.set_status(IndicatorStatus.ATTENTION);
                });
                menu.append(item);

                indicator.set_menu(menu);

                win.show_all();

                Gtk.main();
                return 0;
        }
}
}}}

=== Haskell example ===
{{{#!highlight haskell
-- Either install the Haskell bindings through cabal (cabal install happindicator) or clone the git repository
-- at https://github.com/A1kmm/happindicator and install from there.

import Graphics.UI.AppIndicator
import Graphics.UI.Gtk
import Control.Monad

main = do
  initGUI
  appInd <- appIndicatorNew "appIndicatorDemo" "appointment-soon" AppIndicatorCategoryApplicationStatus
  appIndicatorSetStatus appInd AppIndicatorStatusActive
  set appInd [ appIndicatorAttentionIconName := Just "folder", 
               appIndicatorIconDesc := Just "Demo - non-attention",
               appIndicatorAttentionIconDesc := Just "Demo - attention", 
               appIndicatorLabel := Just "1" ]
  indMenu <- menuNew
  forM_ ["Hello", "World", "I'm a MenuItem"] $ \itemName -> do
    item <- menuItemNewWithLabel itemName
    menuShellAppend indMenu item
    item `on` menuItemActivate $ do
      appIndicatorSetStatus appInd AppIndicatorStatusAttention
    widgetShow item
  widgetShow indMenu
  appIndicatorSetMenu appInd indMenu
  mainGUI
}}}

=== Custom Fallbacks ===

By default the Application Indicator supports a fallback which will create a GtkStatusIcon with the same icon as the Application Indicator. It supports the menu and responds to all the same state and icon changes. For most applications this should be complete sufficient for their needs. Some applications may wish to handle the callback slightly differently than this. In that case the fallback functions are provided in the class structure so that they can be subclassed and overridden.

There are two functions {{{fallback}}} and {{{unfallback}}}.  In general, the fallback function should setup the fallback scenario and the unfallback will take it down.  Unfallback will be called if the application indicator returns or at shutdown if that never occurs.

For a very simple example of a fallback function you can look at the [[[http://bazaar.launchpad.net/~indicator-applet-developers/indicator-application/trunk/annotate/head:/tests/test-libappindicator-fallback-item.c|| fallback test]]] that creates an object overriding the fallback and unfallback functions.  Also, the code in the [[[http://bazaar.launchpad.net/~indicator-applet-developers/indicator-application/trunk/annotate/head:/src/libappindicator/app-indicator.c|| Application Indicator itself]]] for the fallback and unfallback functions was designed so that it only uses Public API functions so it can be copied directly and modified.

You can also use the 'connection_changed' signal to watch changes to the connections.

== Treatment of the API ==

Menus should be presented from lowest `Position` value on the leading end, to highest `Position` value on the trailing end. If an indicator does not declare a `Position` value, it should fill the 32-bit integer with the most significant byte being filled by the category: 0 for `APP_INDICATOR_CATEGORY_APPLICATION_STATUS`, 40 for APP_INDICATOR_CATEGORY_COMMUNICATIONS, 80 for `APP_INDICATOR_CATEGORY_SYSTEM_SERVICES`, 120 for `APP_INDICATOR_CATEGORY_HARDWARE`, or 160 for `APP_INDICATOR_CATEGORY_OTHER`, with the remaining three bytes filled by the first 3 bytes of the application name.

The title of the menu should consist of the icon represented by `IconName`, followed by the text in `Label` if any. If that text is wider than 6 em, it should be cropped at the trailing end.