GTK+ Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GtkFontSelectionDialog

## Name

GtkFontSelectionDialog -- a dialog box for selecting fonts.

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkFontSelectionDialog;
    GtkWidget*  gtk_font_selection_dialog_new   (const gchar *title);
    GdkFont*    gtk_font_selection_dialog_get_font
                                                (GtkFontSelectionDialog *fsd);
    gchar*      gtk_font_selection_dialog_get_font_name
                                                (GtkFontSelectionDialog *fsd);
    gboolean    gtk_font_selection_dialog_set_font_name
                                                (GtkFontSelectionDialog *fsd,
                                                 const gchar *fontname);
    gchar*      gtk_font_selection_dialog_get_preview_text
                                                (GtkFontSelectionDialog *fsd);
    void        gtk_font_selection_dialog_set_preview_text
                                                (GtkFontSelectionDialog *fsd,
                                                 const gchar *text);
    void        gtk_font_selection_dialog_set_filter
                                                (GtkFontSelectionDialog *fsd,
                                                 GtkFontFilterType filter_type,
                                                 GtkFontType font_type,
                                                 gchar **foundries,
                                                 gchar **weights,
                                                 gchar **slants,
                                                 gchar **setwidths,
                                                 gchar **spacings,
                                                 gchar **charsets);
    enum        GtkFontType;
    enum        GtkFontFilterType;

## Object Hierarchy

      GtkObject
       +----GtkWidget
             +----GtkContainer
                   +----GtkBin
                         +----GtkWindow
                               +----GtkFontSelectionDialog

## Description

The GtkFontSelectionDialog widget is a dialog box for selecting a font.

To set the font which is initially selected, use gtk_font_selection_dialog_set_font_name().

To get the selected font use gtk_font_selection_dialog_get_font() or gtk_font_selection_dialog_get_font_name().

To change the text which is shown in the preview area, use gtk_font_selection_dialog_set_preview_text().

Filters can be used to limit the fonts shown. There are 2 filters in the GtkFontSelectionDialog - a base filter and a user filter. The base filter can not be changed by the user, so this can be used when the user must choose from the restricted set of fonts (e.g. for a terminal-type application you may want to force the user to select a fixed-width font). The user filter can be changed or reset by the user, by using the 'Reset Filter' button or changing the options on the 'Filter' page of the dialog.

Example 1. Setting a filter to show only fixed-width fonts.

      gchar *spacings[] = { "c", "m", NULL };
      gtk_font_selection_dialog_set_filter (GTK_FONT_SELECTION_DIALOG (fontsel),
    				       GTK_FONT_FILTER_BASE, GTK_FONT_ALL,
    				       NULL, NULL, NULL, NULL, spacings, NULL);

To allow only true scalable fonts to be selected use:

Example 2. Setting a filter to show only true scalable fonts.

      gtk_font_selection_dialog_set_filter (GTK_FONT_SELECTION_DIALOG (fontsel),
    				       GTK_FONT_FILTER_BASE, GTK_FONT_SCALABLE,
    				       NULL, NULL, NULL, NULL, NULL, NULL);

## Details

### struct GtkFontSelectionDialog

    struct GtkFontSelectionDialog;

The GtkFontSelectionDialog struct contains private data only, and should only be accessed using the functions below.

### gtk_font_selection_dialog_new ()

    GtkWidget*  gtk_font_selection_dialog_new   (const gchar *title);

Creates a new GtkFontSelectionDialog.

`title` : | the title of the dialog box.
Returns : | a new GtkFontSelectionDialog.

### gtk_font_selection_dialog_get_font ()

    GdkFont*    gtk_font_selection_dialog_get_font
                                                (GtkFontSelectionDialog *fsd);

Gets the currently-selected font.

`fsd` : | a GtkFontSelectionDialog.
Returns : | the currently-selected font, or NULL if no font is selected.

### gtk_font_selection_dialog_get_font_name ()

    gchar*      gtk_font_selection_dialog_get_font_name
                                                (GtkFontSelectionDialog *fsd);

Gets the currently-selected font name.

`fsd` : | a GtkFontSelectionDialog.
Returns : | the currently-selected font name, or NULL if no font is selected.

### gtk_font_selection_dialog_set_font_name ()

    gboolean    gtk_font_selection_dialog_set_font_name
                                                (GtkFontSelectionDialog *fsd,
                                                 const gchar *fontname);

Sets the currently-selected font.

`fsd` : | a GtkFontSelectionDialog.
`fontname` : | a fontname.
Returns : | TRUE if the font was found.

### gtk_font_selection_dialog_get_preview_text ()

    gchar*      gtk_font_selection_dialog_get_preview_text
                                                (GtkFontSelectionDialog *fsd);

Gets the text displayed in the preview area.

`fsd` : | a GtkFontSelectionDialog.
Returns : | the text displayed in the preview area.

### gtk_font_selection_dialog_set_preview_text ()

    void        gtk_font_selection_dialog_set_preview_text
                                                (GtkFontSelectionDialog *fsd,
                                                 const gchar *text);

Sets the text displayed in the preview area.

`fsd` : | a GtkFontSelectionDialog.
`text` : | the text to display in the preview area.

### gtk_font_selection_dialog_set_filter ()

    void        gtk_font_selection_dialog_set_filter
                                                (GtkFontSelectionDialog *fsd,
                                                 GtkFontFilterType filter_type,
                                                 GtkFontType font_type,
                                                 gchar **foundries,
                                                 gchar **weights,
                                                 gchar **slants,
                                                 gchar **setwidths,
                                                 gchar **spacings,
                                                 gchar **charsets);

Sets one of the two font filters, to limit the fonts shown.

`fsd` : | a GtkFontSelectionDialog.
`filter_type` : | which of the two font filters to set, either GTK_FONT_FILTER_BASE or GTK_FONT_FILTER_USER. The user filter can be changed by the user, but the base filter is permanent.
`font_type` : | the types of font to be shown. This is a bitwise combination of GTK_FONT_BITMAP, GTK_FONT_SCALABLE and GTK_FONT_SCALABLE_BITMAP, or GTK_FONT_ALL to show all three font types.
`foundries` : | a NULL-terminated array of strings containing foundry names which will be shown, or NULL to show all foundries.
`weights` : | a NULL-terminated array of strings containing weight names which will be shown, or NULL to show all weights.
`slants` : | a NULL-terminated array of strings containing slant names which will be shown, or NULL to show all slants.
`setwidths` : | a NULL-terminated array of strings containing setwidth names which will be shown, or NULL to show all setwidths.
`spacings` : | a NULL-terminated array of strings containing spacings which will be shown, or NULL to show all spacings.
`charsets` : | a NULL-terminated array of strings containing charset names which will be shown, or NULL to show all charsets.

### enum GtkFontType

    typedef enum
    {
      GTK_FONT_BITMAP		= 1 << 0,
      GTK_FONT_SCALABLE		= 1 << 1,
      GTK_FONT_SCALABLE_BITMAP	= 1 << 2,

      GTK_FONT_ALL			= 0x07
    } GtkFontType;

A set of bit flags used to specify the type of fonts shown when calling gtk_font_selection_dialog_set_filter() or gtk_font_selection_set_filter().

`GTK_FONT_BITMAP` | bitmap fonts.
`GTK_FONT_SCALABLE` | scalable fonts.
`GTK_FONT_SCALABLE_BITMAP` | scaled bitmap fonts.
`GTK_FONT_ALL` | a bitwise combination of all of the above.

### enum GtkFontFilterType

    typedef enum
    {
      GTK_FONT_FILTER_BASE,
      GTK_FONT_FILTER_USER
    } GtkFontFilterType;

A set of bit flags used to specify the filter being set when calling gtk_font_selection_dialog_set_filter() or gtk_font_selection_set_filter().

`GTK_FONT_FILTER_BASE` | the base filter, which can't be changed by the user.
`GTK_FONT_FILTER_USER` | the user filter, which can be changed from within the 'Filter' page of the GtkFontSelection widget.

## See Also

GtkFontSelection

  the underlying widget for selecting fonts.

<<< Previous Page | Home | Up | Next Page >>>
GtkFontSelection | GtkFrame