gtktreemodel

			gtk+ reference manual
top \| description \| object hierarchy \| \| known derived interfaces \| known implementations \| signals

gtktreemodel — древовидный интерфейс используемый gtktreeview

краткое описание

#include <gtk/gtk.h>


            gtktreemodel;
            gtktreeiter;
            gtktreepath;
            gtktreerowreference;
            gtktreemodeliface;

gboolean    (*gtktreemodelforeachfunc)      (gtktreemodel *model,
                                             gtktreepath *path,
                                             gtktreeiter *iter,
                                             gpointer data);
enum        gtktreemodelflags;

gtktreepath* gtk_tree_path_new              (void);
gtktreepath* gtk_tree_path_new_from_string  (const gchar *path);
gtktreepath* gtk_tree_path_new_from_indices (gint first_index,
                                             ...);

gchar*      gtk_tree_path_to_string         (gtktreepath *path);
gtktreepath* gtk_tree_path_new_first        (void);
#define     gtk_tree_path_new_root          ()
void        gtk_tree_path_append_index      (gtktreepath *path,
                                             gint index_);
void        gtk_tree_path_prepend_index     (gtktreepath *path,
                                             gint index_);

gint        gtk_tree_path_get_depth         (gtktreepath *path);
gint*       gtk_tree_path_get_indices       (gtktreepath *path);
void        gtk_tree_path_free              (gtktreepath *path);

gtktreepath* gtk_tree_path_copy             (const gtktreepath *path);
gint        gtk_tree_path_compare           (const gtktreepath *a,
                                             const gtktreepath *b);
void        gtk_tree_path_next              (gtktreepath *path);

gboolean    gtk_tree_path_prev              (gtktreepath *path);
gboolean    gtk_tree_path_up                (gtktreepath *path);
void        gtk_tree_path_down              (gtktreepath *path);

gboolean    gtk_tree_path_is_ancestor       (gtktreepath *path,
                                             gtktreepath *descendant);
gboolean    gtk_tree_path_is_descendant     (gtktreepath *path,
                                             gtktreepath *ancestor);

gtktreerowreference* gtk_tree_row_reference_new
                                            (gtktreemodel *model,
                                             gtktreepath *path);
gtktreerowreference* gtk_tree_row_reference_new_proxy
                                            (gobject *proxy,
                                             gtktreemodel *model,
                                             gtktreepath *path);

gtktreemodel* gtk_tree_row_reference_get_model
                                            (gtktreerowreference *reference);
gtktreepath* gtk_tree_row_reference_get_path
                                            (gtktreerowreference *reference);

gboolean    gtk_tree_row_reference_valid    (gtktreerowreference *reference);
void        gtk_tree_row_reference_free     (gtktreerowreference *reference);
gtktreerowreference* gtk_tree_row_reference_copy

                                            (gtktreerowreference *reference);
void        gtk_tree_row_reference_inserted (gobject *proxy,
                                             gtktreepath *path);
void        gtk_tree_row_reference_deleted  (gobject *proxy,
                                             gtktreepath *path);
void        gtk_tree_row_reference_reordered

                                            (gobject *proxy,
                                             gtktreepath *path,
                                             gtktreeiter *iter,
                                             gint *new_order);
gtktreeiter* gtk_tree_iter_copy             (gtktreeiter *iter);
void        gtk_tree_iter_free              (gtktreeiter *iter);

gtktreemodelflags gtk_tree_model_get_flags  (gtktreemodel *tree_model);
gint        gtk_tree_model_get_n_columns    (gtktreemodel *tree_model);
gtype       gtk_tree_model_get_column_type  (gtktreemodel *tree_model,
                                             gint index_);

gboolean    gtk_tree_model_get_iter         (gtktreemodel *tree_model,
                                             gtktreeiter *iter,
                                             gtktreepath *path);
gboolean    gtk_tree_model_get_iter_from_string

                                            (gtktreemodel *tree_model,
                                             gtktreeiter *iter,
                                             const gchar *path_string);
gboolean    gtk_tree_model_get_iter_first   (gtktreemodel *tree_model,
                                             gtktreeiter *iter);
#define     gtk_tree_model_get_iter_root    (tree_model, iter)

gtktreepath* gtk_tree_model_get_path        (gtktreemodel *tree_model,
                                             gtktreeiter *iter);
void        gtk_tree_model_get_value        (gtktreemodel *tree_model,
                                             gtktreeiter *iter,
                                             gint column,
                                             gvalue *value);

gboolean    gtk_tree_model_iter_next        (gtktreemodel *tree_model,
                                             gtktreeiter *iter);
gboolean    gtk_tree_model_iter_children    (gtktreemodel *tree_model,
                                             gtktreeiter *iter,
                                             gtktreeiter *parent);

gboolean    gtk_tree_model_iter_has_child   (gtktreemodel *tree_model,
                                             gtktreeiter *iter);
gint        gtk_tree_model_iter_n_children  (gtktreemodel *tree_model,
                                             gtktreeiter *iter);

gboolean    gtk_tree_model_iter_nth_child   (gtktreemodel *tree_model,
                                             gtktreeiter *iter,
                                             gtktreeiter *parent,
                                             gint n);

gboolean    gtk_tree_model_iter_parent      (gtktreemodel *tree_model,
                                             gtktreeiter *iter,
                                             gtktreeiter *child);
gchar*      gtk_tree_model_get_string_from_iter

                                            (gtktreemodel *tree_model,
                                             gtktreeiter *iter);
void        gtk_tree_model_ref_node         (gtktreemodel *tree_model,
                                             gtktreeiter *iter);
void        gtk_tree_model_unref_node       (gtktreemodel *tree_model,
                                             gtktreeiter *iter);
