Package: gtk

Class gtk-dialog

Superclasses

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

Documented Subclasses

Direct Slots

use-header-bar
The use-header-bar property of type :int (Read / Write / Construct)
True if the dialog uses a header bar for action buttons instead of the action area. For technical reasons, this property is declared as an integer property, use the value 1 for true or -1 for false.
Allowed values: [-1, 1]
Default value: -1

Details

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.

Examples

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

GtkDialog as GtkBuildable

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>    

Style Property Details

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

Signal Details

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.
 

Slot Access Functions

Inherited Slot Access Functions

gtk-container-border-width
gtk-container-child
gtk-container-resize-mode
gtk-window-accept-focus
gtk-window-application
gtk-window-attached-to
gtk-window-decorated
gtk-window-default-height
gtk-window-default-width
gtk-window-deletable
gtk-window-destroy-with-parent
gtk-window-focus-on-map
gtk-window-focus-visible
gtk-window-gravity
gtk-window-has-resize-grip
gtk-window-has-toplevel-focus
gtk-window-hide-titlebar-when-maximized
gtk-window-icon
gtk-window-icon-name
gtk-window-is-active
gtk-window-mnemonics-visible
gtk-window-modal
gtk-window-opacity
gtk-window-resizable
gtk-window-resize-grip-visible
gtk-window-role
gtk-window-screen
gtk-window-skip-pager-hint
gtk-window-skip-taskbar-hint
gtk-window-startup-id
gtk-window-title
gtk-window-transient-for
gtk-window-type
gtk-window-type-hint
gtk-window-urgency-hint
gtk-window-window-position
gtk-widget-app-paintable
gtk-widget-can-default
gtk-widget-can-focus
gtk-widget-composite-child
gtk-widget-double-buffered
gtk-widget-events
gtk-widget-expand
gtk-widget-focus-on-click
gtk-widget-halign
gtk-widget-has-default
gtk-widget-has-focus
gtk-widget-has-tooltip
gtk-widget-height-request
gtk-widget-hexpand
gtk-widget-hexpand-set
gtk-widget-is-focus
gtk-widget-margin
gtk-widget-margin-bottom
gtk-widget-margin-end
gtk-widget-margin-left
gtk-widget-margin-right
gtk-widget-margin-start
gtk-widget-margin-top
gtk-widget-name
gtk-widget-no-show-all
gtk-widget-opacity
gtk-widget-parent
gtk-widget-receives-default
gtk-widget-scale-factor
gtk-widget-sensitive
gtk-widget-style
gtk-widget-tooltip-markup
gtk-widget-tooltip-text
gtk-widget-valign
gtk-widget-vexpand
gtk-widget-vexpand-set
gtk-widget-visible
gtk-widget-width-request
gtk-widget-window
g-object-has-reference
g-object-pointer
g-object-signal-handlers

See also

*2021-12-3