DzlSuggestion: Dazzle Reference Manual

## DzlSuggestion DzlSuggestion |

## Functions

DzlSuggestion * | dzl_suggestion_new ()
const gchar * | dzl_suggestion_get_id ()
void | dzl_suggestion_set_id ()
const gchar * | dzl_suggestion_get_icon_name ()
void | dzl_suggestion_set_icon_name ()
const gchar * | dzl_suggestion_get_title ()
void | dzl_suggestion_set_title ()
const gchar * | dzl_suggestion_get_subtitle ()
void | dzl_suggestion_set_subtitle ()
gchar * | dzl_suggestion_suggest_suffix ()
gchar * | dzl_suggestion_replace_typed_text ()
GIcon * | dzl_suggestion_get_icon ()
cairo_surface_t * | dzl_suggestion_get_icon_surface ()
const gchar * | dzl_suggestion_get_secondary_icon_name ()
void | dzl_suggestion_set_secondary_icon_name ()
GIcon * | dzl_suggestion_get_secondary_icon ()
cairo_surface_t * | dzl_suggestion_get_secondary_icon_surface ()

## Properties

GIcon * | icon | Read
char * | icon-name | Read / Write
char * | id | Read / Write
GIcon * | secondary-icon | Read
char * | secondary-icon-name | Read / Write
char * | subtitle | Read / Write
char * | title | Read / Write

## Signals

char* | replace-typed-text | Run Last
char* | suggest-suffix | Run Last

## Types and Values

#define | DZL_TYPE_SUGGESTION
struct | DzlSuggestionClass
| DzlSuggestion

## Object Hierarchy

        GObject
        ╰── DzlSuggestion

## Description

## Functions

### dzl_suggestion_new ()

    DzlSuggestion *
    dzl_suggestion_new (void);

### dzl_suggestion_get_id ()

    const gchar *
    dzl_suggestion_get_id (DzlSuggestion *self);

### dzl_suggestion_set_id ()

    void
    dzl_suggestion_set_id (DzlSuggestion *self,
                           const gchar *id);

### dzl_suggestion_get_icon_name ()

    const gchar *
    dzl_suggestion_get_icon_name (DzlSuggestion *self);

### dzl_suggestion_set_icon_name ()

    void
    dzl_suggestion_set_icon_name (DzlSuggestion *self,
                                  const gchar *icon_name);

### dzl_suggestion_get_title ()

    const gchar *
    dzl_suggestion_get_title (DzlSuggestion *self);

### dzl_suggestion_set_title ()

    void
    dzl_suggestion_set_title (DzlSuggestion *self,
                              const gchar *title);

### dzl_suggestion_get_subtitle ()

    const gchar *
    dzl_suggestion_get_subtitle (DzlSuggestion *self);

### dzl_suggestion_set_subtitle ()

    void
    dzl_suggestion_set_subtitle (DzlSuggestion *self,
                                 const gchar *subtitle);

### dzl_suggestion_suggest_suffix ()

    gchar *
    dzl_suggestion_suggest_suffix (DzlSuggestion *self,
                                   const gchar *typed_text);

This function requests potential text to append to `typed_text` to make it more clear to the user what they will be activating by selecting this suggestion. For example, if they start typing "gno", a potential suggested suffix might be "me.org" to create "gnome.org".

#### Parameters

self | a DzlSuggestion |
typed_text | The user entered text |

#### Returns

Suffix to append to `typed_text` or `NULL` to leave it unchanged.

[transfer full][nullable]

### dzl_suggestion_replace_typed_text ()

    gchar *
    dzl_suggestion_replace_typed_text (DzlSuggestion *self,
                                       const gchar *typed_text);

This function is meant to be used to replace the text in the entry with text that represents the suggestion most accurately. This happens when the user presses tab while typing a suggestion. For example, if typing "gno" in the entry, you might have a suggest_suffix of "me.org" so that the user sees "gnome.org". But the replace_typed_text might include more data such as "https://gnome.org" as it more closely represents the suggestion.

#### Parameters

self | An DzlSuggestion |
typed_text | the text that was typed into the entry |

#### Returns

The replacement text to insert into the entry when "tab" is pressed to complete the insertion.

[transfer full][nullable]

### dzl_suggestion_get_icon ()

    GIcon *
    dzl_suggestion_get_icon (DzlSuggestion *self);

Gets the icon for the suggestion, if any.

#### Parameters

self | a DzlSuggestion |

