Index: xs/GtkTreeModel.xs =================================================================== RCS file: /cvsroot/gtk2-perl/gtk2-perl-xs/Gtk2/xs/GtkTreeModel.xs,v retrieving revision 1.37 diff -u -r1.37 GtkTreeModel.xs --- xs/GtkTreeModel.xs 1 Mar 2004 02:51:55 -0000 1.37 +++ xs/GtkTreeModel.xs 19 May 2004 19:57:57 -0000 @@ -417,6 +417,45 @@ =for flags GtkTreeModelFlags =cut +=for position SYNOPSIS + +=head1 SYNOPSIS + + # Three ways of getting the iter pointing to the location 3:2:5 + + # get the iterator from a string + $iter = $model->get_iter_from_string ("3:2:5"); + + # get the iterator from a path + $path = Gtk2::TreePath->new_from_string ("3:2:5"); + $iter = $model->get_iter ($path); + + # walk the tree to find the iterator + $iter = $model->get_nth_child (undef, 3); + $iter = $model->get_nth_child ($iter, 2); + $iter = $model->get_nth_child ($iter, 5); + + + # getting and setting values + + # assuming a model with these columns + use constant STRING_COLUMN => 0; + use constant INT_COLUMN => 1; + + # set values + $model->set ($iter, + STRING_COLUMN, $new_string_value, + INT_COLUMN, $new_int_value); + + # and get values + ($int, $str) = $model->get ($iter, INT_COLUMN, STRING_COLUMN); + + # if you don't specify a list of column numbers, + # you get all of them. + @values = $model->get ($iter); + +=cut + =for position DESCRIPTION =head1 DESCRIPTION @@ -425,7 +464,49 @@ Gtk2::TreeView widget. It is an abstract interface, designed to be usable with any appropriate data structure. -FIXME FIXME say more here +The model is represented as a hierarchical tree of strongly-typed, columned +data. In other words, the model can be seen as a tree where every node has +different values depending on which column is being queried. The type of +data found in a column is determined by using the GType system (i.e. package +names like Glib::Int, Gtk2::Button, Glib::Scalar, etc). The types are +homogeneous per column across all nodes. It is important to note that this +interface only provides a way of examining a model and observing changes. +The implementation of each individual model decides how and if changes are +made. + +In order to make life simpler for programmers who do not need to write their +own specialized model, two generic models are provided — the Gtk2::TreeStore +and the Gtk2::ListStore. To use these, the developer simply pushes data into +these models as necessary. These models provide the data structure as well +as all appropriate tree interfaces. As a result, implementing drag and drop, +sorting, and storing data is trivial. For the vast majority of trees and +lists, these two models are sufficient. For information on how to implement +your own model in Perl, see L. + +Models are accessed on a node/column level of granularity. One can query for +the value of a model at a certain node and a certain column on that node. +There are two structures used to reference a particular node in a model: +the Gtk2::TreePath and the Gtk2::TreeIter (short for "iterator"). Most of +the interface consists of operations on a Gtk2::TreeIter. + +A path is essentially a potential node. It is a location on a model that +may or may not actually correspond to a node on a specific model. The +Gtk2::TreePath object can be converted into either an array of unsigned +integers or a string. The string form is a list of numbers separated by a +colon. Each number refers to the offset at that level. Thus, the path '0' +refers to the root node and the path '2:4' refers to the fifth child of the +third node. + +By contrast, a Gtk2::TreeIter is a reference to a specific node on a specific +model. To the user of a model, the iter is merely an opaque object. +One can convert a path to an iterator by calling C. +These iterators are the primary way of accessing a model and are similar to +the iterators used by Gtk2::TextBuffer. They are generally used only for a +short time, and are valid only as long as the model is unchanged. The model +interface defines a set of operations using them for navigating the model. + +(The preceding description and most of the method descriptions have been +adapted directly from the Gtk+ C API reference.) =cut @@ -623,7 +704,7 @@ GtkTreePath *path =for apidoc -Returns a list of integers. +Returns a list of integers describing the current indices of I<$path>. =cut void gtk_tree_path_get_indices (path) @@ -643,23 +724,41 @@ ## GtkTreePath * gtk_tree_path_copy (GtkTreePath *path) ## void gtk_tree_path_free (GtkTreePath *path) +=for apidoc +Compares two paths. If I<$a> appears before I<$b> in the three, returns -1. +If I<$b> appears before I<$a>, returns 1. If the nodes are equal, returns 0. +=cut gint gtk_tree_path_compare (a, b) GtkTreePath *a GtkTreePath *b +=for apidoc +Moves I<$path> to point to the next node at the current depth. +=cut void gtk_tree_path_next (path) GtkTreePath *path +=for apidoc +Moves I<$path> to point to the previous node at the current depth, if it +exists. Returns true if there is a previous node and I<$path> was modified. +=cut gboolean gtk_tree_path_prev (path) GtkTreePath *path +=for apidoc +Moves I<$path> to point to its parent node; returns false if there is no +parent. +=cut gboolean gtk_tree_path_up (path) GtkTreePath *path +=for apidoc +Moves I<$path> to point to the first child of the current path. +=cut void gtk_tree_path_down (path) GtkTreePath *path @@ -781,6 +880,9 @@ RETVAL ## gboolean gtk_tree_model_get_iter (GtkTreeModel *tree_model, GtkTreeIter *iter, GtkTreePath *path) +=for +Returns a new Gtk2::TreeIter corresponding to I<$path>. +=cut GtkTreeIter_copy * gtk_tree_model_get_iter (tree_model, path) GtkTreeModel *tree_model @@ -799,6 +901,10 @@ ##### plain old string? ## gboolean gtk_tree_model_get_iter_from_string (GtkTreeModel *tree_model, GtkTreeIter *iter, const gchar *path_string) +=for apidoc +Returns a new iter pointing to the node described by I<$path_string>, or +undef if the path does not exist. +=cut GtkTreeIter_copy * gtk_tree_model_get_iter_from_string (tree_model, path_string) GtkTreeModel *tree_model @@ -815,6 +921,11 @@ #if GTK_CHECK_VERSION(2,2,0) ## gchar * gtk_tree_model_get_string_from_iter (GtkTreeModel *tree_model, GtkTreeIter *iter) +=for apidoc +Generates a string representation of the iter. This string is a ':' separated +list of numbers. For example, "4:10:0:3" would be an acceptable return value +for this string. +=cut gchar_own * gtk_tree_model_get_string_from_iter (tree_model, iter) GtkTreeModel *tree_model @@ -823,6 +934,10 @@ #endif /* 2.2.0 */ ## gboolean gtk_tree_model_get_iter_first (GtkTreeModel *tree_model, GtkTreeIter *iter) +=for apidoc +Return a new iter pointing to the first node in the tree (the one at path +"0"), or undef if the tree is empty. +=cut GtkTreeIter_copy * gtk_tree_model_get_iter_first (tree_model) GtkTreeModel *tree_model @@ -838,6 +953,9 @@ ### gtk_tree_model_get_iter_root is deprecated ## GtkTreePath * gtk_tree_model_get_path (GtkTreeModel *tree_model, GtkTreeIter *iter) +=for apidoc +Return a new Gtk2::TreePath corresponding to I<$iter>. +=cut GtkTreePath_own * gtk_tree_model_get_path (tree_model, iter) GtkTreeModel *tree_model @@ -903,6 +1021,11 @@ ## ## gboolean gtk_tree_model_iter_next (GtkTreeModel *tree_model, GtkTreeIter *iter) +=for apidoc +Return a new iter pointing to node following I<$iter> at the current level, +or undef if there is no next node. I<$iter> is unaltered. (Note: this is +different from the C version, which modifies the iter.) +=cut GtkTreeIter_own * gtk_tree_model_iter_next (tree_model, iter) GtkTreeModel *tree_model @@ -921,6 +1044,11 @@ RETVAL #### gboolean gtk_tree_model_iter_children (GtkTreeModel *tree_model, GtkTreeIter *iter, GtkTreeIter *parent) +=for apidoc +Returns undef if I<$parent> has no children, otherwise, returns a new iter +to the first child of I<$parent>. I<$parent> is unaltered. If I<$parent> +is undef, this is equivalent to C. +=cut GtkTreeIter_copy * gtk_tree_model_iter_children (tree_model, parent) GtkTreeModel *tree_model @@ -935,18 +1063,29 @@ RETVAL ## gboolean gtk_tree_model_iter_has_child (GtkTreeModel *tree_model, GtkTreeIter *iter) +=for apidoc +Returns true if I<$iter> has child nodes. +=cut gboolean gtk_tree_model_iter_has_child (tree_model, iter) GtkTreeModel *tree_model GtkTreeIter *iter ## gint gtk_tree_model_iter_n_children (GtkTreeModel *tree_model, GtkTreeIter *iter) +=for apidoc +Returns the number of children I<$iter> has. If I<$iter> is undef (or omitted) +then returns the number of toplevel nodes. +=cut gint gtk_tree_model_iter_n_children (tree_model, iter=NULL) GtkTreeModel *tree_model GtkTreeIter_ornull *iter ## gboolean gtk_tree_model_iter_nth_child (GtkTreeModel *tree_model, GtkTreeIter *iter, GtkTreeIter *parent, gint n) +=for apidoc +Returns an iter to the child of I<$parent> at index I<$n>, or undef if there +is no such child. I<$parent> is unaltered. +=cut GtkTreeIter_copy * gtk_tree_model_iter_nth_child (tree_model, parent, n) GtkTreeModel *tree_model @@ -962,6 +1101,10 @@ RETVAL ## gboolean gtk_tree_model_iter_parent (GtkTreeModel *tree_model, GtkTreeIter *iter, GtkTreeIter *child) +=for apidoc +Returns a new iter pointing to I<$child>'s parent node, or undef if I<$child> +doesn't have a parent. I<$child> is unaltered. +=cut GtkTreeIter_copy * gtk_tree_model_iter_parent (tree_model, child) GtkTreeModel *tree_model @@ -976,12 +1119,34 @@ RETVAL ## void gtk_tree_model_ref_node (GtkTreeModel *tree_model, GtkTreeIter *iter) +=for apidoc +Lets the tree ref the node. This is an optional method for models to implement. +To be more specific, models may ignore this call as it exists primarily for +performance reasons. + +This function is primarily meant as a way for views to let caching model know +when nodes are being displayed (and hence, whether or not to cache that node.) +For example, a file-system based model would not want to keep the entire +file-hierarchy in memory, just the sections that are currently being +displayed by every current view. + +A model should be expected to be able to get an iter independent of its reffed +state. +=cut void gtk_tree_model_ref_node (tree_model, iter) GtkTreeModel *tree_model GtkTreeIter *iter ## void gtk_tree_model_unref_node (GtkTreeModel *tree_model, GtkTreeIter *iter) +=for apidoc +Lets the tree unref the node. This is an optional method for models to +implement. To be more specific, models may ignore this call as it exists +primarily for performance reasons. + +For more information on what this means, see C. +Please note that nodes that are deleted are not unreffed. +=cut void gtk_tree_model_unref_node (tree_model, iter) GtkTreeModel *tree_model