From AWN Wiki

Some applets can be detached from Awn. Once they are detached, they appear on the desktop and can be used normally. There is a Youtube video of it in action. This page is used for the documentation of it for applet developers. It is also a work in progress. See these two Bazaar branches:

• lp:~sharkbaitbobby/awn/awn-detach2
• lp:~awn-extras/awn-extras/awn-detach3

[edit] Documentation

Detach is integrated in AwnApplet and AwnAppletSimple. If the applet is an AwnAppletSimple, the reflections will be turned off automatically. You will probably only have to look at the main function and the menu item.

[edit] Simple Function

This code enables all features of Detach, but does not do anything with the menu item.

applet = awn_applet_new_with_detach(uid, orient, height);

applet = awn_applet_simple_new_with_detach(uid, orient, height);

self.enable_detach()

[edit] Configuration

Detach can use AwnConfigClient so the applet will be positioned at the same place when Awn is started, if it was detached when Awn was exited. Use this function, which returns the used AwnConfigClient. Note that it is per-instance, and stored in app/UID. Detach uses the keys detached (boolean), detached_x (integer), and detached_y (integer).

awn_applet_detach_config(applet);

self.detach_config()

[edit] Detaching and Attaching

Applets are detached and attached using this code:

awn_applet_set_detached(applet, TRUE);
awn_applet_set_detached(applet, FALSE);

self.set_detached(True)
self.set_detached(False)

You can also get the current status using similar functions:

gboolean detached = awn_applet_get_detached(applet);

detached = self.get_detached()

[edit] Dragging around the Desktop

By default, Detach will not drag the applet around the desktop if it is detached. This is done since most applets display the dialog when the button is pressed without being released, and the applet dialog could display for a little bit before the applet is moved around the desktop. If dragging around the desktop is enabled, connecting to button-release-event instead of button-press-event should work. Also note that if this is enabled, dropping on Awn when the applet is near it will be enabled. To disable this, see Lock.

awn_applet_enable_drag_around_desktop(applet);

self.enable_drag_around_desktop()

[edit] Dragging from Awn

By default, Detach will not drag the applet from Awn. Use this code to allow that to happen. See above and Lock.

awn_applet_enable_drag_from_awn(applet);

self.enable_drag_from_awn()

[edit] GObject Signals

The signal 'detached' is emitted after the applet has been reparented, right before the detached window is displayed. The signal 'attached' is emitted after the detached window is hidden, right before the applet widget is reparented. These signals belong to AwnApplet. AwnAppletSimple connects to these signals to turn on/off reflections.

[edit] Menu Item

Detach provides a GtkImageMenuItem with an arrow and the text "Detach" or "Attach." It is automatically updated whenever the applet is detached or attached. Detach creates a new menu item whenever this is called, and keeps a list so it can change the text and arrow direction. Menu items are automatically removed from the list when they are destroyed.

GtkWidget *detach_menu_item = awn_applet_detach_menu_item(applet);
gtk_menu_shell_append(GTK_MENU_SHELL(menu), detach_menu_item);

detach_menu_item = self.detach_menu_item()
menu.append(detach_menu_item)

[edit] Lock

If you want to prevent an applet from being dragged around the desktop or dragged from Awn, use this code:

awn_applet_set_locked(applet, TRUE);
gboolean locked = awn_applet_get_locked(applet);

self.set_locked(True)
locked = self.get_locked()

However, if you want the user to be able to do this via a menu item, use the following code.

GtkWidget *detach_lock_item = awn_applet_detach_lock_item(applet);
gtk_menu_shell_append(GTK_MENU_SHELL(menu), detach_lock_item);

detach_lock_item = self.detach_lock_item()
menu.append(detach_lock_item)

[edit] Height Request

If you want your applet to be at a greater height than displayed on the bar, the top of the applet will be cut off. This code prevents that from happening when detached.

awn_applet_set_height_request(applet, 125);
guint height = awn_applet_get_height_request(applet);

self.set_height_request(125)
height_request = self.get_height_request()