gtk-window, gtk-bin, gtk-container, gtk-widget, g-initially-unowned, 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-font-selection-dialog, gtk-message-dialog, gtk-page-setup-unix-dialog, gtk-print-unix-dialog, gtk-recent-chooser-dialog
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 GtkBuildableThe 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
The "close" signal
lambda (dialog) : ActionThe "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.
The "response" signal
lambda (dialog response-id) : Run LastEmitted 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.
Inherited Slot Access Functions