AwnThemedIcon

## AwnThemedIcon AwnThemedIcon — A AwnIcon subclass that provides gtk themed icon support |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libawn/libawn.h>

                        AwnThemedIconPrivate;
                        AwnThemedIcon;
    GtkWidget *         awn_themed_icon_new                 (void);
    void                awn_themed_icon_set_state           (AwnThemedIcon *icon,
                                                             const gchar *state);
    const gchar *       awn_themed_icon_get_state           (AwnThemedIcon *icon);
    void                awn_themed_icon_set_size            (AwnThemedIcon *icon,
                                                             gint size);
    gint                awn_themed_icon_get_size            (AwnThemedIcon *icon);
    const gchar *       awn_themed_icon_get_default_theme_name
                                                            (AwnThemedIcon *icon);
    void                awn_themed_icon_set_info            (AwnThemedIcon *icon,
                                                             const gchar *applet_name,
                                                             const gchar *uid,
                                                             GStrv states,
                                                             GStrv icon_names);
    void                awn_themed_icon_set_info_simple     (AwnThemedIcon *icon,
                                                             const gchar *applet_name,
                                                             const gchar *uid,
                                                             const gchar *icon_name);
    void                awn_themed_icon_set_info_append     (AwnThemedIcon *icon,
                                                             const gchar *state,
                                                             const gchar *icon_name);
    void                awn_themed_icon_set_applet_info     (AwnThemedIcon *icon,
                                                             const gchar *applet_name,
                                                             const gchar *uid);
    void                awn_themed_icon_override_gtk_theme  (AwnThemedIcon *icon,
                                                             const gchar *theme_name);
    GdkPixbuf *         awn_themed_icon_get_icon_at_size    (AwnThemedIcon *icon,
                                                             gint size,
                                                             const gchar *state);
    void                awn_themed_icon_clear_icons         (AwnThemedIcon *icon,
                                                             gint scope);
    void                awn_themed_icon_clear_info          (AwnThemedIcon *icon);
    void                awn_themed_icon_preload_icon        (AwnThemedIcon *icon,
                                                             gchar *state,
                                                             gint size);
    GtkIconTheme *      awn_themed_icon_get_awn_theme       (AwnThemedIcon *icon);
    GtkWidget *         awn_themed_icon_create_custom_icon_item
                                                            (AwnThemedIcon *icon,
                                                             const gchar *icon_name);
    GtkWidget *         awn_themed_icon_create_remove_custom_icon_item
                                                            (AwnThemedIcon *icon,
                                                             const gchar *icon_name);
    void                awn_themed_icon_drag_data_received  (GtkWidget *widget,
                                                             GdkDragContext *context,
                                                             gint x,
                                                             gint y,
                                                             GtkSelectionData *selection_data,
                                                             guint info,
                                                             guint evt_time);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkDrawingArea
                               +----AwnIcon
                                     +----AwnThemedIcon

## Implemented Interfaces

AwnThemedIcon implements AtkImplementorIface, GtkBuildable and AwnOverlayable.

## Properties

      "applet-name"              gchar*                : Read / Write / Construct
      "drag-and-drop"            gboolean              : Read / Write / Construct
      "rotate"                   GdkPixbufRotation     : Read / Write / Construct

## Description

Provides convenient support for one or more themed icons using lists of of icon names / icon states. Includes support of transparent (to applet) modification of displayed icons through drag and drop. A subclass of AwnIcon.

## Details

### AwnThemedIconPrivate

    typedef struct _AwnThemedIconPrivate AwnThemedIconPrivate;

### AwnThemedIcon

    typedef struct _AwnThemedIcon AwnThemedIcon;

Provides convenient support for one or more themed icons using lists of of icon names / icon states. Includes support of transparent (to applet) modification of displayed icons through drag and drop. A subclass of AwnIcon.

### awn_themed_icon_new ()

    GtkWidget *         awn_themed_icon_new                 (void);

Creates a new instance of AwnThemedIcon.

Returns : | an instance of AwnThemedIcon

### awn_themed_icon_set_state ()

    void                awn_themed_icon_set_state           (AwnThemedIcon *icon,
                                                             const gchar *state);

