HdyAvatar: Handy Reference Manual

## HdyAvatar HdyAvatar — A widget displaying an image, with a generated fallback. |

## Functions

GdkPixbuf * | (*HdyAvatarImageLoadFunc) ()
GtkWidget * | hdy_avatar_new ()
const gchar * | hdy_avatar_get_icon_name ()
void | hdy_avatar_set_icon_name ()
const gchar * | hdy_avatar_get_text ()
void | hdy_avatar_set_text ()
gboolean | hdy_avatar_get_show_initials ()
void | hdy_avatar_set_show_initials ()
void | hdy_avatar_set_image_load_func ()
gint | hdy_avatar_get_size ()
void | hdy_avatar_set_size ()
GdkPixbuf * | hdy_avatar_draw_to_pixbuf ()
void | hdy_avatar_draw_to_pixbuf_async ()
GdkPixbuf * | hdy_avatar_draw_to_pixbuf_finish ()
GLoadableIcon * | hdy_avatar_get_loadable_icon ()
void | hdy_avatar_set_loadable_icon ()

## Properties

char * | icon-name | Read / Write
GLoadableIcon * | loadable-icon | Read / Write
gboolean | show-initials | Read / Write
int | size | Read / Write
char * | text | Read / Write

## Types and Values

#define | HDY_TYPE_AVATAR
| HdyAvatar

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkDrawingArea
                    ╰── HdyAvatar

## Implemented Interfaces

HdyAvatar implements AtkImplementorIface and GtkBuildable.

## Description

HdyAvatar is a widget to display a round avatar. A provided image is made round before displaying, if no image is given this widget generates a round fallback with the initials of the “text” on top of a colord background. The color is picked based on the hash of the “text”. If “show-initials” is set to `FALSE`, `avatar-default-symbolic` is shown in place of the initials. Use `hdy_avatar_set_loadable_icon()` or “loadable-icon” to set a custom image.

### CSS nodes

HdyAvatar has a single CSS node with name avatar.

## Functions

### HdyAvatarImageLoadFunc ()

    GdkPixbuf *
    (*HdyAvatarImageLoadFunc) (gint size,
                               gpointer user_data);

`HdyAvatarImageLoadFunc` has been deprecated since version 1.2 and should not be used in newly-written code.

use `hdy_avatar_set_loadable_icon()` instead.

The returned GdkPixbuf is expected to be square with width and height set to `size` . The image is cropped to a circle without any scaling or transformation.

#### Parameters

size | the required size of the avatar |
user_data | user data. | [closure]

#### Returns

the GdkPixbuf to use as a custom avatar or `NULL` to fallback to the generated avatar.

[nullable][transfer full]

### hdy_avatar_new ()

    GtkWidget *
    hdy_avatar_new (gint size,
                    const gchar *text,
                    gboolean show_initials);

Creates a new HdyAvatar.

#### Parameters

size | The size of the avatar |
text | The text used to generate the color and initials if `show_initials` is `TRUE`. The color is selected at random if `text` is empty. | [nullable]
show_initials | whether to show the initials or the fallback icon on top of the color generated based on `text` . |

#### Returns

the newly created HdyAvatar

### hdy_avatar_get_icon_name ()

    const gchar *
    hdy_avatar_get_icon_name (HdyAvatar *self);

Gets the name of the icon in the icon theme to use when the icon should be displayed.

#### Parameters

self | a HdyAvatar |

#### Returns

the name of the icon from the icon theme.

[nullable][transfer none]

Since: 1.0

### hdy_avatar_set_icon_name ()

    void
    hdy_avatar_set_icon_name (HdyAvatar *self,
                              const gchar *icon_name);

Sets the name of the icon in the icon theme to use when the icon should be displayed. If no name is set, the avatar-default-symbolic icon will be used. If the name doesn't match a valid icon, it is an error and no icon will be displayed. If the icon theme is changed, the image will be updated automatically.

#### Parameters

self | a HdyAvatar |
icon_name | the name of the icon from the icon theme. | [nullable]

Since: 1.0

### hdy_avatar_get_text ()

    const gchar *
    hdy_avatar_get_text (HdyAvatar *self);

Get the text used to generate the fallback initials and color

#### Parameters

self | a HdyAvatar |

#### Returns

returns the text used to generate the fallback initials. This is the internal string used by the HdyAvatar, and must not be modified.

[nullable][transfer none]

### hdy_avatar_set_text ()

    void
    hdy_avatar_set_text (HdyAvatar *self,
                         const gchar *text);

Set the text used to generate the fallback initials color

#### Parameters

self | a HdyAvatar |
text | the text used to get the initials and color. | [nullable]

### hdy_avatar_get_show_initials ()

    gboolean
    hdy_avatar_get_show_initials (HdyAvatar *self);

Returns whether initials are used for the fallback or the icon.

#### Parameters

self | a HdyAvatar |

#### Returns

`TRUE` if the initials are used for the fallback.

### hdy_avatar_set_show_initials ()

    void
    hdy_avatar_set_show_initials (HdyAvatar *self,
                                  gboolean show_initials);

Sets whether the initials should be shown on the fallback avatar or the icon.

#### Parameters

self | a HdyAvatar |
show_initials | whether the initials should be shown on the fallback avatar or the icon. |

### hdy_avatar_set_image_load_func ()

    void
    hdy_avatar_set_image_load_func (HdyAvatar *self,
                                    HdyAvatarImageLoadFunc load_image,
                                    gpointer user_data,
                                    GDestroyNotify destroy);

`hdy_avatar_set_image_load_func` has been deprecated since version 1.2 and should not be used in newly-written code.

use `hdy_avatar_set_loadable_icon()` instead.

A callback which is called when the custom image need to be reloaded for some reason (e.g. scale-factor changes).

#### Parameters

self | a HdyAvatar |
load_image | callback to set a custom image. | [closure user_data][nullable]
user_data | user data passed to `load_image` . | [nullable]
destroy | destroy notifier for `user_data` . | [nullable]

### hdy_avatar_get_size ()

    gint
    hdy_avatar_get_size (HdyAvatar *self);

Returns the size of the avatar.

#### Parameters

self | a HdyAvatar |

#### Returns

the size of the avatar.

### hdy_avatar_set_size ()

    void
    hdy_avatar_set_size (HdyAvatar *self,
                         gint size);

Sets the size of the avatar.

#### Parameters

self | a HdyAvatar |
size | The size to be used for the avatar |

### hdy_avatar_draw_to_pixbuf ()

    GdkPixbuf *
    hdy_avatar_draw_to_pixbuf (HdyAvatar *self,
                               gint size,
                               gint scale_factor);

Renders `self` into a pixbuf at `size` and `scale_factor` . This can be used to export the fallback avatar.

#### Parameters

self | a HdyAvatar |
size | The size of the pixbuf |
scale_factor | The scale factor |

#### Returns

the pixbuf.

[transfer full]

Since: 1.2

### hdy_avatar_draw_to_pixbuf_async ()

    void
    hdy_avatar_draw_to_pixbuf_async (HdyAvatar *self,
                                     gint size,
                                     gint scale_factor,
                                     GCancellable *cancellable,
                                     GAsyncReadyCallback callback,
                                     gpointer user_data);

Renders asynchronously `self` into a pixbuf at `size` and `scale_factor` . This can be used to export the fallback avatar.

#### Parameters

self | a HdyAvatar |
size | The size of the pixbuf |
scale_factor | The scale factor |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
callback | a GAsyncReadyCallback to call when the avatar is generated. | [scope async]
user_data | the data to pass to callback function. | [closure]

Since: 1.2

### hdy_avatar_draw_to_pixbuf_finish ()

    GdkPixbuf *
    hdy_avatar_draw_to_pixbuf_finish (HdyAvatar *self,
                                      GAsyncResult *async_result);

Finishes an asynchronous draw of an avatar to a pixbuf.

#### Parameters

self | a HdyAvatar |
async_result | a GAsyncResult |

#### Returns

a GdkPixbuf.

[transfer full]

Since: 1.2

### hdy_avatar_get_loadable_icon ()

    GLoadableIcon *
    hdy_avatar_get_loadable_icon (HdyAvatar *self);

Gets the GLoadableIcon set via `hdy_avatar_set_loadable_icon()`.

#### Parameters

self | a HdyAvatar |

#### Returns

the GLoadableIcon.

[nullable][transfer none]

Since: 1.2

### hdy_avatar_set_loadable_icon ()

    void
    hdy_avatar_set_loadable_icon (HdyAvatar *self,
                                  GLoadableIcon *icon);

Sets the GLoadableIcon to use as an avatar. The previous avatar is displayed till the new avatar is loaded, to immediately remove the custom avatar set the loadable-icon to `NULL`.

The GLoadableIcon set via this function is prefered over a set HdyAvatarImageLoadFunc.

#### Parameters

self | a HdyAvatar |
icon | a GLoadableIcon. | [nullable]

Since: 1.2

## Types and Values

### HDY_TYPE_AVATAR

    #define HDY_TYPE_AVATAR (hdy_avatar_get_type())

### HdyAvatar

    typedef struct _HdyAvatar HdyAvatar;

## Property Details

### The `“icon-name”` property

      “icon-name”                char *

The name of the icon in the icon theme to use when the icon should be displayed. If no name is set, the avatar-default-symbolic icon will be used. If the name doesn't match a valid icon, it is an error and no icon will be displayed. If the icon theme is changed, the image will be updated automatically.

Owner: HdyAvatar

Flags: Read / Write

Default value: NULL

Since: 1.0

### The `“loadable-icon”` property

      “loadable-icon”            GLoadableIcon *

A GLoadableIcon used to load the avatar.

Owner: HdyAvatar

Flags: Read / Write

Since: 1.2

### The `“show-initials”` property

      “show-initials”            gboolean

Whether to show the initials.

Owner: HdyAvatar

Flags: Read / Write

Default value: FALSE

### The `“size”` property

      “size”                     int

The avatar size of the avatar.

Owner: HdyAvatar

Flags: Read / Write

Allowed values: >= -1

Default value: -1

### The `“text”` property

      “text”                     char *

The text used for the initials and for generating the color. If “show-initials” is `FALSE` it's only used to generate the color.

Owner: HdyAvatar

Flags: Read / Write

Default value: NULL