From cb12593d579609a32d14b33efd1b1dff37fee292 Mon Sep 17 00:00:00 2001 From: Stefan Jeske Date: Sun, 10 May 1998 17:05:39 +0000 Subject: [PATCH] Started documentation of GtkCTree. --- ChangeLog | 7 +++ ChangeLog.pre-2-0 | 7 +++ ChangeLog.pre-2-10 | 7 +++ ChangeLog.pre-2-2 | 7 +++ ChangeLog.pre-2-4 | 7 +++ ChangeLog.pre-2-6 | 7 +++ ChangeLog.pre-2-8 | 7 +++ docs/faq/gtkfaq.sgml | 1 + docs/gtk.texi | 108 ++++++++++++++++++++++++++++++++++++- docs/gtk_tut.sgml | 1 + docs/gtkfaq.sgml | 1 + docs/tutorial/gtk_tut.sgml | 1 + gtk/gtkctree.c | 44 +++++++++------ gtk/gtkctree.h | 12 ++--- gtk/testgtk.c | 11 ++-- tests/testgtk.c | 11 ++-- 16 files changed, 206 insertions(+), 33 deletions(-) diff --git a/ChangeLog b/ChangeLog index c6054ab30f..01ac53f9a5 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +1998-05-10 Stefan Jeske + + * 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 * configure.in (LIBS): Try to figure out if this diff --git a/ChangeLog.pre-2-0 b/ChangeLog.pre-2-0 index c6054ab30f..01ac53f9a5 100644 --- a/ChangeLog.pre-2-0 +++ b/ChangeLog.pre-2-0 @@ -1,3 +1,10 @@ +1998-05-10 Stefan Jeske + + * 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 * configure.in (LIBS): Try to figure out if this diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index c6054ab30f..01ac53f9a5 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,3 +1,10 @@ +1998-05-10 Stefan Jeske + + * 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 * configure.in (LIBS): Try to figure out if this diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2 index c6054ab30f..01ac53f9a5 100644 --- a/ChangeLog.pre-2-2 +++ b/ChangeLog.pre-2-2 @@ -1,3 +1,10 @@ +1998-05-10 Stefan Jeske + + * 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 * configure.in (LIBS): Try to figure out if this diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index c6054ab30f..01ac53f9a5 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,3 +1,10 @@ +1998-05-10 Stefan Jeske + + * 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 * configure.in (LIBS): Try to figure out if this diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index c6054ab30f..01ac53f9a5 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,3 +1,10 @@ +1998-05-10 Stefan Jeske + + * 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 * configure.in (LIBS): Try to figure out if this diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index c6054ab30f..01ac53f9a5 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,3 +1,10 @@ +1998-05-10 Stefan Jeske + + * 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 * configure.in (LIBS): Try to figure out if this diff --git a/docs/faq/gtkfaq.sgml b/docs/faq/gtkfaq.sgml index 26d5981fc2..c402259420 100644 --- a/docs/faq/gtkfaq.sgml +++ b/docs/faq/gtkfaq.sgml @@ -565,6 +565,7 @@ The GTK+ Tutorial lists the following widgets: | | `GtkCheckButton | | `GtkRadioButton | +GtkCList + | `GtkCTree | +GtkFixed | +GtkList | +GtkMenuShell diff --git a/docs/gtk.texi b/docs/gtk.texi index a92155a855..618418e78e 100644 --- a/docs/gtk.texi +++ b/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 diff --git a/docs/gtk_tut.sgml b/docs/gtk_tut.sgml index 64fe5c4f55..47fb5b5af1 100644 --- a/docs/gtk_tut.sgml +++ b/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 diff --git a/docs/gtkfaq.sgml b/docs/gtkfaq.sgml index 26d5981fc2..c402259420 100644 --- a/docs/gtkfaq.sgml +++ b/docs/gtkfaq.sgml @@ -565,6 +565,7 @@ The GTK+ Tutorial lists the following widgets: | | `GtkCheckButton | | `GtkRadioButton | +GtkCList + | `GtkCTree | +GtkFixed | +GtkList | +GtkMenuShell diff --git a/docs/tutorial/gtk_tut.sgml b/docs/tutorial/gtk_tut.sgml index 64fe5c4f55..47fb5b5af1 100644 --- a/docs/tutorial/gtk_tut.sgml +++ b/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 diff --git a/gtk/gtkctree.c b/gtk/gtkctree.c index c6013f11db..971a492ba2 100644 --- a/gtk/gtkctree.c +++ b/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 + - clist_row->cell[i].vertical; + ydest = (clip_rectangle.y + (clip_rectangle.height / 2)) + - 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 + - clist_row->cell[i].vertical; + ydest = (clip_rectangle.y + (clip_rectangle.height / 2)) + - 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) diff --git a/gtk/gtkctree.h b/gtk/gtkctree.h index 19033f9044..dda1184bcd 100644 --- a/gtk/gtkctree.h +++ b/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 *parent, - GList *sibling); + GList *node, + GList *new_parent, + 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); diff --git a/gtk/testgtk.c b/gtk/testgtk.c index bbeb06b486..6fd1d7119f 100644 --- a/gtk/testgtk.c +++ b/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; diff --git a/tests/testgtk.c b/tests/testgtk.c index bbeb06b486..6fd1d7119f 100644 --- a/tests/testgtk.c +++ b/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;