Check that the fontsel has a screen assigned before doing anything. This

2006-02-27  Federico Mena Quintero  <federico@novell.com>

	* gtk/gtkfontsel.c (gtk_font_selection_set_font_name): Check that
	the fontsel has a screen assigned before doing anything.  This
	will at least warn the caller of what is wrong, since we only
	populate the family_list until we get a screen.  Also, put the
	reference docs here.  Fixes bug #332756.
	(gtk_font_selection_dialog_get_font_name): Document this here.
	(gtk_font_selection_get_font_name): Document this here; mention
	that the font names get normalized, so the result of this function
	may not be the same as what you set with
	gtk_font_selection_set_font_name().

5 files changed, 78 insertions, 17 deletions

diff --git a/ChangeLog b/ChangeLog
index d85bcbdcb..066e0fdbf 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,16 @@
+2006-02-27  Federico Mena Quintero  <federico@novell.com>
+
+	* gtk/gtkfontsel.c (gtk_font_selection_set_font_name): Check that
+	the fontsel has a screen assigned before doing anything.  This
+	will at least warn the caller of what is wrong, since we only
+	populate the family_list until we get a screen.  Also, put the
+	reference docs here.  Fixes bug #332756.
+	(gtk_font_selection_dialog_get_font_name): Document this here.
+	(gtk_font_selection_get_font_name): Document this here; mention
+	that the font names get normalized, so the result of this function
+	may not be the same as what you set with
+	gtk_font_selection_set_font_name().
+
 2006-02-27  Matthias Clasen  <mclasen@redhat.com>
 
 	* gtk/gtk.symbols:
diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10
index d85bcbdcb..066e0fdbf 100644
--- a/ChangeLog.pre-2-10
+++ b/ChangeLog.pre-2-10
@@ -1,3 +1,16 @@
+2006-02-27  Federico Mena Quintero  <federico@novell.com>
+
+	* gtk/gtkfontsel.c (gtk_font_selection_set_font_name): Check that
+	the fontsel has a screen assigned before doing anything.  This
+	will at least warn the caller of what is wrong, since we only
+	populate the family_list until we get a screen.  Also, put the
+	reference docs here.  Fixes bug #332756.
+	(gtk_font_selection_dialog_get_font_name): Document this here.
+	(gtk_font_selection_get_font_name): Document this here; mention
+	that the font names get normalized, so the result of this function
+	may not be the same as what you set with
+	gtk_font_selection_set_font_name().
+
 2006-02-27  Matthias Clasen  <mclasen@redhat.com>
 
 	* gtk/gtk.symbols:
diff --git a/docs/reference/gtk/tmpl/gtkfontsel.sgml b/docs/reference/gtk/tmpl/gtkfontsel.sgml
index 129b564b6..9ca01f6fe 100644
--- a/docs/reference/gtk/tmpl/gtkfontsel.sgml
+++ b/docs/reference/gtk/tmpl/gtkfontsel.sgml
@@ -16,8 +16,7 @@ To set the font which is initially selected, use
 gtk_font_selection_set_font_name().
 </para>
 <para>
-To get the selected font use gtk_font_selection_get_font()
-or gtk_font_selection_get_font_name().
+To get the selected font use gtk_font_selection_get_font_name().
 </para>
 <para>
 To change the text which is shown in the preview area, use
@@ -80,24 +79,19 @@ Gets the currently-selected font.
 
 <!-- ##### FUNCTION gtk_font_selection_get_font_name ##### -->
 <para>
-Gets the currently-selected font name.
 </para>
 
-@fontsel: a #GtkFontSelection.
-@Returns: the name of the currently selected font, or %NULL if
-    no font is selected.  You should g_free() the returned font name
-    after you are done with it.
-A newly allocated string with the currently-se
+@fontsel: 
+@Returns: 
 
 
 <!-- ##### FUNCTION gtk_font_selection_set_font_name ##### -->
 <para>
-Sets the currently-selected font.
 </para>
 
-@fontsel: a #GtkFontSelection.
-@fontname: a fontname.
-@Returns: %TRUE if the font was found.
+@fontsel:
+@fontname:
+@Returns: 
 
 
 <!-- ##### FUNCTION gtk_font_selection_get_preview_text ##### -->
