selections

			gtk+ reference manual
top \| description

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_);

`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 сигналы.