void        gtk_tree_model_get              (gtktreemodel *tree_model,
                                             gtktreeiter *iter,
                                             ...);
void        gtk_tree_model_get_valist       (gtktreemodel *tree_model,
                                             gtktreeiter *iter,
                                             va_list var_args);
void        gtk_tree_model_foreach          (gtktreemodel *model,
                                             gtktreemodelforeachfunc func,
                                             gpointer user_data);
void        gtk_tree_model_row_changed      (gtktreemodel *tree_model,
                                             gtktreepath *path,
                                             gtktreeiter *iter);
void        gtk_tree_model_row_inserted     (gtktreemodel *tree_model,
                                             gtktreepath *path,
                                             gtktreeiter *iter);
void        gtk_tree_model_row_has_child_toggled

                                            (gtktreemodel *tree_model,
                                             gtktreepath *path,
                                             gtktreeiter *iter);
void        gtk_tree_model_row_deleted      (gtktreemodel *tree_model,
                                             gtktreepath *path);
void        gtk_tree_model_rows_reordered   (gtktreemodel *tree_model,
                                             gtktreepath *path,
                                             gtktreeiter *iter,
                                             gint *new_order);

иерархия объектов

  ginterface
   +----gtktreemodel

предпосылки

gtktreemodel нуждается в gobject.

известные наследуемые интерфейсы

gtktreemodel необходим gtktreesortable.

известные реализации

gtktreemodel осуществляет gtktreemodelsort, gtktreestore, gtkliststore и gtktreemodelfilter.

сигналы

"row-changed"
            void        user_function      (gtktreemodel *tree_model,
                                            gtktreepath  *path,
                                            gtktreeiter  *iter,
                                            gpointer      user_data)       : run last
"row-deleted"
            void        user_function      (gtktreemodel *tree_model,
                                            gtktreepath  *path,
                                            gpointer      user_data)       : run first
"row-has-child-toggled"
            void        user_function      (gtktreemodel *tree_model,
                                            gtktreepath  *path,
                                            gtktreeiter  *iter,
                                            gpointer      user_data)       : run last
"row-inserted"
            void        user_function      (gtktreemodel *tree_model,
                                            gtktreepath  *path,
                                            gtktreeiter  *iter,
                                            gpointer      user_data)       : run first
"rows-reordered"
            void        user_function      (gtktreemodel *tree_model,
                                            gtktreepath  *path,
                                            gtktreeiter  *iter,
                                            gpointer      arg3,
                                            gpointer      user_data)       : run first

описание

gtktreemodel интерфейс в основном определяет древовидный интерфейс для использования с виджетом gtktreeview. это абстрактный интерфейс и спроектирован для использования с любой соответствующей структурой данных. программист просто реализует этот интерфейс для своего типа данных чтобы их можно было просматривать в виджете gtktreeview.

модель представляет строго типизированную древовидную иерархию колоннообразных данных. другими словами, модель может рассматриваться как дерево где каждая ветвь имеет различные значения, в зависимости от которых делается запрос столбца. тип данных находящихся в столбце определяется с помощью системы gtype (то есть g_type_int, gtk_type_button, g_type_pointer, и т.д.). типы однородны вдоль столбца через все ветви. важно отметить, что этот интерфейс обеспечивает только способ проверки модели и наблюдения за изменениями. реализация каждой отдельной модели решает как и сделаны ли изменения.

чтобы облегчить жизнь программистам, которые не нуждаются в написании собственных специфических моделей, две основные модели обеспечивают — gtktreestore и gtkliststore. для их использования, разработчик просто помещает свои данные в них по мере необходимости. эти модели обеспечивают структуру данных также как все соответствующие древовидные интерфейсы. как результат, реализация drag and drop, сортировка и тривиальное хранение данных. для большинства списков и деревьев, эти две модели будут вполне достаточны.

доступ к моделям детализируется уровнем ветвь/колонка. можно запросить значение модели в определенной ветке и определенной колонке на этой ветке. есть две структуры используемые для ссылки на специфическую ветвь в модели. это gtktreepath и gtktreeiter .^[4] большинство интерфейсов состоят из операций с gtktreeiter.

путь – это по существу потенциальная ветвь. это положение на модели которое может или не может фактически соответствовать ветви для специфической модели. структура gtktreepath может быть преобразована в массив целых чисел или в строку. форма строки – это список чисел разделённых двоеточием. каждое число относится к смещению на этом уровне. таким образом, путь “0” ссылается на корневую ветвь, а путь “2:4” ссылается на пятый пункт третьей ветви.

в отличии от этого, gtktreeiter это ссылка на определённую ветвь в определенной модели. это основная структура с целыми числами и тремя основными указателями. они заполняют модель способом определенным моделью. можно преобразовать путь в итератор вызвав gtk_tree_model_get_iter(). эти итераторы первичный способ доступа к модели и похожи на итераторы используемые в gtktextbuffer. они в основном статично расположены в стеке и используются только в течении короткого времени. интерфейс модели определяет ряд операций используемых для управления моделью.

ожидается что модели заполняются итераторами с закрытыми данными. например, gtkliststore модель, которая внутренне является простым связанным списком, хранит список ветвей в одном из указателей. gtktreemodelsort хранит массив и смещение в двух указателях. дополнительно, есть целочисленная область. эта область в основном заполняется уникальным штампом согласно модели. это штамп для перехвата ошибок в результате использования недопустимых итераторов модели.

жизненный цикл итераторов может быть немного запутанным сначала. итераторы всегда доступны пока модель не изменяется (и не издают сигналы). модель владеет всеми невыполненными итераторами и ничего не нужно делать для их освобождения, с точки зрения пользователя. в дополнение, некоторые модели гарантируют что итераторы доступны пока ветвь к которой он обращается доступна ( gtktreestore и gtkliststore). хотя в основном не интересно, так как каждый всегда должен учитывать случай, где итераторы не сохраняются вне границ сигнала, некоторые очень важные расширения были сделаны в сортировке модели. как результат, gtk_tree_model_iters_persist флаг был добавлен для указания этого поведения.

