GTK+ Reference Manual |
||||
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Style Properties | Signals |
GtkDialogGtkDialog Создание всплывающих окон |
#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 |
Не помещать разделитель между областью действия и содержимым диалога. |
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+. |
GtkWidget* gtk_dialog_new (void);Создаёт новое диалоговое окно. Виджеты не должны быть упакованы в GtkWindow непосредственно, но в vbox и action_area, как описано выше.
Возвращает : |
новый GtkDialog. |
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 : |
|
first_button_text : |
набор ID или текст для входа в первую кнопку, или NULL |
... : |
Ответный ID для первой кнопки, потом дополнительные кнопки, заканчивается NULL |
Возвращает : |
новый GtkDialog |
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 : |
|
Возвращает : |
Ответный ID |
void gtk_dialog_response (GtkDialog *dialog,
gint response_id);
Издаёт "response" сигнал с данным ответным ID. Используется для указания того, что пользователь ответил на диалог в некотором роде; обычно либо вы либо gtk_dialog_run() будете контролировать сигнал "response" и предпринимать соответствующие действия.
dialog : |
|
response_id : |
ответный ID |
GtkWidget* gtk_dialog_add_button (GtkDialog *dialog,
const gchar *button_text,
gint response_id);
Добавляет кнопку с данным текстом (или заготовленную кнопку, если button_text это заготовленный ID) и устанавливает чтобы щелчок на кнопке издавал "response" сигнал с данным response_id. Кнопка присоединяется к концу диалоговой области действия. Виджет кнопка возвращается, но обычно вам не нужно это.
dialog : |
|
button_text : |
Текст кнопки, или заготовленный ID |
response_id : |
ответный ID для кнопки |
Возвращает : |
Добавленный виджет кнопки |
void gtk_dialog_add_buttons (GtkDialog *dialog,
const gchar *first_button_text,
...);
Добавляет больше кнопок, так же как многократный вызов gtk_dialog_add_button(). Список переменных аргументов должен быть NULL-завершенным как для gtk_dialog_new_with_buttons(). Каждая кнопка должна иметь и текст и ответный ID.
dialog : |
|
first_button_text : |
Текст кнопки или заготовленный ID |
... : |
ответный ID для первой кнопки, затем остальные пары text-response_id |
void gtk_dialog_add_action_widget (GtkDialog *dialog,
GtkWidget *child,
gint response_id);
Добавляет активизируемый виджет к области действия GtkDialog, подключает обработчик сигнала который будет издаёт сигнал "response" в диалоге когда виджет активизируется. Виджет прикладывается к концу диалоговой области действия. Если вы хотите добавить не активизирующийся виджет, просто упакуйте его в поле action_area структуры GtkDialog.
dialog : |
|
child : |
Активизирующийся виджет |
response_id : |
Ответный ID для child |
gboolean gtk_dialog_get_has_separator (GtkDialog *dialog);Определяет доступен ли разделитель диалога.
dialog : |
|
Возвращает : |
TRUE если диалог имеет разделитель |
void gtk_dialog_set_default_response (GtkDialog *dialog,
gint response_id);
Устанавливает последний виджет в диалоговой области действия с данным response_id как виджет по умолчанию для диалога. Нажатие "Enter" обычно активизирует виджет по умолчанию.
dialog : |
|
response_id : |
ответный ID |
void gtk_dialog_set_has_separator (GtkDialog *dialog,
gboolean setting);
Устанавливает имеет ли диалог разделитель над кнопками. TRUE по умолчанию.
dialog : |
|
setting : |
TRUE для получения разделителя |
void gtk_dialog_set_response_sensitive
(GtkDialog *dialog,
gint response_id,
gboolean setting);
Вызывает gtk_widget_set_sensitive (widget, setting) для каждого виджета в диалоговой области действия с данным response_id. Удобный способ регулировать чувствительность диалоговых кнопок.
dialog : |
|
response_id : |
Ответный ID |
setting : |
TRUE для чувствительности |
gint gtk_dialog_get_response_for_widget
(GtkDialog *dialog,
GtkWidget *widget);
Получает ответный id виджета в диалоговой области действия.
dialog : |
|
widget : |
Виджет в области действия dialog |
Возвращает : |
Ответный id widget, или GTK_RESPONSE_NONE если widget не имеет установленного ответного id. |
Начиная с версии 2.8
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
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 : |
|
first_response_id : |
Ответный id используемый кнопками одного dialog's |
... : |
Список ответных ids кнопок dialog's, заканчивается -1 |
Начиная с версии 2.6
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 : |
|
n_params : |
Число ответных ids в new_order |
new_order : |
Массив ответных ids кнопок dialog's |
Начиная с версии 2.6
"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 : |
пользовательские данные устанавливаемые при подключении обработчика сигнала |
void user_function (GtkDialog *dialog,
gint arg1,
gpointer user_data) : Run last
Издаётся когда нажат виджет действия, диалог получает событие удаления, или программист приложения вызывает gtk_dialog_response(). На удаляющем событии, ответный ID равен GTK_RESPONSE_NONE. Иначе, это зависит от нажатого виджета действия.
dialog : |
объект получающий сигнал. |
arg1 : |
ответный ID |
user_data : |
пользовательские данные устанавливаемые при подключении обработчика сигнала |
Вертикальная упаковка виджетов. |
|
Изменяет свойства вашего диалогового окна. |
|
Добавляет их к action_area для получения ответа от пользователя. |