From AWN Wiki

[edit] AWN Applet Development Guidelines

AWN applets are a way for a user to customize their experience and to help them use their AWN however they would like. These guidelines are intended for developers writing applets so that applets have a unified look and feel.

[edit] Optional Preferences

These guidelines only specify what your applet should do by default. Any option that the user explicitly chooses is not part of the scope of this specification.

[edit] Applet Appearance

Maintaining a consistent color scheme and having a similar appearance throughout allows AWN and its applets to feel integrated and easily usable.

[edit] Dialog Colors

All applets SHOULD default to the GTK+ colors used in AWN by default. In other words, don't override the styles unless users ask to do so. While you can include facilities to change the colors of dialogs, these changes SHOULD NOT be enabled by default.

[edit] Dialog Style

Applets SHOULD use the default AWN dialogs. Use of custom dialogs is not discouraged; however, if they are used, they SHOULD NOT be the default.

[edit] Icon Style

All icons displayed in the AWN bar MUST follow several conventions:

• Applets SHOULD resize their icon to be the size of the AWN bar. Awn Applet Simple does a simple scale of pixbuf on bar height changes but it is preferable that the applet produce best quality icon on these occasions.
• If an applet uses a Theme icon it MUST continue to function in a usable manner if that icon is not present.This means that users without a specific icon in their theme will still be able to use the applet. A common method of accomplishing this goal is to bundle icons with the applets.
• Applets should attempt to use an appropriate theme icon if there is a reasonable choice available. This allows applets to have a greater likelihood of visually conforming to the user's desktop. Bundled icons are acceptable as an option in all cases and it is recognized that sometimes they are the best default choice.

[edit] Applet Behavior

Maintaining consistent behavior across applets simplifies life for the user by making applets predictable and intuitive.

[edit] Notifications

Any applet that needs to implement "notifications", that cannot be done through simple manipulation of the applet icon, SHOULD support the Freedesktop (libnotify) specification as the default method. Other notification methods, such as mumbles, may optionally be supported.

[edit] Icon Behavior

The icon SHOULD provide one of two functions:

• act somewhat like a launcher, simply running a specific command every time it is pressed, or
• toggle whether a dialog is shown.

For example, an applet to control a media player might start a specific player when the icon is clicked and no player is running, or open the dialog to play or pause if one is. An applet shouldn't, for example, update data from the internet when clicked. If that is to happen, it should happen through a timer.

The following pointers apply to the applet icon and its behaviour.

• An icon SHOULD NOT open or close its dialog when it is hovered over. No action should be triggered by a hover other than the display of the applet title.

• An applet SHOULD, by default, toggle the state of its dialog when it is left-clicked.

• An applet SHOULD open a secondary dialog or launch a program when middle-clicked (if one exists/is suitable).

• An applet MUST show a context menu on right-click that at minimum contains the libawn default menu plus an about applet menu item.

• If a secondary dialog, or external program does not make sense or is not available, the applet MUST NOT do anything when middle clicked.

[edit] Python Applet Dependencies