diff --git a/docs/reference/gtk/tmpl/gtkfontseldlg.sgml b/docs/reference/gtk/tmpl/gtkfontseldlg.sgml
index cf89cf9fc..9afe5f60d 100644
--- a/docs/reference/gtk/tmpl/gtkfontseldlg.sgml
+++ b/docs/reference/gtk/tmpl/gtkfontseldlg.sgml
@@ -13,8 +13,7 @@ To set the font which is initially selected, use
 gtk_font_selection_dialog_set_font_name().
 </para>
 <para>
-To get the selected font use gtk_font_selection_dialog_get_font()
-or gtk_font_selection_dialog_get_font_name().
+To get the selected font use gtk_font_selection_dialog_get_font_name().
 </para>
 <para>
 To change the text which is shown in the preview area, use
@@ -67,11 +66,10 @@ Gets the currently-selected font.
 
 <!-- ##### FUNCTION gtk_font_selection_dialog_get_font_name ##### -->
 <para>
-Gets the currently-selected font name.
 </para>
 
-@fsd: a #GtkFontSelectionDialog.
-@Returns: the currently-selected font name, or %NULL if no font is selected.
+@fsd: 
+@Returns: 
 
 
 <!-- ##### FUNCTION gtk_font_selection_dialog_set_font_name ##### -->
diff --git a/gtk/gtkfontsel.c b/gtk/gtkfontsel.c
index 3f95b14a8..8b2a20b25 100644
--- a/gtk/gtkfontsel.c
+++ b/gtk/gtkfontsel.c
@@ -1167,6 +1167,20 @@ gtk_font_selection_get_font (GtkFontSelection *fontsel)
   return gtk_font_selection_get_font_internal (fontsel);
 }
 
+/**
+ * gtk_font_selection_get_font_name:
+ * @fontsel: a #GtkFontSelection
+ * 
+ * Gets the currently-selected font name.  Note that this can be a different
+ * string than what you set with gtk_font_selection_set_font_name(), as
+ * the font selection 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.
+ * 
+ * Return value: A string with the name of the current font, or #NULL if no font
+ * is selected.  You must free this string with g_free().
+ **/
 gchar *
 gtk_font_selection_get_font_name (GtkFontSelection *fontsel)
 {
@@ -1185,6 +1199,20 @@ gtk_font_selection_get_font_name (GtkFontSelection *fontsel)
    - i.e. the name in the main list. If we can't find that, then just return.
    Next we try to set each of the properties according to the fontname.
    Finally we select the font family & style in the lists. */
+
+/**
+ * gtk_font_selection_set_font_name:
+ * @fontsel: a #GtkFontSelection
+ * @fontname: a font name like "Helvetica 12" or "Times Bold 18"
+ * 
+ * Sets the currently-selected font.  Note that the @fontsel needs to know the
+ * screen in which it will appear for this to work; this can be guaranteed by
+ * simply making sure that the @fontsel is inserted in a toplevel window before
+ * you call this function.
+ * 
+ * Return value: #TRUE if the font could be set successfully; #FALSE if no such
+ * font exists or if the @fontsel doesn't belong to a particular screen yet.
+ **/
 gboolean
 gtk_font_selection_set_font_name (GtkFontSelection *fontsel,
 				  const gchar      *fontname)
@@ -1200,6 +1228,7 @@ gtk_font_selection_set_font_name (GtkFontSelection *fontsel,
   const gchar *new_family_name;
   
   g_return_val_if_fail (GTK_IS_FONT_SELECTION (fontsel), FALSE);
+  g_return_val_if_fail (gtk_widget_has_screen (GTK_WIDGET (fontsel)), FALSE);
   
   new_desc = pango_font_description_from_string (fontname);
   new_family_name = pango_font_description_get_family (new_desc);
@@ -1404,6 +1433,20 @@ gtk_font_selection_dialog_new (const gchar *title)
   return GTK_WIDGET (fontseldiag);
 }
 
+/**
+ * gtk_font_selection_dialog_get_font_name:
+ * @fsd: a #GtkFontSelectionDialog
+ * 
+ * Gets the currently-selected font name.  Note that this can be a different
+ * string than what you set with gtk_font_selection_dialog_set_font_name(), as
+ * the font selection 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.
+ * 
+ * Return value: A string with the name of the current font, or #NULL if no font
+ * is selected.  You must free this string with g_free().
+ **/
 gchar*
 gtk_font_selection_dialog_get_font_name (GtkFontSelectionDialog *fsd)
 {