Prev

Up

Home

GTK+ Reference Manual

Next

Top  |  Description  |  Object Hierarchy  |  Properties  |  Style Properties  |  Signals

GtkDialog

GtkDialog Создание всплывающих окон

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

#include <gtk/gtk.h> GtkDialog; enum GtkDialogFlags; enum GtkResponseType; GtkWidget* gtk_dialog_new (void); GtkWidget* gtk_dialog_new_with_buttons (const gchar *title, GtkWindow *parent, GtkDialogFlags flags, const gchar *first_button_text, ...); gint gtk_dialog_run (GtkDialog *dialog); void gtk_dialog_response (GtkDialog *dialog, gint response_id); GtkWidget* gtk_dialog_add_button (GtkDialog *dialog, const gchar *button_text, gint response_id); void gtk_dialog_add_buttons (GtkDialog *dialog, const gchar *first_button_text, ...); void gtk_dialog_add_action_widget (GtkDialog *dialog, GtkWidget *child, gint response_id); gboolean gtk_dialog_get_has_separator (GtkDialog *dialog); void gtk_dialog_set_default_response (GtkDialog *dialog, gint response_id); void gtk_dialog_set_has_separator (GtkDialog *dialog, gboolean setting); void gtk_dialog_set_response_sensitive (GtkDialog *dialog, gint response_id, gboolean setting); gint gtk_dialog_get_response_for_widget (GtkDialog *dialog, GtkWidget *widget); gboolean gtk_alternative_dialog_button_order (GdkScreen *screen); void gtk_dialog_set_alternative_button_order (GtkDialog *dialog, gint first_response_id, ...); void gtk_dialog_set_alternative_button_order_from_array (GtkDialog *dialog, gint n_params, gint *new_order);

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

GObject +----GInitiallyUnowned +----GtkObject +----GtkWidget +----GtkContainer +----GtkBin +----GtkWindow +----GtkDialog +----GtkAboutDialog +----GtkColorSelectionDialog +----GtkFileChooserDialog +----GtkFileSelection +----GtkFontSelectionDialog +----GtkInputDialog +----GtkMessageDialog

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

GtkDialog осуществляет AtkImplementorIface.

Свойства

  "has-separator"        gboolean              : Read / Write

Свойства стиля

"action-area-border" gint : Read "button-spacing" gint : Read "content-area-border" gint : Read

Сигналы

"close" void user_function (GtkDialog *dialog, gpointer user_data) : Run last / Action "response" void user_function (GtkDialog *dialog, gint arg1, gpointer user_data) : Run last

Описание

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

GTK+ рассматривает диалог как окно разделённое вертикально. Верхняя часть GtkVBox, а в нижней упаковывается виджет такой как GtkLabel или GtkEntry. Нижняя область известна как action_area. В основном используется для упаковки кнопок внутри диалога для выполнения таких функций как cancel, ok, или apply. Две области разделяются с помощью GtkHSeparator.

GtkDialog окна создаются вызовами gtk_dialog_new() или gtk_dialog_new_with_buttons(). gtk_dialog_new_with_buttons() предпочтительна; она позволяет вам устанавливать заголовок диалога, некоторые удобные флаги и добавлять простые кнопки.

Если 'dialog' вновь созданный диалог, две первичные области окна могут быть доступны как GTK_DIALOG(dialog)->vbox и GTK_DIALOG(dialog)->action_area, как показано в примере ниже.

Диалог 'modal' (то есть тот, который замораживает для пользовательского ввода остальную часть приложения), может быть создан вызовом gtk_window_set_modal() на диалоге. Используйте макрос GTK_WINDOW() для помещения виджета возвращенного из gtk_dialog_new() в GtkWindow. Когда используется gtk_dialog_new_with_buttons() вы можете также поместить флаг GTK_DIALOG_MODAL для создания модального диалога.

Если вы хотите добавить кнопки к GtkDialog используйте gtk_dialog_new_with_buttons(), gtk_dialog_add_button(), gtk_dialog_add_buttons(), или gtk_dialog_add_action_widget(), нажатие на кнопке издаст сигнал называемый "response" с ID ответа который вы определили. GTK+ никогда не будет назначать значение IDs отзыва; это полностью прерогатива пользователя. Но для удобства, вы можете использовать IDs ответов в перечислении GtkResponseType (они все имеют значение меньше нуля). Если диалог получит удаляющее событие, сигнал "response" будет издан с ID ответа GTK_RESPONSE_DELETE_EVENT.

Если вы хотите блокировать ожидание диалога, чтобы вернуться перед возвращением контроля процесса вашему коду, вы можете вызвать gtk_dialog_run(). Эта функция входит в рекурсивный главный цикл и ждёт пользователя, чтобы ответить на диалог, возвращая ID ответа соответствующего кнопке которой щелкнул пользователь.

Для простого диалога в следующем примере, в действительности вы наверное использовали бы GtkMessageDialog. Но если вам нужно больше чем просто сообщение в диалоге вам придётся создать диалог вручную.

Пример 1. Использование GtkDialog.

/* Функция для открытия диалогового окна отображающего предоставленное сообщение. */ void quick_message (gchar *message) { GtkWidget *dialog, *label; /* Создаём виджеты */ dialog = gtk_dialog_new_with_buttons ("Message", main_application_window, GTK_DIALOG_DESTROY_WITH_PARENT, GTK_STOCK_OK, GTK_RESPONSE_NONE, NULL); label = gtk_label_new (message); /* Гарантирует закрытие диалога когда пользователь ответил. */ g_signal_connect_swapped (dialog, "response", G_CALLBACK (gtk_widget_destroy), dialog); /* Добавляет ярлык и отображает всё что мы добавили к диалогу. */ gtk_container_add (GTK_CONTAINER (GTK_DIALOG(dialog)->vbox), label); gtk_widget_show_all (dialog); }

Детали

GtkDialog

typedef struct { GtkWidget *vbox; GtkWidget *action_area; } GtkDialog;

vbox это GtkVBox главная часть диалогового окна.

action_area это GtkHButtonBox упакованный ниже деления GtkHSeparator в диалоге. Рассматривается также как любой другой GtkHButtonBox.


enum GtkDialogFlags

typedef enum { GTK_DIALOG_MODAL = 1 << 0, /* call gtk_window_set_modal (win, TRUE) */ GTK_DIALOG_DESTROY_WITH_PARENT = 1 << 1, /* call gtk_window_set_destroy_with_parent () */ GTK_DIALOG_NO_SEPARATOR = 1 << 2 /* no separator bar above buttons */ } GtkDialogFlags;

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

GTK_DIALOG_MODAL

Создаёт модальную конструкцию диалога, смотрите gtk_widget_set_modal().

GTK_DIALOG_DESTROY_WITH_PARENT

Закрывает диалог когда закрывается родитель, смотрите gtk_window_set_destroy_with_parent().

GTK_DIALOG_NO_SEPARATOR

Не помещать разделитель между областью действия и содержимым диалога.


enum GtkResponseType

typedef enum { /* GTK возвращает это если ответ виджета не имеет response_id, * или если диалог с точки зрения программы скрыт или разрушен. */ GTK_RESPONSE_NONE = -1, /* GTK не будет возвращать их если вы не помещаете их как * ответ для виджета действия. Они для вашего * удобства. */ GTK_RESPONSE_REJECT = -2, GTK_RESPONSE_ACCEPT = -3, /* Если диалог удалён. */ GTK_RESPONSE_DELETE_EVENT = -4, /* Эти тоже возвращаются из диалогов GTK и вы можете использовать их * самостоятельно если вам нравится. */ GTK_RESPONSE_OK = -5, GTK_RESPONSE_CANCEL = -6, GTK_RESPONSE_CLOSE = -7, GTK_RESPONSE_YES = -8, GTK_RESPONSE_NO = -9, GTK_RESPONSE_APPLY = -10, GTK_RESPONSE_HELP = -11 } GtkResponseType;

Встроенные значения для использования как ids ответов в gtk_dialog_add_button(). Все предопределённые значения отрицательны, GTK+ оставляет положительные значения для определённых приложением (application-defined) ids ответов.

GTK_RESPONSE_NONE

Returned if an action widget has no response id, or if the dialog gets programmatically hidden or destroyed.

GTK_RESPONSE_REJECT

Общий id ответа, не используется диалогами GTK+.

GTK_RESPONSE_ACCEPT

Общий id ответа, не используется диалогами GTK+.

GTK_RESPONSE_DELETE_EVENT

Возвращается если диалог удалён.

GTK_RESPONSE_OK

Возвращается кнопкой OK в диалогах GTK+.

GTK_RESPONSE_CANCEL

Возвращается кнопкой Cancel в диалогах GTK+.

GTK_RESPONSE_CLOSE

Возвращается кнопкой Close в диалогах GTK+.

GTK_RESPONSE_YES

Возвращается кнопкой Yes в диалогах GTK+.

GTK_RESPONSE_NO

Возвращается кнопкой No в диалогах GTK+.

GTK_RESPONSE_APPLY

Возвращается кнопкой Apply в диалогах GTK+.

GTK_RESPONSE_HELP

Возвращается кнопкой Help в диалогах GTK+.


gtk_dialog_new ()

GtkWidget*  gtk_dialog_new                  (void);

Создаёт новое диалоговое окно. Виджеты не должны быть упакованы в GtkWindow непосредственно, но в vbox и action_area, как описано выше.

Возвращает :

новый GtkDialog.


gtk_dialog_new_with_buttons ()

GtkWidget* gtk_dialog_new_with_buttons (const gchar *title, GtkWindow *parent, GtkDialogFlags flags, const gchar *first_button_text, ...);

Создаёт новый GtkDialog с заголовком title (или NULL для заголовка по умолчанию; смотрите gtk_window_set_title()) и переходящим родителем parent (или NULL; смотрите gtk_window_set_transient_for()). Аргумент flags может быть использован для создания модальных диалогов (GTK_DIALOG_MODAL) и/или разрушения вместе с переходящим родителем (GTK_DIALOG_DESTROY_WITH_PARENT). После flags, кнопки пары text/response ID должны быть перечислены, с NULL указателем заканчивающим список. Кнопка text может быть любой из заготовленных ID таких как GTK_STOCK_OK, или некоторый произвольный текст. Ответный ID любым позитивным числом, или одним из значений перечисления GtkResponseType. Если пользователь щелкнул один раз на этих кнопках диалога, GtkDialog издаст сигнал "response" с соответствующим ответным ID. Если GtkDialog получает сигнал "delete_event", это издаст "response" с ответным ID GTK_RESPONSE_DELETE_EVENT. Однако, закрытый диалог не издаёт сигнал "response"; поэтому будьте осторожны полагаясь на "response" когда используете флаг GTK_DIALOG_DESTROY_WITH_PARENT. Кнопки располагаются с лева на право, поэтому первая копка в списке будет крайней левой кнопкой в диалоге.

Простой пример:

GtkWidget *dialog = gtk_dialog_new_with_buttons ("My dialog", main_app_window, GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT, GTK_STOCK_OK, GTK_RESPONSE_ACCEPT, GTK_STOCK_CANCEL, GTK_RESPONSE_REJECT, NULL);

title :

Заголовок диалога, или NULL

parent :

Переходящий родитель диалога, или NULL

flags :

из GtkDialogFlags

first_button_text :

набор ID или текст для входа в первую кнопку, или NULL

... :

Ответный ID для первой кнопки, потом дополнительные кнопки, заканчивается NULL

Возвращает :

новый GtkDialog


gtk_dialog_run ()

gint        gtk_dialog_run                  (GtkDialog *dialog);

Блоки в основном рекурсивном цикле до dialog либо издают ответный сигнал, либо разрушаются. Если диалог разрушен в течении вызова gtk_dialog_run(), gtk_dialog_returns GTK_RESPONSE_NONE. Иначе, возвращается ID ответа из эмиссии сигнала "response". Перед вводом в рекурсивный основной цикл, gtk_dialog_run() на диалоге для вас вызывает gtk_widget_show(). Помните что вы всё ещё должны самостоятельно отображать дочерние виджеты диалога.

В течении gtk_dialog_run(), поведение "delete_event" по умолчанию отключено; если диалог получает "delete_event", он не будет разрушен как обычные окна, а gtk_dialog_run() вернёт GTK_RESPONSE_DELETE_EVENT. Кроме того, в течении gtk_dialog_run() диалог будет модальным. Вы можете вынудить gtk_dialog_run() вернуться в любое время вызвав gtk_dialog_response() издающий сигнал "response". Разрушение диалога в течении gtk_dialog_run() будет очень плохой идеей, потому что ваш код выполняемый после, не будет знать разрушен диалог или нет.

После возврата gtk_dialog_run(), вы несете ответственность за разрушение или скрытие диалога если вы хотите это сделать.

Типичное использование функции может быть таким:

gint result = gtk_dialog_run (GTK_DIALOG (dialog)); switch (result) { case GTK_RESPONSE_ACCEPT: do_application_specific_something (); break; default: do_nothing_since_dialog_was_cancelled (); break; } gtk_widget_destroy (dialog);

Помните что даже при том, что рекурсивный основной цикл даёт эффект модального диалога (это не позволяет пользователю взаимодействовать с другими окнами программы пока выполняется диалог), обратные вызовы такие как timeouts, IO channel watches, DND drops, и т.д., будут вызваны в течении gtk_dialog_run().

dialog :

GtkDialog

Возвращает :

Ответный ID


gtk_dialog_response ()

void gtk_dialog_response (GtkDialog *dialog, gint response_id);

Издаёт "response" сигнал с данным ответным ID. Используется для указания того, что пользователь ответил на диалог в некотором роде; обычно либо вы либо gtk_dialog_run() будете контролировать сигнал "response" и предпринимать соответствующие действия.

dialog :

GtkDialog

response_id :

ответный ID


gtk_dialog_add_button ()

GtkWidget* gtk_dialog_add_button (GtkDialog *dialog, const gchar *button_text, gint response_id);

Добавляет кнопку с данным текстом (или заготовленную кнопку, если button_text это заготовленный ID) и устанавливает чтобы щелчок на кнопке издавал "response" сигнал с данным response_id. Кнопка присоединяется к концу диалоговой области действия. Виджет кнопка возвращается, но обычно вам не нужно это.

dialog :

GtkDialog

button_text :

Текст кнопки, или заготовленный ID

response_id :

ответный ID для кнопки

Возвращает :

Добавленный виджет кнопки


gtk_dialog_add_buttons ()

void gtk_dialog_add_buttons (GtkDialog *dialog, const gchar *first_button_text, ...);

Добавляет больше кнопок, так же как многократный вызов gtk_dialog_add_button(). Список переменных аргументов должен быть NULL-завершенным как для gtk_dialog_new_with_buttons(). Каждая кнопка должна иметь и текст и ответный ID.

dialog :

GtkDialog

first_button_text :

Текст кнопки или заготовленный ID

... :

ответный ID для первой кнопки, затем остальные пары text-response_id


gtk_dialog_add_action_widget ()

void gtk_dialog_add_action_widget (GtkDialog *dialog, GtkWidget *child, gint response_id);

Добавляет активизируемый виджет к области действия GtkDialog, подключает обработчик сигнала который будет издаёт сигнал "response" в диалоге когда виджет активизируется. Виджет прикладывается к концу диалоговой области действия. Если вы хотите добавить не активизирующийся виджет, просто упакуйте его в поле action_area структуры GtkDialog.

dialog :

GtkDialog

child :

Активизирующийся виджет

response_id :

Ответный ID для child


gtk_dialog_get_has_separator ()

gboolean    gtk_dialog_get_has_separator    (GtkDialog *dialog);

Определяет доступен ли разделитель диалога.

dialog :

GtkDialog

Возвращает :

TRUE если диалог имеет разделитель


gtk_dialog_set_default_response ()

void gtk_dialog_set_default_response (GtkDialog *dialog, gint response_id);

Устанавливает последний виджет в диалоговой области действия с данным response_id как виджет по умолчанию для диалога. Нажатие "Enter" обычно активизирует виджет по умолчанию.

dialog :

GtkDialog

response_id :

ответный ID


gtk_dialog_set_has_separator ()

void gtk_dialog_set_has_separator (GtkDialog *dialog, gboolean setting);

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

dialog :

GtkDialog

setting :

TRUE для получения разделителя


gtk_dialog_set_response_sensitive ()

void gtk_dialog_set_response_sensitive (GtkDialog *dialog, gint response_id, gboolean setting);

Вызывает gtk_widget_set_sensitive (widget, setting) для каждого виджета в диалоговой области действия с данным response_id. Удобный способ регулировать чувствительность диалоговых кнопок.

dialog :

GtkDialog

response_id :

Ответный ID

setting :

TRUE для чувствительности


gtk_dialog_get_response_for_widget ()

gint gtk_dialog_get_response_for_widget (GtkDialog *dialog, GtkWidget *widget);

Получает ответный id виджета в диалоговой области действия.

dialog :

GtkDialog

widget :

Виджет в области действия dialog

Возвращает :

Ответный id widget, или GTK_RESPONSE_NONE если widget не имеет установленного ответного id.

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


gtk_alternative_dialog_button_order ()

gboolean gtk_alternative_dialog_button_order (GdkScreen *screen);

Возвращает TRUE если диалоги используют альтернативный порядок кнопок на экране screen. Смотрите gtk_dialog_set_alternative_button_order() для более подробной информации об альтернативном порядке кнопок.

Если вам нужно использовать эту функцию, вы должны вероятно подключиться к ::notify:gtk-alternative-button-order сигналу объекта GtkSettings ассоциированного с экраном screen, чтобы получить уведомление если установленный порядок кнопок изменится.

screen :

GdkScreen, или NULL для использования экрана по умолчанию

Возвращает :

Должен ли использоваться альтернативный порядок кнопок

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


gtk_dialog_set_alternative_button_order ()

void gtk_dialog_set_alternative_button_order (GtkDialog *dialog, gint first_response_id, ...);

Устанавливает альтернативный порядок кнопок. Если установки gtk-alternative-button-order установлены в TRUE, кнопки диалога перестраиваются согласно порядка переданного в эту функцию.

По умолчанию, GTK+ диалоги используют порядок утверждённый Gnome Human Interface Guidelines с утвердительной кнопкой скраю справа, а кнопкой отмены с лева от неё. Но встроенные диалоги GTK+ и GtkMessageDialogs обеспечивают альтернативный порядок кнопок, который более подходит для других платформ, например Windows.

Используйте эту функцию после добавления всех кнопок к вашему диалогу, как показано в следующем примере:

cancel_button = gtk_dialog_add_button (GTK_DIALOG (dialog), GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL); ok_button = gtk_dialog_add_button (GTK_DIALOG (dialog), GTK_STOCK_OK, GTK_RESPONSE_OK); gtk_widget_grab_default (ok_button); help_button = gtk_dialog_add_button (GTK_DIALOG (dialog), GTK_STOCK_HELP, GTK_RESPONSE_HELP); gtk_dialog_set_alternative_button_order (GTK_DIALOG (dialog), GTK_RESPONSE_OK, GTK_RESPONSE_CANCEL, GTK_RESPONSE_HELP, -1);

dialog :

GtkDialog

first_response_id :

Ответный id используемый кнопками одного dialog's

... :

Список ответных ids кнопок dialog's, заканчивается -1

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


gtk_dialog_set_alternative_button_order_from_array ()

void gtk_dialog_set_alternative_button_order_from_array (GtkDialog *dialog, gint n_params, gint *new_order);

Устанавливает альтернативный порядок кнопок. Если gtk-alternative-button-order установки установлены в TRUE, кнопки диалога перестраиваются согласно ответных ids в new_order.

Смотрите gtk_dialog_set_alternative_button_order() для подробностей.

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

dialog :

GtkDialog

n_params :

Число ответных ids в new_order

new_order :

Массив ответных ids кнопок dialog's

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

Детали свойств

Свойство "has-separator"

  "has-separator"        gboolean              : Read / Write

Диалог имеет разделительную полосу над кнопками.

Значение по умолчанию: TRUE

Детали свойств стиля

Свойство стиля "action-area-border"

  "action-area-border"   gint                  : Read

Ширина кромки вокруг области кнопок внизу диалога.

Допустимые значения: >= 0

Значение по умолчанию: 5


Свойство стиля "button-spacing"

  "button-spacing"       gint                  : Read

Интервал между кнопками.

Допустимые значения: >= 0

Значение по умолчанию: 10


Свойство стиля "content-area-border"

  "content-area-border"  gint                  : Read

Ширина кромки вокруг главной диалоговой области.

Допустимые значения: >= 0

Значение по умолчанию: 2

Детали сигнала

Сигнал "close"

void user_function (GtkDialog *dialog, gpointer user_data) : Run last / Action

dialog :

объект получающий сигнал.

user_data :

пользовательские данные устанавливаемые при подключении обработчика сигнала


Сигнал "response"

void user_function (GtkDialog *dialog, gint arg1, gpointer user_data) : Run last

Издаётся когда нажат виджет действия, диалог получает событие удаления, или программист приложения вызывает gtk_dialog_response(). На удаляющем событии, ответный ID равен GTK_RESPONSE_NONE. Иначе, это зависит от нажатого виджета действия.

dialog :

объект получающий сигнал.

arg1 :

ответный ID

user_data :

пользовательские данные устанавливаемые при подключении обработчика сигнала

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

GtkVBox

Вертикальная упаковка виджетов.

GtkWindow

Изменяет свойства вашего диалогового окна.

GtkButton

Добавляет их к action_area для получения ответа от пользователя.