Switches to the icon state specificed. This will switch the displayed icon to the corresponding themed icon.

`icon` : | A pointer to an AwnThemedIcon object.
`state` : | The icon state that is to be enabled.

### awn_themed_icon_get_state ()

    const gchar *       awn_themed_icon_get_state           (AwnThemedIcon *icon);

Get the current icon state of the AwnThemedIcon.

`icon` : | A pointer to an AwnThemedIcon object.
Returns : | a pointer to the current icon state string.

### awn_themed_icon_set_size ()

    void                awn_themed_icon_set_size            (AwnThemedIcon *icon,
                                                             gint size);

Set the Icon size.

`icon` : | A pointer to an AwnThemedIcon object.
`size` : | An icon size

### awn_themed_icon_get_size ()

    gint                awn_themed_icon_get_size            (AwnThemedIcon *icon);

Get the current icon size.

`icon` : | A pointer to an AwnThemedIcon object.
Returns : | the current icon size.

### awn_themed_icon_get_default_theme_name ()

    const gchar *       awn_themed_icon_get_default_theme_name
                                                            (AwnThemedIcon *icon);

Retrieve the default system icon theme name

`icon` : | A pointer to an AwnThemedIcon object.
Returns : | the current default icon theme name.

### awn_themed_icon_set_info ()

    void                awn_themed_icon_set_info            (AwnThemedIcon *icon,
                                                             const gchar *applet_name,
                                                             const gchar *uid,
                                                             GStrv states,
                                                             GStrv icon_names);

Sets a list of Icon names and Icon states for the specific Applet name / UID instance.

`icon` : | A pointer to an AwnThemedIcon object.
`applet_name` : | The applet name.
`uid` : | The applet's UID.
`states` : | A NULL terminated list of icon states.
`icon_names` : | A NULL terminated list of theme icon names that corresponds to the states arra.

### awn_themed_icon_set_info_simple ()

    void                awn_themed_icon_set_info_simple     (AwnThemedIcon *icon,
                                                             const gchar *applet_name,
                                                             const gchar *uid,
                                                             const gchar *icon_name);

Sets icon name for a specific Applet name / UID instance. Used for Icons that only have one icon.

`icon` : | A pointer to an AwnThemedIcon object.
`applet_name` : | The applet name.
`uid` : | The applet's UID.
`icon_name` : | A themed icon name.

### awn_themed_icon_set_info_append ()

    void                awn_themed_icon_set_info_append     (AwnThemedIcon *icon,
                                                             const gchar *state,
                                                             const gchar *icon_name);

Appends a icon state/ icon name pair to the existing list of themed icons.

`icon` : | A pointer to an AwnThemedIcon object.
`state` : | An Icon state.
`icon_name` : | A icon name.

### awn_themed_icon_set_applet_info ()

    void                awn_themed_icon_set_applet_info     (AwnThemedIcon *icon,
                                                             const gchar *applet_name,
                                                             const gchar *uid);

Sets the applet name / uid pair for the icon. If an existing applet name has previously been set then the value will not be modified.

`icon` : | A pointer to an AwnThemedIcon object.
`applet_name` : | The applet name.
`uid` : | The UID of the applet instance.

### awn_themed_icon_override_gtk_theme ()

    void                awn_themed_icon_override_gtk_theme  (AwnThemedIcon *icon,
                                                             const gchar *theme_name);

Overrides the default icon theme with a different icon theme.

`icon` : | A pointer to an AwnThemedIcon object.
`theme_name` : | A icon theme name.

### awn_themed_icon_get_icon_at_size ()

    GdkPixbuf *         awn_themed_icon_get_icon_at_size    (AwnThemedIcon *icon,
                                                             gint size,
                                                             const gchar *state);

Retrieve an icon as a GdkPixbuf at a specific size and for a specific icon state. Note that this will not change the currently displayed icon. The caller is responsible of unreffing the pixbuf.

`icon` : | A pointer to an AwnThemedIcon object.
`size` : | A icon theme name.
`state` : | The desired icon state.
Returns : | an GdkPixbuf for the requested state of the requested size.

### awn_themed_icon_clear_icons ()

    void                awn_themed_icon_clear_icons         (AwnThemedIcon *icon,
                                                             gint scope);

Delete icons from the custom awn-theme in $HOME/.icons/awn-theme

`icon` : | A pointer to an AwnThemedIcon object.
`scope` : | Scope to clear. One of SCOPE_AWN_THEME, SCOPE_AWN_APPLET, SCOPE_AWN_UID.

### awn_themed_icon_clear_info ()

    void                awn_themed_icon_clear_info          (AwnThemedIcon *icon);

Clears any icon names and icon states that have been set for the Icon.

`icon` : | A pointer to an AwnThemedIcon object.

### awn_themed_icon_preload_icon ()

    void                awn_themed_icon_preload_icon        (AwnThemedIcon *icon,
                                                             gchar *state,
                                                             gint size);

Queues a preload of an icon. The icon load and cache of the icon is queued using `g_idle_add()`.

`icon` : | A pointer to an AwnThemedIcon object.
`state` : | The icon state.
`size` : | The size of the icon. A value less than or equal to 0 indicates the current size should be used.

### awn_themed_icon_get_awn_theme ()

    GtkIconTheme *      awn_themed_icon_get_awn_theme       (AwnThemedIcon *icon);

A convenience method for bindings.

`icon` : | The themed icon.
Returns : | The current icon theme associated with the themed icon.

### awn_themed_icon_create_custom_icon_item ()

    GtkWidget *         awn_themed_icon_create_custom_icon_item
                                                            (AwnThemedIcon *icon,
                                                             const gchar *icon_name);

Creates a "Customize Icon" menu item.

`icon` : | A pointer to an AwnThemedIcon object.
`icon_name` : | The name of the customized icon.
Returns : | A GtkImageMenuItem for the Customize Icon that can be added to an applet icon's context menu.

### awn_themed_icon_create_remove_custom_icon_item ()

    GtkWidget *         awn_themed_icon_create_remove_custom_icon_item
                                                            (AwnThemedIcon *icon,
                                                             const gchar *icon_name);

Creates a "Remove Customize Icon" menu item. Will only be visible when a custom icon is in use.

`icon` : | A pointer to an AwnThemedIcon object.
`icon_name` : | A custom icon or name or NULL if the default customer icons are to be used
Returns : | A GtkImageMenuItem for the Customize Icon that can be added to an applet icon's context menu.

### awn_themed_icon_drag_data_received ()

    void                awn_themed_icon_drag_data_received  (GtkWidget *widget,
                                                             GdkDragContext *context,
                                                             gint x,
                                                             gint y,
                                                             GtkSelectionData *selection_data,
                                                             guint info,
                                                             guint evt_time);

This is exposed for applets that need to do their own drag and drop handling but still want to chain the this function so it can handle icons that are dropped. Use this by setting the drag_and_drop property of AwnThemedIcon and chaining to this function from the applet drag data received handler.

`widget` : | An AwnThemedIcon object.
`context` : | The GDK drag context.
`x` : | The X position of the drop.
`y` : | The Y position of the drop.
`selection_data` : | The received data.
`info` : | The info that has been registered with the target in the GtkTargetList.
`evt_time` : | The drag event time.

## Property Details

### The `"applet-name"` property

      "applet-name"              gchar*                : Read / Write / Construct

The applet name.

Default value: NULL

### The `"drag-and-drop"` property

      "drag-and-drop"            gboolean              : Read / Write / Construct

Whether to enable the dragging and dropping of icons, so that a user can customize the icon via a user interface. One example of an applet that would not want this behavior enabled is a trash applet that allowed a user to drag and drop files onto it, in order to send them to the trash.

If this value is `FALSE`, the icon customization behavior can be used as a fallback by calling awn_themed_icon_drag_data_received in a custom signal handler for "drag-data-received".

Default value: TRUE

### The `"rotate"` property

      "rotate"                   GdkPixbufRotation     : Read / Write / Construct

Rotates the icon as per GdkPixbufRotation.

Default value: GDK_PIXBUF_ROTATE_NONE

## See Also

#AwnIcon, AwnOverlaidIcon, GtkIconTheme