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 ()

## Properties

char * | icon-name | 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_image_load_func()` to set a custom image. Create a HdyAvatarImageLoadFunc similar to this example:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    static GdkPixbuf *
    image_load_func (gint size, gpointer user_data)
    {
      g_autoptr (GError) error = NULL;
      g_autoptr (GdkPixbuf) pixbuf = NULL;
      g_autofree gchar *file = gtk_file_chooser_get_filename ("avatar.png");
      gint width, height;

      gdk_pixbuf_get_file_info (file, &width, &height);

      pixbuf = gdk_pixbuf_new_from_file_at_scale (file,
                                                 (width <= height) ? size : -1,
                                                 (width >= height) ? size : -1,
                                                 TRUE,
                                                 error);
      if (error != NULL) {
       g_critical ("Failed to create pixbuf from file: %s", error->message);

       return NULL;
      }

      return pixbuf;
    }

### CSS nodes

HdyAvatar has a single CSS node with name avatar.

## Functions

### HdyAvatarImageLoadFunc ()

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

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);

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 |

## 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 `“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