Interface file-chooser - cl-cffi-gtk3 API documentation

Package: gtk

Interface gtk:file-chooser

Superclasses

gobject:object, common-lisp:standard-object, common-lisp:t

Documented Subclasses

gtk:file-chooser-button, gtk:file-chooser-dialog, gtk:file-chooser-native, gtk:file-chooser-widget

Direct Slots

action

The action property of type gtk:file-chooser-action (Read / Write)
The type of operation that the file selector is performing.
Default value: :action-open

create-folders

The create-folders property of type :boolean (Read / Write)
Whether a file chooser not in :action-open mode will offer the user to create new folders.
Default value: true

do-overwrite-confirmation

The do-overwrite-confirmation property of type :boolean (Read / Write)
Whether a file chooser in :action-save mode will present an overwrite confirmation dialog if the user selects a file name that already exists.
Default value: false

The extra-widget property of type gtk:widget (Read / Write)
Application supplied widget for extra options.

filter

The filter property of type gtk:file-filter (Read / Write)
The current filter for selecting which files are displayed.

local-only

The local-only property of type :boolean (Read / Write)
Whether the selected file(s) should be limited to local file URLs.
Default value: true

The preview-widget property of type gtk:widget (Read / Write)
Application supplied widget for custom previews.

The preview-widget-active property of type :boolean (Read / Write)
Whether the application supplied widget for custom previews should be shown.
Default value: true

select-multiple

The select-multiple property of type :boolean (Read / Write)
Whether to allow multiple files to be selected.
Default value: false

show-hidden

The show-hidden property of type :boolean (Read / Write)
Whether the hidden files and folders should be displayed.
Default value: false

use-preview-label

The use-preview-label property of type :boolean (Read / Write)
Whether to display a stock label with the name of the previewed file.
Default value: true

Details

The gtk:file-chooser interface is an interface that can be implemented by file selection widgets. The main widgets that implement this interface are the gtk:file-chooser-widget, gtk:file-chooser-dialog, and gtk:file-chooser-button widgets. You do not need to write a widget that implements the gtk:file-chooser interface unless you are trying to adapt an existing file selector to expose a standard programming interface.

The gtk:file-chooser interface allows for shortcuts to various places in the filesystem. In the default implementation these are displayed in the left pane. It may be a bit confusing at first that these shortcuts come from various sources and in various flavours, so lets explain the terminology here:

Bookmarks: are created by the user, by dragging folders from the right pane to the left pane, or by using the "Add". Bookmarks can be renamed and deleted by the user.
Shortcuts: can be provided by the application or by the underlying filesystem abstraction, for example, both the gnome-vfs and the Windows filesystems provide "Desktop" shortcuts. Shortcuts cannot be modified by the user.
Volumes: are provided by the underlying filesystem abstraction. Volumes are the "roots" of the filesystem.

File Names and Encodings

When the user is finished selecting files in a gtk:file-chooser widget, the program can get the selected names either as filenames or as URIs. For URIs, the normal escaping rules are applied if the URI contains non-ASCII characters. However, filenames are always returned in the character set specified by the G_FILENAME_ENCODING environment variable. Please see the GLib documentation for more details about this variable.

This means that while you can pass the result of the the gtk:file-chooser-filename function to the open() or fopen() functions, you may not be able to directly set it as the text of a gtk:label widget unless you convert it first to UTF-8, which all GTK widgets expect. You should use the g_filename_to_utf8() function to convert filenames into strings that can be passed to GTK widgets.

Adding a Preview Widget

You can add a custom preview widget to a file chooser and then get notification about when the preview needs to be updated. To install a preview widget, use the gtk:file-chooser-preview-widget function. Then, connect to the "update-preview" signal to get notified when you need to update the contents of the preview.

Your callback should use the gtk:file-chooser-preview-filename function to see what needs previewing. Once you have generated the preview for the corresponding file, you must call the gtk:file-chooser-preview-widget-active function with a boolean flag that indicates whether your callback could successfully generate a preview.

Example: Sample Usage

(defun create-file-chooser-preview ()
  (let ((response nil)
        (preview-width 256)
        (preview-height 256)
        (chooser (gtk:file-chooser-dialog-new "Example File Chooser Preview"
                                              nil
                                              :open
                                              "gtk-open" :accept
                                              "gtk-cancel" :cancel))
        (preview (make-instance 'gtk:image
                                :margin 24)))
    ;; Handler for the signal "upadate-preview"
    (g:signal-connect chooser "update-preview"
        (lambda (chooser)
          (let* ((filename (gtk:file-chooser-preview-filename chooser))
                 (pixbuf (when filename
                           (gdk:pixbuf-new-from-file-at-size filename
                                                             preview-width
                                                             preview-height))))
            (if pixbuf
                (progn
                  (gtk:image-set-from-pixbuf preview pixbuf)
                  (setf (gtk:file-chooser-preview-widget-active chooser) t))
                (setf (gtk:file-chooser-preview-widget-active chooser) nil)))))
    ;; Set the preview widget
    (setf (gtk:file-chooser-preview-widget chooser) preview)
    ;; Run the file chooser dialog
    (when (eq :accept
              (setf response
                    (gtk:dialog-run chooser)))
      (format t "Save to file ~A~%"
                (gtk:file-chooser-filename chooser)))
    (gtk:widget-destroy chooser)
    response))

Adding Extra Widgets

You can add extra widgets to a file chooser to provide options that are not present in the default design. For example, you can add a toggle button to give the user the option to open a file in read-only mode. You can use the gtk:file-chooser-extra-widget function to insert additional widgets in a file chooser.

