AwnApplet

## AwnApplet AwnApplet |

## Synopsis

                        AwnAppletPrivate;
                        AwnApplet;
    gboolean            (*AwnAppletInitFunc)                (AwnApplet *applet);
    AwnApplet *         (*AwnAppletInitPFunc)               (const gchar *canonical_name,
                                                             const gchar *uid,
                                                             gint panel_id);
    AwnApplet *         awn_applet_new                      (const gchar *canonical_name,
                                                             const gchar *uid,
                                                             gint panel_id);
    const gchar*        awn_applet_get_canonical_name       (AwnApplet *applet);
    GtkPositionType     awn_applet_get_pos_type             (AwnApplet *applet);
    void                awn_applet_set_pos_type             (AwnApplet *applet,
                                                             GtkPositionType position);
    AwnPathType         awn_applet_get_path_type            (AwnApplet *applet);
    void                awn_applet_set_path_type            (AwnApplet *applet,
                                                             AwnPathType path);
    gint                awn_applet_get_offset               (AwnApplet *applet);
    gint                awn_applet_get_offset_at            (AwnApplet *applet,
                                                             gint x,
                                                             gint y);
    void                awn_applet_set_offset               (AwnApplet *applet,
                                                             gint offset);
    gint                awn_applet_get_size                 (AwnApplet *applet);
    void                awn_applet_set_size                 (AwnApplet *applet,
                                                             gint size);
    const gchar *       awn_applet_get_uid                  (AwnApplet *applet);
    void                awn_applet_set_uid                  (AwnApplet *applet,
                                                             const gchar *uid);
    AwnAppletFlags      awn_applet_get_behavior             (AwnApplet *applet);
    void                awn_applet_set_behavior             (AwnApplet *applet,
                                                             AwnAppletFlags flags);
    GtkWidget*          awn_applet_create_default_menu      (AwnApplet *applet);
    guint               awn_applet_inhibit_autohide         (AwnApplet *applet,
                                                             const gchar *reason);
    void                awn_applet_uninhibit_autohide       (AwnApplet *applet,
                                                             guint cookie);
    GdkNativeWindow     awn_applet_docklet_request          (AwnApplet *applet,
                                                             gint min_size,
                                                             gboolean shrink,
                                                             gboolean expand);
    GtkWidget *         awn_applet_create_pref_item         (void);
    GtkWidget *         awn_applet_create_about_item        (AwnApplet *applet,
                                                             const gchar *copyright,
                                                             AwnAppletLicense license,
                                                             const gchar *version,
                                                             const gchar *comments,
                                                             const gchar *website,
                                                             const gchar *website_label,
                                                             const gchar *icon_name,
                                                             const gchar *translator_credits,
                                                             const gchar **authors,
                                                             const gchar **artists,
                                                             const gchar **documenters);
    GtkWidget *         awn_applet_create_about_item_simple (AwnApplet *applet,
                                                             const gchar *copyright,
                                                             AwnAppletLicense license,
                                                             const gchar *version);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkContainer
                               +----GtkBin
                                     +----GtkWindow
                                           +----GtkPlug
                                                 +----AwnApplet
                                                       +----AwnAppletSimple

## Implemented Interfaces

AwnApplet implements AtkImplementorIface and GtkBuildable.

## Properties

      "canonical-name"           gchar*                : Read / Write / Construct Only
      "display-name"             gchar*                : Read / Write
      "max-size"                 gint                  : Read / Write
      "offset"                   gint                  : Read / Write
      "offset-modifier"          gfloat                : Read / Write
      "panel-id"                 gint                  : Read / Write / Construct Only
      "panel-xid"                gint64                : Read
      "path-type"                gint                  : Read / Write / Construct
      "position"                 GtkPositionType       : Read / Write
      "quit-on-delete"           gboolean              : Read / Write
      "show-all-on-embed"        gboolean              : Read / Write
      "size"                     gint                  : Read / Write
      "uid"                      gchar*                : Read / Write / Construct

## Signals

      "applet-deleted"                                 : Run First
      "flags-changed"                                  : Run First
      "menu-creation"                                  : Run First
      "offset-changed"                                 : Run First
      "origin-changed"                                 : Run Last
      "panel-configure-event"                          : Run Last
      "position-changed"                               : Run First
      "size-changed"                                   : Run First

## Description

## Details

### AwnAppletPrivate

    typedef struct _AwnAppletPrivate AwnAppletPrivate;

### AwnApplet

    typedef struct _AwnApplet AwnApplet;

### AwnAppletInitFunc ()

    gboolean            (*AwnAppletInitFunc)                (AwnApplet *applet);

Function prototype used as entry point for applets. Hook to have an AwnApplet built for you.

`applet` : | AwnApplet instance created for you.
Returns : | return TRUE if applet construction was successful, FALSE otherwise.

### AwnAppletInitPFunc ()

    AwnApplet *         (*AwnAppletInitPFunc)               (const gchar *canonical_name,
                                                             const gchar *uid,
                                                             gint panel_id);

Function prototype used as entry point for applets. Hook to build your own AwnApplet.

`canonical_name` : | applet's canonical name.
`uid` : | applet's unique ID.
`panel_id` : | ID of AwnPanel associated with this applet.
Returns : | return the constructed AwnApplet (or its subclass) or NULL.

### awn_applet_new ()

    AwnApplet *         awn_applet_new                      (const gchar *canonical_name,
                                                             const gchar *uid,
                                                             gint panel_id);

Creates a new AwnApplet which tries to connect via DBus to AwnPanel with the given ID. You can pass zero `panel_id` to not connect to any panel.

`canonical_name` : | canonical name of the applet.
`uid` : | unique ID of the applet.
`panel_id` : | ID of AwnPanel associated with the applet.
Returns : | the new AwnApplet.

### awn_applet_get_canonical_name ()

    const gchar*        awn_applet_get_canonical_name       (AwnApplet *applet);

Retrieve the applet's canonical name.

`applet` : | The AwnApplet.
Returns : | the applet's canonical name.

### awn_applet_get_pos_type ()

    GtkPositionType     awn_applet_get_pos_type             (AwnApplet *applet);

Gets current position of the applet. See `awn_applet_set_pos_type()`. This value corresponds to the value used by the associated panel.

`applet` : | an AwnApplet.
Returns : | current position of the applet.

### awn_applet_set_pos_type ()

    void                awn_applet_set_pos_type             (AwnApplet *applet,
                                                             GtkPositionType position);

Sets current position of the applet. Note that setting the position emits the "position-changed" signal.

`applet` : | an AwnApplet.
`position` : | new position of the applet.

### awn_applet_get_path_type ()

    AwnPathType         awn_applet_get_path_type            (AwnApplet *applet);

Gets currently used path type for this applet. This value corresponds to the value used by the associated panel.

`applet` : | an AwnApplet.
Returns : | currently used path type.

### awn_applet_set_path_type ()

    void                awn_applet_set_path_type            (AwnApplet *applet,
                                                             AwnPathType path);

Sets path type used by this applet. See `awn_applet_get_offset_at()`.

`applet` : | an AwnApplet.
`path` : | path type for this applet.

### awn_applet_get_offset ()

    gint                awn_applet_get_offset               (AwnApplet *applet);

Gets current offset set for the applet. This value corresponds to the value used by the associated panel. `see_also`: `awn_applet_get_offset_at()`.

`applet` : | an AwnApplet.
Returns : | current offset.

### awn_applet_get_offset_at ()

    gint                awn_applet_get_offset_at            (AwnApplet *applet,
                                                             gint x,
                                                             gint y);

`see_also`: `awn_applet_set_path_type()`.

Gets offset for widget with [`x`, `y`] coordinates with respect to the current path type.

`applet` : | an AwnApplet.
`x` : | X-coordinate.
`y` : | Y-coordinate.
Returns : | offset which should have the widget with [x, y] coordinates.

### awn_applet_set_offset ()

    void                awn_applet_set_offset               (AwnApplet *applet,
                                                             gint offset);

Sets offset used by this applet. Note that setting the offset emits the "offset-changed" signal.

`applet` : | an AwnApplet.
`offset` : | new offset for this applet.

### awn_applet_get_size ()

    gint                awn_applet_get_size                 (AwnApplet *applet);

Gets the current size set for the applet. This value corresponds to the value used by the associated panel.

`applet` : | an AwnApplet.
Returns : | current size set for the applet.

### awn_applet_set_size ()

    void                awn_applet_set_size                 (AwnApplet *applet,
                                                             gint size);

Sets new size for the applet. Note that setting the size emits the "size-changed" signal.

`applet` : | an AwnApplet.
`size` : | new size of the applet.

### awn_applet_get_uid ()

    const gchar *       awn_applet_get_uid                  (AwnApplet *applet);

Gets the unique ID for the applet.

`applet` : | an AwnApplet.
Returns : | unique ID for the applet.

