drag and drop

			gtk+ reference manual
top \| description

drag and drop — функции контролирующие drag and drop обработку

краткий обзор

#include <gtk/gtk.h>


enum        gtkdestdefaults;
enum        gtktargetflags;

void        gtk_drag_dest_set               (gtkwidget *widget,
                                             gtkdestdefaults flags,
                                             const gtktargetentry *targets,
                                             gint n_targets,
                                             gdkdragaction actions);
void        gtk_drag_dest_set_proxy         (gtkwidget *widget,
                                             gdkwindow *proxy_window,
                                             gdkdragprotocol protocol,
                                             gboolean use_coordinates);
void        gtk_drag_dest_unset             (gtkwidget *widget);
gdkatom     gtk_drag_dest_find_target       (gtkwidget *widget,
                                             gdkdragcontext *context,
                                             gtktargetlist *target_list);
gtktargetlist* gtk_drag_dest_get_target_list
                                            (gtkwidget *widget);
void        gtk_drag_dest_set_target_list   (gtkwidget *widget,
                                             gtktargetlist *target_list);
void        gtk_drag_dest_add_text_targets  (gtkwidget *widget);
void        gtk_drag_dest_add_image_targets (gtkwidget *widget);
void        gtk_drag_dest_add_uri_targets   (gtkwidget *widget);
void        gtk_drag_finish                 (gdkdragcontext *context,
                                             gboolean success,
                                             gboolean del,
                                             guint32 time_);
void        gtk_drag_get_data               (gtkwidget *widget,
                                             gdkdragcontext *context,
                                             gdkatom target,
                                             guint32 time_);
gtkwidget*  gtk_drag_get_source_widget      (gdkdragcontext *context);
void        gtk_drag_highlight              (gtkwidget *widget);
void        gtk_drag_unhighlight            (gtkwidget *widget);

gdkdragcontext* gtk_drag_begin              (gtkwidget *widget,
                                             gtktargetlist *targets,
                                             gdkdragaction actions,
                                             gint button,
                                             gdkevent *event);
void        gtk_drag_set_icon_widget        (gdkdragcontext *context,
                                             gtkwidget *widget,
                                             gint hot_x,
                                             gint hot_y);
void        gtk_drag_set_icon_pixmap        (gdkdragcontext *context,
                                             gdkcolormap *colormap,
                                             gdkpixmap *pixmap,
                                             gdkbitmap *mask,
                                             gint hot_x,
                                             gint hot_y);
void        gtk_drag_set_icon_pixbuf        (gdkdragcontext *context,
                                             gdkpixbuf *pixbuf,
                                             gint hot_x,
                                             gint hot_y);
void        gtk_drag_set_icon_stock         (gdkdragcontext *context,
                                             const gchar *stock_id,
                                             gint hot_x,
                                             gint hot_y);
void        gtk_drag_set_icon_name          (gdkdragcontext *context,
                                             const gchar *icon_name,
                                             gint hot_x,
                                             gint hot_y);
void        gtk_drag_set_icon_default       (gdkdragcontext *context);
void        gtk_drag_set_default_icon       (gdkcolormap *colormap,
                                             gdkpixmap *pixmap,
                                             gdkbitmap *mask,
                                             gint hot_x,
                                             gint hot_y);
gboolean    gtk_drag_check_threshold        (gtkwidget *widget,
                                             gint start_x,
                                             gint start_y,
                                             gint current_x,
                                             gint current_y);
void        gtk_drag_source_set             (gtkwidget *widget,
                                             gdkmodifiertype start_button_mask,
                                             const gtktargetentry *targets,
                                             gint n_targets,
                                             gdkdragaction actions);
void        gtk_drag_source_set_icon        (gtkwidget *widget,
                                             gdkcolormap *colormap,
                                             gdkpixmap *pixmap,
                                             gdkbitmap *mask);
void        gtk_drag_source_set_icon_pixbuf (gtkwidget *widget,
                                             gdkpixbuf *pixbuf);
void        gtk_drag_source_set_icon_stock  (gtkwidget *widget,
                                             const gchar *stock_id);
void        gtk_drag_source_set_icon_name   (gtkwidget *widget,
                                             const gchar *icon_name);
void        gtk_drag_source_unset           (gtkwidget *widget);
void        gtk_drag_source_set_target_list (gtkwidget *widget,
                                             gtktargetlist *target_list);
gtktargetlist* gtk_drag_source_get_target_list
                                            (gtkwidget *widget);
void        gtk_drag_source_add_text_targets
                                            (gtkwidget *widget);
void        gtk_drag_source_add_image_targets
                                            (gtkwidget *widget);
void        gtk_drag_source_add_uri_targets (gtkwidget *widget);

описание

gtk+ имеет богатый набор функций для обеспечения взаимодействия процессов методом drag-and-drop (технология перемещения объектов интерфейса, дословно означает - перетащить и бросить). gtk+ может выполнять drag-and-drop (dnd) через множество протоколов. в настоящее время поддерживаются протоколы xdnd и motif. также как функциями перечисленными здесь, приложения могут нуждаться в использовании некоторых средств предусмотренных selections. кроме того, drag and drop api использует сигналы класса gtkwidget.

детали

enum gtkdestdefaults

typedef enum {
  gtk_dest_default_motion     = 1 << 0, /* отвечает на "drag_motion" */
  gtk_dest_default_highlight  = 1 << 1, /* авто-подсвечивание (auto-highlight) */
  gtk_dest_default_drop       = 1 << 2, /* отвечает на "drag_drop" */
  gtk_dest_default_all        = 0x07
} gtkdestdefaults;

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

`gtk_dest_default_motion`	если установлено для виджета, gtk+, в течении перетаскивания по этому виджету, будет контролировать возможный список целей и действий перетаскивания этого виджета и вызовет `gdk_drag_status()` для соответствующего.
`gtk_dest_default_highlight`	если установлено для виджета, gtk+ будет подсвечивать этот виджет в течении перетаскивания по этому виджету, пока действия и формат перетаскивания действительны.
`gtk_dest_default_drop`	если установлено для виджета, когда произойдет доставка, gtk+ будет контролировать возможный список действий и целей для перетаскивания и вызовет `gtk_drag_get_data()`. в независимости, выполнена доставка или нет, gtk+ вызовет `gtk_drag_finish()`. если действие было перемещением, при успешной доставке будет передано `true` в параметр `delete` для `gtk_drag_finish()`.
`gtk_dest_default_all`	если установлено, определяет что все действия по умолчанию должны быть выполнены.

enum gtktargetflags

typedef enum {
  gtk_target_same_app = 1 << 0,    /*< nick=same-app >*/
  gtk_target_same_widget = 1 << 1  /*< nick=same-widget >*/
} gtktargetflags;

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

`gtk_target_same_app`	если установлено, цель будет выделена для перетаскивания в пределах одного приложения.
`gtk_target_same_widget`	если установлено, цель будет выделена только для перетаскивания в пределах одного виджета.

gtk_drag_dest_set ()

void        gtk_drag_dest_set               (gtkwidget *widget,
                                             gtkdestdefaults flags,
                                             const gtktargetentry *targets,
                                             gint n_targets,
                                             gdkdragaction actions);

устанавливает виджет как потенциальное место для доставки¹ при перетаскивании².

`widget` :	gtkwidget
`flags` :	флаги определяют какие действия gtk+ должен предпринять от имени виджета для доставки на тот виджет. поля `targets` и `actions` используются только если `gtk_dest_default_motion` или `gtk_dest_default_drop` получены.
`targets` :	указатель массива gtktargetentrys указывающий тип доставки допустимый для этого виджета.
`n_targets` :	число записей в `targets`.
`actions` :	битовая маска возможных действий для доставки в этот виджет.

gtk_drag_dest_set_proxy ()

void        gtk_drag_dest_set_proxy         (gtkwidget *widget,
                                             gdkwindow *proxy_window,
                                             gdkdragprotocol protocol,
                                             gboolean use_coordinates);

устанавливает этот виджет как вспомогательный для доставки в другие окна.

`widget` :	gtkwidget
`proxy_window` :	окно отправления событий перетаскивания
`protocol` :	протокол перетаскивания принятый `proxy_window` (для определения протокола используйте `gdk_drag_get_protocol()`)
`use_coordinates` :	если `true`, отправляются координаты места назначения, потому что это встроенное суб-окно.

gtk_drag_dest_unset ()

void        gtk_drag_dest_unset             (gtkwidget *widget);

очищает информацию о месте перетаскивания установленную с помощью gtk_drag_dest_set(). виджет не будет больше получать события перемещения.

widget :

gtkwidget

gtk_drag_dest_find_target ()

gdkatom     gtk_drag_dest_find_target       (gtkwidget *widget,
                                             gdkdragcontext *context,
                                             gtktargetlist *target_list);

ищет соответствие между context->targets и dest_target_list, возвращает первый соответствующий цели, иначе возвращает gdk_none. dest_target_list - обычно возвращаемое значение gtk_drag_dest_get_target_list(), но некоторые виджеты могут иметь различия допустимых целей для различных виджетов; на этот случай, они имеют обработчик drag_motion помещающий правильный список целей в эту функцию.

`widget` :	целевой виджет перетаскивания
`context` :	содержимое перетаскивания
`target_list` :	список допустимых для перетаскивания целей, или `null` для использования gtk_drag_dest_get_target_list (`widget`).
возвращает :	первую цель, которую исходное предложение и место доставки смогут принять, или `gdk_none`

gtk_drag_dest_get_target_list ()

gtktargetlist* gtk_drag_dest_get_target_list
                                            (gtkwidget *widget);

возвращает список целей допустимых для операции drag-and-drop определённым виджетом.

`widget` :	gtkwidget
возвращает :	gtktargetlist, или `null` если не существует

gtk_drag_dest_set_target_list ()

void        gtk_drag_dest_set_target_list   (gtkwidget *widget,
                                             gtktargetlist *target_list);

устанавливает типы целей допустимые данным виджетом для операции drag-and-drop. сначала виджет должен быть сделан местоположением для перетаскивания с помощью gtk_drag_dest_set().

`widget` :	gtkwidget местоположение перетаскивания
`target_list` :	список доступных для перетаскивания целей, или `null` для несуществующих

gtk_drag_dest_add_text_targets ()

void        gtk_drag_dest_add_text_targets  (gtkwidget *widget);

добавляет поддержку текстовых целей gtkselection в список целей местоположения для перемещения. цели добавляются с info = 0. если вам нужно другое значение, используйте gtk_target_list_add_text_targets() и gtk_drag_dest_set_target_list().

widget :

gtkwidget местоположение перетаскивания

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

gtk_drag_dest_add_image_targets ()

void        gtk_drag_dest_add_image_targets (gtkwidget *widget);

добавляет поддержку целевых изображений gtkselection в список целей местоположения для перемещения. цели добавляются с info = 0. если вам нужно другое значение, используйте gtk_target_list_add_image_targets() и gtk_drag_dest_set_target_list().

widget :

gtkwidget местоположение перетаскивания

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

gtk_drag_dest_add_uri_targets ()

void        gtk_drag_dest_add_uri_targets   (gtkwidget *widget);

добавляет целевую поддержку uri gtkselection в список целей местоположения для перемещения. цели добавляются с info = 0. если вам нужно другое значение, используйте gtk_target_list_add_uri_targets() и gtk_drag_dest_set_target_list().

widget :

gtkwidget местоположение перетаскивания

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

gtk_drag_finish ()

void        gtk_drag_finish                 (gdkdragcontext *context,
                                             gboolean success,
                                             gboolean del,
                                             guint32 time_);

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

`context` :	содержимое перетаскивания.
`success` :	флаг информирующий об успешном или нет завершении доставки.
`del` :	флаг информирующий, должен ли источник удалять оригинальные данные. (т.е. выполнить перемещение а не копирование)
`time_` :	метка временем для сигнала "drag_data_drop".

