Class Dialog

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gobject.InitiallyUnowned
org.gnome.gtk.Widget
org.gnome.gtk.Window
org.gnome.gtk.Dialog
All Implemented Interfaces:
Accessible, Buildable, ConstraintTarget, Native, Root, ShortcutManager, Proxy
Direct Known Subclasses:
AppChooserDialog, ColorChooserDialog, FileChooserDialog, FontChooserDialog, MessageDialog, PageSetupUnixDialog, PrintUnixDialog
@Generated("org.javagi.JavaGI") @Deprecated public class Dialog extends Window implements Accessible, Buildable, ConstraintTarget, Native, Root, ShortcutManager
Deprecated.
Use Window instead

Dialogs are a convenient way to prompt the user for a small amount of input.

An example GtkDialog

Typical uses are to display a message, ask a question, or anything else that does not require extensive effort on the user’s part.

The main area of a GtkDialog is called the "content area", and is yours to populate with widgets such a GtkLabel or GtkEntry, to present your information, questions, or tasks to the user.

In addition, dialogs allow you to add "action widgets". Most commonly, action widgets are buttons. Depending on the platform, action widgets may be presented in the header bar at the top of the window, or at the bottom of the window. To add action widgets, create your GtkDialog using withButtons(String, Window, Set, String, Object...), or use addButton(String, int), addButtons(String, Object...), or addActionWidget(Widget, int).

GtkDialogs uses some heuristics to decide whether to add a close button to the window decorations. If any of the action buttons use the response ID ResponseType.CLOSE or ResponseType.CANCEL, the close button is omitted.

Clicking a button that was added as an action widget will emit the Gtk.Dialog::response signal with a response ID that you specified. GTK will never assign a meaning to positive response IDs; these are entirely user-defined. But for convenience, you can use the response IDs in the Gtk.ResponseType enumeration (these all have values less than zero). If a dialog receives a delete event, the Gtk.Dialog::response signal will be emitted with the ResponseType.DELETE_EVENT response ID.

Dialogs are created with a call to Dialog() or withButtons(String, Window, Set, String, Object...). The latter is recommended; it allows you to set the dialog title, some convenient flags, and add buttons.

A “modal” dialog (that is, one which freezes the rest of the application from user input), can be created by calling Window.setModal(boolean) on the dialog. When using withButtons(String, Window, Set, String, Object...), you can also pass the DialogFlags.MODAL flag to make a dialog modal.

For the simple dialog in the following example, a MessageDialog would save some effort. But you’d need to create the dialog contents manually if you had more than a simple message in the dialog.

An example for simple GtkDialog usage:

// Function to open a dialog box with a message
void
quick_message (GtkWindow *parent, char *message)
{
 GtkWidget *dialog, *label, *content_area;
 GtkDialogFlags flags;

 // Create the widgets
 flags = GTK_DIALOG_DESTROY_WITH_PARENT;
 dialog = gtk_dialog_new_with_buttons ("Message",
                                       parent,
                                       flags,
                                       _("_OK"),
                                       GTK_RESPONSE_NONE,
                                       NULL);
 content_area = gtk_dialog_get_content_area (GTK_DIALOG (dialog));
 label = gtk_label_new (message);

 // Ensure that the dialog box is destroyed when the user responds

 g_signal_connect_swapped (dialog,
                           "response",
                           G_CALLBACK (gtk_window_destroy),
                           dialog);

 // Add the label, and show everything we’ve added

 gtk_box_append (GTK_BOX (content_area), label);
 gtk_widget_show (dialog);
}

GtkDialog as GtkBuildable

The GtkDialog implementation of the GtkBuildable interface exposes the contentArea as an internal child with the name “content_area”.

GtkDialog supports a custom <action-widgets> element, which can contain multiple <action-widget> elements. The “response” attribute specifies a numeric response, and the content of the element is the id of widget (which should be a child of the dialogs actionArea). To mark a response as default, set the “default” attribute of the <action-widget> element to true.

GtkDialog supports adding action widgets by specifying “action” as the “type” attribute of a <child> element. The widget will be added either to the action area or the headerbar of the dialog, depending on the “use-header-bar” property. The response id has to be associated with the action widget using the <action-widgets> element.

An example of a GtkDialog UI definition fragment:

<object class="GtkDialog" id="dialog1">
  <child type="action">
    <object class="GtkButton" id="button_cancel"/>
  </child>
  <child type="action">
    <object class="GtkButton" id="button_ok">
    </object>
  </child>
  <action-widgets>
    <action-widget response="cancel">button_cancel</action-widget>
    <action-widget response="ok" default="true">button_ok</action-widget>
  </action-widgets>