### awn_applet_set_uid ()

    void                awn_applet_set_uid                  (AwnApplet *applet,
                                                             const gchar *uid);

Sets new unique ID for the applet.

`applet` : | an AwnApplet.
`uid` : | new unique ID for the applet.

### awn_applet_get_behavior ()

    AwnAppletFlags      awn_applet_get_behavior             (AwnApplet *applet);

Gets the flags set for this applet.

`applet` : | an AwnApplet.
Returns : | flags set for this applet.

### awn_applet_set_behavior ()

    void                awn_applet_set_behavior             (AwnApplet *applet,
                                                             AwnAppletFlags flags);

Sets behavior flags for this applet. Note that setting the flags to AWN_APPLET_IS_SEPARATOR or AWN_APPLET_IS_EXPANDER will send a DBus request to the associated AwnPanel which will destroy the socket used by this applet.

`applet` : | an AwnApplet.
`flags` : | flags for this applet.

### awn_applet_create_default_menu ()

    GtkWidget*          awn_applet_create_default_menu      (AwnApplet *applet);

Creates an default applet context menu. Includes a dock preferences menu item

`applet` : | An AwnApplet.
Returns : | A default GtkMenu for AwnApplet

### awn_applet_inhibit_autohide ()

    guint               awn_applet_inhibit_autohide         (AwnApplet *applet,
                                                             const gchar *reason);

Requests the associated AwnPanel to disable autohide (if the panel is already hidden it will unhide) until a call to `awn_applet_uninhibit_autohide()` with the returned ID is made.

`applet` : | an AwnApplet.
`reason` : | reason for the inhibit.
Returns : | cookie ID which can be used in `awn_applet_uninhibit_autohide()`.

### awn_applet_uninhibit_autohide ()

    void                awn_applet_uninhibit_autohide       (AwnApplet *applet,
                                                             guint cookie);

Uninhibits autohide of the associated AwnPanel. See `awn_applet_inhibit_autohide()`.

`applet` : | an AwnApplet.
`cookie` : | inhibit cookie returned by the call to `awn_applet_inhibit_autohide()`.

### awn_applet_docklet_request ()

    GdkNativeWindow     awn_applet_docklet_request          (AwnApplet *applet,
                                                             gint min_size,
                                                             gboolean shrink,
                                                             gboolean expand);

Requests docklet mode from the associated AwnPanel - all applets will be hidden and only one window will be shown.

`applet` : | AwnApplet instance.
`min_size` : | Minimum size required.
`shrink` : | If true and the panel has greater size than requested, it will shrink to min_size. Otherwise current panel size will be allocated.
`expand` : | If true the embedded window will be allowed to expand, otherwise the window will be restricted to min_size.
Returns : | non-zero window XID which can be passed to GtkPlug constructor, or zero if the call failed (or another application is currently using docklet mode).

### awn_applet_create_pref_item ()

    GtkWidget *         awn_applet_create_pref_item         (void);

Create a Dock Preferences menu item.

Returns : | A GtkImageMenuItem for the Dock Preferences that can be added to an applet icon's context menu.

### awn_applet_create_about_item ()

    GtkWidget *         awn_applet_create_about_item        (AwnApplet *applet,
                                                             const gchar *copyright,
                                                             AwnAppletLicense license,
                                                             const gchar *version,
                                                             const gchar *comments,
                                                             const gchar *website,
                                                             const gchar *website_label,
                                                             const gchar *icon_name,
                                                             const gchar *translator_credits,
                                                             const gchar **authors,
                                                             const gchar **artists,
                                                             const gchar **documenters);

Creates an about dialog and an associated menu item for use in the applet's context menu. The `copyright` and `license` parameters are mandatory. The rest are optional. See also GtkAboutDialog for a description of the parameters other than `license`.

`applet` : | An AwnApplet.
`copyright` : | The copyright holder string.
`license` : | Must be one of the values enumerated in AwnAppletLicense.
`version` : | Applet version string.
`comments` : | Comment string.
`website` : | Website string.
`website_label` : | Website label string.
`icon_name` : | Icon name.
`translator_credits` : | Translator's credit string.
`authors` : | Array of author strings.
`artists` : | Array of artist strings.
`documenters` : | Array of documentor strings.
Returns : | An "about applet" GtkMenuItem

### awn_applet_create_about_item_simple ()

    GtkWidget *         awn_applet_create_about_item_simple (AwnApplet *applet,
                                                             const gchar *copyright,
                                                             AwnAppletLicense license,
                                                             const gchar *version);

Creates an about dialog and an associated menu item for use in the applet's context menu. The `copyright` and `license` parameters are mandatory. See also GtkAboutDialog for a description of the parameters other than `license`.

`applet` : | An AwnApplet.
`copyright` : | The copyright holder string.
`license` : | Must be one of the values enumerated in AwnAppletLicense.
`version` : | Applet version string.
Returns : | An "about applet" GtkMenuItem

## Property Details

### The `"canonical-name"` property

      "canonical-name"           gchar*                : Read / Write / Construct Only

The canonical name of the applet. The format should be considered the same as a GObject property name: [a-zA-Z][a-zA-Z0-9_\-] In English, the first character must be a lowercase letter of the English alphabet, and the following character(s) can be one or more lowercase English letters, numbers, and/or minus characters.

For all applets in the Awn Extras project, this name should be the same as the main directory as the applet sources.

### Note

For Python applets, it should also be the same name as the main applet script.

Default value: NULL

### The `"display-name"` property

      "display-name"             gchar*                : Read / Write

Display name for the applet.

Default value: NULL

### The `"max-size"` property

      "max-size"                 gint                  : Read / Write

The maximum visible size of the applet.

Allowed values: >= 0

Default value: 48

### The `"offset"` property

      "offset"                   gint                  : Read / Write

The icon offset of the bar.

Allowed values: >= 0

Default value: 0

### The `"offset-modifier"` property

      "offset-modifier"          gfloat                : Read / Write

The offset modifier for non-linear path types.

Default value: 1

### The `"panel-id"` property

      "panel-id"                 gint                  : Read / Write / Construct Only

The id of the Awn Panel the applet connects to.

Allowed values: >= 0

Default value: 0

### The `"panel-xid"` property

      "panel-xid"                gint64                : Read

The XID of the awn panel the applet is connected to.

Default value: 0

### The `"path-type"` property

      "path-type"                gint                  : Read / Write / Construct

Path used on the panel.

Allowed values: [0,1]

Default value: 0

### The `"position"` property

      "position"                 GtkPositionType       : Read / Write

The current bar position.

Default value: GTK_POS_BOTTOM

### The `"quit-on-delete"` property

      "quit-on-delete"           gboolean              : Read / Write

Whether the applet quits when it's socket is destroyed.

Default value: TRUE

### The `"show-all-on-embed"` property

      "show-all-on-embed"        gboolean              : Read / Write

The applet will automatically call show_all when it's embedded in the socket.

Default value: TRUE

### The `"size"` property

      "size"                     gint                  : Read / Write

The current visible size of the bar.

Allowed values: >= 0

Default value: 48

### The `"uid"` property

      "uid"                      gchar*                : Read / Write / Construct

Awn's Unique ID for this applet instance.

Default value: NULL

## Signal Details

### The `"applet-deleted"` signal

    void                user_function                      (AwnApplet *awnapplet,
                                                            gpointer   user_data)      : Run First

`awnapplet` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"flags-changed"` signal

    void                user_function                      (AwnApplet *awnapplet,
                                                            gint       arg1,
                                                            gpointer   user_data)      : Run First

`awnapplet` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The `"menu-creation"` signal

    void                user_function                      (AwnApplet *awnapplet,
                                                            GtkMenu   *arg1,
                                                            gpointer   user_data)      : Run First

`awnapplet` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The `"offset-changed"` signal

    void                user_function                      (AwnApplet *awnapplet,
                                                            gint       arg1,
                                                            gpointer   user_data)      : Run First

`awnapplet` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The `"origin-changed"` signal

    void                user_function                      (AwnApplet    *awnapplet,
                                                            GdkRectangle *arg1,
                                                            gpointer      user_data)      : Run Last

`awnapplet` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The `"panel-configure-event"` signal

    void                user_function                      (AwnApplet *awnapplet,
                                                            GdkEvent  *event,
                                                            gpointer   user_data)      : Run Last

`awnapplet` : | the object which received the signal.
`event` : |
`user_data` : | user data set when the signal handler was connected.

### The `"position-changed"` signal

    void                user_function                      (AwnApplet      *awnapplet,
                                                            GtkPositionType arg1,
                                                            gpointer        user_data)      : Run First

`awnapplet` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The `"size-changed"` signal

    void                user_function                      (AwnApplet *awnapplet,
                                                            gint       arg1,
                                                            gpointer   user_data)      : Run First

`awnapplet` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.