Applets written in Python MUST give a visual error to the user (for example, by way of an error dialog) if one or more of its dependencies are not met. Although work is under way to provide a sort of infrastructure in the Python Awn module (see Launchpad bug #160375), until it is in a released version of Awn, developers are obligated to write a similar function themselves.

[edit] Terminal Output

Applets SHOULD NOT generate any terminal output during normal operation. Error messages are fine. "Main dialog opened" is not only completely useless but also uncalled for. This also includes GTK/GObject warnings. If you don't know what's causing them, ask someone more knowledgeable. A user's awn session should not spam his console with useless warnings. Note that due to the virtual impossibility of meeting this criterion, some leeway will be allowed.

[edit] Shared Configuration Keys

Shared configuration keys have been introduced to AWN and they SHOULD be honored by applets. They are located in the 'applets' configuration folder in a subfolder called 'shared'. Applets should check any keys located in this folder and behave appropriately. It is anticipated that those applets using AWNlib will have them applied for free in most cases. As of this writing most existing applets do not follow this guideline but they will be converted as time permits.

[edit] Menus

An applet MUST provide a right-click context menu. It is advisable to use the libawn API to generate the basic menu and add any additional menu items as needed. If the libawn is not used then the context menu MUST duplicate the functionality and appearance as if the default menu was used.
C example:

GtkWidget *menu;
menu = awn_applet_create_default_menu (applet);

Python:

menu = self.create_default_menu() #Where self is the applet

Vala:

menu = create_default_menu()

[edit] Coding Style

[edit] Paths

Paths MUST NOT be hardcoded. This is problematic in two cases in particular:

1. When distributions package an applet, the paths may not conform to their guidelines for file placement.
2. Some people who install applets from source install them to a non-standard prefix (i.e., not /usr or /usr/local).

[edit] Blocking Network Calls

If an applet is using networking functionality that blocks then it SHOULD do so in a separate thread/process. If a network call is used in the applet's main thread then it have an end result of stuttering animations and reduced responsivenes to input up to a worst case scenario of "freezing" for several minutes at a time. Either uses a separate thread/process or use non-blocking network calls.

[edit] Exception Handling

An issue that is related to Terminal Output is that of proper error handling. Applets SHOULD attempt to anticipate likely error conditions and handle them in an appropriate manner. An common example is the necessity of properly error handling in network oriented applets which might experience a loss of connectivity. This requirement does NOT allow for the indiscriminate use of try/catch blocks. An exception SHOULD only be caught if it will be handled appropriately OR if it can be harmlessly ignored in the context of the code in question. It is often appropriate to provide an appropriately formatted warning message on the terminal when an exception is caught.

If the error is such that it could have some bearing on the user (such as a failed import) that error MUST be graphically displayed to the user - not just terminal output, but some sort of graphical indication that an error occurred, hopefully with details of the error and ways to fix that error.

[edit] Infrastructure

[edit] Build System

If you plan on submitting your applet for inclusion in Awn Extras, make sure you list all of your dependencies when submitting a blueprint.

[edit] Applet License and Copyright

Applet MUST have a copyright on the top of all files: Name and email of the author, and license of the file. Add other copyright(s) if a part of the code was written by someone else. Not following this rule is grounds for removal from the build system or deletion from AWN-Extras.

[edit] Libraries

Every attempt SHOULD be made to use system libraries. Bundling of libraries with applets is strongly discouraged and MUST be justifiable from a technical perspective.

[edit] Desktop Files

Desktop files SHOULD be validated with the command desktop-file-validate (part of the desktop-file-utils package). To ensure that desktop files validate, all applets MUST set the "Type" key to "Application" (both case-sensitive) in their desktop files.

Python applets MUST have the key "X-AWN-AppletType" with the value "Python" (both case-sensitive) in their desktop files (see Launchpad bug #179232).

Applets SHOULD have the key "X-AWN-AppletCategory" that determines the category of applets in belongs in. These should be one of the Freedesktop.Org Main Categories as defined by the Desktop Menu Specification. Test applets in particular are to go under Development,Debugging where users can safely ignore them.

The "Name" and "Comment" fields of the applet's desktop file MUST NOT be longer than the default width of AWN Manager.

When an applet is included in Awn Extras, the desktop file SHOULD be named applet_name.desktop.in.in, so that the build system can replace certain variables in it, and then so that intltool can insert the translations into the file. In order for the latter to happen, the translatable keys MUST be prepended with an underscore ( _ ). This file should be listed in the AC_OUTPUT section of the configure.ac file as src/applet_name/applet_name.desktop.in

Here is an example desktop file for the fictional foobar applet, named src/foobar/foobar.desktop.in.in in the awn-extras tree:

[Desktop Entry]
Type=Application
_Name=Foo Bar
_Comment=Connects to stuff
Exec=@LIBDIR@/awn/applets/foobar/foobar.so
Icon=gtk-yes
X-AWN-AppletType=C
X-AWN-AppletCategory=Utility

[edit] Icon Naming and Installation

If your applet is themable, that is, has more than one set of differently-styled icons (or has the capability to support them), it SHOULD follow the Themable Application-specific Icons specification.

[edit] Configuration

If your applet can be configured by a user, it SHOULD use Awn's builtin configuration API (AwnConfigClient in C, awn.Config in Python). Please make sure that a schema-ini file is also created and maintained (details in the link).

[edit] Document Information

[edit] Document Conventions

This document attempts to conform to rfc2119. In particular, this means that the phrases MUST, SHOULD, and MAY (and their negative complements, such as MUST NOT) have significant meaning.

[edit] Status

This document is currently a work in progress. However, anyone who hopes to have their applet added to awn-extras SHOULD follow these guidelines as much as possible. The guidelines are not yet required (the previous sentence should be changed to MUST when that happens), but will be in the future. However, there is always room for dispute and edging. If you feel your applet requires an exception, please discuss on the talk page or one of the locations below.

[edit] Discussion

There is a forum thread for discussion and a Launchpad blueprint. Please also feel free to use the talk page.