[ новости /+++ | форум | теги | ]

Каталог документации / Раздел "Программирование, языки" / Оглавление документа

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

#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;

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

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_dialog_new ()

GtkWidget*  gtk_dialog_new                  (void);

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

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

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().

gtk_dialog_response ()

void        gtk_dialog_response             (GtkDialog *dialog,
                                             gint response_id);

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

gtk_dialog_add_button ()

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

Добавляет кнопку с данным текстом (или заготовленную кнопку, если button_text это заготовленный ID) и устанавливает чтобы щелчок на кнопке издавал "response" сигнал с данным response_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.

gtk_dialog_add_action_widget ()

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

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

gtk_dialog_get_has_separator ()

gboolean    gtk_dialog_get_has_separator    (GtkDialog *dialog);

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

gtk_dialog_set_default_response ()

void        gtk_dialog_set_default_response (GtkDialog *dialog,
                                             gint response_id);

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

gtk_dialog_set_has_separator ()

void        gtk_dialog_set_has_separator    (GtkDialog *dialog,
                                             gboolean 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. Удобный способ регулировать чувствительность диалоговых кнопок.

gtk_dialog_get_response_for_widget ()

gint        gtk_dialog_get_response_for_widget
                                            (GtkDialog *dialog,
                                             GtkWidget *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, чтобы получить уведомление если установленный порядок кнопок изменится.

Начиная с версии 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);

Начиная с версии 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() для подробностей.

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

Начиная с версии 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

Сигнал "response"

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

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

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

Партнёры:

Хостинг: