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

#include <gtk/gtk.h>


            gtkliststore;
gtkliststore* gtk_list_store_new            (gint n_columns,
                                             ...);

gtkliststore* gtk_list_store_newv           (gint n_columns,
                                             gtype *types);
void        gtk_list_store_set_column_types (gtkliststore *list_store,
                                             gint n_columns,
                                             gtype *types);
void        gtk_list_store_set              (gtkliststore *list_store,
                                             gtktreeiter *iter,
                                             ...);
void        gtk_list_store_set_valist       (gtkliststore *list_store,
                                             gtktreeiter *iter,
                                             va_list var_args);
void        gtk_list_store_set_value        (gtkliststore *list_store,
                                             gtktreeiter *iter,
                                             gint column,
                                             gvalue *value);

gboolean    gtk_list_store_remove           (gtkliststore *list_store,
                                             gtktreeiter *iter);
void        gtk_list_store_insert           (gtkliststore *list_store,
                                             gtktreeiter *iter,
                                             gint position);
void        gtk_list_store_insert_before    (gtkliststore *list_store,
                                             gtktreeiter *iter,
                                             gtktreeiter *sibling);
void        gtk_list_store_insert_after     (gtkliststore *list_store,
                                             gtktreeiter *iter,
                                             gtktreeiter *sibling);
void        gtk_list_store_insert_with_values

                                            (gtkliststore *list_store,
                                             gtktreeiter *iter,
                                             gint position,
                                             ...);
void        gtk_list_store_insert_with_valuesv
                                            (gtkliststore *list_store,
                                             gtktreeiter *iter,
                                             gint position,
                                             gint *columns,
                                             gvalue *values,
                                             gint n_values);
void        gtk_list_store_prepend          (gtkliststore *list_store,
                                             gtktreeiter *iter);
void        gtk_list_store_append           (gtkliststore *list_store,
                                             gtktreeiter *iter);
void        gtk_list_store_clear            (gtkliststore *list_store);

gboolean    gtk_list_store_iter_is_valid    (gtkliststore *list_store,
                                             gtktreeiter *iter);
void        gtk_list_store_reorder          (gtkliststore *store,
                                             gint *new_order);
void        gtk_list_store_swap             (gtkliststore *store,
                                             gtktreeiter *a,
                                             gtktreeiter *b);
void        gtk_list_store_move_before      (gtkliststore *store,
                                             gtktreeiter *iter,
                                             gtktreeiter *position);
void        gtk_list_store_move_after       (gtkliststore *store,
                                             gtktreeiter *iter,
                                             gtktreeiter *position);

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

  gobject
   +----gtkliststore

осуществляемые интерфейсы

gtkliststore осуществляет gtktreemodel, gtktreedragsource, gtktreedragdest и gtktreesortable.

описание

объект gtkliststore это модель списка используемый с виджетом gtktreeview. он осуществляет gtktreemodel интерфейс и логически может использовать все методы доступные там. он также осуществляет gtktreesortable интерфейс, поэтому может быть отсортирован. наконец, он осуществляет интерфейс drag and drop.

gtkliststore может применить большинство типов gobject как тип столбца, однако он не может применять обычные типы. внутри он сохраняет копию помещаемых данных(такие как строка или контейнерный указатель). столбцы которые применяют gobjects обрабатываются немного по другому. gtkliststore сохраняет ссылку на объект вместо копии значения. как результат, если объект изменён, вызывается gtk_tree_model_row_changed издавая сигнал "row_changed". это обычно касается списков с сохранёнными gdkpixbufs.

пример 5. создание простого списка хранения.

enum {
  column_string,
  column_int,
  column_boolean,
  n_columns
};

