GtkFontPickerButton

[Matthias Clasen <maclas gmx de>]

Proposal: GtkFontPickerButton
==============================

http://bugzilla.gnome.org/show_bug.cgi?id=107682

This is a clone of the GnomeFontPicker widget currently found in
libgnomeui. To cite its documentation:

The GtkFontPickerButton widget is a simple font picker in a button.
It displays the name and (optionally) size of the currently selected 
font.  When the user clicks on the button, a font selection dialog
pops up. The font picker emits the "font_set" signal when the font is set.

I have made the following changes to the GnomeFontPicker while moving
it to the Gtk namespace:

* adjust the API to GTK conventions: getters for all setters; add 
  notification for properties

* simplify by removing the different modes and hardwire the font_info
  mode behaviour of GnomeFontPicker (all uses of GnomeFontPicker which 
  I could find used that mode)

* remove deprecated GdkFont support

* append "Button" to the widget name to prevent confusion between 
  GtkFontSelection and GtkFontPicker


API details
===========

/**
 * gtk_font_picker_button_new:
 *
 * Creates a new font picker widget.
 *
 * Returns: a new font picker widget.
 */

GtkWidget *
gtk_font_picker_button_new (void)

/**
 * gtk_font_picker_button_set_title:
 * @gfp: a #GtkFontPickerButton
 * @title: a string containing the font selection dialog title
 *
 * Sets the title for the font selection dialog.  If @title is %NULL,
 * then the default is used.
 */
void
gtk_font_picker_button_set_title (GtkFontPickerButton *gfp, 
                                  const gchar         *title)


/**
 * gtk_font_picker_button_get_title:
 * @gfp: a #GtkFontPickerButton
 *
 * Retrieves name of the font selection dialog title.
 *
 * Returns: an internal copy of the title string which must not be freed.
 */
G_CONST_RETURN gchar*
gtk_font_picker_button_get_title (GtkFontPickerButton *gfp)

/**
 * gtk_font_picker_button_get_use_font_in_label:
 * @gfp: a #GtkFontPickerButton
 *
 * Returns whether the selected font is used in the label.
 *
 * Returns: whether the selected font is used in the label.
 */

gboolean
gtk_font_picker_button_get_use_font_in_label (GtkFontPickerButton *gfp)

/**
 * gtk_font_picker_button_get_label_font_size:
 * @gfp: a #GtkFontPickerButton
 *
 * Returns the font size to be used for the label.
 *
 * Returns: the font size to be used for the label.
 */
gint
gtk_font_picker_button_get_label_font_size (GtkFontPickerButton *gfp)

/**
 * gtk_font_picker_button_set_use_font_in_label:
 * @gfp: a #GtkFontPickerButton
 * @use_font_in_label: If %TRUE, font name will be written using font chosen.
 * @size: Display font using this point size.
 *
 * If @use_font_in_label is %TRUE, font name will be written using font chosen
 * by user and using @size passed to this function.  
 */
void  gtk_font_picker_button_set_use_font_in_label (GtkFontPickerButton *gfp,
                                                    gboolean use_font_in_label,
                                                    gint size)

/**
 * gtk_font_picker_button_get_show_size:
 * @gfp: a #GtkFontPickerButton
 * 
 * Returns whether the font size will be shown in the label.
 * 
 * Return value: whether the font size will be shown in the label.
 **/
gboolean 
gtk_font_picker_button_get_show_size (GtkFontPickerButton *gfp)

/**
 * gtk_font_picker_button_set_show_size:
 * @gfp: a #GtkFontPickerButton
 * @show_size: %TRUE if font size should be displayed in dialog.
 *
 * If @show_size is %TRUE, font size will be displayed along with font chosen
 * by user.  
 */
void
gtk_font_picker_button_set_show_size (GtkFontPickerButton *gfp,
                                      gboolean             show_size)

/**
 * gtk_font_picker_button_get_font_name:
 * @gfp: a #GtkFontPickerButton
 *
 * Retrieves name of font from font selection dialog.
 *
 * Returns: an internal copy of the font name, must not be freed.
 */
const gchar *gtk_font_picker_button_get_font_name (GtkFontPickerButton *gfp)

/**
 * gtk_font_picker_button_set_font_name:
 * @gfp: a #GtkFontPickerButton
 * @fontname: Name of font to display in font selection dialog
 *
 * Sets or updates the currently-displayed font in font picker dialog.
 *
 * Returns: Return value of gtk_font_selection_dialog_set_font_name() if the
 * font selection dialog exists, otherwise %FALSE.
 */

gboolean gtk_font_picker_button_set_font_name (GtkFontPickerButton *gfp,
                                               const gchar         *fontname)

/**
 * gtk_font_picker_button_get_preview_text:
 * @gfp: a #GtkFontPickerButton
 *
 * Retrieves preview text from font selection dialog if available.
 *
 * Returns: an internal copy of preview text string, or %NULL if no
 * font dialog is being displayed.
 */
const gchar *gtk_font_picker_button_get_preview_text (GtkFontPickerButton *gfp)

/**
 * gtk_font_picker_button_set_preview_text:
 * @gfp: a #GtkFontPickerButton
 * @text: New preview text
 *
 * Sets the preview text in the font picker, and in the font selection dialog if one
 * is being displayed.
 */
void gtk_font_picker_button_set_preview_text (GtkFontPickerButton *gfp,
                                              const gchar         *text)