gtk-window, gtk-bin, gtk-container, gtk-widget, gtk-buildable, g-object, common-lisp:standard-object, common-lisp:t

gtk-about-dialog, gtk-app-chooser-dialog, gtk-color-chooser-dialog, gtk-color-selection-dialog, gtk-file-chooser-dialog, gtk-font-chooser-dialog, gtk-message-dialog, gtk-page-setup-unix-dialog, gtk-print-unix-dialog, gtk-recent-chooser-dialog

Dialogs are a convenient way to prompt the user for a small amount of input, e.g. to display a message, ask a question, or anything else that does not require extensive effort on the part of the user.

GTK treats a dialog as a window split vertically. The top section is known as the "content area" and is a gtk-box widget with a :vertical orientation. This is where widgets such as a gtk-label or a gtk-entry widget should be packed. The bottom area is known as the "action area". This is generally used for packing buttons into the dialog which may perform functions such as Cancel, OK, or Apply.

The gtk-dialog widget is created with a call to to the gtk-dialog-new or gtk-dialog-new-with-buttons functions. The gtk-dialog-new-with-buttons function is recommended. It allows you to set the dialog title, some convenient flags, and add simple buttons.

If the dialog is a newly created dialog, the two primary areas of the dialog can be accessed through the gtk-dialog-content-area and gtk-dialog-action-area functions.

A modal dialog, that is, one which freezes the rest of the application from user input, can be created by calling the gtk-window-modal function on the dialog. When using the gtk-dialog-new-with-buttons function you can also pass the :modal flag of the gtk-dialog-flags flags to make a dialog modal.

If you add buttons to a dialog using the gtk-dialog-new-with-buttons, gtk-dialog-add-button, gtk-dialog-add-buttons, or gtk-dialog-add-action-widget functions, clicking the button will emit a signal called "response" 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-response-type enumeration. These all have values less than zero. If a dialog receives a delete event, the "response" signal will be emitted with a :delete-event response ID.

If you want to block waiting for a dialog to return before returning control flow to your code, you can call the gtk-dialog-run function. This function enters a recursive main loop and waits for the user to respond to the dialog, returning the response ID corresponding to the button the user clicked.

For the simple dialog in the following example, in reality you would probably use a gtk-message-dialog widget to save yourself some effort. But you would need to create the dialog contents manually if you had more than a simple message in the dialog. Simple gtk-dialog widget usage:

;; Function to open a dialog displaying the message provided.
(defun quick-message (window message)
  (let (;; Create the widgets
        (dialog (gtk-dialog-new-with-buttons "Message"
                                             window
                                             '(:destroy-with-parent)
                                             "_OK"
                                             :none))
        (label (gtk-label-new message)))
    ;; Ensure that the dialog is destroyed when the user responds.
    (g-signal-connect dialog "response"
                      (lambda (dialog id)
                        (declare (ignore id))
                        (gtk-widget-destroy dialog)))
    ;; Add the label, and show everything we have added to the dialog.
    (gtk-container-add (gtk-dialog-content-area dialog) label)
    (gtk-widget-show-all dialog)))    

You can use a dialog as a toplevel window from Lisp code. The following code shows a complete example of a function which displays a message in a dialog. In this case you have to connect to the "response" signal. It is not possible to use the gtk-dialog-run and gtk-dialog-response functions for this toplevel dialog. In the Lisp binding your program will hang, when using this functions to run the dialog and to get the response.

A toplevel dialog which can be called from any Lisp code:

(defun example-dialog-toplevel (message)
 (let ((response nil))
   (within-main-loop
    (let (;; Create the widgets
          (dialog (gtk-dialog-new-with-buttons "Demo Toplevel Dialog"
                                               nil ; No Parent window
                                               '(:modal)
                                               "_OK"
                                               :none
                                               "_Cancel"
                                               :cancel))
          (label (gtk-label-new message)))
      ;; Signal handler for the dialog to handle the signal "destroy".
      (g-signal-connect dialog "destroy"
                        (lambda (widget)
                          (declare (ignore widget))
                          ;; Quit the main loop and destroy the thread.
                          (leave-gtk-main)))
      ;; Get the response and destroy the dialog.
      (g-signal-connect dialog "response"
                        (lambda (dialog id)
                          (setf response id)
                          (gtk-widget-destroy dialog)))
      ;; Add the label, and show everything we have added to the dialog.
      (gtk-container-add (gtk-dialog-content-area dialog) label)
      (gtk-widget-show-all dialog)))
    ;; Wait until the dialog is destroyed.
    (join-gtk-main)
    (when response
      (format t "The response ID is ~A" response))))    

The gtk-dialog implementation of the gtk-buildable interface exposes the content area and action area as internal children with the names vbox and action_area.

The gtk-dialog implementation 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 the widget, which should be a child of the action area of the dialog. To mark a response as default, set the "default" attribute of the <action-widget> element to true.

The gtk-dialog implementation 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.

Example: A gtk-dialog 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">
      <property name="can-default">True</property>
    </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>    

action-area-border

The action-area-border style property of type :int (Read)
Width of border around the button area at the bottom of the dialog.
Allowed values: >= 0
Default value: 0

button-spacing

The button-spacing style property of type :int (Read)
Spacing between buttons.
Allowed values: >= 0
Default value: 4

content-area-border

The content-area-border style property of type :int (Read)
Width of border around the main dialog area.
Allowed values: >= 0
Default value: 2

content-area-spacing

The content-area-spacing style property of type :int (Read)
The default spacing used between elements of the content area of the dialog, as returned by the gtk-dialog-content-area function, unless the gtk-box-spacing function was called on that widget directly.
Allowed values: >= 0
Default value: 0

The "close" signal

 lambda (dialog)    :action      

A keybinding signal which gets emitted when the user uses a keybinding to close the dialog. The default binding for this signal is the Escape key.

dialog

The gtk-dialog widget on which the signal is emitted.

The "response" signal

 lambda (dialog response)    :run-last      

Emitted when an action widget is clicked, the dialog receives a delete event, or the application programmer calls the gtk-dialog-response function. On a delete event, the response ID is the :delete-event value of the gtk-response-type enumeration. Otherwise, it depends on which action widget was clicked.

dialog

The gtk-dialog widget on which the signal is emitted.

response

An integer with the response ID.