{
  gtkliststore *list_store;
  gtktreepath *path;
  gtktreeiter iter;
  gint i;

  list_store = gtk_list_store_new (n_columns,
                                   g_type_string,
                                   g_type_int,
                                   g_type_boolean);

  for (i = 0; i < 10; i++)
    {
      gchar *some_data;

      some_data = get_some_data (i);

      /* добавляем новую строку в модель */
      gtk_list_store_append (list_store, &iter);
      gtk_list_store_set (list_store, &iter,
                          column_string, some_data,
                          column_int, i,
                          column_boolean,  false,
                          -1);

      /* поскольку сохраняется копия строки, мы
       * освобождаем some_data.
       */
      g_free (some_data);
    }

  /* изменяем специфическую строку */
  path = gtk_tree_path_new_from_string ("4");
  gtk_tree_model_get_iter (gtk_tree_model (list_store),
                           &iter,
                           path);
  gtk_tree_path_free (path);
  gtk_list_store_set (list_store, &iter,
                      column_boolean, true,
                      -1);
}

разбор выполнения

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

атомарные операции

важно отметить, что только методы gtk_list_store_insert_with_values и gtk_list_store_insert_with_valuesv являются атомарными, в смысле что строка прилагается к хранению и поля заполняются значениями с помощью единственной операции учитывающей сигналы gtktreemodel. в отличии от использования например gtk_list_store_append и затем gtk_list_store_set которые сначала создадут строку, которая переключит сигнал "row_inserted" gtktreemodel в gtkliststore. однако строка ещё пуста и любой обработчик сигнала подключаемый к "row_inserted" в этом специфическом хранилище должен предполагать ситуацию что строка может быть пуста. это особенно важно если вы оборачиваете gtkliststore в gtktreemodelfilter и используете gtktreemodelfiltervisiblefunc. используя любую не атомарную операцию для прикрепления строк к gtkliststore заставит gtktreemodelfiltervisiblefunc сначала обратиться к пустой строке; функция должна быть к этому готова.

детали

gtkliststore

typedef struct _gtkliststore gtkliststore;

gtk_list_store_new ()

gtkliststore* gtk_list_store_new            (gint n_columns,
                                             ...);

создаёт новый список хранения n_columns столбцов и помещением каждого типа. помните, поддерживаются только стандартные базовые типы из gobject.

как пример, gtk_tree_store_new (3, g_type_int, g_type_string, gdk_type_pixbuf); создаст новый gtkliststore с тремя столбцами, типов int, string и gdkpixbuf соответственно.

gtk_list_store_newv ()

gtkliststore* gtk_list_store_newv           (gint n_columns,
                                             gtype *types);

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

gtk_list_store_set_column_types ()

void        gtk_list_store_set_column_types (gtkliststore *list_store,
                                             gint n_columns,
                                             gtype *types);

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

gtk_list_store_set ()

void        gtk_list_store_set              (gtkliststore *list_store,
                                             gtktreeiter *iter,
                                             ...);

устанавливает значение одной или более ячеек в строке указанной iter. список переменных аргументов должен содержать целое число столбцов, каждый номер столбца сопровождается устанавливаемым значением. список заканчивается -1. например, для установки столбца 0 с типом g_type_string в значение "foo", вы должны написать gtk_list_store_set (store, iter, 0, "foo", -1).

gtk_list_store_set_valist ()

void        gtk_list_store_set_valist       (gtkliststore *list_store,
                                             gtktreeiter *iter,
                                             va_list var_args);

смотрите gtk_list_store_set(); эта версия имеет va_list для использования языковыми привязками.

gtk_list_store_set_value ()

void        gtk_list_store_set_value        (gtkliststore *list_store,
                                             gtktreeiter *iter,
                                             gint column,
                                             gvalue *value);

устанавливает данные в ячейку определенную iter и column. тип value должен конвертироваться к типу столбца.

gtk_list_store_remove ()

gboolean    gtk_list_store_remove           (gtkliststore *list_store,
                                             gtktreeiter *iter);

удаляет строку из списка хранения. после удаления, iter устанавливается в следующую доступную строку, или отменяется если он указывал на последнюю строку в list_store.

gtk_list_store_insert ()

void        gtk_list_store_insert           (gtkliststore *list_store,
                                             gtktreeiter *iter,
                                             gint position);

создаёт новую строку в position. iter изменяется для указания на новую строку. если position больше чем количество строк в списке, новая строка добавляется в список. строка будет пустой после вызова этой функции. для заполнения значений вы должны вызвать gtk_list_store_set() или gtk_list_store_set_value().

gtk_list_store_insert_before ()

void        gtk_list_store_insert_before    (gtkliststore *list_store,
                                             gtktreeiter *iter,
                                             gtktreeiter *sibling);

вставляет новую строку перед sibling. если sibling это null, то строка добавляется в конец списка. iter будет изменён для указания на новую строку. строка будет пустой после вызова этой функции. для заполнения значений вы должны вызвать gtk_list_store_set() или gtk_list_store_set_value().

gtk_list_store_insert_after ()

void        gtk_list_store_insert_after     (gtkliststore *list_store,
                                             gtktreeiter *iter,
                                             gtktreeiter *sibling);

вставляет новую строку после sibling. если sibling это null, то строка будет вставлена в начало списка. iter будет изменён для указания на новую строку. строка будет пустой после вызова этой функции. для заполнения значений вы должны вызвать gtk_list_store_set() или gtk_list_store_set_value().

gtk_list_store_insert_with_values ()

void        gtk_list_store_insert_with_values
                                            (gtkliststore *list_store,
                                             gtktreeiter *iter,
                                             gint position,
                                             ...);

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

вызов gtk_list_store_insert_with_values(list_store, iter, position...) имеет тот же эффект как вызов

gtk_list_store_insert (list_store, iter, position);
gtk_list_store_set (list_store, iter, ...);

разница в том, что в предыдущем издаётся сигнал row_inserted, в то время как последний издаст сигналы row_inserted, row_changed и, если список хранения отсортирован, rows_reordered. так как издание сигнала rows_reordered повторно может повлиять на выполнение программы, gtk_list_store_insert_with_values() должен в основном использоваться для вставки строк в сортированный список хранения.

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

gtk_list_store_insert_with_valuesv ()

void        gtk_list_store_insert_with_valuesv
                                            (gtkliststore *list_store,
                                             gtktreeiter *iter,
                                             gint position,
                                             gint *columns,
                                             gvalue *values,
                                             gint n_values);

вариант gtk_list_store_insert_with_values() который берет столбцы и значения как два массива, вместо переменных аргументов. эта функция в основном полезна для языковых привязок.

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

gtk_list_store_prepend ()

void        gtk_list_store_prepend          (gtkliststore *list_store,
                                             gtktreeiter *iter);

вставляет новую строку в начало list_store. iter будет изменён для указания на новую строку. строка будет пустой после вызова этой функции. для заполнения значений вы должны вызвать gtk_list_store_set() или gtk_list_store_set_value().

gtk_list_store_append ()

void        gtk_list_store_append           (gtkliststore *list_store,
                                             gtktreeiter *iter);

добавляет новую строку к list_store. iter будет изменён для указания на новую строку. строка будет пустой после вызова этой функции. для заполнения значений вы должны вызвать gtk_list_store_set() or gtk_list_store_set_value().

gtk_list_store_clear ()

void        gtk_list_store_clear            (gtkliststore *list_store);

удаляет все строки из списка хранения.

gtk_list_store_iter_is_valid ()

gboolean    gtk_list_store_iter_is_valid    (gtkliststore *list_store,
                                             gtktreeiter *iter);

внимание

это очень медленная функция. используйте её только для отладки и/или тестирования.

проверят доступность итератора в gtkliststore.

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

gtk_list_store_reorder ()

void        gtk_list_store_reorder          (gtkliststore *store,
                                             gint *new_order);

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

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

gtk_list_store_swap ()

void        gtk_list_store_swap             (gtkliststore *store,
                                             gtktreeiter *a,
                                             gtktreeiter *b);

переставляет a и b в store. помните, эта функция работает только на не сортированных хранилищах.

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

gtk_list_store_move_before ()

void        gtk_list_store_move_before      (gtkliststore *store,
                                             gtktreeiter *iter,
                                             gtktreeiter *position);

перемещает iter в store в позицию перед position. помните, эта функция работает только на не сортированных хранилищах. если position равно null, iter будет перемещен в конец списка.

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

gtk_list_store_move_after ()

void        gtk_list_store_move_after       (gtkliststore *store,
                                             gtktreeiter *iter,
                                             gtktreeiter *position);

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

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

смотрите также

gtktreemodel, gtktreestore