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

#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. иначе, это зависит от нажатого виджета действия.

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