Commit 10e9727a authored by 7's avatar 7 Committed by Jonathan Blandford

Added user docs.

2000-10-17    <jrb@redhat.com>

	* gtk/gtktreemodel.c: Added user docs.

	* gtk/gtk.h: remove gtktreedatalist.h.
parent 77d01658
2000-10-17 <jrb@redhat.com>
* gtk/gtktreemodel.c: Added user docs.
* gtk/gtk.h: remove gtktreedatalist.h.
* gtk/gtktreestore.c (gtk_tree_store_get_type): Get the correct
parent when generating my type.
......
2000-10-17 <jrb@redhat.com>
* gtk/gtktreemodel.c: Added user docs.
* gtk/gtk.h: remove gtktreedatalist.h.
* gtk/gtktreestore.c (gtk_tree_store_get_type): Get the correct
parent when generating my type.
......
2000-10-17 <jrb@redhat.com>
* gtk/gtktreemodel.c: Added user docs.
* gtk/gtk.h: remove gtktreedatalist.h.
* gtk/gtktreestore.c (gtk_tree_store_get_type): Get the correct
parent when generating my type.
......
2000-10-17 <jrb@redhat.com>
* gtk/gtktreemodel.c: Added user docs.
* gtk/gtk.h: remove gtktreedatalist.h.
* gtk/gtktreestore.c (gtk_tree_store_get_type): Get the correct
parent when generating my type.
......
2000-10-17 <jrb@redhat.com>
* gtk/gtktreemodel.c: Added user docs.
* gtk/gtk.h: remove gtktreedatalist.h.
* gtk/gtktreestore.c (gtk_tree_store_get_type): Get the correct
parent when generating my type.
......
2000-10-17 <jrb@redhat.com>
* gtk/gtktreemodel.c: Added user docs.
* gtk/gtk.h: remove gtktreedatalist.h.
* gtk/gtktreestore.c (gtk_tree_store_get_type): Get the correct
parent when generating my type.
......
2000-10-17 <jrb@redhat.com>
* gtk/gtktreemodel.c: Added user docs.
* gtk/gtk.h: remove gtktreedatalist.h.
* gtk/gtktreestore.c (gtk_tree_store_get_type): Get the correct
parent when generating my type.
......
......@@ -139,7 +139,6 @@
#include <gtk/gtktooltips.h>
#include <gtk/gtktree.h>
#include <gtk/gtktreeitem.h>
#include <gtk/gtktreedatalist.h>
#include <gtk/gtktreemodel.h>
#include <gtk/gtktreeselection.h>
#include <gtk/gtktreestore.h>
......
......@@ -48,6 +48,14 @@ gtk_tree_model_get_type (void)
return tree_model_type;
}
/**
* gtk_tree_path_new:
* @void:
*
* Creates a new #GtkTreePath.
*
* Return value: A newly created #GtkTreePath.
**/
/* GtkTreePath Operations */
GtkTreePath *
gtk_tree_path_new (void)
......@@ -60,6 +68,16 @@ gtk_tree_path_new (void)
return retval;
}
/**
* gtk_tree_path_new_from_string:
* @path: The string representation of a path.
*
* Creates a new #GtkTreePath initialized to @path. @path is expected to be a
* colon separated list of numbers. For example, the string "10:4:0" would
* create a path of depth 3.
*
* Return value: A newly created #GtkTreePath.
**/
GtkTreePath *
gtk_tree_path_new_from_string (gchar *path)
{
......@@ -78,12 +96,22 @@ gtk_tree_path_new_from_string (gchar *path)
if (*ptr == '\000')
break;
/* FIXME: should we error out if this is not a ':', or should we be tolerant? */
path = ptr + 1;
}
return retval;
}
/**
* gtk_tree_path_to_string:
* @path: A #GtkTreePath
*
* Generates a string representation of the path. This string is a ':'
* separated list of numbers. For example, "4:10:0:3" would be an acceptable return value for this string.
*
* Return value: A newly allocated string. Must be freed with #g_free.
**/
gchar *
gtk_tree_path_to_string (GtkTreePath *path)
{
......@@ -108,6 +136,15 @@ gtk_tree_path_to_string (GtkTreePath *path)
return retval;
}
/**
* gtk_tree_path_new_root:
* @void:
*
* Creates a new root #GtkTreePath. The string representation of this path is
* "0"
*
* Return value: A new #GtkTreePath.
**/
GtkTreePath *
gtk_tree_path_new_root (void)
{
......@@ -119,11 +156,24 @@ gtk_tree_path_new_root (void)
return retval;
}
/**
* gtk_tree_path_append_index:
* @path: A #GtkTreePath.
* @index: The index.
*
* Appends a new index to a path. As a result, the depth of the path is
* increased.
**/
void
gtk_tree_path_append_index (GtkTreePath *path,
gint index)
{
gint *new_indices = g_new (gint, ++path->depth);
gint *new_indices;
g_return_if_fail (path != NULL);
g_return_if_fail (index >= 0);
new_indices = = g_new (gint, ++path->depth);
if (path->indices == NULL)
{
path->indices = new_indices;
......@@ -137,6 +187,14 @@ gtk_tree_path_append_index (GtkTreePath *path,
path->indices[path->depth - 1] = index;
}
/**
* gtk_tree_path_prepend_index:
* @path: A #GtkTreePath.
* @index: The index.
*
* Prepends a new index to a path. As a result, the depth of the path is
* increased.
**/
void
gtk_tree_path_prepend_index (GtkTreePath *path,
gint index)
......@@ -154,18 +212,45 @@ gtk_tree_path_prepend_index (GtkTreePath *path,
path->indices[0] = index;
}
/**
* gtk_tree_path_get_depth:
* @path: A #GtkTreePath.
*
* Returns the current depth of @path.
*
* Return value: The depth of @path
**/
gint
gtk_tree_path_get_depth (GtkTreePath *path)
{
g_return_val_if_fail (path != NULL, 0);
return path->depth;
}
/**
* gtk_tree_path_get_indices:
* @path: A #GtkTreePath.
*
* Returns the current indices of @path. This is an array of integers, each
* representing a node in a tree.
*
* Return value: The current indices, or NULL.
**/
gint *
gtk_tree_path_get_indices (GtkTreePath *path)
{
g_return_val_if_fail (path != NULL, NULL);
return path->indices;
}
/**
* gtk_tree_path_free:
* @path: A #GtkTreePath.
*
* Frees @path.
**/
void
gtk_tree_path_free (GtkTreePath *path)
{
......@@ -173,6 +258,14 @@ gtk_tree_path_free (GtkTreePath *path)
g_free (path);
}
/**
* gtk_tree_path_copy:
* @path: A #GtkTreePath.
*
* Creates a new #GtkTreePath based upon @path.
*
* Return value: A new #GtkTreePath.
**/
GtkTreePath *
gtk_tree_path_copy (GtkTreePath *path)
{
......@@ -185,9 +278,20 @@ gtk_tree_path_copy (GtkTreePath *path)
return retval;
}
/**
* gtk_tree_path_compare:
* @a: A #GtkTreePath.
* @b: A #GtkTreePath to compare with.
*
* Compares two paths. If @a appears before @b in a tree, then 1, is returned.
* If @b appears before @a, then -1 is returned. If the two nodes are equal,
* then 0 is returned.
*
* Return value: The relative positions of @a and @b
**/
gint
gtk_tree_path_compare (GtkTreePath *a,
GtkTreePath *b)
gtk_tree_path_compare (const GtkTreePath *a,
const GtkTreePath *b)
{
gint p = 0, q = 0;
......@@ -208,14 +312,27 @@ gtk_tree_path_compare (GtkTreePath *a,
return (a->depth < b->depth?1:-1);
}
/**
* gtk_tree_path_next:
* @path: A #GtkTreePath.
*
* Moves the @path to point to the next node at the current depth.
**/
void
gtk_tree_path_next (GtkTreePath *path)
{
g_return_if_fail (path != NULL);
g_return_if_fail (path->depth > 0);
path->indices[path->depth - 1] ++;
}
/**
* gtk_tree_path_prev:
* @path: A #GtkTreePath.
*
* Moves the @path to point to the previous node at the current depth, if it exists.
**/
gint
gtk_tree_path_prev (GtkTreePath *path)
{
......@@ -229,6 +346,14 @@ gtk_tree_path_prev (GtkTreePath *path)
return TRUE;
}
/**
* gtk_tree_path_up:
* @path: A #GtkTreePath.
*
* Moves the @path to point to it's parent node, if it has a parent.
*
* Return value: TRUE if @path has a parent, and the move was made.
**/
gint
gtk_tree_path_up (GtkTreePath *path)
{
......@@ -242,6 +367,12 @@ gtk_tree_path_up (GtkTreePath *path)
return TRUE;
}
/**
* gtk_tree_path_down:
* @path: A #GtkTreePath.
*
* Moves @path to point to the first child of the current path.
**/
void
gtk_tree_path_down (GtkTreePath *path)
{
......@@ -250,6 +381,14 @@ gtk_tree_path_down (GtkTreePath *path)
gtk_tree_path_append_index (path, 0);
}
/**
* gtk_tree_model_get_n_columns:
* @tree_model: A #GtkTreeModel.
*
* Returns the number of columns supported by the #tree_model
*
* Return value: The number of columns.
**/
gint
gtk_tree_model_get_n_columns (GtkTreeModel *tree_model)
{
......@@ -257,7 +396,16 @@ gtk_tree_model_get_n_columns (GtkTreeModel *tree_model)
return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->get_n_columns) (tree_model);
}
/* Node options */
/**
* gtk_tree_model_get_node:
* @tree_model: A #GtkTreeModel.
* @path: The @GtkTreePath.
*
* Returns a #GtkTreeNode located at @path. If such a node does not exist, NULL
* is returned.
*
* Return value: A #GtkTreeNode located at @path, or NULL.
**/
GtkTreeNode
gtk_tree_model_get_node (GtkTreeModel *tree_model,
GtkTreePath *path)
......@@ -266,6 +414,16 @@ gtk_tree_model_get_node (GtkTreeModel *tree_model,
return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->get_node) (tree_model, path);
}
/**
* gtk_tree_model_get_path:
* @tree_model: A #GtkTreeModel.
* @node: The #GtkTreeNode.
*
* Returns a newly created #GtkTreePath that points to @node. This path should
* be freed with #gtk_tree_path_free.
*
* Return value: a newly created #GtkTreePath.
**/
GtkTreePath *
gtk_tree_model_get_path (GtkTreeModel *tree_model,
GtkTreeNode node)
......@@ -274,16 +432,36 @@ gtk_tree_model_get_path (GtkTreeModel *tree_model,
return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->get_path) (tree_model, node);
}
/**
* gtk_tree_model_node_get_value:
* @tree_model: A #GtkTreeModel.
* @node: The #GtkTreeNode.
* @column: A column on the node.
* @value: An empty #GValue to set.
*
* Sets initializes and sets @value to that at @column. When done with value,
* #g_value_unset needs to be called on it.
**/
void
gtk_tree_model_node_get_value (GtkTreeModel *tree_model,
GtkTreeNode node,
gint column,
GValue *value)
gint column,
GValue *value)
{
g_return_if_fail (GTK_TREE_MODEL_GET_IFACE (tree_model)->node_get_value != NULL);
(* GTK_TREE_MODEL_GET_IFACE (tree_model)->node_get_value) (tree_model, node, column, value);
}
/**
* gtk_tree_model_node_next:
* @tree_model: A #GtkTreeModel.
* @node: A reference to a #GtkTreeNode.
*
* Sets @node to be the node following it at the current level. If there is no
* next @node, FALSE is returned, and *@node is set to NULL.
*
* Return value: TRUE if @node has been changed to the next node.
**/
gboolean
gtk_tree_model_node_next (GtkTreeModel *tree_model,
GtkTreeNode *node)
......@@ -292,6 +470,16 @@ gtk_tree_model_node_next (GtkTreeModel *tree_model,
return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->node_next) (tree_model, node);
}
/**
* gtk_tree_model_node_children:
* @tree_model: A #GtkTreeModel.
* @node: The #GtkTreeNode to get children from.
*
* Returns the first child node of @node. If it has no children, then NULL is
* returned.
*
* Return value: The first child of @node, or NULL.
**/
GtkTreeNode
gtk_tree_model_node_children (GtkTreeModel *tree_model,
GtkTreeNode node)
......@@ -300,6 +488,15 @@ gtk_tree_model_node_children (GtkTreeModel *tree_model,
return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->node_children) (tree_model, node);
}
/**
* gtk_tree_model_node_has_child:
* @tree_model: A #GtkTreeModel.
* @node: The #GtkTreeNode to test for children.
*
* Returns TRUE if @node has children, FALSE otherwise.
*
* Return value: TRUE if @node has children.
**/
gboolean
gtk_tree_model_node_has_child (GtkTreeModel *tree_model,
GtkTreeNode node)
......@@ -308,6 +505,15 @@ gtk_tree_model_node_has_child (GtkTreeModel *tree_model,
return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->node_has_child) (tree_model, node);
}
/**
* gtk_tree_model_node_n_children:
* @tree_model: A #GtkTreeModel.
* @node: The #GtkTreeNode.
*
* Returns the number of children that @node has.
*
* Return value: The number of children of @node.
**/
gint
gtk_tree_model_node_n_children (GtkTreeModel *tree_model,
GtkTreeNode node)
......@@ -316,15 +522,35 @@ gtk_tree_model_node_n_children (GtkTreeModel *tree_model,
return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->node_n_children) (tree_model, node);
}
/**
* gtk_tree_model_node_nth_child:
* @tree_model: A #GtkTreeModel.
* @node: The #GtkTreeNode to get the child from.
* @n: The index of the desired #GtkTreeNode.
*
* Returns a child of @node, using the given index. The first index is 0. If
* the index is too big, NULL is returned.
*
* Return value: the child of @node at index @n.
**/
GtkTreeNode
gtk_tree_model_node_nth_child (GtkTreeModel *tree_model,
GtkTreeNode node,
gint n)
gint n)
{
g_return_val_if_fail (GTK_TREE_MODEL_GET_IFACE (tree_model)->node_nth_child != NULL, NULL);
return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->node_nth_child) (tree_model, node, n);
}
/**
* gtk_tree_model_node_parent:
* @tree_model: A #GtkTreeModel.
* @node: The #GtkTreeNode.
*
* Returns the parent of @node. If @node is at depth 0, then NULL is returned.
*
* Return value: Returns the parent node of @node, or NULL.
**/
GtkTreeNode
gtk_tree_model_node_parent (GtkTreeModel *tree_model,
GtkTreeNode node)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment