Prev

Up

Home

GTK+ Reference Manual

Next

Top  |  Description

Selections

Selections Функции для обработки меж-процессорного взаимодействия посредством выделения

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

#include <gtk/gtk.h> GtkTargetEntry; GtkTargetList; GtkTargetPair; GtkTargetList* gtk_target_list_new (const GtkTargetEntry *targets, guint ntargets); GtkTargetList* gtk_target_list_ref (GtkTargetList *list); void gtk_target_list_unref (GtkTargetList *list); void gtk_target_list_add (GtkTargetList *list, GdkAtom target, guint flags, guint info); void gtk_target_list_add_table (GtkTargetList *list, const GtkTargetEntry *targets, guint ntargets); void gtk_target_list_add_text_targets (GtkTargetList *list, guint info); void gtk_target_list_add_image_targets (GtkTargetList *list, guint info, gboolean writable); void gtk_target_list_add_uri_targets (GtkTargetList *list, guint info); void gtk_target_list_add_rich_text_targets (GtkTargetList *list, guint info, gboolean deserializable, GtkTextBuffer *buffer); void gtk_target_list_remove (GtkTargetList *list, GdkAtom target); gboolean gtk_target_list_find (GtkTargetList *list, GdkAtom target, guint *info); void gtk_target_table_free (GtkTargetEntry *targets, gint n_targets); GtkTargetEntry* gtk_target_table_new_from_list (GtkTargetList *list, gint *n_targets); gboolean gtk_selection_owner_set (GtkWidget *widget, GdkAtom selection, guint32 time_); gboolean gtk_selection_owner_set_for_display (GdkDisplay *display, GtkWidget *widget, GdkAtom selection, guint32 time_); void gtk_selection_add_target (GtkWidget *widget, GdkAtom selection, GdkAtom target, guint info); void gtk_selection_add_targets (GtkWidget *widget, GdkAtom selection, const GtkTargetEntry *targets, guint ntargets); void gtk_selection_clear_targets (GtkWidget *widget, GdkAtom selection); gboolean gtk_selection_convert (GtkWidget *widget, GdkAtom selection, GdkAtom target, guint32 time_); void gtk_selection_data_set (GtkSelectionData *selection_data, GdkAtom type, gint format, const guchar *data, gint length); gboolean gtk_selection_data_set_text (GtkSelectionData *selection_data, const gchar *str, gint len); guchar* gtk_selection_data_get_text (GtkSelectionData *selection_data); gboolean gtk_selection_data_set_pixbuf (GtkSelectionData *selection_data, GdkPixbuf *pixbuf); GdkPixbuf* gtk_selection_data_get_pixbuf (GtkSelectionData *selection_data); gboolean gtk_selection_data_set_uris (GtkSelectionData *selection_data, gchar **uris); gchar** gtk_selection_data_get_uris (GtkSelectionData *selection_data); gboolean gtk_selection_data_get_targets (GtkSelectionData *selection_data, GdkAtom **targets, gint *n_atoms); gboolean gtk_selection_data_targets_include_image (GtkSelectionData *selection_data, gboolean writable); gboolean gtk_selection_data_targets_include_text (GtkSelectionData *selection_data); gboolean gtk_selection_data_targets_include_uri (GtkSelectionData *selection_data); gboolean gtk_selection_data_targets_include_rich_text (GtkSelectionData *selection_data, GtkTextBuffer *buffer); gboolean gtk_targets_include_image (GdkAtom *targets, gint n_targets, gboolean writable); gboolean gtk_targets_include_text (GdkAtom *targets, gint n_targets); gboolean gtk_targets_include_uri (GdkAtom *targets, gint n_targets); gboolean gtk_targets_include_rich_text (GdkAtom *targets, gint n_targets, GtkTextBuffer *buffer); void gtk_selection_remove_all (GtkWidget *widget); gboolean gtk_selection_clear (GtkWidget *widget, GdkEventSelection *event); GtkSelectionData* gtk_selection_data_copy (GtkSelectionData *data); void gtk_selection_data_free (GtkSelectionData *data);

Описание

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

Некоторые типовые данные определённые в этом разделе используются в GtkClipboard и drag-and-drop API's. Структура GtkTargetEntry и объекты GtkTargetList представляют списки типов данных которые поддерживаются при отправки и получении данных. Объект GtkSelectionData используется для сохранения части данных на ряду с типом данных и другой ассоциированной информацией.

Детали

GtkTargetEntry

typedef struct { gchar *target; guint flags; guint info; } GtkTargetEntry;

Структура GtkTargetEntry представляет единственный тип данных которым может быть снабжён виджет для выделения или поставки или получения в течении drag-and-drop процесса. Она содержит строку представляющую тип перетаскивания, поля флагов (используются только для drag and drop - смотрите GtkTargetFlags), а также целочисленный ID полученный приложением. Целочисленный ID будет позднее помещён как параметр сигнала для таких сигналов как "selection_get". Это позволит приложениям идентифицировать тип цели без расширенного сравнения строк.


GtkTargetList

typedef struct { GList *list; guint ref_count; } GtkTargetList;

Структура GtkTargetList представляет рассчитанный список GtkTargetPair. Она используется для представления некоторой информации, такой как таблица GtkTargetEntry, но в эффективной форме. Эта структура должна быть обработана как не прозрачная.


GtkTargetPair

typedef struct { GdkAtom target; guint flags; guint info; } GtkTargetPair;

Внутренне используемая структура обработки кода в процессе drag-and-drop и выделении.


gtk_target_list_new ()

GtkTargetList* gtk_target_list_new (const GtkTargetEntry *targets, guint ntargets);

Создаёт новый GtkTargetList из массива GtkTargetEntry.

targets :

Указатель массива GtkTargetEntry

ntargets :

Число данных в targets.

Возвращает :

Новый GtkTargetList.


gtk_target_list_ref ()

void        gtk_target_list_ref             (GtkTargetList *list);

Увеличивает счёт ссылок GtkTargetList на один.

list :

GtkTargetList


gtk_target_list_unref ()

void        gtk_target_list_unref           (GtkTargetList *list);

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

list :

GtkTargetList


gtk_target_list_add ()

void gtk_target_list_add (GtkTargetList *list, GdkAtom target, guint flags, guint info);

Присоединяет другую цель к GtkTargetList.

list :

GtkTargetList

target :

Интернированный атом представляющий цель

flags :

Флаги для этой цели

info :

ID который будет возвращён приложению


gtk_target_list_add_table ()

void gtk_target_list_add_table (GtkTargetList *list, const GtkTargetEntry *targets, guint ntargets);

Добавляет таблицу GtkTargetEntry к списку целей.

list :

GtkTargetList

targets :

таблица GtkTargetEntry

ntargets :

Число целей в таблице


gtk_target_list_add_text_targets ()

void gtk_target_list_add_text_targets (GtkTargetList *list, guint info);

Добавляет текстовые цели поддерживаемые GtkSelection к списку целей. Все цели добавляются с тем же самым info.

list :

GtkTargetList

info :

ID который будет возвращён приложению

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


gtk_target_list_add_image_targets ()

void gtk_target_list_add_image_targets (GtkTargetList *list, guint info, gboolean writable);

Добавляет целевые изображения поддерживаемые GtkSelection к списку целей. Все цели добавляются с тем же самым info.

list :

GtkTargetList

info :

ID который будет возвращён приложению

writable :

Добавлять ли только цели которые GTK+ знает как преобразовать в формат буфера изображения

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


gtk_target_list_add_uri_targets ()

void gtk_target_list_add_uri_targets (GtkTargetList *list, guint info);

Добавляет URI цели поддерживаемые GtkSelection к списку целей. Все цели добавляются с тем же самым info.

list :

GtkTargetList

info :

ID который будет возвращён приложению

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


gtk_target_list_remove ()

void gtk_target_list_remove (GtkTargetList *list, GdkAtom target);

Удаляет цель из списка целей.

list :

GtkTargetList

target :

Интернированный атом представляющий цель


gtk_target_list_find ()

gboolean gtk_target_list_find (GtkTargetList *list, GdkAtom target, guint *info);

Ищет полученную цель в GtkTargetList.

list :

GtkTargetList

target :

Интернированный атом представляющий цель для поиска

info :

Указатель расположения сохранённой приложением информации для цели

Возвращает :

TRUE если цель найдена, иначе FALSE


gtk_target_table_free ()

void gtk_target_table_free (GtkTargetEntry *targets, gint n_targets);

Эта функция освобождает таблицу целей возвращенных gtk_target_table_new_from_list()

targets :

массив GtkTargetEntry

n_targets :

Количество целей в массиве

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


gtk_target_table_new_from_list ()

GtkTargetEntry* gtk_target_table_new_from_list (GtkTargetList *list, gint *n_targets);

Эта функция создаёт массив GtkTargetEntry который содержит цели помещённые как list. Возвращаемая таблица должна освобождаться с помощью gtk_target_table_free() когда больше не нужна.

list :

GtkTargetList

n_targets :

Место для хранения возвращаемого количества целей в таблице

Возвращает :

Новая таблица.

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


gtk_selection_owner_set ()

gboolean gtk_selection_owner_set (GtkWidget *widget, GdkAtom selection, guint32 time_);

Требование монопольного использования данного выделения для специального виджета, или, если widget равен NULL, освобождение монопольного выделения.

widget :

GtkWidget, или NULL.

selection :

Интернированный атом представляющий требуемое выделение

time_ :

Отметка времени требования выделения

Возвращает :

TRUE если операция выполнена


gtk_selection_owner_set_for_display ()

gboolean gtk_selection_owner_set_for_display (GdkDisplay *display, GtkWidget *widget, GdkAtom selection, guint32 time_);

Требование монопольного использования данного выделения для специального виджета, или, если widget равен NULL, освобождение монопольного выделения.

display :

Gdkdisplay в котором установлено выделение

widget :

Новый владелец выделения (GdkWidget), или NULL.

selection :

Интернированный атом представляющий требуемое выделение

time_ :

Отметка времени требования выделения

Возвращает :

TRUE если операция выполнена

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


gtk_selection_add_target ()

void gtk_selection_add_target (GtkWidget *widget, GdkAtom selection, GdkAtom target, guint info);

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

widget :

GtkTarget

selection :

выделение

target :

Цель для добавления.

info :

Целое положительное число которое будет возвращено приложению.


gtk_selection_add_targets ()

void gtk_selection_add_targets (GtkWidget *widget, GdkAtom selection, const GtkTargetEntry *targets, guint ntargets);

Добавление таблицы целей в список поддерживаемых целей для данного виджета и выделения.

widget :

GtkWidget

selection :

выделение

targets :

Таблица целей для добавления

ntargets :

Число данных в targets


gtk_selection_clear_targets ()

void gtk_selection_clear_targets (GtkWidget *widget, GdkAtom selection);

Удаляет все цели зарегистрированные для данного выделения виджета.

widget :

GtkWidget

selection :

Атом представляющий выделение


gtk_selection_convert ()

gboolean gtk_selection_convert (GtkWidget *widget, GdkAtom selection, GdkAtom target, guint32 time_);

Запрос содержимого выделения. При получении генерируется сигнал "selection_received".

widget :

Запрашивающий виджет

selection :

Получаемое выделение

target :

Форма желаемой информации (например, STRING)

time_ :

Время запроса (обычно инициирование события) В непредвиденном случае вы можете использовать GDK_CURRENT_TIME

Возвращает :

TRUE если запрос удачен. FALSE если запрос не может быть обработан. (например, запрос для этого виджета уже был в процессе).


gtk_selection_data_set ()

void gtk_selection_data_set (GtkSelectionData *selection_data, GdkAtom type, gint format, const guchar *data, gint length);

Сохранение новых данных в объекте GtkSelectionData. Должен быть вызван только из callback-функции обработчика выделения. Сохранённые данные заканчиваются нулём (Zero-terminates).

selection_data :

Указатель на GtkSelectionData структуру.

type :

Тип выделенных данных

format :

формат (число бит в модуле)

data :

Указатель на данные (будет скопирован)

length :

Длина данных


gtk_selection_data_set_text ()

gboolean gtk_selection_data_set_text (GtkSelectionData *selection_data, const gchar *str, gint len);

Устанавливает содержимое выделения в виде строки в кодировке UTF-8. Строка преобразуется в форму определённую selection_data->target.

selection_data :

GtkSelectionData

str :

Строка в UTF-8

len :

длина str, или -1 если str заканчивается нулём (nul-terminated).

Возвращает :

TRUE если выделение было удачно установлено, иначе FALSE.


gtk_selection_data_get_text ()

guchar*     gtk_selection_data_get_text     (GtkSelectionData *selection_data);

Получает содержимое выделенных данных как строку в кодировке UTF-8.

selection_data :

GtkSelectionData

Возвращает :

Если выделенные данные содержат известный текстовый тип и он может быть преобразован в UTF-8, вновь размещенную строку содержащую преобразованный текст, иначе NULL. Если результат не NULL нужно освобождать с помощью g_free().


gtk_selection_data_set_pixbuf ()

gboolean gtk_selection_data_set_pixbuf (GtkSelectionData *selection_data, GdkPixbuf *pixbuf);

Устанавливает содержимое выделения из GdkPixbuf. Буфер изображения (pixbuf) преобразуется в определённую форму selection_data->target.

selection_data :

GtkSelectionData

pixbuf :

GdkPixbuf

Возвращает :

TRUE если выделение было удачно установлено, иначе FALSE.

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


gtk_selection_data_get_pixbuf ()

GdkPixbuf*  gtk_selection_data_get_pixbuf   (GtkSelectionData *selection_data);

Получает содержимое выделенных данных как GdkPixbuf.

selection_data :

GtkSelectionData

Возвращает :

Если выделенные данные содержат допустимый тип изображения и оно может быть преобразовано в GdkPixbuf, возвращается вновь размещенный буфер изображения (pixbuf), иначе NULL. Если результат не NULL, то нужно освобождать с помощью g_object_unref().

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


gtk_selection_data_set_uris ()

gboolean gtk_selection_data_set_uris (GtkSelectionData *selection_data, gchar **uris);

Устанавливает содержимое выделения из списка URIs. Строка преобразуется в определённую форму selection_data->target.

selection_data :

GtkSelectionData

uris :

NULL-заканчивающийся массив строк URIs

Возвращает :

TRUE если выделение было удачно установлено, иначе FALSE.

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


gtk_selection_data_get_uris ()

gchar**     gtk_selection_data_get_uris     (GtkSelectionData *selection_data);

Получает содержимое выделенных данных как массив URIs.

selection_data :

GtkSelectionData

Возвращает :

Если выделенные данные содержат список URIs, вновь размещаемый массив строк завершаемый NULL содержащий URIs, иначе NULL. Если результат не NULL, нужно освобождать с помощью g_strfreev().

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


gtk_selection_data_get_targets ()

gboolean gtk_selection_data_get_targets (GtkSelectionData *selection_data, GdkAtom **targets, gint *n_atoms);

Получает содержимое selection_data как массив целей. Это может использоваться для интерпретации результатов полученных стандартом TARGETS целей, который всегда поставляется для любого выделения.

selection_data :

Объект GtkSelectionData

targets :

Размещение сохранённого массива целей. Результат сохранённый здесь должен быть освобождён с помощью g_free().

n_atoms :

Размещение числа сохраняемых пунктов в targets.

Возвращает :

TRUE если selection_data содержит допустимый массив целей, иначе FALSE.


gtk_selection_data_targets_include_image ()

gboolean gtk_selection_data_targets_include_image (GtkSelectionData *selection_data, gboolean writable);

Получает объект GtkSelectionData содержащий список целей, определяется если какие-нибудь цели в targets могут быть использованы для обеспечения GdkPixbuf.

selection_data :

объект GtkSelectionData

writable :

Принимать ли только цели которые GTK+ знает как преобразовывать в формат буфера изображений (pixbuf)

Возвращает :

TRUE если selection_data содержит список целей и цель подходит для включения изображения, иначе FALSE.

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


gtk_selection_data_targets_include_text ()

gboolean gtk_selection_data_targets_include_text (GtkSelectionData *selection_data);

Получает объект GtkSelectionData содержащий список целей, определяется если какая-нибудь цель в targets может быть использована для обеспечения текста.

selection_data :

Объект GtkSelectionData

Возвращает :

TRUE если selection_data содержит список целей и цель подходит для включения текста, иначе FALSE.


gtk_selection_data_targets_include_uri ()

gboolean gtk_selection_data_targets_include_uri (GtkSelectionData *selection_data);

Полученный объект GtkSelectionData содержит список адресов, определяет может ли какой нибудь адрес в targets использоваться для обеспечения списка или URIs.

selection_data :

объект GtkSelectionData

Возвращает :

TRUE если selection_data содержит список адресов и подходящий для текста адрес включён, иначе FALSE.

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


gtk_selection_data_targets_include_rich_text ()

gboolean gtk_selection_data_targets_include_rich_text (GtkSelectionData *selection_data, GtkTextBuffer *buffer);

Полученный объект GtkSelectionData содержит список адресов, определяет может ли какой нибудь адрес в targets использоваться для обеспечения rich text.

selection_data :

объект GtkSelectionData

buffer :

GtkTextBuffer

Возвращает :

TRUE если selection_data содержит список адресов и подходящий для rich text адрес включён, иначе FALSE.

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


gtk_targets_include_image ()

gboolean gtk_targets_include_image (GdkAtom *targets, gint n_targets, gboolean writable);

Определяет может ли какой нибудь адрес в targets использоваться для обеспечения GdkPixbuf.

targets :

массив GdkAtoms

n_targets :

длина targets

writable :

Применяются ли только те адреса которые GTK+ знает как конвертировать в формат pixbuf

Возвращает :

TRUE если targets включает подходящий адрес для изображений, иначе FALSE.

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


gtk_targets_include_text ()

gboolean gtk_targets_include_text (GdkAtom *targets, gint n_targets);

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

targets :

массив GdkAtoms

n_targets :

длина targets

Возвращает :

TRUE если targets включает подходящий для текста адрес, иначе FALSE.

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


gtk_targets_include_uri ()

gboolean gtk_targets_include_uri (GdkAtom *targets, gint n_targets);

Определяет может ли какой нибудь адрес в targets использоваться для обеспечения списка uri.

targets :

массив GdkAtoms

n_targets :

длина targets

Возвращает :

TRUE если targets включает подходящий адрес для списка uri, иначе FALSE.

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


gtk_targets_include_rich_text ()

gboolean gtk_targets_include_rich_text (GdkAtom *targets, gint n_targets, GtkTextBuffer *buffer);

Определяет если какой нибудь адрес в targets подходит для обеспечения rich text.

targets :

массив GdkAtoms

n_targets :

длина targets

buffer :

GtkTextBuffer

Возвращает :

TRUE если targets включает подходящий адрес для rich text, иначе FALSE.

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


gtk_selection_remove_all ()

void        gtk_selection_remove_all        (GtkWidget *widget);

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

widget :

GtkWidget


gtk_selection_clear ()

gboolean gtk_selection_clear (GtkWidget *widget, GdkEventSelection *event);

Внимание

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

Обработчик по умолчанию для сигнала GtkWidget::selection_clear_event.

widget :

GtkWidget

event :

событие

Возвращает :

TRUE если событие было обработано, иначе false

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


gtk_selection_data_copy ()

GtkSelectionData* gtk_selection_data_copy   (GtkSelectionData *data);

Создаёт копию структуры GtkSelectionData и принадлежащих ей данных.

data :

Указатель на структуру GtkSelectionData.

Возвращает :

Указатель на копию data.


gtk_selection_data_free ()

void        gtk_selection_data_free         (GtkSelectionData *data);

Освобождает структуру GtkSelectionData возвращаемую gtk_selection_data_copy().

data :

Указатель на структуру GtkSelectionData.

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

GtkWidget

Большая часть операций выделения происходит через сигналы для GtkWidget. В частности, если вы используете функции из этого раздела, вы можете обратить внимание на ::selection_get, ::selection_received и :selection_clear_event сигналы.