default xscale/yscale to 0.0, not 0.5, 0.5 isn't useful

2001-09-08  Havoc Pennington  <hp@pobox.com>

	* gtk/gtkalignment.c (gtk_alignment_class_init): default
	xscale/yscale to 0.0, not 0.5, 0.5 isn't useful

	* tests/testtextbuffer.c: fix usage of gtk_text_iter_spew

	* gtk/gtktextiter.c: fix docs
	(gtk_text_iter_spew): get rid of this

	* gtk/gtklayout.c: docs

	* gtk/gtkbutton.c (gtk_button_construct_child): add an alignment
	to center image and label together, instead of having image on
	left and label centered, patch/suggestion from Jacob

	* gtk/gtkdialog.c: docs

2001-09-08  Havoc Pennington  <hp@pobox.com>

	* gtk/tmpl/gtklayout.sgml: docs

	* gdk-pixbuf/gdk-pixbuf.sgml: remove the section on compiling
	gdk-pixbuf since it isn't a standalone package anymore

	* gtk/building.sgml: section on compiling GTK itself

7 files changed, 200 insertions, 46 deletions

diff --git a/gtk/gtkalignment.c b/gtk/gtkalignment.c
index df78a4310e..f4eaa1c08a 100644
--- a/gtk/gtkalignment.c
+++ b/gtk/gtkalignment.c
@@ -122,7 +122,7 @@ gtk_alignment_class_init (GtkAlignmentClass *class)
                                                       _("Value between 0.0 and 1.0 to indicate X scale"),
                                                       0.0,
                                                       1.0,
-                                                      0.5,
+                                                      0.0,
                                                       G_PARAM_READABLE | G_PARAM_WRITABLE));
   g_object_class_install_property (gobject_class,
                                    PROP_YSCALE,
@@ -131,7 +131,7 @@ gtk_alignment_class_init (GtkAlignmentClass *class)
                                                       _("Value between 0.0 and 1.0 to indicate Y scale"),
                                                       0.0,
                                                       1.0,
-                                                      0.5,
+                                                      0.0,
                                                       G_PARAM_READABLE | G_PARAM_WRITABLE));
 }
 
@@ -142,8 +142,8 @@ gtk_alignment_init (GtkAlignment *alignment)
 
   alignment->xalign = 0.5;
   alignment->yalign = 0.5;
-  alignment->xscale = 1.0;
-  alignment->yscale = 1.0;
+  alignment->xscale = 0.0;
+  alignment->yscale = 0.0;
 }
 
 GtkWidget*