#### Returns

a GIcon or `NULL`.

[transfer full][nullable]

Since: 3.30

### dzl_suggestion_get_icon_surface ()

    cairo_surface_t *
    dzl_suggestion_get_icon_surface (DzlSuggestion *self,
                                     GtkWidget *widget);

This function allows subclasses to dynamicly generate content for the suggestion such as may be required when integrating with favicons or similar.

`widget` is provided so that the implementation may determine scale or any other style-specific settings from the style context.

#### Parameters

self | a DzlSuggestion |
widget | a widget that may contain the surface |

#### Returns

a cairo_surface_t or `NULL`.

[transfer full][nullable]

Since: 3.30

### dzl_suggestion_get_secondary_icon_name ()

    const gchar *
    dzl_suggestion_get_secondary_icon_name
                                   (DzlSuggestion *self);

### dzl_suggestion_set_secondary_icon_name ()

    void
    dzl_suggestion_set_secondary_icon_name
                                   (DzlSuggestion *self,
                                    const gchar *icon_name);

### dzl_suggestion_get_secondary_icon ()

    GIcon *
    dzl_suggestion_get_secondary_icon (DzlSuggestion *self);

Gets the secondary icon for the suggestion, if any.

#### Parameters

self | a DzlSuggestion |

#### Returns

a GIcon or `NULL`.

[transfer full][nullable]

Since: 3.36

### dzl_suggestion_get_secondary_icon_surface ()

    cairo_surface_t *
    dzl_suggestion_get_secondary_icon_surface
                                   (DzlSuggestion *self,
                                    GtkWidget *widget);

This function allows subclasses to dynamicly generate content for the suggestion such as may be required when integrating with favicons or similar.

`widget` is provided so that the implementation may determine scale or any other style-specific settings from the style context.

#### Parameters

self | a DzlSuggestion |
widget | a widget that may contain the surface |

#### Returns

a cairo_surface_t or `NULL`.

[transfer full][nullable]

Since: 3.36

## Types and Values

### DZL_TYPE_SUGGESTION

    #define DZL_TYPE_SUGGESTION (dzl_suggestion_get_type())

### struct DzlSuggestionClass

    struct DzlSuggestionClass {
      GObjectClass parent_class;

      gchar           *(*suggest_suffix)     (DzlSuggestion *self,
                                              const gchar   *typed_text);
      gchar           *(*replace_typed_text) (DzlSuggestion *self,
                                              const gchar   *typed_text);
      GIcon           *(*get_icon)           (DzlSuggestion *self);
      cairo_surface_t *(*get_icon_surface)   (DzlSuggestion *self,
                                              GtkWidget     *widget);
      GIcon           *(*get_secondary_icon) (DzlSuggestion *self);
      cairo_surface_t *(*get_secondary_icon_surface)   (DzlSuggestion *self,
                                                        GtkWidget     *widget);
    };

### DzlSuggestion

    typedef struct _DzlSuggestion DzlSuggestion;

## Property Details

### The `“icon”` property

      “icon”                     GIcon *

The GIcon for the suggestion.

Owner: DzlSuggestion

Flags: Read

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

      “icon-name”                char *

The name of the icon to display.

Owner: DzlSuggestion

Flags: Read / Write

Default value: NULL

### The `“id”` property

      “id”                       char *

The suggestion identifier.

Owner: DzlSuggestion

Flags: Read / Write

Default value: NULL

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

      “secondary-icon”           GIcon *

The secondary GIcon for the suggestion on the right.

Owner: DzlSuggestion

Flags: Read

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

      “secondary-icon-name”      char *

The name of the secondary icon to display.

Owner: DzlSuggestion

Flags: Read / Write

Default value: NULL

### The `“subtitle”` property

      “subtitle”                 char *

The subtitle of the suggestion.

Owner: DzlSuggestion

Flags: Read / Write

Default value: NULL

### The `“title”` property

      “title”                    char *

The title of the suggestion.

Owner: DzlSuggestion

Flags: Read / Write

Default value: NULL

## Signal Details

### The `“replace-typed-text”` signal

    char*
    user_function (DzlSuggestion *dzlsuggestion,
                   char          *arg1,
                   gpointer       user_data)

Flags: Run Last

### The `“suggest-suffix”` signal

    char*
    user_function (DzlSuggestion *dzlsuggestion,
                   char          *arg1,
                   gpointer       user_data)

Flags: Run Last