ниже приводятся некоторые примеры, для демонстрации некоторых основных операций модели. первый пример показывает три способа получения итератора в позиции “3:2:5”. в то время как первый метод отображения прост, второй более обычен, так как вы часто получаете пути из callback-функций.

пример 1. получение gtktreeiter

/* три способа получить итератор указывающий расположение */
{
  gtktreepath *path;
  gtktreeiter iter;
  gtktreeiter parent_iter;

  /* получаем итератор из строки */
  gtk_tree_model_get_iter_from_string (model, &iter, "3:2:5");

  /* получаем итератор из пути */
  path = gtk_tree_path_new_from_string ("3:2:5");
  gtk_tree_model_get_iter (model, &iter, path);
  gtk_tree_path_free (path);


  /* проходим по дереву в поиске итератора */
  gtk_tree_model_iter_nth_child (model, &iter, null, 3);
  parent_iter = iter;
  gtk_tree_model_iter_nth_child (model, &iter, &parent_iter, 2);
  parent_iter = iter;
  gtk_tree_model_iter_nth_child (model, &iter, &parent_iter, 5);
}

это второй пример показывающий быстрый способ выполнить итерацию через список и получить строку и целое число из каждой линии. функция populate_model используемая ниже не показана, так как она определена в gtkliststore. для информации как написать такую функцию, смотрите документацию gtkliststore.

пример 2. чтение данных из gtktreemodel

enum
{
  string_column,
  int_column,
  n_columns
};

{
  gtktreemodel *list_store;
  gtktreeiter iter;
  gboolean valid;
  gint row_count = 0;

  /* создаём новый list_store */
  list_store = gtk_list_store_new (n_columns, g_type_string, g_type_int);

  /* заполняем список хранения данных */
  populate_model (list_store);

  /* получаем первый итератор в списке */
  valid = gtk_tree_model_get_iter_first (list_store, &iter);

  while (valid)
    {
      /* проходим через список, читаем каждую строку */
      gchar *str_data;
      gint   int_data;

      /* удостоверьтесь что вы закончили вызов gtk_tree_model_get()
       * значением '-1' */
      gtk_tree_model_get (list_store, &iter, 
                          string_column, &str_data,
                          int_column, &int_data,
                          -1);

      /* делаем кое-что с данными */
      g_print ("row %d: (%s,%d)\n", row_count, str_data, int_data);
      g_free (str_data);

      row_count ++;
      valid = gtk_tree_model_iter_next (list_store, &iter);
    }
}

детали

gtktreemodel

typedef struct _gtktreemodel gtktreemodel;

gtktreeiter

typedef struct {
  gint stamp;
  gpointer user_data;
  gpointer user_data2;
  gpointer user_data3;
} gtktreeiter;

gtktreeiter первичная структура доступа к структуре. ожидается что модели поместят уникальное целое число в элемент stamp, и поместят определенные моделью данные в три элемента user_data.

gint `stamp`;	уникальный штамп перехватывающий недопустимые итераторы
gpointer `user_data`;	данные определенные моделью
gpointer `user_data2`;	данные определенные моделью
gpointer `user_data3`;	данные определенные моделью

gtktreepath

typedef struct _gtktreepath gtktreepath;

gtktreerowreference

typedef struct _gtktreerowreference gtktreerowreference;

gtktreemodeliface

typedef struct {
  gtypeinterface g_iface;

  /* сигналы */
  void         (* row_changed)           (gtktreemodel *tree_model,
                                          gtktreepath  *path,
                                          gtktreeiter  *iter);
  void         (* row_inserted)          (gtktreemodel *tree_model,
                                          gtktreepath  *path,
                                          gtktreeiter  *iter);
  void         (* row_has_child_toggled) (gtktreemodel *tree_model,
                                          gtktreepath  *path,
                                          gtktreeiter  *iter);
  void         (* row_deleted)           (gtktreemodel *tree_model,
                                          gtktreepath  *path);
  void         (* rows_reordered)        (gtktreemodel *tree_model,
                                          gtktreepath  *path,
                                          gtktreeiter  *iter,
                                          gint         *new_order);

  /* виртуальная таблица */
  gtktreemodelflags (* get_flags)  (gtktreemodel *tree_model);   

  gint         (* get_n_columns)   (gtktreemodel *tree_model);
  gtype        (* get_column_type) (gtktreemodel *tree_model,
                                    gint          index_);
  gboolean     (* get_iter)        (gtktreemodel *tree_model,
                                    gtktreeiter  *iter,
                                    gtktreepath  *path);
  gtktreepath *(* get_path)        (gtktreemodel *tree_model,
                                    gtktreeiter  *iter);
  void         (* get_value)       (gtktreemodel *tree_model,
                                    gtktreeiter  *iter,
                                    gint          column,
                                    gvalue       *value);
  gboolean     (* iter_next)       (gtktreemodel *tree_model,
                                    gtktreeiter  *iter);
  gboolean     (* iter_children)   (gtktreemodel *tree_model,
                                    gtktreeiter  *iter,
                                    gtktreeiter  *parent);
  gboolean     (* iter_has_child)  (gtktreemodel *tree_model,
                                    gtktreeiter  *iter);
  gint         (* iter_n_children) (gtktreemodel *tree_model,
                                    gtktreeiter  *iter);
  gboolean     (* iter_nth_child)  (gtktreemodel *tree_model,
                                    gtktreeiter  *iter,
                                    gtktreeiter  *parent,
                                    gint          n);
  gboolean     (* iter_parent)     (gtktreemodel *tree_model,
                                    gtktreeiter  *iter,
                                    gtktreeiter  *child);
  void         (* ref_node)        (gtktreemodel *tree_model,
                                    gtktreeiter  *iter);
  void         (* unref_node)      (gtktreemodel *tree_model,
                                    gtktreeiter  *iter);
} gtktreemodeliface;

