GtkFontChooser: GTK+ 3 Reference Manual

## GtkFontChooser GtkFontChooser — Interface implemented by widgets displaying fonts |

## Functions

PangoFontFamily * | gtk_font_chooser_get_font_family ()
PangoFontFace * | gtk_font_chooser_get_font_face ()
gint | gtk_font_chooser_get_font_size ()
gchar * | gtk_font_chooser_get_font ()
void | gtk_font_chooser_set_font ()
PangoFontDescription * | gtk_font_chooser_get_font_desc ()
void | gtk_font_chooser_set_font_desc ()
gchar * | gtk_font_chooser_get_preview_text ()
void | gtk_font_chooser_set_preview_text ()
gboolean | gtk_font_chooser_get_show_preview_entry ()
void | gtk_font_chooser_set_show_preview_entry ()
gboolean | (*GtkFontFilterFunc) ()
void | gtk_font_chooser_set_filter_func ()
void | gtk_font_chooser_set_font_map ()
PangoFontMap * | gtk_font_chooser_get_font_map ()

## Properties

gchar * | font | Read / Write
PangoFontDescription * | font-desc | Read / Write
gchar * | preview-text | Read / Write
gboolean | show-preview-entry | Read / Write

## Signals

void | font-activated | Run First

## Types and Values

| GtkFontChooser

## Object Hierarchy

        GInterface
        ╰── GtkFontChooser

## Prerequisites

GtkFontChooser requires GObject.

## Known Implementations

GtkFontChooser is implemented by GtkFontButton, GtkFontChooserDialog and GtkFontChooserWidget.

## Includes

    #include <gtk/gtk.h>

## Description

GtkFontChooser is an interface that can be implemented by widgets displaying the list of fonts. In GTK+, the main objects that implement this interface are GtkFontChooserWidget, GtkFontChooserDialog and GtkFontButton. The GtkFontChooser interface has been introducted in GTK+ 3.2.

## Functions

### gtk_font_chooser_get_font_family ()

    PangoFontFamily *
    gtk_font_chooser_get_font_family (GtkFontChooser *fontchooser);

Gets the PangoFontFamily representing the selected font family. Font families are a collection of font faces.

If the selected font is not installed, returns `NULL`.

#### Parameters

fontchooser | a GtkFontChooser |

#### Returns

A PangoFontFamily representing the selected font family, or `NULL`. The returned object is owned by `fontchooser` and must not be modified or freed.

[nullable][transfer none]

Since: 3.2

### gtk_font_chooser_get_font_face ()

    PangoFontFace *
    gtk_font_chooser_get_font_face (GtkFontChooser *fontchooser);

Gets the PangoFontFace representing the selected font group details (i.e. family, slant, weight, width, etc).

If the selected font is not installed, returns `NULL`.

#### Parameters

fontchooser | a GtkFontChooser |

#### Returns

A PangoFontFace representing the selected font group details, or `NULL`. The returned object is owned by `fontchooser` and must not be modified or freed.

[nullable][transfer none]

Since: 3.2

### gtk_font_chooser_get_font_size ()

    gint
    gtk_font_chooser_get_font_size (GtkFontChooser *fontchooser);

The selected font size.

#### Parameters

fontchooser | a GtkFontChooser |

#### Returns

A n integer representing the selected font size, or -1 if no font size is selected.

Since: 3.2

### gtk_font_chooser_get_font ()

    gchar *
    gtk_font_chooser_get_font (GtkFontChooser *fontchooser);

Gets the currently-selected font name.

Note that this can be a different string than what you set with `gtk_font_chooser_set_font()`, as the font chooser widget may normalize font names and thus return a string with a different structure. For example, “Helvetica Italic Bold 12” could be normalized to “Helvetica Bold Italic 12”.

Use `pango_font_description_equal()` if you want to compare two font descriptions.

#### Parameters

fontchooser | a GtkFontChooser |

#### Returns

A string with the name of the current font, or `NULL` if no font is selected. You must free this string with `g_free()`.

[nullable][transfer full]

Since: 3.2

### gtk_font_chooser_set_font ()

    void
    gtk_font_chooser_set_font (GtkFontChooser *fontchooser,
                               const gchar *fontname);

Sets the currently-selected font.

#### Parameters

fontchooser | a GtkFontChooser |
fontname | a font name like “Helvetica 12” or “Times Bold 18” |

Since: 3.2

### gtk_font_chooser_get_font_desc ()

    PangoFontDescription *
    gtk_font_chooser_get_font_desc (GtkFontChooser *fontchooser);

Gets the currently-selected font.

Note that this can be a different string than what you set with `gtk_font_chooser_set_font()`, as the font chooser widget may normalize font names and thus return a string with a different structure. For example, “Helvetica Italic Bold 12” could be normalized to “Helvetica Bold Italic 12”.

Use `pango_font_description_equal()` if you want to compare two font descriptions.

#### Parameters

fontchooser | a GtkFontChooser |

#### Returns

A PangoFontDescription for the current font, or `NULL` if no font is selected.

[nullable][transfer full]

Since: 3.2

### gtk_font_chooser_set_font_desc ()

    void
    gtk_font_chooser_set_font_desc (GtkFontChooser *fontchooser,
                                    const PangoFontDescription *font_desc);

Sets the currently-selected font from `font_desc` .

#### Parameters

fontchooser | a GtkFontChooser |
font_desc | a PangoFontDescription |