Example: Sample Usage

(defun create-file-chooser-widget ()
  (let ((response nil)
        (chooser (gtk:file-chooser-dialog-new "Example File Chooser Widget"
                                              nil
                                              :open
                                              "gtk-open" :accept
                                              "gtk-cancel" :cancel))
        (extra-widget (make-instance 'gtk:box
                                     :orientation :horizontal
                                     :spacing 12))
        (local-only (gtk:check-button-new-with-label "Local only"))
        (select-multiple (gtk:check-button-new-with-label "Select Multiple"))
        (show-hidden (gtk:check-button-new-with-label "Show hidden")))
    ;; Connect signal handlers to the toggle buttons
    (g:signal-connect local-only "toggled"
                      (lambda (button)
                        (setf (gtk:file-chooser-local-only chooser)
                              (gtk:toggle-button-active button))))
    (g:signal-connect select-multiple "toggled"
                      (lambda (button)
                        (setf (gtk:file-chooser-select-multiple chooser)
                              (gtk:toggle-button-active button))))
    (g:signal-connect show-hidden "toggled"
                      (lambda (button)
                        (setf (gtk:file-chooser-show-hidden chooser)
                              (gtk:toggle-button-active button))))
    ;; Put the extra widgets in a box
    (gtk:box-pack-start extra-widget local-only)
    (setf (gtk:toggle-button-active local-only) t) ; default is true
    (gtk:box-pack-start extra-widget select-multiple)
    (gtk:box-pack-start extra-widget show-hidden)
    (setf (gtk:file-chooser-extra-widget chooser) extra-widget)
    ;; Show the extra widgets
    (gtk:widget-show-all extra-widget)
    ;; Run the file chooser dialog
    (when (eq :accept
              (setf response
                    (gtk:dialog-run chooser)))
      (format t "Open file ~A~%"
                (gtk:file-chooser-filename chooser)))
    (gtk:widget-destroy chooser)
    response))

If you want to set more than one extra widget in the file chooser, you can add a container such as a gtk:box or a gtk:grid widget and include your widgets in it. Then, set the container as the whole extra widget.

Signal Details

The "confirm-overwrite" signal

lambda (chooser)    :run-last

chooser: The gtk:file-chooser widget that received the signal.
Returns: The gtk:file-chooser-confirmation value that indicates which action to take after emitting the signal.

The signal gets emitted whenever it is appropriate to present a confirmation dialog when the user has selected a file name that already exists. The signal only gets emitted when the file chooser is in :save mode.

Most applications just need to turn on the do-overwrite-confirmation property, and they will automatically get a stock confirmation dialog. Applications which need to customize this behavior should do that, and also connect to the "confirm-overwrite" signal.

A signal handler for this signal must return a value of the gtk:file-chooser-confirmation enumeration, which indicates the action to take. If the handler determines that the user wants to select a different filename, it should return the :select-again value. If it determines that the user is satisfied with his choice of file name, it should return the :accept-filename value. On the other hand, if it determines that the stock confirmation dialog should be used, it should return the :confirm value. The following example illustrates this.

Example: Custom confirmation

(defun confirm-overwrite (chooser)
  (let ((uri (gtk:file-chooser-uri chooser)))
    ;; Check for read-only file
    (if (is-uri-read-only uri)
        (if (user-wants-to-replace-read-only-file uri)
            ;; User accepts overwriting
            :accept-filename
            ;; User rejects overwriting
            :select-again)
         ;; Fall back to the default dialog
         :confirm)))
   ...
  (let ((chooser (gtk:file-choose-dialog-new ...)))
    ...
    (setf (gtk:file-chooser-do-overwrite-confirmation chooser) t)
    (g:signal-connect chooser "confirm-overwrite" #'confirm-overwrite)
    ... )

The "current-folder-changed" signal

lambda (chooser)    :run-last

chooser: The gtk:file-chooser widget that received the signal.

The signal is emitted when the current folder in a file chooser changes. This can happen due to the user performing some action that changes folders, such as selecting a bookmark or visiting a folder on the file list. It can also happen as a result of calling a function to explicitly change the current folder in a file chooser. Normally you do not need to connect to this signal, unless you need to keep track of which folder a file chooser is showing.

The "file-activated" signal

lambda (chooser)    :run-last

chooser: The gtk:file-chooser widget that received the signal.

The signal is emitted when the user "activates" a file in the file chooser. This can happen by double-clicking on a file in the file list, or by pressing the Enter key. Normally you do not need to connect to the signal. It is used internally by the gtk:file-chooser-dialog class to know when to activate the default button in the dialog.

The "selection-changed" signal

lambda (chooser)    :run-last

chooser: The gtk:file-chooser widget that received the signal.

The signal is emitted when there is a change in the set of selected files in a file chooser. This can happen when the user modifies the selection with the mouse or the keyboard, or when explicitly calling functions to change the selection. Normally you do not need to connect to the signal, as it is easier to wait for the file chooser to finish running.

The "update-preview" signal

lambda (chooser)    :run-last

chooser: The gtk:file-chooser widget that received the signal.

The signal is emitted when the preview in a file chooser should be regenerated. For example, this can happen when the currently selected file changes. You should use this signal if you want your file chooser to have a preview widget. Once you have installed a preview widget with the gtk:file-chooser-preview-widget function, you should update it when the signal is emitted. You can use the gtk:file-chooser-preview-filename or gtk:file-chooser-preview-uri functions to get the name of the file to preview. Your widget may not be able to preview all kinds of files. Your callback function must call the gtk:file-chooser-preview-widget-active function to inform the file chooser about whether the preview was generated successfully or not.