[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11. Dialogs


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.1 General Dialog

figures/dialog-window403x167

Figure 11.1: General Dialog Window

The dialog widget is just a window with a few things pre-packed into it. The dialog widget is of type GtkDialog which is represented by the Lisp class gtk-dialog. A dialog widget can be created with the function gtk-dialog-new or the call (make-instance 'gtk-dialog). The function gtk-dialog-new does not take an argument. In addition the function gtk-dialog-new-with-buttons is available. It allows you to set the dialog title, some convenient flags, and add simple buttons.

The dialog widget consists of an content area which is of type gtk-box with the value :vertical of type gtk-orientation. The content area can be filled with the content of a dialog. At the button of the window the dialog widget has an action area which takes the desired buttons of the dialog.

The function gtk-dialog-get-content-area gets the content area of a dialog. Because the content area is a vertical box of type gtk-box any desired widgets can be added to the content area with the functions gtk-box-pack-start or gtk-box-pack-end. To display the content area it is necessary to call the function gtk-widget-show explicitly. The function create-dialog in example-dialog-window shows how to fill widgets into a dialog widget.

The action area can be filled with the desired buttons for the dialog window. Standard buttons can be added with the function gtk-dialog-add-button. The function takes three arguments. The first argument is the dialog window the button is added to. The second argument is a string which is the text of the button or a stock ID. The last argument is of the enumeration type gtk-response-type and defines the response type of the button. Possible values of gtk-response-type are shown in table-gtk-response-type.

Alternatively to the function gtk-dialog-add-button buttons can be added with the functions gtk-box-pack-start or gtk-box-pack-end to the action area. The action area is of type gtk-button-box with a :horizontal orientation and can be get with the function gtk-dialog-get-action-area.

Table 11.1: Values of the gtk-response-type enumeration

:none

Returned if an action widget has no response ID, or if the dialog gets programmatically hidden or destroyed.

:reject

Generic response ID, not used by GTK+ dialogs

:accept

Generic response ID, not used by GTK+ dialogs

:event

Returned if the dialog is deleted

:ok

Returned by OK buttons in GTK+ dialogs

:cancel

Returned by Cancel buttons in GTK+ dialogs

:close

Returned by Close buttons in GTK+ dialogs

:yes

Returned by Yes buttons in GTK+ dialogs

:no

Returned by No buttons in GTK+ dialogs

:apply

Returned by Apply buttons in GTK+ dialogs

:help

Returned by Help buttons in GTK+ dialogs

After creation and configuration of the dialog window the dialog is executed with the function gtk-dialog-run. The function takes the dialog window of type gtk-dialog as the only argument. After closing the dialog window with one of the buttons the response is returned as an integer value of type gtk-response-type.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.2 Message Dialog

figures/message-dialog480x157

Figure 11.2: Message Dialog

A message dialog gtk-message-dialog is a subclass of the more general class gtk-dialog and gives an easy way to display messages to the user. figure-message-dialog shows an example for an informational message.

A message dialog is created with the call (make-instance 'gtk-message-dialog) or the functions gtk-message-dialog-new and gtk-message-dialog-new-with-markup. Various properties control the appearance of a message dialog. The function create-message-dialog in example-dialog-window shows the settings of the properties message-type, buttons, text, and secondary-text. The type of a message dialog is one of the values of the gtk-message-type enumeration. The possible values are listed in table-gtk-message-type. Predefined buttons of the gtk-buttons-type enumeration for a message dialog are listed in table-gtk-buttons-type.

Table 11.2: The type of message being displayed in the dialog.

:info

Informational message

:warning

Nonfatal warning message

:question

Question requiring a choice

:error

Fatal error message

:other

None of the above, doesn't get an icon

Table 11.3: Prebuilt sets of buttons for a message dialog.

:none

no buttons at all

:ok

an OK button

:close

a Close button

:canel

a Cancel button

:yes-no

Yes and No buttons

:ok-cancel

OK and Cancel buttons


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.3 About Dialog

figures/about-dialog353x228

Figure 11.3: About Dialog

The gtk-about-dialog offers a simple way to display information about a program like its logo, name, copyright, website and license. It is also possible to give credits to the authors, documenters, translators and artists who have worked on the program. An about dialog is typically opened when the user selects the About option from the Help menu. All parts of the dialog are optional.

About dialogs often contain links and email addresses. gtk-about-dialog displays these as clickable links. By default, it calls the function gtk-show-uri when a user clicks one. The behavior can be overridden with the "activate-link" signal.

To make constructing a gtk-about-dialog as convenient as possible, the function gtk-show-about-dialog is available which constructs and shows a dialog and keeps it around so that it can be shown again.

Note that GTK+ sets a default title of _("About %s") on the dialog window, where %s is replaced by the name of the application, but in order to ensure proper translation of the title, applications should set the title property explicitly when constructing a gtk-about-dialog.

It is possible to show a gtk-about-dialog like any other gtk-dialog, e. g. using gtk-dialog-run. In this case, you might need to know that the 'Close' button returns the :cancel response ID.

Example 11.1: Examples for a general, a message, and an about dialog.

(defun license-text ()
  (format nil
          "This program is free software: you can redistribute it and/or ~
          modify it under the terms of the GNU Lesser General Public ~
          License for Lisp as published by the Free Software Foundation, ~
          either version 3 of the License, or (at your option) any later ~
          version and with a preamble to the GNU Lesser General Public ~
          License that clarifies the terms for use with Lisp programs and ~
          is referred as the LLGPL.~%~% ~
          This program is distributed in the hope that it will be useful, ~
          but WITHOUT ANY WARRANTY; without even the implied warranty of ~
          MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the ~
          GNU Lesser General Public License for more details. ~%~% ~
          You should have received a copy of the GNU Lesser General Public ~
          License along with this program and the preamble to the Gnu ~
          Lesser General Public License.  If not, see ~
          <http://www.gnu.org/licenses/> and ~
          <http://opensource.franz.com/preamble.html>."))

(defun create-dialog ()
  (let ((dialog (make-instance 'gtk-dialog
                               :title "Dialog Window"
                               :has-separator t)))
    ;; Add a border width to the vbox of the content area
    (setf (gtk-container-border-width (gtk-dialog-get-content-area dialog))
          12)
    ;; Add a label widget with text to the content area
    (let ((vbox (make-instance 'gtk-vbox :border-width 12))
          (label (make-instance 'gtk-label
                                :wrap t
                                :label
                                (format nil
                                        "The content area is the place to ~
                                         put in the widgets.~%~% ~
                                         The action area is separated from ~
                                         the content area with a horizontal ~
                                         line."))))
      (gtk-box-pack-start vbox label)
      (gtk-box-pack-start (gtk-dialog-get-content-area dialog) vbox)
      ;; Show the content area of the dialog
      (gtk-widget-show (gtk-dialog-get-content-area dialog)))
    ;; Add buttons with a stock ID to the action area
    (gtk-dialog-add-button dialog "gtk-yes" :yes)
    (gtk-dialog-add-button dialog "gtk-no" :no)
    (gtk-dialog-add-button dialog "gtk-cancel" :cancel)
    (gtk-dialog-set-default-response dialog :cancel)
    ;; Change the order of the buttons
    (gtk-dialog-set-alternative-button-order dialog
                                             (list :yes :cancel :no))
    ;; Run the dialog and print the message on the console
    (format t "Response was: ~S~%" (gtk-dialog-run dialog))
    ;; Destroy the dialog
    (gtk-widget-destroy dialog)))

(defun create-message-dialog ()
  (let ((dialog (make-instance 'gtk-message-dialog
                               :message-type :info
                               :buttons :ok
                               :text "Info Message Dialog"
                               :secondary-text
                               (format nil
                                       "This is a message dialog of type ~
                                        :info with a secondary text."))))
    ;; Run the message dialog
    (gtk-dialog-run dialog)
    ;; Destroy the message dialog
    (gtk-widget-destroy dialog)))

(defun create-about-dialog ()
  (let ((dialog (make-instance 'gtk-about-dialog
                               :program-name "Example Dialog"
                               :version "0.00"
                               :copyright "(c) Dieter Kaiser"
                               :website
                               "github.com/crategus/cl-cffi-gtk"
                               :website-label "Project web site"
                               :license (license-text)
                               :authors '("Kalyanov Dmitry"
                                          "Dieter Kaiser")
                               :documenters '("Dieter Kaiser")
                               :artists '("None")
                               :logo-icon-name
                               "applications-development"
                               :wrap-license t)))
    ;; Run the about dialog
    (gtk-dialog-run dialog)
    ;; Destroy the about dialog
    (gtk-widget-destroy dialog)))

(defun example-dialog ()
  (within-main-loop
    (let ((window (make-instance 'gtk-window
                                 :type :toplevel
                                 :title "Example Dialog"
                                 :default-width 250
                                 :border-width 12))
          (vbox (make-instance 'gtk-vbox
                               :spacing 6)))
      (g-signal-connect window "destroy"
                        (lambda (widget)
                          (declare (ignore widget))
                          (leave-gtk-main)))
      (gtk-container-add window vbox)
      (let ((button (make-instance 'gtk-button
                                   :label "Open a Dialog Window")))
        (gtk-box-pack-start vbox button)
        (g-signal-connect button "clicked"
           (lambda (widget)
             (declare (ignore widget))
             ;; Create and show the dialog
             (create-dialog))))
      (let ((button (make-instance 'gtk-button
                                   :label "Open a Message Dialog")))
        (gtk-box-pack-start vbox button)
        (g-signal-connect button "clicked"
           (lambda (widget)
             (declare (ignore widget))
             ;; Create and show the message dialog
             (create-message-dialog))))
      (let ((button (make-instance 'gtk-button
                                   :label "Open an About Dialog")))
        (gtk-box-pack-start vbox button)
        (g-signal-connect button "clicked"
           (lambda (widget)
             (declare (ignore widget))
             ;; Create and show the about dialog
             (create-about-dialog))))
      (gtk-box-pack-start vbox
                          (make-instance 'gtk-hseparator))
      ;; Create a quit button
      (let ((button (make-instance 'gtk-button
                                   :label "Quit")))
        (g-signal-connect button "clicked"
                          (lambda (widget)
                            (declare (ignore widget))
                            (gtk-widget-destroy window)))
        (gtk-box-pack-start vbox button))
      (gtk-widget-show window))))

[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Crategus on January, 10 2016 using texi2html 1.76.