@@ -178,7 +178,7 @@ gtk_alignment_set_property (GObject         *object,
     {
     case PROP_XALIGN:
       gtk_alignment_set (alignment,
-			 g_value_get_float(value),
+			 g_value_get_float (value),
 			 alignment->yalign,
 			 alignment->xscale,
 			 alignment->yscale);
@@ -186,7 +186,7 @@ gtk_alignment_set_property (GObject         *object,
     case PROP_YALIGN:
       gtk_alignment_set (alignment,
 			 alignment->xalign,
-			 g_value_get_float(value),
+			 g_value_get_float (value),
 			 alignment->xscale,
 			 alignment->yscale);
       break;
@@ -194,7 +194,7 @@ gtk_alignment_set_property (GObject         *object,
       gtk_alignment_set (alignment,
 			 alignment->xalign,
 			 alignment->yalign,
-			 g_value_get_float(value),
+			 g_value_get_float (value),
 			 alignment->yscale);
       break;
     case PROP_YSCALE:
@@ -202,7 +202,7 @@ gtk_alignment_set_property (GObject         *object,
 			 alignment->xalign,
 			 alignment->yalign,
 			 alignment->xscale,
-			 g_value_get_float(value));
+			 g_value_get_float (value));
       break;
     default:
       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
diff --git a/gtk/gtkbutton.c b/gtk/gtkbutton.c
index 61cafd9967..5d4a27a7b6 100644
--- a/gtk/gtkbutton.c
+++ b/gtk/gtkbutton.c
@@ -25,6 +25,7 @@
  */
 
 #include <string.h>
+#include "gtkalignment.h"
 #include "gtkbutton.h"
 #include "gtklabel.h"
 #include "gtkmain.h"
@@ -405,6 +406,7 @@ gtk_button_construct_child (GtkButton *button)
   GtkWidget *label;
   GtkWidget *image;
   GtkWidget *hbox;
+  GtkWidget *align;
 
   if (!button->constructed)
     return;
@@ -425,13 +427,16 @@ gtk_button_construct_child (GtkButton *button)
       gtk_label_set_mnemonic_widget (GTK_LABEL (label), GTK_WIDGET (button));
       
       image = gtk_image_new_from_stock (button->label_text, GTK_ICON_SIZE_BUTTON);
-      hbox = gtk_hbox_new (FALSE, 1);
+      hbox = gtk_hbox_new (FALSE, 2);
 
+      align = gtk_alignment_new (0.5, 0.5, 0.0, 0.0);
+      
       gtk_box_pack_start (GTK_BOX (hbox), image, FALSE, FALSE, 0);
-      gtk_box_pack_end (GTK_BOX (hbox), label, TRUE, TRUE, 0);
+      gtk_box_pack_end (GTK_BOX (hbox), label, FALSE, FALSE, 0);
       
-      gtk_container_add (GTK_CONTAINER (button), hbox);
-      gtk_widget_show_all (hbox);
+      gtk_container_add (GTK_CONTAINER (button), align);
+      gtk_container_add (GTK_CONTAINER (align), hbox);
+      gtk_widget_show_all (align);
 
       return;
     }
diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c
index 15398ce199..c758db0943 100644
--- a/gtk/gtkdialog.c
+++ b/gtk/gtkdialog.c
@@ -689,6 +689,15 @@ gtk_dialog_set_default_response (GtkDialog *dialog,
   g_list_free (children);
 }
 
+/**
+ * gtk_dialog_set_has_separator:
+ * @dialog: a #GtkDialog
+ * @setting: %TRUE to have a separator
+ *
+ * Sets whether the dialog has a separator above the buttons.
+ * %TRUE by default.
+ * 
+ **/
 void
 gtk_dialog_set_has_separator (GtkDialog *dialog,
                               gboolean   setting)
@@ -718,6 +727,14 @@ gtk_dialog_set_has_separator (GtkDialog *dialog,
   g_object_notify (G_OBJECT (dialog), "has_separator");
 }
 
+/**
+ * gtk_dialog_get_has_separator:
+ * @dialog: a #GtkDialog
+ * 
+ * Accessor for whether the dialog has a separator.
+ * 
+ * Return value: %TRUE if the dialog has a separator
+ **/
 gboolean
 gtk_dialog_get_has_separator (GtkDialog *dialog)
 {
diff --git a/gtk/gtklayout.c b/gtk/gtklayout.c
index 607137f882..c28f4a59e1 100644
--- a/gtk/gtklayout.c
+++ b/gtk/gtklayout.c
@@ -106,6 +106,17 @@ static GtkWidgetClass *parent_class = NULL;
 
 /* Public interface
  */
+/**
+ * gtk_layout_new:
+ * @hadjustment: horizontal scroll adjustment, or %NULL
+ * @vadjustment: vertical scroll adjustment, or %NULL
+ * 
+ * Creates a new #GtkLayout. Unless you have a specific adjustment
+ * you'd like the layout to use for scrolling, pass %NULL for
+ * @hadjustment and @vadjustment.
+ * 
+ * Return value: a new #GtkLayout
+ **/
   
 GtkWidget*    
 gtk_layout_new (GtkAdjustment *hadjustment,
@@ -120,6 +131,19 @@ gtk_layout_new (GtkAdjustment *hadjustment,
   return GTK_WIDGET (layout);
 }
 
+/**
+ * gtk_layout_get_hadjustment:
+ * @layout: a #GtkLayout
+ * 
+ * This function should only be called after the layout has been
+ * placed in a #GtkScrolledWindow or otherwise configured for
+ * scrolling. It returns the #GtkAdjustment used for communication
+ * between the horizontal scrollbar and @layout.
+ *
+ * See #GtkScrolledWindow, #GtkScrollbar, #GtkAdjustment for details.
+ * 
+ * Return value: horizontal scroll adjustment
+ **/
 GtkAdjustment* 
 gtk_layout_get_hadjustment (GtkLayout     *layout)
 {
@@ -127,6 +151,19 @@ gtk_layout_get_hadjustment (GtkLayout     *layout)
 
   return layout->hadjustment;
 }
+/**
+ * gtk_layout_get_vadjustment:
+ * @layout: a #GtkLayout
+ * 
+ * This function should only be called after the layout has been
+ * placed in a #GtkScrolledWindow or otherwise configured for
+ * scrolling. It returns the #GtkAdjustment used for communication
+ * between the vertical scrollbar and @layout.
+ *
+ * See #GtkScrolledWindow, #GtkScrollbar, #GtkAdjustment for details.
+ * 
+ * Return value: vertical scroll adjustment
+ **/
 GtkAdjustment* 
 gtk_layout_get_vadjustment (GtkLayout     *layout)
 {
@@ -204,6 +241,16 @@ gtk_layout_finalize (GObject *object)
   G_OBJECT_CLASS (parent_class)->finalize (object);
 }
 
+/**
+ * gtk_layout_set_hadjustment:
+ * @layout: a #GtkLayout
+ * @adjustment: new scroll adjustment
+ *
+ * Sets the horizontal scroll adjustment for the layout.
+ *
+ * See #GtkScrolledWindow, #GtkScrollbar, #GtkAdjustment for details.
+ * 
+ **/
 void           
 gtk_layout_set_hadjustment (GtkLayout     *layout,
 			    GtkAdjustment *adjustment)
@@ -214,7 +261,16 @@ gtk_layout_set_hadjustment (GtkLayout     *layout,
   g_object_notify (G_OBJECT (layout), "hadjustment");
 }
  
-
+/**
+ * gtk_layout_set_vadjustment:
+ * @layout: a #GtkLayout
+ * @adjustment: new scroll adjustment
+ *
+ * Sets the vertical scroll adjustment for the layout.
+ *
+ * See #GtkScrolledWindow, #GtkScrollbar, #GtkAdjustment for details.
+ * 
+ **/
 void           
 gtk_layout_set_vadjustment (GtkLayout     *layout,
 			    GtkAdjustment *adjustment)
@@ -246,6 +302,17 @@ get_child (GtkLayout  *layout,
   return NULL;
 }
 
+/**
+ * gtk_layout_put:
+ * @layout: a #GtkLayout
+ * @child_widget: child widget
+ * @x: X position of child widget
+ * @y: Y position of child widget
+ *
+ * Adds @child_widget to @layout, at position (@x,@y).
+ * @layout becomes the new parent container of @child_widget.
+ * 
+ **/
 void           
 gtk_layout_put (GtkLayout     *layout, 
 		GtkWidget     *child_widget, 
@@ -309,6 +376,16 @@ gtk_layout_move_internal (GtkLayout       *layout,
     gtk_widget_queue_resize (GTK_WIDGET (layout));
 }
 
+/**
+ * gtk_layout_move:
+ * @layout: a #GtkLayout
+ * @child_widget: a current child of @layout
+ * @x: X position to move to
+ * @y: Y position to move to
+ *
+ * Moves a current child of @layout to a new position.
+ * 
+ **/
 void           
 gtk_layout_move (GtkLayout     *layout, 
 		 GtkWidget     *child_widget, 
@@ -345,6 +422,15 @@ gtk_layout_set_adjustment_upper (GtkAdjustment *adj,
     }
 }
 
+/**
+ * gtk_layout_set_size:
+ * @layout: a #GtkLayout
+ * @width: width of entire scrollable area
+ * @height: height of entire scrollable area
+ *
+ * Sets the size of the scrollable area of the layout.
+ * 
+ **/
 void
 gtk_layout_set_size (GtkLayout     *layout, 
 		     guint          width,
@@ -403,6 +489,12 @@ gtk_layout_get_size (GtkLayout *layout,
     *height = layout->height;
 }
 
+/**
+ * gtk_layout_freeze:
+ * @layout: a #GtkLayout
+ * 
+ * This is a deprecated function, it doesn't do anything useful.
+ **/
 void
 gtk_layout_freeze (GtkLayout *layout)
 {
@@ -411,6 +503,12 @@ gtk_layout_freeze (GtkLayout *layout)
   layout->freeze_count++;
 }
 
+/**
+ * gtk_layout_thaw:
+ * @layout: a #GtkLayout
+ * 
+ * This is a deprecated function, it doesn't do anything useful.
+ **/
 void
 gtk_layout_thaw (GtkLayout *layout)
 {
diff --git a/gtk/gtklayout.h b/gtk/gtklayout.h
index b216761b1e..68bb43cb3a 100644
--- a/gtk/gtklayout.h
+++ b/gtk/gtklayout.h
@@ -64,9 +64,11 @@ struct _GtkLayout {
 
   GtkAdjustment *hadjustment;
   GtkAdjustment *vadjustment;
-  
+
+  /*< public >*/
   GdkWindow *bin_window;
 
+  /*< private >*/
   GdkVisibilityState visibility;
   gint scroll_x;
   gint scroll_y;
@@ -86,12 +88,12 @@ GtkType        gtk_layout_get_type        (void) G_GNUC_CONST;
 GtkWidget*     gtk_layout_new             (GtkAdjustment *hadjustment,
 				           GtkAdjustment *vadjustment);
 void           gtk_layout_put             (GtkLayout     *layout, 
-		                           GtkWidget     *widget, 
+		                           GtkWidget     *child_widget, 
 		                           gint           x, 
 		                           gint           y);
   
 void           gtk_layout_move            (GtkLayout     *layout, 
-		                           GtkWidget     *widget, 
+		                           GtkWidget     *child_widget, 
 		                           gint           x, 
 		                           gint           y);
   
diff --git a/gtk/gtktextiter.c b/gtk/gtktextiter.c
index ae52c76d17..2d5ecc8b5a 100644
--- a/gtk/gtktextiter.c
+++ b/gtk/gtktextiter.c
@@ -699,6 +699,17 @@ gtk_text_iter_get_line_index (const GtkTextIter *iter)
   return real->line_byte_offset;
 }
 
+/**
+ * gtk_text_iter_get_visible_line_offset:
+ * @iter: a #GtkTextIter
+ * 
+ * Returns the offset in characters from the start of the
+ * line to the given @iter, not counting characters that
+ * are invisible due to tags with the "invisible" flag
+ * toggled on.
+ * 
+ * Return value: offset in visible characters from the start of the line 
+ **/
 gint
 gtk_text_iter_get_visible_line_offset (const GtkTextIter *iter)
 {
@@ -750,6 +761,18 @@ gtk_text_iter_get_visible_line_offset (const GtkTextIter *iter)
   return vis_offset;
 }
 
+
+/**
+ * gtk_text_iter_get_visible_line_index:
+ * @iter: a #GtkTextIter
+ * 
+ * Returns the number of bytes from the start of the
+ * line to the given @iter, not counting bytes that
+ * are invisible due to tags with the "invisible" flag
+ * toggled on.
+ * 
+ * Return value: byte index of @iter with respect to the start of the line
+ **/
 gint
 gtk_text_iter_get_visible_line_index (const GtkTextIter *iter)
 {
@@ -2499,6 +2522,22 @@ gtk_text_iter_backward_line (GtkTextIter *iter)
   return TRUE;
 }
 
+
+/**
+ * gtk_text_iter_forward_lines:
+ * @iter: a #GtkTextIter
+ * @count: number of lines to move forward
+ *
+ * Moves @count lines forward, if possible (if @count would move
+ * past the start or end of the buffer, moves to the start or end of
+ * the buffer).  The return value indicates whether the iterator moved
+ * onto a dereferenceable position; if the iterator didn't move, or
+ * moved onto the end iterator, then FALSE is returned. If @count is 0,
+ * the function does nothing and returns FALSE. If @count is negative,
+ * moves backward by 0 - @count lines.
+ *
+ * Return value: whether @iter moved and is dereferenceable
+ **/
 gboolean
 gtk_text_iter_forward_lines (GtkTextIter *iter, gint count)
 {
@@ -2530,6 +2569,21 @@ gtk_text_iter_forward_lines (GtkTextIter *iter, gint count)
     }
 }
 
+/**
+ * gtk_text_iter_backward_lines:
+ * @iter: a #GtkTextIter
+ * @count: number of lines to move backward
+ *
+ * Moves @count lines backward, if possible (if @count would move
+ * past the start or end of the buffer, moves to the start or end of
+ * the buffer).  The return value indicates whether the iterator moved
+ * onto a dereferenceable position; if the iterator didn't move, or
+ * moved onto the end iterator, then FALSE is returned. If @count is 0,
+ * the function does nothing and returns FALSE. If @count is negative,
+ * moves forward by 0 - @count lines.
+ *
+ * Return value: whether @iter moved and is dereferenceable
+ **/
 gboolean
 gtk_text_iter_backward_lines (GtkTextIter *iter, gint count)
 {
@@ -2838,7 +2892,7 @@ gtk_text_iter_forward_word_end (GtkTextIter *iter)
 }
 
 /**
- * gtk_text_iter_forward_word_end:
+ * gtk_text_iter_backward_word_start:
  * @iter: a #GtkTextIter
  * 
  * Moves backward to the next word start. (If @iter is currently on a
@@ -3075,7 +3129,9 @@ gtk_text_iter_backward_sentence_start (GtkTextIter      *iter)
  * @iter: a #GtkTextIter
  * @count: number of sentences to move
  * 
- * Calls gtk_text_iter_forward_sentence_end() up to @count times.
+ * Calls gtk_text_iter_forward_sentence_end() @count times (or until
+ * gtk_text_iter_forward_sentence_end() returns %FALSE). If @count is
+ * negative, moves backward instead of forward.
  * 
  * Return value: %TRUE if @iter moved and is not the end iterator
  **/
@@ -3105,11 +3161,13 @@ gtk_text_iter_forward_sentence_ends (GtkTextIter      *iter,
 }
 
 /**
- * gtk_text_iter_forward_sentence_ends:
+ * gtk_text_iter_backward_sentence_starts:
  * @iter: a #GtkTextIter
  * @count: number of sentences to move
  * 
- * Calls gtk_text_iter_backward_sentence_start() up to @count times.
+ * Calls gtk_text_iter_backward_sentence_start() up to @count times,
+ * or until it returns %FALSE. If @count is negative, moves forward
+ * instead of backward.
  * 
  * Return value: %TRUE if @iter moved and is not the end iterator
  **/
@@ -4936,28 +4994,6 @@ _gtk_text_btree_get_end_iter         (GtkTextBTree   *tree,
 }
 
 void
-gtk_text_iter_spew (const GtkTextIter *iter, const gchar *desc)
-{
-  GtkTextRealIter *real = (GtkTextRealIter*)iter;
-
-  g_return_if_fail (iter != NULL);
-
-  if (real->chars_changed_stamp != _gtk_text_btree_get_chars_changed_stamp (real->tree))
-    g_print (" %20s: <invalidated iterator>\n", desc);
-  else
-    {
-      check_invariants (iter);
-      g_print (" %20s: line %d / char %d / line char %d / line byte %d\n",
-               desc,
-               gtk_text_iter_get_line (iter),
-               gtk_text_iter_get_offset (iter),
-               gtk_text_iter_get_line_offset (iter),
-               gtk_text_iter_get_line_index (iter));
-      check_invariants (iter);
-    }
-}
-
-void
 _gtk_text_iter_check (const GtkTextIter *iter)
 {
   const GtkTextRealIter *real = (const GtkTextRealIter*)iter;
diff --git a/gtk/gtktextiter.h b/gtk/gtktextiter.h
index c3ea8516d7..e48ab466e4 100644
--- a/gtk/gtktextiter.h
+++ b/gtk/gtktextiter.h
@@ -259,10 +259,6 @@ gboolean gtk_text_iter_in_range        (const GtkTextIter *iter,
 void     gtk_text_iter_order           (GtkTextIter *first,
                                         GtkTextIter *second);
 
-/* Debug */
-void     gtk_text_iter_spew            (const GtkTextIter *iter,
-                                        const gchar *desc);
-
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */