Started documentation of GtkCTree.

ChangeLog

@@ -1,3 +1,10 @@
+1998-05-10  Stefan Jeske  <stefan@gtk.org>
+
+	* gtk/gtkctree.c (gtk_ctree_is_visible): Changed return value
+	to gboolean.
+
+	* docs/gtk.texi (GtkCTree): Started documentation of GtkCTree.
+
 Sat May  9 20:11:20 1998  Owen Taylor  <otaylor@gtk.org>
 
 	* configure.in (LIBS): Try to figure out if this

ChangeLog.pre-2-0

@@ -1,3 +1,10 @@
+1998-05-10  Stefan Jeske  <stefan@gtk.org>
+
+	* gtk/gtkctree.c (gtk_ctree_is_visible): Changed return value
+	to gboolean.
+
+	* docs/gtk.texi (GtkCTree): Started documentation of GtkCTree.
+
 Sat May  9 20:11:20 1998  Owen Taylor  <otaylor@gtk.org>
 
 	* configure.in (LIBS): Try to figure out if this

ChangeLog.pre-2-10

@@ -1,3 +1,10 @@
+1998-05-10  Stefan Jeske  <stefan@gtk.org>
+
+	* gtk/gtkctree.c (gtk_ctree_is_visible): Changed return value
+	to gboolean.
+
+	* docs/gtk.texi (GtkCTree): Started documentation of GtkCTree.
+
 Sat May  9 20:11:20 1998  Owen Taylor  <otaylor@gtk.org>
 
 	* configure.in (LIBS): Try to figure out if this

ChangeLog.pre-2-2

@@ -1,3 +1,10 @@
+1998-05-10  Stefan Jeske  <stefan@gtk.org>
+
+	* gtk/gtkctree.c (gtk_ctree_is_visible): Changed return value
+	to gboolean.
+
+	* docs/gtk.texi (GtkCTree): Started documentation of GtkCTree.
+
 Sat May  9 20:11:20 1998  Owen Taylor  <otaylor@gtk.org>
 
 	* configure.in (LIBS): Try to figure out if this

ChangeLog.pre-2-4

@@ -1,3 +1,10 @@
+1998-05-10  Stefan Jeske  <stefan@gtk.org>
+
+	* gtk/gtkctree.c (gtk_ctree_is_visible): Changed return value
+	to gboolean.
+
+	* docs/gtk.texi (GtkCTree): Started documentation of GtkCTree.
+
 Sat May  9 20:11:20 1998  Owen Taylor  <otaylor@gtk.org>
 
 	* configure.in (LIBS): Try to figure out if this

ChangeLog.pre-2-6

@@ -1,3 +1,10 @@
+1998-05-10  Stefan Jeske  <stefan@gtk.org>
+
+	* gtk/gtkctree.c (gtk_ctree_is_visible): Changed return value
+	to gboolean.
+
+	* docs/gtk.texi (GtkCTree): Started documentation of GtkCTree.
+
 Sat May  9 20:11:20 1998  Owen Taylor  <otaylor@gtk.org>
 
 	* configure.in (LIBS): Try to figure out if this

ChangeLog.pre-2-8

@@ -1,3 +1,10 @@
+1998-05-10  Stefan Jeske  <stefan@gtk.org>
+
+	* gtk/gtkctree.c (gtk_ctree_is_visible): Changed return value
+	to gboolean.
+
+	* docs/gtk.texi (GtkCTree): Started documentation of GtkCTree.
+
 Sat May  9 20:11:20 1998  Owen Taylor  <otaylor@gtk.org>
 
 	* configure.in (LIBS): Try to figure out if this

docs/faq/gtkfaq.sgml

@@ -565,6 +565,7 @@ The GTK+ Tutorial lists the following widgets:
      | |   `GtkCheckButton
      | |     `GtkRadioButton
      | +GtkCList
+     |   `GtkCTree
      | +GtkFixed
      | +GtkList
      | +GtkMenuShell

docs/gtk.texi

@@ -762,6 +762,7 @@ The available widgets (in alphabetical order):
 * GtkColorSelection::		The color selector widget.
 * GtkCombo::			The combo box widget.
 * GtkContainer::                The container widget.
+* GtkCTree::                    The multi-column tree widget.
 * GtkCurve::			The curve widget.
 * GtkGammaCurve::		The gamma curve widget.
 * GtkDialog::                   The dialog widget.
@@ -1774,7 +1775,7 @@ a @code{GtkWidget} object. @code{NULL} is returned on failure.
 @gtkstdmacros{Combo, COMBO}
 
 @page
-@node GtkContainer, GtkCurve, GtkCombo, Widgets
+@node GtkContainer, GtkCTree, GtkCombo, Widgets
 @comment node-name, next, previous, up
 @section The container widget
 
@@ -1853,8 +1854,111 @@ Remove @var{widget} from @var{container}.
 
 @gtkstdmacros{Container, CONTAINER}
 
+@page 
+@node GtkCTree, GtkCurve, GtkContainer, Widgets
+@comment node-name, next, previous, up
+@section The multi-column tree widget
+
+@subsection Description
+
+The GtkCTree widget is a multi-columned list with a designated column, the 
+@code{tree column}, to display hierarchically-organized data. Each node is
+either a folder (a branch of the tree) or a leaf. Nodes can be
+(recursively) expanded, collapsed, (un)selected, removed, moved, sorted etc. 
+
+GtkCTree is a descendant of @pxref{GtkCList}. Therefore, a cell in a column
+other than the tree column can only contain a string, a pixmap, both or 
+nothing. A node in the tree column can contain a string and up to two pixmaps
+and masks, indicating the "folder openend" and "folder closed" status.
+
+Compared to GtkCList, there is no concept of row numbers. Therefore, a number
+of GtkCList methods had to be re-implemented taking @code{GList *node} 
+arguments instead of @code{gint row}.
+
+@subsection Options
+
+@subsection Signals
+
+@deftypefn Signal void GtkCTree::tree_expand (GtkCTree *@var{ctree}, GList *@var{node})
+@end deftypefn
+@deftypefn Signal void GtkCTree::tree_collapse (GtkCTree *@var{ctree}, GList *@var{node})
+@end deftypefn
+@deftypefn Signal void GtkCTree::tree_move (GtkCTree *@var{ctree}, GList *@var{node}, GList *@var{new_parent}, GList *@var{new_sibling})
+@end deftypefn
+@deftypefn Signal void GtkCTree::tree_select_row (GtkCTree *@var{ctree}, GList *@var{row}, gint @var{column})
+@end deftypefn
+@deftypefn Signal void GtkCTree::tree_unselect_row (GtkCTree *@var{ctree}, GList *@var{row}, gint @var{column})
+@end deftypefn
+
+@subsection Functions
+
+@deftypefun GtkType gtk_ctree_get_type (void)
+Returns the @code{GtkCTree} type identifier.
+@end deftypefun
+
+@deftypefun GtkWidget* gtk_ctree_new (gint @var{columns}, gint @var{tree_column})
+Creates a new GtkCTree widget with the given number of columns and the given tree column.
+
+On success, a pointer to the newly created widget is returned, and @code{NULL} otherwise.
+@end deftypefun
+
+@deftypefun GtkWidget* gtk_ctree_new_with_titles (gint @var{columns}, gint @var{tree_column}, gchar *@var{titles[]})
+Creates a new GtkCTree widget with the given number of columns and the given tree column. The column titles are initialized to the strings of the array @var{titles}.
+
+On success, a pointer to the newly created widget is returned, and @code{NULL} otherwise.
+@end deftypefun
+
+@deftypefun GList* gtk_ctree_insert (GtkCTree *@var{ctree}, GList *@var{parent}, GList *@var{sibling}, gchar *@var{text[]}, guint8 @var{spacing}, GdkPixmap *@var{pixmap_closed}, GdkPixmap *@var{mask_closed}, GdkPixmap *@var{pixmap_opened}, GdkPixmap *@var{mask_opened}, gboolean @var{is_leaf}, gboolean @var{expanded})
+Inserts a new node at the given position. If @var{parent} == NULL, the node is
+inserted at root level. If @var{sibling} == NULL, the node is appended to the 
+existing list of siblings. Otherwise, the node is inserted before @var{sibling}.
+If not NULL, the two pixmaps/masks are used to indicate the opened/closed status
+of the node. @var{spacing} is the number of pixels between pixmap and text.
+If @var{is_leaf} == TRUE, the node cannot have any children.
+The initial expanded/collapsed status is given by @var{expanded}.
+
+On success, the pointer to the newly inserted node is returned, and NULL 
+otherwise.
+@end deftypefun
+
+@deftypefun void gtk_ctree_remove (GtkCTree *@var{ctree}, GList *@var{node})
+Removes the given node and all its children.
+@end deftypefun
+
+@deftypefun void gtk_ctree_clear (GtkCTree *@var{ctree})
+Removes all nodes of @var{ctree}.
+@end deftypefun
+
+@deftypefun void gtk_ctree_post_recursive (GtkCTree *@var{ctree}, GList *@var{node}, GtkCTreeFunc @var{func}, gpointer @var{data})
+Apply @var{func} to @var{node} and all its children, traversing @var{ctree} in
+post-order.
+@end deftypefun
+
+@deftypefun void gtk_ctree_pre_recursive (GtkCTree *@var{ctree}, GList *@var{node}, GtkCTreeFunc @var{func}, gpointer @var{data})
+Apply @var{func} to @var{node} and all its children, traversing @var{ctree} in
+pre-order.
+@end deftypefun
+
+@deftypefun gboolean gtk_ctree_is_visible (GtkCTree *@var{ctree}, GList *@var{node})
+Returns the visibility status of the given node. A node is said to be visible
+if in the chain of parent nodes every node is expanded. Or : the node is 
+currently being displayed (but not necessarily inside the viewing area).
+@end deftypefun
+
+@c @deftypefun void gtk_ctree_scroll_to (GtkCTree *@var{ctree}, gint @var{row}, gint@var{column}, gfloat @var{row_align}, gfloat @var{col_align})
+@c Scroll the viewing area of the @code{GtkCtree} in @var{ctree} to @var{column}
+@c and @var{row}. The @var{row_align} and @var{col_align} are between zero and
+@c one, representing the location the row should appear on screen. Setting 
+@c @var{row_align} or the @var{col_align} to 0.0 will be the top or left of the
+@c viewing area. Setting the @var{row_align} or @var{col_align} to 1.0 will
+@c be the bottom or right of the viewing area. If the @var{row} or @var{column}
+@c is -1 then there is no change.
+@c @end deftypefun
+
+@gtkstdmacros{CTree, CTREE}
+
 @page
-@node GtkCurve, GtkGammaCurve, GtkContainer, Widgets
+@node GtkCurve, GtkGammaCurve, GtkCTree, Widgets
 @comment node-name, next, previous, up
 @section The curve widget
 

docs/gtk_tut.sgml

@@ -1494,6 +1494,7 @@ For your reference, here is the class hierarchy tree used to implement widgets.
      | |   `GtkCheckButton
      | |     `GtkRadioButton
      | +GtkCList
+     |  `GtkCTree
      | +GtkFixed
      | +GtkList
      | +GtkMenuShell

docs/gtkfaq.sgml

@@ -565,6 +565,7 @@ The GTK+ Tutorial lists the following widgets:
      | |   `GtkCheckButton
      | |     `GtkRadioButton
      | +GtkCList
+     |   `GtkCTree
      | +GtkFixed
      | +GtkList
      | +GtkMenuShell

docs/tutorial/gtk_tut.sgml

@@ -1494,6 +1494,7 @@ For your reference, here is the class hierarchy tree used to implement widgets.
      | |   `GtkCheckButton
      | |     `GtkRadioButton
      | +GtkCList
+     |  `GtkCTree
      | +GtkFixed
      | +GtkList
      | +GtkMenuShell

gtk/gtkctree.c

@@ -1036,7 +1036,8 @@ draw_row (GtkCList     *clist,
   /* draw the cell borders and background */
   if (area)
     {
-      if (gdk_rectangle_intersect (area, &cell_rectangle, &intersect_rectangle))
+      if (gdk_rectangle_intersect (area, &cell_rectangle, 
+				   &intersect_rectangle))
 	gdk_draw_rectangle (clist->clist_window,
 			    widget->style->base_gc[GTK_STATE_NORMAL],
 			    TRUE,
@@ -1050,7 +1051,8 @@ draw_row (GtkCList     *clist,
 	{
 	  cell_rectangle.y += clist->row_height + CELL_SPACING;
 
-	  if (gdk_rectangle_intersect (area, &cell_rectangle, &intersect_rectangle))
+	  if (gdk_rectangle_intersect (area, &cell_rectangle, 
+				       &intersect_rectangle))
 	    gdk_draw_rectangle (clist->clist_window,
 				widget->style->base_gc[GTK_STATE_NORMAL],
 				TRUE,
@@ -1130,7 +1132,7 @@ draw_row (GtkCList     *clist,
       clip_rectangle.x = clist->column[i].area.x + clist->hoffset;
       clip_rectangle.width = clist->column[i].area.width;
 
-      /* calculate clipping region clipping region */
+      /* calculate clipping region */
       if (i == ctree->tree_column)
 	{
 	  clip_rectangle.y -= CELL_SPACING;
@@ -1163,7 +1165,8 @@ draw_row (GtkCList     *clist,
 	  break;
 
 	case GTK_CELL_PIXMAP:
-	  gdk_window_get_size (GTK_CELL_PIXMAP (clist_row->cell[i])->pixmap, &width, &height);
+	  gdk_window_get_size (GTK_CELL_PIXMAP (clist_row->cell[i])->pixmap, 
+			       &width, &height);
 	  pixmap_width = width;
 	  break;
 
@@ -1223,11 +1226,13 @@ draw_row (GtkCList     *clist,
 	  break;
 
 	case GTK_JUSTIFY_CENTER:
-	  offset = (clip_rectangle.x + (clip_rectangle.width / 2)) - (width / 2);
+	  offset = (clip_rectangle.x + (clip_rectangle.width / 2)) 
+	    - (width / 2);
 	  break;
 
 	case GTK_JUSTIFY_FILL:
-	  offset = (clip_rectangle.x + (clip_rectangle.width / 2)) - (width / 2);
+	  offset = (clip_rectangle.x + (clip_rectangle.width / 2)) 
+	    - (width / 2);
 	  break;
 
 	default:
@@ -1627,12 +1632,13 @@ draw_row (GtkCList     *clist,
 	      xsrc = 0;
 	      ysrc = 0;
 	      xdest = offset + clist_row->cell[i].horizontal;
-	      ydest = (clip_rectangle.y + (clip_rectangle.height / 2)) - height / 2 +
+	      ydest = (clip_rectangle.y + (clip_rectangle.height / 2)) 
-		clist_row->cell[i].vertical;
+		- height / 2 + clist_row->cell[i].vertical;
 
 	      if (GTK_CELL_PIXMAP (clist_row->cell[i])->mask)
 		{
-		  gdk_gc_set_clip_mask (fg_gc, GTK_CELL_PIXMAP (clist_row->cell[i])->mask);
+		  gdk_gc_set_clip_mask (fg_gc, GTK_CELL_PIXMAP 
+					(clist_row->cell[i])->mask);
 		  gdk_gc_set_clip_origin (fg_gc, xdest, ydest);
 		}
 	      gdk_draw_pixmap (clist->clist_window, fg_gc,
@@ -1651,12 +1657,13 @@ draw_row (GtkCList     *clist,
 	      xsrc = 0;
 	      ysrc = 0;
 	      xdest = offset + clist_row->cell[i].horizontal;
-	      ydest = (clip_rectangle.y + (clip_rectangle.height / 2)) - height / 2 +
+	      ydest = (clip_rectangle.y + (clip_rectangle.height / 2)) 
-		clist_row->cell[i].vertical;
+		- height / 2 + clist_row->cell[i].vertical;
 	      
 	      if (GTK_CELL_PIXTEXT (clist_row->cell[i])->mask)
 		{
-		  gdk_gc_set_clip_mask (fg_gc, GTK_CELL_PIXTEXT (clist_row->cell[i])->mask);
+		  gdk_gc_set_clip_mask (fg_gc, GTK_CELL_PIXTEXT
+					(clist_row->cell[i])->mask);
 		  gdk_gc_set_clip_origin (fg_gc, xdest, ydest);
 		}
               
@@ -1666,7 +1673,8 @@ draw_row (GtkCList     *clist,
 	      
 	      gdk_gc_set_clip_origin (fg_gc, 0, 0);
 	      
-	      xdest += pixmap_width + GTK_CELL_PIXTEXT (clist_row->cell[i])->spacing;
+	      xdest += pixmap_width + GTK_CELL_PIXTEXT
+		(clist_row->cell[i])->spacing;
 	  
 	      /* draw the string */
 	      gdk_gc_set_clip_rectangle (fg_gc, rect);
@@ -2893,7 +2901,7 @@ gtk_ctree_pre_recursive (GtkCTree     *ctree,
     }
 }
 
-gint
+gboolean
 gtk_ctree_is_visible (GtkCTree *ctree, 
 		      GList    *node)
 { 
@@ -3144,9 +3152,11 @@ gtk_ctree_real_select_recursive (GtkCTree *ctree,
     }
 
   if (state)
-    gtk_ctree_post_recursive (ctree, node, GTK_CTREE_FUNC (tree_select), NULL);
+    gtk_ctree_post_recursive (ctree, node,
+			      GTK_CTREE_FUNC (tree_select), NULL);
   else 
-    gtk_ctree_post_recursive (ctree, node, GTK_CTREE_FUNC (tree_unselect), NULL);
+    gtk_ctree_post_recursive (ctree, node,
+			      GTK_CTREE_FUNC (tree_unselect), NULL);
   
   if (thaw)
     gtk_clist_thaw (clist);
@@ -3597,7 +3607,7 @@ gtk_ctree_scroll_to (GtkCTree *ctree,
 	gtk_adjustment_set_value (adj, adj->upper - adj->page_size);
       else
 	gtk_adjustment_set_value (adj, y);
-    } 
+    }
      
   /* adjust horizontal scrollbar */
   if (column >= 0)

gtk/gtkctree.h

@@ -107,13 +107,13 @@ struct _GtkCTreeClass
 			     GList    *row,
 			     gint      column);
   void (*tree_expand)       (GtkCTree *ctree,
-			     GList    *child);
+			     GList    *node);
   void (*tree_collapse)     (GtkCTree *ctree,
-			     GList    *child);
+			     GList    *node);
   void (*tree_move)         (GtkCTree *ctree,
-			     GList    *child,
+			     GList    *node,
-			     GList    *parent,
+			     GList    *new_parent,
-			     GList    *sibling);
+			     GList    *new_sibling);
 };
 
 struct _GtkCTreeRow
@@ -178,7 +178,7 @@ void       gtk_ctree_pre_recursive          (GtkCTree     *ctree,
 					     GList        *node,
 					     GtkCTreeFunc  func,
 					     gpointer      data);
-gint       gtk_ctree_is_visible             (GtkCTree     *ctree, 
+gboolean   gtk_ctree_is_visible             (GtkCTree     *ctree, 
 					     GList        *node);
 GList *    gtk_ctree_last                   (GtkCTree     *ctree,
 					     GList        *node);

gtk/testgtk.c

@@ -3755,7 +3755,7 @@ void toggle_sel_mode (GtkWidget *widget, GtkCTree *ctree)
 void build_recursive (GtkCTree *ctree, gint cur_depth, gint depth, 
 		      gint num_books, gint num_pages, GList *parent)
 {
-  gchar *text [2];
+  gchar *text[2];
   gchar buf1[60];
   gchar buf2[60];
   GList *sibling;
@@ -3921,7 +3921,8 @@ void create_ctree (void)
 				GTK_SIGNAL_FUNC (after_move), NULL);
       gtk_box_pack_start (GTK_BOX (vbox), GTK_WIDGET (ctree), TRUE, TRUE, 0);
       gtk_clist_column_titles_passive (GTK_CLIST (ctree));
-      gtk_clist_set_column_justification (GTK_CLIST (ctree), 2, GTK_JUSTIFY_RIGHT);
+      gtk_clist_set_column_justification (GTK_CLIST (ctree), 2,
+					  GTK_JUSTIFY_RIGHT);
       gtk_clist_set_selection_mode (GTK_CLIST (ctree), GTK_SELECTION_MULTIPLE);
       gtk_clist_set_policy (GTK_CLIST (ctree), GTK_POLICY_ALWAYS, 
 			    GTK_POLICY_AUTOMATIC);
@@ -4029,7 +4030,8 @@ void create_ctree (void)
       gtk_option_menu_set_history (GTK_OPTION_MENU (omenu2), 1);
       
       omenu3 = gtk_option_menu_new ();
-      gtk_tooltips_set_tip (tooltips, omenu3, "The tree's justification.", NULL);
+      gtk_tooltips_set_tip (tooltips, omenu3, "The tree's justification.",
+			    NULL);
       
       menu = gtk_menu_new ();
       submenu = NULL;
@@ -4056,7 +4058,8 @@ void create_ctree (void)
       gtk_option_menu_set_history (GTK_OPTION_MENU (omenu3), 0);
       
       omenu = gtk_option_menu_new ();
-      gtk_tooltips_set_tip (tooltips, omenu, "The list's selection mode.", NULL);
+      gtk_tooltips_set_tip (tooltips, omenu, "The list's selection mode.",
+			    NULL);
       
       menu = gtk_menu_new ();
       submenu = NULL;

tests/testgtk.c

@@ -3755,7 +3755,7 @@ void toggle_sel_mode (GtkWidget *widget, GtkCTree *ctree)
 void build_recursive (GtkCTree *ctree, gint cur_depth, gint depth, 
 		      gint num_books, gint num_pages, GList *parent)
 {
-  gchar *text [2];
+  gchar *text[2];
   gchar buf1[60];
   gchar buf2[60];
   GList *sibling;
@@ -3921,7 +3921,8 @@ void create_ctree (void)
 				GTK_SIGNAL_FUNC (after_move), NULL);
       gtk_box_pack_start (GTK_BOX (vbox), GTK_WIDGET (ctree), TRUE, TRUE, 0);
       gtk_clist_column_titles_passive (GTK_CLIST (ctree));
-      gtk_clist_set_column_justification (GTK_CLIST (ctree), 2, GTK_JUSTIFY_RIGHT);
+      gtk_clist_set_column_justification (GTK_CLIST (ctree), 2,
+					  GTK_JUSTIFY_RIGHT);
       gtk_clist_set_selection_mode (GTK_CLIST (ctree), GTK_SELECTION_MULTIPLE);
       gtk_clist_set_policy (GTK_CLIST (ctree), GTK_POLICY_ALWAYS, 
 			    GTK_POLICY_AUTOMATIC);
@@ -4029,7 +4030,8 @@ void create_ctree (void)
       gtk_option_menu_set_history (GTK_OPTION_MENU (omenu2), 1);
       
       omenu3 = gtk_option_menu_new ();
-      gtk_tooltips_set_tip (tooltips, omenu3, "The tree's justification.", NULL);
+      gtk_tooltips_set_tip (tooltips, omenu3, "The tree's justification.",
+			    NULL);
       
       menu = gtk_menu_new ();
       submenu = NULL;
@@ -4056,7 +4058,8 @@ void create_ctree (void)
       gtk_option_menu_set_history (GTK_OPTION_MENU (omenu3), 0);
       
       omenu = gtk_option_menu_new ();
-      gtk_tooltips_set_tip (tooltips, omenu, "The list's selection mode.", NULL);
+      gtk_tooltips_set_tip (tooltips, omenu, "The list's selection mode.",
+			    NULL);
       
       menu = gtk_menu_new ();
       submenu = NULL;