Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkfontseldlg.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkFontSelectionDialog
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 a dialog box for selecting fonts.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The #GtkFontSelectionDialog widget is a dialog box for selecting a font.
  10 </para>
  11 <para>
  12 To set the font which is initially selected, use
  13 gtk_font_selection_dialog_set_font_name().
  14 </para>
  15 <para>
  16 To get the selected font use gtk_font_selection_dialog_get_font()
  17 or gtk_font_selection_dialog_get_font_name().
  18 </para>
  19 <para>
  20 To change the text which is shown in the preview area, use
  21 gtk_font_selection_dialog_set_preview_text().
  22 </para>
  23 <para>
  24 Filters can be used to limit the fonts shown. There are 2 filters in the
  25 #GtkFontSelectionDialog - a base filter and a user filter. The base filter
  26 can not be changed by the user, so this can be used when the user must choose
  27 from the restricted set of fonts (e.g. for a terminal-type application you may
  28 want to force the user to select a fixed-width font). The user filter can be
  29 changed or reset by the user, by using the 'Reset Filter' button or changing
  30 the options on the 'Filter' page of the dialog.
  31 </para>
  32
  33 <example>
  34 <title>Setting a filter to show only fixed-width fonts.</title>
  35 <programlisting>
  36   gchar *spacings[] = { "c", "m", NULL };
  37   gtk_font_selection_dialog_set_filter (GTK_FONT_SELECTION_DIALOG (fontsel),
  38                                        GTK_FONT_FILTER_BASE, GTK_FONT_ALL,
  39                                        NULL, NULL, NULL, NULL, spacings, NULL);
  40 </programlisting>
  41 </example>
  42
  43 <para>
  44 To allow only true scalable fonts to be selected use:
  45 </para>
  46
  47 <example>
  48 <title>Setting a filter to show only true scalable fonts.</title>
  49 <programlisting>
  50   gtk_font_selection_dialog_set_filter (GTK_FONT_SELECTION_DIALOG (fontsel),
  51                                        GTK_FONT_FILTER_BASE, GTK_FONT_SCALABLE,
  52                                        NULL, NULL, NULL, NULL, NULL, NULL);
  53 </programlisting>
  54 </example>
  55
  56 <!-- ##### SECTION See_Also ##### -->
  57 <para>
  58 <variablelist>
  59
  60 <varlistentry>
  61 <term>#GtkFontSelection</term>
  62 <listitem><para>the underlying widget for selecting fonts.</para></listitem>
  63 </varlistentry>
  64
  65 </variablelist>
  66 </para>
  67
  68 <!-- ##### STRUCT GtkFontSelectionDialog ##### -->
  69 <para>
  70 The #GtkFontSelectionDialog struct contains private data only, and should
  71 only be accessed using the functions below.
  72 </para>
  73
  74
  75 <!-- ##### FUNCTION gtk_font_selection_dialog_new ##### -->
  76 <para>
  77 Creates a new #GtkFontSelectionDialog.
  78 </para>
  79
  80 @title: the title of the dialog box.
  81 @Returns: a new #GtkFontSelectionDialog.
  82
  83
  84 <!-- ##### FUNCTION gtk_font_selection_dialog_get_font ##### -->
  85 <para>
  86 Gets the currently-selected font.
  87 </para>
  88
  89 @fsd: a #GtkFontSelectionDialog.
  90 @Returns: the currently-selected font, or NULL if no font is selected.
  91
  92
  93 <!-- ##### FUNCTION gtk_font_selection_dialog_get_font_name ##### -->
  94 <para>
  95 Gets the currently-selected font name.
  96 </para>
  97
  98 @fsd: a #GtkFontSelectionDialog.
  99 @Returns: the currently-selected font name, or NULL if no font is selected.
 100
 101
 102 <!-- ##### FUNCTION gtk_font_selection_dialog_set_font_name ##### -->
 103 <para>
 104 Sets the currently-selected font.
 105 </para>
 106
 107 @fsd: a #GtkFontSelectionDialog.
 108 @fontname: a fontname.
 109 @Returns: TRUE if the font was found.
 110
 111
 112 <!-- ##### FUNCTION gtk_font_selection_dialog_get_preview_text ##### -->
 113 <para>
 114 Gets the text displayed in the preview area.
 115 </para>
 116
 117 @fsd: a #GtkFontSelectionDialog.
 118 @Returns: the text displayed in the preview area.
 119
 120
 121 <!-- ##### FUNCTION gtk_font_selection_dialog_set_preview_text ##### -->
 122 <para>
 123 Sets the text displayed in the preview area.
 124 </para>
 125
 126 @fsd: a #GtkFontSelectionDialog.
 127 @text: the text to display in the preview area.
 128
 129
 130 <!-- ##### FUNCTION gtk_font_selection_dialog_set_filter ##### -->
 131 <para>
 132 Sets one of the two font filters, to limit the fonts shown.
 133 </para>
 134
 135 @fsd: a #GtkFontSelectionDialog.
 136 @filter_type: which of the two font filters to set, either
 137 #GTK_FONT_FILTER_BASE or #GTK_FONT_FILTER_USER. The user filter
 138 can be changed by the user, but the base filter is permanent.
 139 @font_type: the types of font to be shown. This is a bitwise combination of
 140 #GTK_FONT_BITMAP, #GTK_FONT_SCALABLE and #GTK_FONT_SCALABLE_BITMAP,
 141 or #GTK_FONT_ALL to show all three font types.
 142 @foundries: a NULL-terminated array of strings containing foundry names which
 143 will be shown, or NULL to show all foundries.
 144 @weights: a NULL-terminated array of strings containing weight names which
 145 will be shown, or NULL to show all weights.
 146 @slants: a NULL-terminated array of strings containing slant names which
 147 will be shown, or NULL to show all slants.
 148 @setwidths: a NULL-terminated array of strings containing setwidth names which
 149 will be shown, or NULL to show all setwidths.
 150 @spacings: a NULL-terminated array of strings containing spacings which
 151 will be shown, or NULL to show all spacings.
 152 @charsets: a NULL-terminated array of strings containing charset names which
 153 will be shown, or NULL to show all charsets.
 154
 155
 156 <!-- ##### ENUM GtkFontType ##### -->
 157 <para>
 158 A set of bit flags used to specify the type of fonts shown
 159 when calling gtk_font_selection_dialog_set_filter() or
 160 gtk_font_selection_set_filter().
 161 </para>
 162
 163 @GTK_FONT_BITMAP: bitmap fonts.
 164 @GTK_FONT_SCALABLE: scalable fonts.
 165 @GTK_FONT_SCALABLE_BITMAP: scaled bitmap fonts.
 166 @GTK_FONT_ALL: a bitwise combination of all of the above.
 167
 168 <!-- ##### ENUM GtkFontFilterType ##### -->
 169 <para>
 170 A set of bit flags used to specify the filter being set
 171 when calling gtk_font_selection_dialog_set_filter() or
 172 gtk_font_selection_set_filter().
 173 </para>
 174
 175 @GTK_FONT_FILTER_BASE: the base filter, which can't be changed by the user.
 176 @GTK_FONT_FILTER_USER: the user filter, which can be changed from within the
 177 'Filter' page of the #GtkFontSelection widget.
 178