Package: gtk

Class gtk-dialog

Superclasses

gtk-window, gtk-bin, gtk-container, gtk-widget, g-initially-unowned, 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 gtk-header-bar for action buttons instead of the action-area. For technical reasons, this property is declared as an integer property, but you should only set it to true or nil.
Allowed values: [-1, 1]
Default value: -1
Since 3.12

Details

Dialog windows 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 user's part.

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

gtk-dialog windows are created with a call to to the functions gtk-dialog-new or gtk-dialog-new-with-buttons. The function gtk-dialog-new-with-buttons 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 window can be accessed through the functions gtk-dialog-get-content-area and gtk-dialog-get-action-area, as can be seen from the example below.

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

If you add buttons to a gtk-dialog window using the functions gtk-dialog-new-with-buttons, gtk-dialog-add-button, gtk-dialog-add-buttons, or gtk-dialog-add-action-widget, 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 response ID of :delete-event.

If you want to block waiting for a dialog to return before returning control flow to your code, you can call the function gtk-dialog-run. 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 window 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.

Example: Simple gtk-dialog usage
;; Function to open a dialog window displaying the message provided.
(defun quick-message (window message)
  (let (;; Create the widgets
        (dialog (gtk-dialog-new-with-buttons "Message"
                                             window
                                             '(:destroy-with-parent)
                                             "gtk-ok"
                                             :none))
        (label (gtk-label-new message)))
    ;; Ensure that the dialog window is destroyed when the user responds.
    (g-signal-connect dialog "response"
                      (lambda (dialog response-id)
                        (declare (ignore response-id))
                        (gtk-widget-destroy dialog)))
    ;; Add the label, and show everything we have added to the dialog.
    (gtk-container-add (gtk-dialog-get-content-area dialog) label)
    (gtk-widget-show-all dialog)))  
You can use a dialog window as a toplevel window from Lisp code. The following code shows a complete example of a function which displays a message in a dialog window. In this case you have to connect to the "response" signal. It is not possible to use the functions gtk-dialog-run and gtk-dialog-response. In the Lisp binding your program will hang, when using this functions to run the dialog window and to get the response.

Example: A toplevel dialog which can be called from any Lisp code
(defun demo-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)
                                               "gtk-ok"
                                               :none
                                               "gtk-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 response-id)
                          (declare (ignore response-id))
                          (setf response response-id)
                          (gtk-widget-destroy dialog)))
      ;; Add the label, and show everything we have added to the dialog.
      (gtk-container-add (gtk-dialog-get-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 vbox and action_area as internal children with the names "vbox" and "action_area".

gtk-dialog 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 action_area.

Example: A gtk-dialog UI definition fragment.
 <object class="GtkDialog" id="dialog1">
   <child internal-child="vbox">
     <object class="GtkVBox" id="vbox">
       <child internal-child="action_area">
         <object class="GtkHButtonBox" id="button_box">
           <child>
            <object class="GtkButton" id="button_cancel"/>
           </child>
           <child>
             <object class="GtkButton" id="button_ok"/>
           </child>
         </object>
       </child>
     </object>
   </child>
   <action-widgets>
     <action-widget response="3">button_ok</action-widget>
     <action-widget response="-5">button_cancel</action-widget>
   </action-widgets>
 </object>    

Style Property Details

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

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

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

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

Signal Details

The "close" signal
 lambda (dialog)   : Action      
The "close signal" is 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 object on which the signal is emitted.
The "response" signal
 lambda (dialog response-id)   : Run Last      
Emitted when an action widget is clicked, the dialog receives a delete event, or the application programmer calls the function gtk-dialog-response. On a delete event, the response ID is :delete-event of type gtk-response-type. Otherwise, it depends on which action widget was clicked.
dialog
The object on which the signal is emitted.
response-id
The response ID.
 

Inherited Slot Access Functions

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-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
gtk-container-border-width
gtk-container-child
gtk-container-resize-mode
pointer
g-object-has-reference
g-object-signal-handlers
2013-9-9