gtktreemodelforeachfunc ()

gboolean    (*gtktreemodelforeachfunc)      (gtktreemodel *model,
                                             gtktreepath *path,
                                             gtktreeiter *iter,
                                             gpointer data);

`model` :
`path` :
`iter` :
`data` :
возвращает :

enum gtktreemodelflags

typedef enum
{
  gtk_tree_model_iters_persist = 1 << 0,
  gtk_tree_model_list_only = 1 << 1
} gtktreemodelflags;

эти флаги указывают различные свойства gtktreemodel. они возвращаются функцией gtk_tree_model_get_flags(), и должны быть статичны в течении существования объекта. более полное описание gtk_tree_model_iters_persist может быть найдено в кратком описании этого раздела.

`gtk_tree_model_iters_persist`	итераторы переживающие все сигналы издаваемые деревом.
`gtk_tree_model_list_only`	модель – только список, без дочерних элементов

gtk_tree_path_new ()

gtktreepath* gtk_tree_path_new              (void);

создаёт новый gtktreepath. это структура ссылок для строк.

возвращает :

вновь созданный gtktreepath.

gtk_tree_path_new_from_string ()

gtktreepath* gtk_tree_path_new_from_string  (const gchar *path);

создаёт новый gtktreepath инициализируемый path. path должен быть списком чисел разделённых двоеточиями. например, строка "10:4:0" указывает путь глубиной в три указателя для 11-той дочерней ветки от корня, 5-ой дочерней ветки от 11-ой и 1-ой дочерней от 5-ой. если передана строка недопустимого пути, возвращается null.

`path` :	строка представляющая путь.
возвращает :	вновь созданный gtktreepath, или `null`

gtk_tree_path_new_from_indices ()

gtktreepath* gtk_tree_path_new_from_indices (gint first_index,
                                             ...);

создаёт новый путь с first_index и varargs как перечень.

`first_index` :	первое целое
`...` :	список целых заканчивающийся -1
возвращает :	вновь созданный gtktreepath.

начиная с версии 2.2

gtk_tree_path_to_string ()

gchar*      gtk_tree_path_to_string         (gtktreepath *path);

создаёт строку представляющую путь. это список чисел разделённых ':'. например, "4:10:0:3" было бы допустимым значением для этой строки.

`path` :	gtktreepath
возвращает :	вновь размещаемая строка. должна освобождаться с помощью `g_free()`.

gtk_tree_path_new_first ()

gtktreepath* gtk_tree_path_new_first        (void);

создаёт новый gtktreepath. представление строки этого пути равно "0"

возвращает :

новый gtktreepath.

gtk_tree_path_new_root()

#define gtk_tree_path_new_root() gtk_tree_path_new_first()

внимание

gtk_tree_path_new_root устарела и не должна использоваться во вновь создаваемом коде. вместо неё используйте gtk_tree_path_new_first().

альтернативное имя для gtk_tree_path_new_first(), используется только для совместимости.

возвращает :

новый gtktreepath.

gtk_tree_path_append_index ()

void        gtk_tree_path_append_index      (gtktreepath *path,
                                             gint index_);

добавляет новый индекс в конец пути. как результат, глубина пути увеличивается.

`path` :	gtktreepath.
`index_` :	индекс.

gtk_tree_path_prepend_index ()

void        gtk_tree_path_prepend_index     (gtktreepath *path,
                                             gint index_);

добавляет новый индекс в начало пути. как результат, глубина пути увеличивается.

`path` :	gtktreepath.
`index_` :	индекс.

gtk_tree_path_get_depth ()

gint        gtk_tree_path_get_depth         (gtktreepath *path);

возвращает текущую глубину path.

`path` :	gtktreepath.
возвращает :	глубина `path`

gtk_tree_path_get_indices ()

gint*       gtk_tree_path_get_indices       (gtktreepath *path);

возвращает текущий индекс path. это массив целых чисел, каждое из которых представляет ветвь дерева. это значение не должно освобождаться.

`path` :	gtktreepath.
возвращает :	текущий индекс, или `null`.

gtk_tree_path_free ()

void        gtk_tree_path_free              (gtktreepath *path);

освобождает path.

path :

gtktreepath.

gtk_tree_path_copy ()

gtktreepath* gtk_tree_path_copy             (const gtktreepath *path);

создаёт новый gtktreepath как копию path.

`path` :	gtktreepath.
возвращает :	новый gtktreepath.

gtk_tree_path_compare ()

gint        gtk_tree_path_compare           (const gtktreepath *a,
                                             const gtktreepath *b);

сравнивает два пути. если a появляется в дереве перед b, то возвращает -1. если b появляется в дереве раньше a, то возвращает 1. если обе ветви эквивалентны, возвращает 0.

`a` :	gtktreepath.
`b` :	gtktreepath с которым сравнивается.
возвращает :	относительная позиция `a` и `b`

gtk_tree_path_next ()

void        gtk_tree_path_next              (gtktreepath *path);

перемещает path в точку следующей ветки текущемй глубины.

path :

gtktreepath.

gtk_tree_path_prev ()

gboolean    gtk_tree_path_prev              (gtktreepath *path);

перемещает path в точку предыдущей ветки текущемй глубины, если возможно.

`path` :	gtktreepath.
возвращает :	`true` если `path` имеет предыдущую ветвь и перемещение было сделано.

gtk_tree_path_up ()

gboolean    gtk_tree_path_up                (gtktreepath *path);

