HdyAvatar

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

Functions

Properties

gchar * icon-name Read / Write
gboolean show-initials Read / Write
gint size Read / Write
gchar * text Read / Write

Types and Values

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”                gchar *

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.

Flags: Read / Write

Default value: NULL

Since: 1.0


The “show-initials” property

  “show-initials”            gboolean

Whether to show the initials.

Flags: Read / Write

Default value: FALSE


The “size” property

  “size”                     gint

The avatar size of the avatar.

Flags: Read / Write

Allowed values: >= -1

Default value: -1


The “text” property

  “text”                     gchar *

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

Flags: Read / Write

Default value: NULL