</object>

Accessibility

GtkDialog uses the AccessibleRole.DIALOG role.

  • Constructor Details

    • Dialog

      public Dialog(MemorySegment address)
      Deprecated.
      Create a Dialog instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • Dialog

      public Dialog()
      Deprecated.
      Create a new Dialog.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Deprecated.
      Get the GType of the Dialog class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      Deprecated.
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected Dialog asParent()
      Deprecated.
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class Window
      Returns:
      the instance as if it were its parent type

    • withButtons

      @Deprecated public static Dialog withButtons(@Nullable String title, @Nullable Window parent, Set<DialogFlags> flags, @Nullable String firstButtonText, Object... varargs)
      Deprecated.
      Use Window instead

      Creates a new GtkDialog with the given title and transient parent.

      The flags argument can be used to make the dialog modal, have it destroyed along with its transient parent, or make it use a headerbar.

      Button text/response ID pairs should be listed in pairs, with a null pointer ending the list. Button text can be arbitrary text. A response ID can be any positive number, or one of the values in the Gtk.ResponseType enumeration. If the user clicks one of these buttons, GtkDialog will emit the Gtk.Dialog::response signal with the corresponding response ID.

      If a GtkDialog receives a delete event, it will emit ::response with a response ID of ResponseType.DELETE_EVENT.

      However, destroying a dialog does not emit the ::response signal; so be careful relying on ::response when using the DialogFlags.DESTROY_WITH_PARENT flag.

      Here’s a simple example:

      GtkWindow *main_app_window; // Window the dialog should show up on
GtkWidget *dialog;
GtkDialogFlags flags = GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT;
dialog = gtk_dialog_new_with_buttons ("My dialog",
                                      main_app_window,
                                      flags,
                                      _("_OK"),
                                      GTK_RESPONSE_ACCEPT,
                                      _("_Cancel"),
                                      GTK_RESPONSE_REJECT,
                                      NULL);
      Parameters:
      title - Title of the dialog
      parent - Transient parent of the dialog
      flags - from GtkDialogFlags
      firstButtonText - text to go in first button
      varargs - response ID for first button, then additional buttons, ending with null
      Returns:
      a new GtkDialog

    • withButtons

      @Deprecated public static Dialog withButtons(@Nullable String title, @Nullable Window parent, DialogFlags flags, @Nullable String firstButtonText, Object... varargs)
      Deprecated.
      Use Window instead

      Creates a new GtkDialog with the given title and transient parent.

      The flags argument can be used to make the dialog modal, have it destroyed along with its transient parent, or make it use a headerbar.

      Button text/response ID pairs should be listed in pairs, with a null pointer ending the list. Button text can be arbitrary text. A response ID can be any positive number, or one of the values in the Gtk.ResponseType enumeration. If the user clicks one of these buttons, GtkDialog will emit the Gtk.Dialog::response signal with the corresponding response ID.

      If a GtkDialog receives a delete event, it will emit ::response with a response ID of ResponseType.DELETE_EVENT.

      However, destroying a dialog does not emit the ::response signal; so be careful relying on ::response when using the DialogFlags.DESTROY_WITH_PARENT flag.

      Here’s a simple example:

      GtkWindow *main_app_window; // Window the dialog should show up on
GtkWidget *dialog;
GtkDialogFlags flags = GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT;
dialog = gtk_dialog_new_with_buttons ("My dialog",
                                      main_app_window,
                                      flags,
                                      _("_OK"),
                                      GTK_RESPONSE_ACCEPT,
                                      _("_Cancel"),
                                      GTK_RESPONSE_REJECT,
                                      NULL);
      Parameters:
      title - Title of the dialog
      parent - Transient parent of the dialog
      flags - from GtkDialogFlags
      firstButtonText - text to go in first button
      varargs - response ID for first button, then additional buttons, ending with null
      Returns:
      a new GtkDialog

    • addActionWidget

      @Deprecated public void addActionWidget(Widget child, int responseId)
      Deprecated.
      Use Window instead

      Adds an activatable widget to the action area of a GtkDialog.

      GTK connects a signal handler that will emit the Gtk.Dialog::response signal on the dialog when the widget is activated. The widget is appended to the end of the dialog’s action area.

      If you want to add a non-activatable widget, simply pack it into the actionArea field of the GtkDialog struct.

      Parameters:
      child - an activatable widget
      responseId - response ID for child

    • addButton

      @Deprecated public Widget addButton(String buttonText, int responseId)
      Deprecated.
      Use Window instead

      Adds a button with the given text.

      GTK arranges things so that clicking the button will emit the Gtk.Dialog::response signal with the given responseId. The button is appended to the end of the dialog’s action area. The button widget is returned, but usually you don’t need it.

      Parameters:
      buttonText - text of button
      responseId - response ID for the button
      Returns:
      the GtkButton widget that was added

    • addButtons

      @Deprecated public void addButtons(String firstButtonText, Object... varargs)
      Deprecated.
      Use Window instead

      Adds multiple buttons.

      This is the same as calling addButton(String, int) repeatedly. The variable argument list should be null-terminated as with withButtons(String, Window, Set, String, Object...). Each button must have both text and response ID.

      Parameters:
      firstButtonText - button text
      varargs - response ID for first button, then more text-response_id pairs

    • getContentArea

      @Deprecated public Box getContentArea()
      Deprecated.
      Use Window instead
      Returns the content area of dialog.
      Returns:
      the content area GtkBox.

    • getHeaderBar

      @Deprecated public HeaderBar getHeaderBar()
      Deprecated.
      Use Window instead

      Returns the header bar of dialog.

      Note that the headerbar is only used by the dialog if the Gtk.Dialog:use-header-bar property is true.

      Returns:
      the header bar

    • getResponseForWidget

      @Deprecated public int getResponseForWidget(Widget widget)
      Deprecated.
      Use Window instead
      Gets the response id of a widget in the action area of a dialog.
      Parameters:
      widget - a widget in the action area of this Dialog
      Returns:
      the response id of widget, or ResponseType.NONE if widget doesn’t have a response id set.

    • getWidgetForResponse

      @Deprecated public @Nullable Widget getWidgetForResponse(int responseId)
      Deprecated.
      Use Window instead
      Gets the widget button that uses the given response ID in the action area of a dialog.
      Parameters:
      responseId - the response ID used by the this Dialog widget
      Returns:
      the widget button that uses the given responseId

    • response

      @Deprecated public void response(int responseId)
      Deprecated.
      Use Window instead

      Emits the ::response signal with the given response ID.

      Used to indicate that the user has responded to the dialog in some way.

      Parameters:
      responseId - response ID

    • setDefaultResponse

      @Deprecated public void setDefaultResponse(int responseId)
      Deprecated.
      Use Window instead

      Sets the default widget for the dialog based on the response ID.

      Pressing “Enter” normally activates the default widget.

      Parameters:
      responseId - a response ID

    • setResponseSensitive

      @Deprecated public void setResponseSensitive(int responseId, boolean setting)
      Deprecated.
      Use Window instead

      A convenient way to sensitize/desensitize dialog buttons.

      Calls gtk_widget_set_sensitive (widget, @setting) for each widget in the dialog’s action area with the given responseId.

      Parameters:
      responseId - a response ID
      setting - true for sensitive

    • close

      public void close()
      Deprecated.
      Signal emitted when the user uses a keybinding to close the dialog.
      Overrides:
      close in class Window

    • onClose

      @Deprecated public SignalConnection<Dialog.CloseCallback> onClose(Dialog.CloseCallback handler)
      Deprecated.
      Use Window instead

      Emitted when the user uses a keybinding to close the dialog.

      This is a keybinding signal.

      The default binding for this signal is the Escape key.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitClose

      @Deprecated public void emitClose()
      Deprecated.
      Emits the "close" signal. See onClose(Dialog.CloseCallback).

    • onResponse

      @Deprecated public SignalConnection<Dialog.ResponseCallback> onResponse(Dialog.ResponseCallback handler)
      Deprecated.
      Use Window instead

      Emitted when an action widget is clicked.

      The signal is also emitted when the dialog receives a delete event, and when response(int) is called. On a delete event, the response ID is ResponseType.DELETE_EVENT. Otherwise, it depends on which action widget was clicked.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitResponse

      @Deprecated public void emitResponse(int responseId)
      Deprecated.
      Emits the "response" signal. See onResponse(Dialog.ResponseCallback).

    • builder

      public static Dialog.Builder<? extends Dialog.Builder> builder()
      Deprecated.
      A Dialog.Builder object constructs a Dialog with the specified properties. Use the various set...() methods to set properties, and finish construction with Dialog.Builder.build().
      Returns:
      the builder object