перемещает path в точку его родительской ветви, если он имеет родителя.

`path` :	gtktreepath.
возвращает :	`true` если `path` имеет родителя и перемещение выполнено.

gtk_tree_path_down ()

void        gtk_tree_path_down              (gtktreepath *path);

перемещает path в точку первого дочернего пункта текущемго пути.

path :

gtktreepath.

gtk_tree_path_is_ancestor ()

gboolean    gtk_tree_path_is_ancestor       (gtktreepath *path,
                                             gtktreepath *descendant);

возвращает true если descendant потомок path.

`path` :	gtktreepath
`descendant` :	другой gtktreepath
возвращает :	`true` если `descendant` содержится внутри `path`

gtk_tree_path_is_descendant ()

gboolean    gtk_tree_path_is_descendant     (gtktreepath *path,
                                             gtktreepath *ancestor);

возвращает true если path потомок ancestor.

`path` :	gtktreepath
`ancestor` :	другой gtktreepath
возвращает :	`true` если `ancestor` содержит `path`

gtk_tree_row_reference_new ()

gtktreerowreference* gtk_tree_row_reference_new
                                            (gtktreemodel *model,
                                             gtktreepath *path);

создаёт строковую ссылку, основанную на path. эта ссылка будет указывать на ветвь на которую указывает path, пока он существует. она слушает все сигналы издаваемые model, и соответственно обновляет путь. если path не допустимый путь в model, то когда возвращается null.

`model` :	gtktreemodel
`path` :	допустимый gtktreepath для контроля
возвращает :	вновь размещаемый gtktreerowreference, или `null`

gtk_tree_row_reference_new_proxy ()

gtktreerowreference* gtk_tree_row_reference_new_proxy
                                            (gobject *proxy,
                                             gtktreemodel *model,
                                             gtktreepath *path);

вам не нужно использовать эту функцию. создаёт ссылку строки основанную на path. эта ссылка будет указывать на ветвь на которую указывает path, пока он существует. если path не допустимый путь в model, то когда возвращается null. однако, в отличии от ссылки созданной с помощью gtk_tree_row_reference_new(), эта не слушает модель для изменений. создающий ссылку должен сделать это явно используя gtk_tree_row_reference_inserted(), gtk_tree_row_reference_deleted(), gtk_tree_row_reference_reordered().

эти функции должны быть вызваны точно за соответствующим сигналом изданным моделью. этот единственный вызов должен обновить все ссылки строки для этого полномочия. так как созданные в gtk+ объекты, такие как gtktreeview уже используют этот механизм внутренне, использование его как полномочного объекта приведет к непредсказуемым результатам. дальше больше, помещение некоторого объекта как model и proxy не работает по причине внутренней реализации.

этот тип строковых ссылок прежде всего предназначен структурам, которые должны тщательно контролировать самостоятельное обновление строковых ссылок и в основном не нужны большинству приложений.

`proxy` :	полномочный gobject
`model` :	gtktreemodel
`path` :	допустимый gtktreepath для контроля
возвращает :	вновь созданный gtktreerowreference, или `null`

gtk_tree_row_reference_get_model ()

gtktreemodel* gtk_tree_row_reference_get_model
                                            (gtktreerowreference *reference);

возвращает модель которую контролирует строковая ссылка.

`reference` :	gtktreerowreference
возвращает :	модель

начиная с версии 2.8

gtk_tree_row_reference_get_path ()

gtktreepath* gtk_tree_row_reference_get_path
                                            (gtktreerowreference *reference);

возвращает путь который указывает в текущий момент строковая ссылка, или null если указанный путь больше не действителен.

`reference` :	gtktreerowreference
возвращает :	текущий путь, или `null`.

gtk_tree_row_reference_valid ()

gboolean    gtk_tree_row_reference_valid    (gtktreerowreference *reference);

возвращает true если reference не-null и ссылается на допустимый в текущий момент путь.

`reference` :	gtktreerowreference, или `null`
возвращает :	`true` если `reference` указывает на допустимый путь.

gtk_tree_row_reference_free ()

void        gtk_tree_row_reference_free     (gtktreerowreference *reference);

освобождает reference. reference может быть null.

reference :

gtktreerowreference, или null

gtk_tree_row_reference_copy ()

gtktreerowreference* gtk_tree_row_reference_copy
                                            (gtktreerowreference *reference);

копирует gtktreerowreference.

`reference` :	gtktreerowreference
возвращает :	копия `reference`.

начиная с версии 2.2

gtk_tree_row_reference_inserted ()

void        gtk_tree_row_reference_inserted (gobject *proxy,
                                             gtktreepath *path);

позволяет установить строковую ссылку созданную gtk_tree_row_reference_new_proxy() , узнав что модель издала сигнал "row_inserted".

`proxy` :	gobject
`path` :	позиция вставляемой строки

gtk_tree_row_reference_deleted ()

void        gtk_tree_row_reference_deleted  (gobject *proxy,
                                             gtktreepath *path);

позволяет удалить строковую ссылку созданную с помощью gtk_tree_row_reference_new_proxy(), узнав что модель издала сигнал "row_deleted".

`proxy` :	gobject
`path` :	позиция пути для удаления

gtk_tree_row_reference_reordered ()

void        gtk_tree_row_reference_reordered
                                            (gobject *proxy,
                                             gtktreepath *path,
                                             gtktreeiter *iter,
                                             gint *new_order);

позволяет установить строковую ссылку созданную gtk_tree_row_reference_new_proxy() , узнав что модель издала сигнал "rows_reordered".

`proxy` :	gobject
`path` :	родительский путь сигнала перестроения
`iter` :	итератор указывающий на родителя перестраиваемого
`new_order` :	новый порядок строк

gtk_tree_iter_copy ()

gtktreeiter* gtk_tree_iter_copy             (gtktreeiter *iter);

создаёт динамически размещаемый итератор дерева как копию iter. эта функция не предназначена для использования приложениями, потому что вы просто можете скопировать структурные значения (gtktreeiter new_iter = iter;). вы должны освобождать этот итератор с помощью gtk_tree_iter_free().

`iter` :	gtktreeiter.
возвращает :	вновь созданная копия `iter`.

gtk_tree_iter_free ()

void        gtk_tree_iter_free              (gtktreeiter *iter);

освобождает итератор который был размещен в динамической памяти. эта функция предназначена для использования в языковых привязках.

iter :

динамически размещаемый итератор дерева.

gtk_tree_model_get_flags ()

gtktreemodelflags gtk_tree_model_get_flags  (gtktreemodel *tree_model);

возвращает установки флагов поддерживаемых этим интерфейсом. флаги являются логической комбинацией gtktreemodelflags. поддерживаемые флаги не должны меняться в течении жизненного цикла tree_model.

`tree_model` :	gtktreemodel.
возвращает :	флаги которые поддерживает этот интерфейс.

gtk_tree_model_get_n_columns ()

gint        gtk_tree_model_get_n_columns    (gtktreemodel *tree_model);

возвращает число колонок поддерживаемых tree_model.

`tree_model` :	gtktreemodel.
возвращает :	число колонок.

gtk_tree_model_get_column_type ()

gtype       gtk_tree_model_get_column_type  (gtktreemodel *tree_model,
                                             gint index_);

возвращает тип колонки.

`tree_model` :	gtktreemodel.
`index_` :	номер колонки.
возвращает :	тип колонки.

gtk_tree_model_get_iter ()

gboolean    gtk_tree_model_get_iter         (gtktreemodel *tree_model,
                                             gtktreeiter *iter,
                                             gtktreepath *path);

устанавливает iter в доступный итератор указывающий path.

`tree_model` :	gtktreemodel.
`iter` :	неинициализированный gtktreeiter.
`path` :	gtktreepath.
возвращает :	`true`, если `iter` был установлен.

gtk_tree_model_get_iter_from_string ()

gboolean    gtk_tree_model_get_iter_from_string
                                            (gtktreemodel *tree_model,
                                             gtktreeiter *iter,
                                             const gchar *path_string);

устанавливает iter в допустимый итератор указывающий path_string, если существует. иначе, iter сбрасывается и возвращается false.

`tree_model` :	gtktreemodel.
`iter` :	неинициализированный gtktreeiter.
`path_string` :	строка представляющая gtktreepath.
возвращает :	`true`, если `iter` был установлен.

gtk_tree_model_get_iter_first ()

gboolean    gtk_tree_model_get_iter_first   (gtktreemodel *tree_model,
                                             gtktreeiter *iter);

инициализирует iter с первым итератором в дереве (у которого путь "0") и возвращает true. возвращает false если дерево пустое.

`tree_model` :	gtktreemodel.
`iter` :	неинициализированный gtktreeiter.
возвращает :	`true`, если `iter` был установлен.

gtk_tree_model_get_iter_root()

#define gtk_tree_model_get_iter_root(tree_model, iter) gtk_tree_model_get_iter_first(tree_model, iter)

внимание

gtk_tree_model_get_iter_root устарела и не должна использоваться во вновь создаваемом коде.

альтернативное имя для gtk_tree_model_get_iter_first(), обеспечивает совместимость; этот макрос будет удалён в следующих версиях gtk+.

`tree_model` :	gtktreemodel.
`iter` :	неинициализированный gtktreeiter.
возвращает :	`true`, если `iter` был установлен.

gtk_tree_model_get_path ()

gtktreepath* gtk_tree_model_get_path        (gtktreemodel *tree_model,
                                             gtktreeiter *iter);

возвращает вновь созданный gtktreepath, на который указывает iter. этот путь должен освобождаться с помощью gtk_tree_path_free().

`tree_model` :	gtktreemodel.
`iter` :	gtktreeiter.
возвращает :	вновь созданный gtktreepath.

gtk_tree_model_get_value ()

void        gtk_tree_model_get_value        (gtktreemodel *tree_model,
                                             gtktreeiter *iter,
                                             gint column,
                                             gvalue *value);

устанавливает инициализацию и value для этой column. когда выполнено с value, g_value_unset() нужно вызвать для освобождения любой распределенной памяти.

`tree_model` :	gtktreemodel.
`iter` :	gtktreeiter.
`column` :	колонка для поиска значения.
`value` :	пустой gvalue для установки.

gtk_tree_model_iter_next ()

gboolean    gtk_tree_model_iter_next        (gtktreemodel *tree_model,
                                             gtktreeiter *iter);

устанавливает iter указывающий на следующую ветвь текущемго уровня. если нет следующего iter, возвращается false и iter становится недоступным.

`tree_model` :	gtktreemodel.
`iter` :	gtktreeiter.
возвращает :	`true` если `iter` был изменен для следующей ветки.

gtk_tree_model_iter_children ()

gboolean    gtk_tree_model_iter_children    (gtktreemodel *tree_model,
                                             gtktreeiter *iter,
                                             gtktreeiter *parent);

устанавливает iter указывающий на первый дочерний пункт parent. если parent не имеет дочерних пунктов, false возвращается и iter становится не доступным. parent остаётся доступной ветвью после вызова этой функции.

если parent равен null возвращается первая ветвь, эквивалентно gtk_tree_model_get_iter_first (tree_model, iter);

`tree_model` :	gtktreemodel.
`iter` :	новый gtktreeiter устанавливаемый для дочернего пункта.
`parent` :	gtktreeiter, или `null`
возвращает :	`true`, если iter был установлен на первый дочерний пункт.