Since: 3.2

### gtk_font_chooser_get_preview_text ()

    gchar *
    gtk_font_chooser_get_preview_text (GtkFontChooser *fontchooser);

Gets the text displayed in the preview area.

#### Parameters

fontchooser | a GtkFontChooser |

#### Returns

the text displayed in the preview area.

[transfer full]

Since: 3.2

### gtk_font_chooser_set_preview_text ()

    void
    gtk_font_chooser_set_preview_text (GtkFontChooser *fontchooser,
                                       const gchar *text);

Sets the text displayed in the preview area. The `text` is used to show how the selected font looks.

#### Parameters

fontchooser | a GtkFontChooser |
text | the text to display in the preview area. | [transfer none]

Since: 3.2

### gtk_font_chooser_get_show_preview_entry ()

    gboolean
    gtk_font_chooser_get_show_preview_entry
                                   (GtkFontChooser *fontchooser);

Returns whether the preview entry is shown or not.

#### Parameters

fontchooser | a GtkFontChooser |

#### Returns

`TRUE` if the preview entry is shown or `FALSE` if it is hidden.

Since: 3.2

### gtk_font_chooser_set_show_preview_entry ()

    void
    gtk_font_chooser_set_show_preview_entry
                                   (GtkFontChooser *fontchooser,
                                    gboolean show_preview_entry);

Shows or hides the editable preview entry.

#### Parameters

fontchooser | a GtkFontChooser |
show_preview_entry | whether to show the editable preview entry or not |

Since: 3.2

### GtkFontFilterFunc ()

    gboolean
    (*GtkFontFilterFunc) (const PangoFontFamily *family,
                          const PangoFontFace *face,
                          gpointer data);

The type of function that is used for deciding what fonts get shown in a GtkFontChooser. See `gtk_font_chooser_set_filter_func()`.

#### Parameters

family | a PangoFontFamily |
face | a PangoFontFace belonging to `family` |
data | user data passed to `gtk_font_chooser_set_filter_func()`. | [closure]

#### Returns

`TRUE` if the font should be displayed

### gtk_font_chooser_set_filter_func ()

    void
    gtk_font_chooser_set_filter_func (GtkFontChooser *fontchooser,
                                      GtkFontFilterFunc filter,
                                      gpointer user_data,
                                      GDestroyNotify destroy);

Adds a filter function that decides which fonts to display in the font chooser.

#### Parameters

fontchooser | a GtkFontChooser |
filter | a GtkFontFilterFunc, or `NULL`. | [allow-none]
user_data | data to pass to `filter` |
destroy | function to call to free `data` when it is no longer needed |

Since: 3.2

### gtk_font_chooser_set_font_map ()

    void
    gtk_font_chooser_set_font_map (GtkFontChooser *fontchooser,
                                   PangoFontMap *fontmap);

Sets a custom font map to use for this font chooser widget. A custom font map can be used to present application-specific fonts instead of or in addition to the normal system fonts.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    FcConfig *config;
    PangoFontMap *fontmap;

    config = FcInitLoadConfigAndFonts ();
    FcConfigAppFontAddFile (config, my_app_font_file);

    fontmap = pango_cairo_font_map_new_for_font_type (CAIRO_FONT_TYPE_FT);
    pango_fc_font_map_set_config (PANGO_FC_FONT_MAP (fontmap), config);

    gtk_font_chooser_set_font_map (font_chooser, fontmap);

Note that other GTK+ widgets will only be able to use the application-specific font if it is present in the font map they use:

    1
    2
    context = gtk_widget_get_pango_context (label);
    pango_context_set_font_map (context, fontmap);

#### Parameters

fontchooser | a GtkFontChooser |
fontmap | a PangoFontMap. | [allow-none]

Since: 3.18

### gtk_font_chooser_get_font_map ()

    PangoFontMap *
    gtk_font_chooser_get_font_map (GtkFontChooser *fontchooser);

Gets the custom font map of this font chooser widget, or `NULL` if it does not have one.

#### Parameters

fontchooser | a GtkFontChooser |

#### Returns

a PangoFontMap, or `NULL`.

[nullable][transfer full]

Since: 3.18

## Types and Values

### GtkFontChooser

    typedef struct _GtkFontChooser GtkFontChooser;

## Property Details

### The `“font”` property

      “font”                     gchar *

The font description as a string, e.g. "Sans Italic 12".

Flags: Read / Write

Default value: "Sans 10"

### The `“font-desc”` property

      “font-desc”                PangoFontDescription *

The font description as a PangoFontDescription.

Flags: Read / Write

### The `“preview-text”` property

      “preview-text”             gchar *

The string with which to preview the font.

Flags: Read / Write

Default value: "The quick brown fox jumps over the lazy dog."

### The `“show-preview-entry”` property

      “show-preview-entry”       gboolean

Whether to show an entry to change the preview text.

Flags: Read / Write

Default value: TRUE

## Signal Details

### The `“font-activated”` signal

    void
    user_function (GtkFontChooser *self,
                   gchar          *fontname,
                   gpointer        user_data)

Emitted when a font is activated. This usually happens when the user double clicks an item, or an item is selected and the user presses one of the keys Space, Shift+Space, Return or Enter.

#### Parameters

self | the object which received the signal |
fontname | the font name |
user_data | user data set when the signal handler was connected. |

Flags: Run First

## See Also

GtkFontChooserDialog, GtkFontChooserWidget, GtkFontButton