gtk_drag_get_data ()

void        gtk_drag_get_data               (gtkwidget *widget,
                                             gdkdragcontext *context,
                                             gdkatom target,
                                             guint32 time_);

получает данные связанные с перетаскиванием. когда данные получены, или поиск заканчивается неудачей, gtk+ будет производить сигнал "drag_data_received". неудачный поиск информируется отрицательной длиной поля selection_data параметра сигнала. однако, когда вызвана gtk_drag_get_data(), потому что было установлено gtk_dest_default_drop, то когда виджет не будет получать уведомления о не удавшемся броске.

`widget` :	виджет который получит сигнал "drag_data_received".
`context` :	содержимое перетаскивания
`target` :	цель (форма данных) поиска.
`time_` :	временная метка для поиска данных. это будет в основном время поиска в "drag_data_motion" или "drag_data_drop" signal.

gtk_drag_get_source_widget ()

gtkwidget*  gtk_drag_get_source_widget      (gdkdragcontext *context);

определяет исходный виджет для перетаскивания.

`context` :	(сторона получателя) содержимое перетаскивания.
возвращает :	если перетаскивание происходит в пределах одного приложения, возвращается указатель на исходный виджет. иначе, `null`.

gtk_drag_highlight ()

void        gtk_drag_highlight              (gtkwidget *widget);

подсвечивает виджет. прикрепляет обработчики к "expose_event" и "draw", таким образом подсветка будет продолжит отображаться, до тех пор пока не вызвана gtk_drag_unhighlight().

widget :

подсвечиваемый виджет

gtk_drag_unhighlight ()

void        gtk_drag_unhighlight            (gtkwidget *widget);

удаляет подсветку установленную gtk_drag_highlight() для виджета.

widget :

виджет с которого удаляется подсветка.

gtk_drag_begin ()

gdkdragcontext* gtk_drag_begin              (gtkwidget *widget,
                                             gtktargetlist *targets,
                                             gdkdragaction actions,
                                             gint button,
                                             gdkevent *event);

инициализирует перетаскивание на исходной стороне. функцию нужно использовать только когда приложение запустило перетаскивание самостоятельно, и не нужно использовать когда используется gtk_drag_source_set().

`widget` :	исходный виджет.
`targets` :	цели (форматы данных) в которые могут передаваться исходные данные.
`actions` :	битовая-маска (bitmask) допустимого действия перетаскивания.
`button` :	кнопка нажимаемая пользователем для начала перетаскивания.
`event` :	событие вызвавшее начало перетаскивания.
возвращает :	содержимое перетаскивания.

gtk_drag_set_icon_widget ()

void        gtk_drag_set_icon_widget        (gdkdragcontext *context,
                                             gtkwidget *widget,
                                             gint hot_x,
                                             gint hot_y);

изменяет значок для виджета к данному виджету. gtk+ не будет удалять значок, поэтому, если вы не хотите его сохранять, вы должны подключить сигнал "drag_end" и удалить его самостоятельно.

`context` :	содержимое перетаскивания. (должно вызываться с содержимым для исходной стороны перетаскивания)
`widget` :	окно верхнего уровня используемое как значок.
`hot_x` :	смещение x, в пределах `widget` , «горячей» точки.
`hot_y` :	смещение y, в пределах `widget` , «горячей» точки.

gtk_drag_set_icon_pixmap ()

void        gtk_drag_set_icon_pixmap        (gdkdragcontext *context,
                                             gdkcolormap *colormap,
                                             gdkpixmap *pixmap,
                                             gdkbitmap *mask,
                                             gint hot_x,
                                             gint hot_y);

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

`context` :	содержимое перетаскивания. (должно вызываться с содержимым для исходной стороны перетаскивания)
`colormap` :	карта цвета для значка
`pixmap` :	данные изображения для значка
`mask` :	маска прозрачности для значка
`hot_x` :	смещение x, относительно пределов `pixmap` , «горячей» точки.
`hot_y` :	смещение y, относительно пределов `pixmap` , «горячей» точки.

gtk_drag_set_icon_pixbuf ()

void        gtk_drag_set_icon_pixbuf        (gdkdragcontext *context,
                                             gdkpixbuf *pixbuf,
                                             gint hot_x,
                                             gint hot_y);

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

`context` :	содержимое перетаскивания. (должно вызываться с содержимым для исходной стороны перетаскивания)
`pixbuf` :	the gdkpixbuf to use as the drag icon.
`hot_x` :	смещение x, относительно пределов `widget` , «горячей» точки.
`hot_y` :	смещение y, относительно пределов `widget` , «горячей» точки.

gtk_drag_set_icon_stock ()

void        gtk_drag_set_icon_stock         (gdkdragcontext *context,
                                             const gchar *stock_id,
                                             gint hot_x,
                                             gint hot_y);

устанавливает значок для данного перетаскивания с исходным id.

`context` :	содержимое перетаскивания. (должно вызываться с содержимым для исходной стороны перетаскивания)
`stock_id` :	id исходного значка используемого для перетаскивания.
`hot_x` :	смещение x, относительно пределов значка , «горячей» точки.
`hot_y` :	смещение y, относительно пределов значка , «горячей» точки.

gtk_drag_set_icon_name ()

void        gtk_drag_set_icon_name          (gdkdragcontext *context,
                                             const gchar *icon_name,
                                             gint hot_x,
                                             gint hot_y);

устанавливает значок для данного перетаскивания из именной темы значков. смотрите документацию gtkicontheme, для подробного изучения деталей. отметьте, размер значка зависит от темы значков (значок загружается в символическом размере gtk_icon_size_dnd), таким образом hot_x и hot_y должны использоваться осторожно.

`context` :	содержимое перетаскивания. (должно вызываться с содержимым для исходной стороны перетаскивания)
`icon_name` :	имя используемого значка
`hot_x` :	смещение x горячей точки в пределах значка
`hot_y` :	смещение y горячей точки в пределах значка

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

gtk_drag_set_icon_default ()

void        gtk_drag_set_icon_default       (gdkdragcontext *context);

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

context :

содержимое перетаскивания. (должно вызываться с содержимым для исходной стороны перетаскивания)

gtk_drag_set_default_icon ()

void        gtk_drag_set_default_icon       (gdkcolormap *colormap,
                                             gdkpixmap *pixmap,
                                             gdkbitmap *mask,
                                             gint hot_x,
                                             gint hot_y);

внимание!

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

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

`colormap` :	цветовая карта для значка.
`pixmap` :	данные изображения для значка.
`mask` :	маска прозрачности для изображения.
`hot_x` :	смещение x, относительно пределов `widget` , «горячей» точки.
`hot_y` :	смещение y, относительно пределов `widget` , «горячей» точки.

gtk_drag_check_threshold ()

gboolean    gtk_drag_check_threshold        (gtkwidget *widget,
                                             gint start_x,
                                             gint start_y,
                                             gint current_x,
                                             gint current_y);

выясняет, если перемещение мышки началось в (start_x, start_y) и закончилось в (current_x, current_y) имея помещаемый gtk+ порог перетаскивания, начинается операция drag-and-drop.

`widget` :	gtkwidget
`start_x` :	x координаты начала перемещения
`start_y` :	y координаты начала перемещения
`current_x` :	текущие x координаты
`current_y` :	текущие y координаты
возвращает :	`true` если порог перемещения помещен.

gtk_drag_source_set ()

void        gtk_drag_source_set             (gtkwidget *widget,
                                             gdkmodifiertype start_button_mask,
                                             const gtktargetentry *targets,
                                             gint n_targets,
                                             gdkdragaction actions);

устанавливает виджет так, что gtk+ будет начинать операцию перетаскивания, когда пользователь нажимает и перемещает виджет. виджет должен иметь окно.

`widget` :	gtkwidget
`start_button_mask` :	битовая маска кнопки которая может начать перетаскивание
`targets` :	таблица целей которые будут поддерживаться перетаскиванием
`n_targets` :	число пунктов в `targets`
`actions` :	битовая маска возможных действий для перетаскивания из этого виджета.

gtk_drag_source_set_icon ()

void        gtk_drag_source_set_icon        (gtkwidget *widget,
                                             gdkcolormap *colormap,
                                             gdkpixmap *pixmap,
                                             gdkbitmap *mask);

устанавливает значок, который будет использоваться для перетаскивания из специального виджета pixmap/mask. gtk+ сохраняет справочную информацию для аргументов и освобождает когда она больше не нужна. используйте вместо этого gtk_drag_source_set_icon_pixbuf().

`widget` :	gtkwidget
`colormap` :	цветовая карта значка
`pixmap` :	данные изображения для значка
`mask` :	прозрачная маска для изображения.

gtk_drag_source_set_icon_pixbuf ()

void        gtk_drag_source_set_icon_pixbuf (gtkwidget *widget,
                                             gdkpixbuf *pixbuf);

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

`widget` :	gtkwidget
`pixbuf` :	gdkpixbuf для значка перетаскивания

gtk_drag_source_set_icon_stock ()

void        gtk_drag_source_set_icon_stock  (gtkwidget *widget,
                                             const gchar *stock_id);

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

`widget` :	gtkwidget
`stock_id` :	id заготовленного для использования значка

gtk_drag_source_set_icon_name ()

void        gtk_drag_source_set_icon_name   (gtkwidget *widget,
                                             const gchar *icon_name);

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

`widget` :	gtkwidget
`icon_name` :	имя используемого значка

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

gtk_drag_source_unset ()

void        gtk_drag_source_unset           (gtkwidget *widget);

отменяет действия gtk_drag_source_set().

widget :

gtkwidget

gtk_drag_source_set_target_list ()

void        gtk_drag_source_set_target_list (gtkwidget *widget,
                                             gtktargetlist *target_list);

изменяет типовую цель которую этот виджет предлагает для drag-and-drop. сначала виджет должен быть сделан источником перетаскивания при помощи gtk_drag_source_set().

`widget` :	gtkwidget – это источник перетаскивания
`target_list` :	список доступных для перетаскивания целей, или `null` если недоступны

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

gtk_drag_source_get_target_list ()

gtktargetlist* gtk_drag_source_get_target_list
                                            (gtkwidget *widget);

получает список целей, которые виджет может предоставить для drag-and-drop.

`widget` :	gtkwidget
возвращает :	gtktargetlist, или `null` если не существует

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

gtk_drag_source_add_text_targets ()

void        gtk_drag_source_add_text_targets
                                            (gtkwidget *widget);

добавляет текстовую цель, поддерживаемый gtkselection список целей источника перемещения. цели добавляются с info = 0. если вам нужно другое значение, используйте gtk_target_list_add_text_targets() и gtk_drag_source_set_target_list().

widget :

gtkwidget – это источник перемещения

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

gtk_drag_source_add_image_targets ()

void        gtk_drag_source_add_image_targets
                                            (gtkwidget *widget);

добавляет перезаписываемые цели изображения, поддерживаемые gtkselection в списке целей источника перемещения. цели добавляются с info = 0. если вам нужно другое значение, используйте gtk_target_list_add_image_targets() и gtk_drag_source_set_target_list().

widget :

gtkwidget – это источник перемещения

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

gtk_drag_source_add_uri_targets ()

void        gtk_drag_source_add_uri_targets (gtkwidget *widget);

добавляет uri целей , поддерживаемые gtkselection в списке целей источника перемещения. цели добавляются с info = 0. если вам нужно другое значение, используйте gtk_target_list_add_uri_targets() и gtk_drag_source_set_target_list().

widget :

gtkwidget – это источник перемещения

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

1доставка – действие завершающее операцию drag-and-drop.

2перетаскивание – составное действие операции перемещения drag-and-drop.