gtk_tree_model_iter_has_child ()

gboolean    gtk_tree_model_iter_has_child   (gtktreemodel *tree_model,
                                             gtktreeiter *iter);

возвращает true если iter имеет дочерний пункт, иначе false.

`tree_model` :	gtktreemodel.
`iter` :	gtktreeiter для проверки дочернего пункта.
возвращает :	`true` если `iter` имеет дочерний пункт.

gtk_tree_model_iter_n_children ()

gint        gtk_tree_model_iter_n_children  (gtktreemodel *tree_model,
                                             gtktreeiter *iter);

возвращает количество дочерних пунктов которые имеет iter. в особом случае, если iter равен null, то когда возвращается число ветвей верхнего уровня.

`tree_model` :	gtktreemodel.
`iter` :	gtktreeiter, или `null`.
возвращает :	число дочерних пунктов `iter`.

gtk_tree_model_iter_nth_child ()

gboolean    gtk_tree_model_iter_nth_child   (gtktreemodel *tree_model,
                                             gtktreeiter *iter,
                                             gtktreeiter *parent,
                                             gint n);

устанавливает iter для дочерних пунктов parent, используя данный индекс. первичный индекс 0. если n слишком большое, или parent не имеет дочерних пунктов, iter становится недоступным и возвращается false. parent будет действительной ветвью после вызова этой функции. в особом случае, если parent равен null, то когда n-ный корневой узел устанавливается.

`tree_model` :	gtktreemodel.
`iter` :	gtktreeiter для установки в n-ный дочерний пункт.
`parent` :	gtktreeiter из которого получается дочерний пункт, или `null`.
`n` :	номер желательного дочернего пункта.
возвращает :	`true`, если `parent` имеет `n-ое` число дочерних пунктов.

gtk_tree_model_iter_parent ()

gboolean    gtk_tree_model_iter_parent      (gtktreemodel *tree_model,
                                             gtktreeiter *iter,
                                             gtktreeiter *child);

устанавливает iter для родителя child. если child верхний уровень и не имеет родителя, то когда iter становится не доступным итератором и возвращается false. child будет доступным элементом после вызова этой функции.

`tree_model` :	gtktreemodel
`iter` :	новый gtktreeiter для установки для родителя.
`child` :	gtktreeiter.
возвращает :	`true`, если `iter` установлен для родителя `child`.

gtk_tree_model_get_string_from_iter ()

gchar*      gtk_tree_model_get_string_from_iter
                                            (gtktreemodel *tree_model,
                                             gtktreeiter *iter);

генерирует строку представляющую итератор. это список чисел разделенных ':'. например, "4:10:0:3" было бы допустимым значением этой строки.

`tree_model` :	gtktreemodel.
`iter` :	gtktreeiter.
возвращает :	вновь созданная строка. должна освобождаться с помощью `g_free()`.

начиная с версии 2.2

gtk_tree_model_ref_node ()

void        gtk_tree_model_ref_node         (gtktreemodel *tree_model,
                                             gtktreeiter *iter);

позволяет дереву ссылаться на ветвь. это дополнительный метод реализации моделей. для большей определенности, модели могут игнорировать этот вызов, так как он существует прежде всего для причин выполнения.

эта функция прежде всего предназначена для просмотра позволяя кэшируемым моделям знать когда отображать элементы (и следовательно, кэшировать или нет этот элемент.) например, модель основанная на файловой системе не хотела бы хранить в памяти всю иерархию файлов, а только разделы которые в текущий момент отображаются каждым текущим представлением (current view).

модель должна быть приспособлена для получения итератора не зависимо от состояния.

`tree_model` :	gtktreemodel.
`iter` :	gtktreeiter.

gtk_tree_model_unref_node ()

void        gtk_tree_model_unref_node       (gtktreemodel *tree_model,
                                             gtktreeiter *iter);

позволяет дереву освобождать элементы. это дополнительный метод реализации моделей. для большей определенности, модели могут игнорировать этот вызов, так как он существует прежде всего для причин выполнения.

для получения большей информации смотрите gtk_tree_model_ref_node(). пожалуйста отметьте, что удаленные элементы это не освобожденные элементы.

`tree_model` :	gtktreemodel.
`iter` :	gtktreeiter.

gtk_tree_model_get ()

void        gtk_tree_model_get              (gtktreemodel *tree_model,
                                             gtktreeiter *iter,
                                             ...);

получает значение одной или более ячеек в строке на которую ссылается iter. переменный список параметров должен содержать целочисленные номера колонок, каждый номер колонки сопровождается местом для хранения получаемого значения. список заканчивается -1. например, для получения значения из колонки 0 с типом g_type_string, вы должны написать: gtk_tree_model_get (model, iter, 0, &place_string_here, -1), где place_string_here это gchar* для заполнения строкой. если соответствует, возвращаемые значения должны быть освобождены или не ссылаемы.

`tree_model` :	gtktreemodel
`iter` :	строки в `tree_model`
`...` :	пары номер колонки и значение возвращаемого расположения, завершает -1

gtk_tree_model_get_valist ()

void        gtk_tree_model_get_valist       (gtktreemodel *tree_model,
                                             gtktreeiter *iter,
                                             va_list var_args);

смотрите gtk_tree_model_get(), эта версия берет va_list для использования в языковых привязках.

`tree_model` :	gtktreemodel
`iter` :	строки в `tree_model`
`var_args` :	список (va_list) пар столбец/возвращаемое расположение

gtk_tree_model_foreach ()

void        gtk_tree_model_foreach          (gtktreemodel *model,
                                             gtktreemodelforeachfunc func,
                                             gpointer user_data);

вызывает функцию func на каждом элементе модели. если func возвращает true, то проходы по дереву прекращаются, и gtk_tree_model_foreach() возвращает true.

`model` :	gtktreemodel
`func` :	функция вызываемая для каждого элемента
`user_data` :	пользовательские данные помещаемые в функцию func.

gtk_tree_model_row_changed ()

void        gtk_tree_model_row_changed      (gtktreemodel *tree_model,
                                             gtktreepath *path,
                                             gtktreeiter *iter);

издаёт сигнал "row_changed" в tree_model.

`tree_model` :	gtktreemodel
`path` :	gtktreepath указатель для измененной строки
`iter` :	допустимый gtktreeiter указатель для измененной строки

gtk_tree_model_row_inserted ()

void        gtk_tree_model_row_inserted     (gtktreemodel *tree_model,
                                             gtktreepath *path,
                                             gtktreeiter *iter);

издаёт сигнал "row_inserted" в tree_model

`tree_model` :	a gtktreemodel
`path` :	gtktreepath указатель для измененной строки
`iter` :	допустимый gtktreeiter указатель для вставляемой строки

gtk_tree_model_row_has_child_toggled ()

void        gtk_tree_model_row_has_child_toggled
                                            (gtktreemodel *tree_model,
                                             gtktreepath *path,
                                             gtktreeiter *iter);

издаёт сигнал "row_has_child_toggled" в tree_model. она вызывается моделью после того, как изменится состояние дочернего элмента.

`tree_model` :	gtktreemodel
`path` :	gtktreepath указатель для измененной строки
`iter` :	допустимый gtktreeiter указатель для измененной строки

gtk_tree_model_row_deleted ()

void        gtk_tree_model_row_deleted      (gtktreemodel *tree_model,
                                             gtktreepath *path);

издаёт сигнал "row_deleted" в tree_model. должна вызываться моделью после удаления строк. положение на которое указывает path должно быть положением строки перед удалением. в последствии оно может быть недопустимым положением.

`tree_model` :	gtktreemodel
`path` :	gtktreepath указатель для измененной строки

gtk_tree_model_rows_reordered ()

void        gtk_tree_model_rows_reordered   (gtktreemodel *tree_model,
                                             gtktreepath *path,
                                             gtktreeiter *iter,
                                             gint *new_order);

издаёт сигнал "rows_reordered" в tree_model. вызывается моделью когда её строки перестраиваются.

`tree_model` :	gtktreemodel
`path` :	gtktreepath указатель элемента дерева где перестраиваются дочерние элементы
`iter` :	допустимый gtktreeiter указатель для элемента где перестроены дочерние элементы, или `null` если глубина `path` равна 0.
`new_order` :	массив целочисленных указывающих текущую позицию каждого дочернего элемента относительно его старой позиции перед переупорядочением, то есть `new_order[newpos] = oldpos`.

детали сигналов

сигнал "row-changed"

void        user_function                  (gtktreemodel *tree_model,
                                            gtktreepath  *path,
                                            gtktreeiter  *iter,
                                            gpointer      user_data)       : run last

этот сигнал издаётся когда в модели изменяется строка.

`tree_model` :	gtktreemodel который издал сигнал
`path` :	gtktreepath идентифицирующий изменяемую строку
`iter` :	допустимый gtktreeiter указатель для измененной строки
`user_data` :	пользовательские данные устанавливаемые при подключении обработчика сигнала.

сигнал "row-deleted"

void        user_function                  (gtktreemodel *tree_model,
                                            gtktreepath  *path,
                                            gpointer      user_data)       : run first

этот сигнал издаётся когда строка удаляется.

помните что никакой итератор не передаётся для обработчика сигнала, та как строка уже удалена.

`tree_model` :	gtktreemodel который издал сигнал
`path` :	gtktreepath идентифицирующий строку
`user_data` :	пользовательские данные устанавливаемые при подключении обработчика сигнала.

сигнал "row-has-child-toggled"

void        user_function                  (gtktreemodel *tree_model,
                                            gtktreepath  *path,
                                            gtktreeiter  *iter,
                                            gpointer      user_data)       : run last

издаётся когда строка получила первую дочернюю строку или потеряна её последняя строка.

`tree_model` :	gtktreemodel который издал сигнал
`path` :	gtktreepath идентифицирующий строку
`iter` :	допустимый gtktreeiter указатель для строки
`user_data` :	пользовательские данные устанавливаемые при подключении обработчика сигнала.

сигнал "row-inserted"

void        user_function                  (gtktreemodel *tree_model,
                                            gtktreepath  *path,
                                            gtktreeiter  *iter,
                                            gpointer      user_data)       : run first

издаётся когда новая строка вставлена в модель.

помните что строка в этой точке может быть ещё пустой, так как это обычный шаблон для вставки первой пустой строки, а затем заполнения нужными значениями.

`tree_model` :	gtktreemodel который издал сигнал
`path` :	gtktreepath идентифицирующий новую строку
`iter` :	допустимый gtktreeiter указатель для новой строки
`user_data` :	пользовательские данные устанавливаемые при подключении обработчика сигнала.

сигнал "rows-reordered"

void        user_function                  (gtktreemodel *tree_model,
                                            gtktreepath  *path,
                                            gtktreeiter  *iter,
                                            gpointer      arg3,
                                            gpointer      user_data)       : run first

издаётся когда дочерние элементы в gtktreemodel перестраиваются.

помните, этот сигнал не издаётся когда строки перестраиваются с помощью dnd, так как при этом осуществляется удаление и последующая вставка строки.

`tree_model` :	gtktreemodel который издал сигнал
`path` :	gtktreepath идентифицирующий дерево элементов в котором дочерние элементы были перестроены
`iter` :	допустимый gtktreeiter указывающий на элемент
`user_data` :	пользовательские данные устанавливаемые при подключении обработчика сигнала.

^[4]iter сокращение для “iterator”