Create  Edit  FrontPage  Index  Search  Changes  History  RSS  Back  Login

Gtk::TreeModel Diff - Ruby-GNOME2 Project Website

  • Added parts are displayed like this.
  • Deleted parts are displayed like this.

= module Gtk::TreeModel

The Gtk::TreeModel interface defines a generic tree interface for use by the Gtk::TreeView widget. It is an abstract interface, and is designed to be usable with any appropriate data structure. structure.

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 Ruby Class (ie. Object, Integer, Float, String, Hash, Gdk::Pixbuf, etc.). The types are homogeneous per column across all nodes.

In order to make life simpler for programmers who do not need to write their own specialized model, model (which is ((<not possible in Ruby|URL:http://www.ruby-forum.com/topic/114021>)) as of ruby-gnome2 version 0.19.3), two generic models are provided the Gtk::TreeStore and the Gtk::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.

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. They are the Gtk::TreePath and the Gtk::TreeIter. Most of the interface consists of operations on a Gtk::TreeIter.

== Included Modules

  * GLib::Interface

== Instance Methods

--- flags

    Gets a set of flags supported by this interface. The flags are a bitwise combination of ((<GtkTreeModelFlags|Gtk::TreeModel#GtkTreeModelFlags>)). The flags supported should not change during the lifecycle of the tree_model.
    * Returns: The flags supported by this interface.

--- n_columns

    Gets the number of columns supported by the tree_model.
    * Returns: The number of columns.

--- get_column_type(index)

    Gets the type of the column.
    * index: The column index.
    * Returns: The type of the column.

--- iter_first

    Gets the first iterator in the tree (the one at the path "0") and returns true. Returns false if the tree is empty.
    * Returns: Gtk::TreeIter or nil

--- get_iter(path)

    Gets the iter to a valid iterator pointing to path.
    * path : The Gtk::TreePath or a String representation of a Gtk::TreePath.
    * Returns: Gtk::TreeIter or nil

--- get_value(iter, column)

    Gets value to that at column. Use Gtk::TreeIter#get_value instead.
    * iter : The Gtk::TreeIter.
    * column : The column to lookup the value at.
    * Returns: The value

--- each {|model, path, iter| ... }

    Calls block on each node in model in a depth-first fashion.
    * {|model, path, iter| ... }: block to call
       * model: Gtk::TreeModel
       * path: Gtk::TreePath
       * iter: Gtk::TreeIter
    * Returns: self

--- row_changed(path, iter)

    Emits the "row_changed" signal on tree_model.
    * path: A Gtk::TreePath pointing to the changed row
    * iter: A valid Gtk::TreeIter pointing to the changed row
    * Returns: self

--- row_inserted(path, iter)

    Emits the "row_inserted" signal on tree_model
    * path: A Gtk::TreePath pointing to the inserted row
    * iter: A valid Gtk::TreeIter pointing to the inserted row
    * Returns: self

--- row_has_child_toggled(path, iter)

    Emits the "row_has_child_toggled" signal on tree_model. This should be called by models after the child state of a node changes.
    * path: A Gtk::TreePath pointing to the changed row
    * iter: A valid Gtk::TreeIter pointing to the changed row
    * Returns: self

--- row_deleted(path)

    Emits the "row_deleted" signal on tree_model. This should be called by models after a row has been removed. The location pointed to by path should be the location that the row previously was at. It may not be a valid location anymore.
    * path : A Gtk::TreePath pointing to the previous location of the deleted row.
    * Returns: self

--- rows_reordered(path, iter, new_order)

    Emits the "rows_reordered" signal on tree_model. This should be called by models when their rows have been reordered.
    * path : A Gtk::TreePath pointing to the tree node whose children have been reordered
    * iter : A valid Gtk::TreeIter pointing to the node whose children have been reordered
    * new_order : an array of integers containing the new indices of the children, i.e. the former child n is now at position new_order[n].  
    * Returns: self

--- iter_is_valid?

     * Returns: self: ((*FIXME*))

== Constants

=== GtkTreeModelFlags

These flags indicate various properties of a Gtk::TreeModel. They are returned by Gtk::TreeModel#flags, and must be static for the lifetime of the object. A more complete description of Gtk::TreeModel::ITERS_PERSIST can be found in the overview of this section.

--- ITERS_PERSIST

    Iterators survive all signals emitted by the tree.

--- LIST_ONLY

    The model is a list only, and never has children.

== Signals

--- row-changed: self, path, iter

     * self: A Gtk::TreeModel
     * path: A Gtk::TreePath pointing to the changed row
     * iter: A valid Gtk::TreeIter pointing to the changed row

--- row-inserted: self, path, iter

     * self: A Gtk::TreeModel
     * path: A Gtk::TreePath pointing to the changed row
     * iter: A valid Gtk::TreeIter pointing to the changed row

--- row-has-child-toggled: self, path, iter

     * self: A Gtk::TreeModel
     * path: A Gtk::TreePath pointing to the changed row
     * iter: A valid Gtk::TreeIter pointing to the changed row

--- row-deleted: self, path

     * self: A Gtk::TreeModel
     * path: A Gtk::TreePath pointing to the changed row

--- rows-reordered: self, path, iter, new_order

     * self: A Gtk::TreeModel
     * path: A Gtk::TreePath pointing to the changed row
     * iter: A valid Gtk::TreeIter pointing to the changed row
     * new_order : an array of integers containing the new indices of the children, i.e. the former child n is now at position new_order[n].

== See Also

Gtk::TreeView, Gtk::TreeStore, Gtk::ListStore, Gtk::TreeSortable

== ChangeLog

-((<Masao>))