GtkListStore

			GTK+ Reference Manual
Top \| Description \| Object Hierarchy \| Implemented Interfaces

GtkListStore

GtkListStore Структура данных, похожая на список, используемая с GtkTreeView

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


#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 соответственно.

`n_columns` :	Количество столбцов в списке хранения
`...` :	Все типы GType для столбцов, от первого до последнего
Возвращает :	новый GtkListStore

gtk_list_store_newv ()

GtkListStore* gtk_list_store_newv (gint n_columns, GType *types);

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

`n_columns` :	Количество столбцов в списке хранения
`types` :	Массив типов GType для столбцов, от первого до последнего
Возвращает :	новый GtkListStore

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.

`list_store` :	GtkListStore
`n_columns` :	Количество столбцов для списка хранения
`types` :	Длина массива n GTypes

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).

`list_store` :	GtkListStore
`iter` :	Итератор строки
`...` :	Пары номер столбца и значение, заканчивается -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 для использования языковыми привязками.

`list_store` :	GtkListStore
`iter` :	Допустимый GtkTreeIter для изменяемой строки
`var_args` :	va_list список пар column/value

gtk_list_store_set_value ()

void gtk_list_store_set_value (GtkListStore *list_store, GtkTreeIter *iter, gint column, GValue *value);

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

`list_store` :	GtkListStore
`iter` :	Допустимый GtkTreeIter изменяемой строки
`column` :	Номер столбца для изменения
`value` :	Новое значение для ячейки

gtk_list_store_remove ()

gboolean gtk_list_store_remove (GtkListStore *list_store, GtkTreeIter *iter);

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

`list_store` :	GtkListStore
`iter` :	Допустимый GtkTreeIter
Возвращает :	`TRUE` если `iter` доступен, `FALSE` если нет.

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().

`list_store` :	GtkListStore
`iter` :	Устанавливаемый GtkTreeIter в значение новой строки
`position` :	Позиция для вставки новой строки

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().

`list_store` :	GtkListStore
`iter` :	Устанавливаемый GtkTreeIter в значение новой строки
`sibling` :	Допустимый GtkTreeIter, или `NULL`

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().

`list_store` :	GtkListStore
`iter` :	Устанавливаемый GtkTreeIter в значение новой строки
`sibling` :	Допустимый GtkTreeIter, или `NULL`

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() должен в основном использоваться для вставки строк в сортированный список хранения.

`list_store` :	GtkListStore
`iter` :	Устанавливаемый GtkTreeIter в значение новой строки, или `NULL`.
`position` :	Позиция для вставки новой строки
`...` :	Пары столбца номер и значение, заканчиваются -1

Начиная с версии 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() который берет столбцы и значения как два массива, вместо переменных аргументов. Эта функция в основном полезна для языковых привязок.

`list_store` :	GtkListStore
`iter` :	Устанавливаемый GtkTreeIter в значение новой строки, или `NULL`.
`position` :	Позиция для вставки новой строки
`columns` :	Массив номеров столбцов
`values` :	Массив GValues
`n_values` :	Длина массивов `columns` и `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().

`list_store` :	GtkListStore
`iter` :	Устанавливаемый GtkTreeIter в значение новой строки

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().

`list_store` :	GtkListStore
`iter` :	Устанавливаемый GtkTreeIter в значение добавленной строки

gtk_list_store_clear ()

void        gtk_list_store_clear            (GtkListStore *list_store);
Удаляет все строки из списка хранения.

	
	
	
		
			list_store :
		
		
			GtkListStore. 
			
		
	


gtk_list_store_iter_is_valid ()
gboolean    gtk_list_store_iter_is_valid    (GtkListStore *list_store,
                                             GtkTreeIter *iter);
Внимание
Это очень
медленная функция. Используйте её только
для отладки и/или тестирования.
Проверят доступность итератора в
GtkListStore.

	
	
	
		
			list_store :
		
		
			GtkListStore. 
			
		
	
	
		
			iter :
		
		
			GtkTreeIter. 
			
		
	
	
		
			Возвращает :
		
		
			TRUE
			если итератор доступен, FALSE
			если итератор не доступен. 
			
		
	

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


gtk_list_store_reorder ()
void        gtk_list_store_reorder          (GtkListStore *store,
                                             gint *new_order);
Перестраивает store в порядок
указанный new_order. Помните,
эта функция работает только на не
сортированных хранилищах.

	
	
	
		
			store :
		
		
			GtkListStore. 
			
		
	
	
		
			new_order :
		
		
			Массив целочисленных отображающих
			новую позицию каждого дочернего пункта
			относительно его старой позиции,
			например new_order[newpos] =
			oldpos. 
			
		
	

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


gtk_list_store_swap ()
void        gtk_list_store_swap             (GtkListStore *store,
                                             GtkTreeIter *a,
                                             GtkTreeIter *b);
Переставляет a и b
в store. Помните, эта функция
работает только на не сортированных
хранилищах.

	
	
	
		
			store :
		
		
			GtkListStore. 
			
		
	
	
		
			a :
		
		
			GtkTreeIter. 
			
		
	
	
		
			b :
		
		
			Другой GtkTreeIter.
						
		
	

Начиная с версии 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 будет перемещен в конец
списка.

	
	
	
		
			store :
		
		
			GtkListStore. 
			
		
	
	
		
			iter :
		
		
			GtkTreeIter. 
			
		
	
	
		
			position :
		
		
			GtkTreeIter, или
			NULL.
						
		
	

Начиная с версии 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 будет перемещён в начало
списка.

	
	
	
		
			store :
		
		
			GtkListStore. 
			
		
	
	
		
			iter :
		
		
			GtkTreeIter. 
			
		
	
	
		
			position :
		
		
			GtkTreeIter, или
			NULL.
						
		
	

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

Смотрите также
GtkTreeModel, GtkTreeStore

`store` :	GtkListStore.
`new_order` :	Массив целочисленных отображающих новую позицию каждого дочернего пункта относительно его старой позиции, например `new_order``[newpos] = oldpos`.

`store` :	GtkListStore.
`a` :	GtkTreeIter.
`b` :	Другой GtkTreeIter.