Package: gtk

Class gtk-file-chooser-dialog

Superclasses

Documented Subclasses

None

Direct Slots

None

Details

gtk-file-chooser-dialog is a dialog box suitable for use with "File/Open" or "File/Save as" commands. This widget works by putting a gtk-file-chooser-widget inside a gtk-dialog. It exposes the GtkFileChooserIface interface, so you can use all of the gtk-file-chooser functions on the file chooser dialog as well as those for gtk-dialog.

Note that gtk-file-chooser-dialog does not have any methods of its own. Instead, you should use the functions that work on a gtk-file-chooser.

Example: Typical usage

In the simplest of cases, you can the following code to use gtk-file-chooser-dialog to select a file for opening:
(defun create-file-chooser-dialog-open (window)
  (let ((dialog (gtk-file-chooser-dialog-new "Open File"
                                             window
                                             :open
                                             "gtk-cancel" :cancel
                                             "gtk-open" :accept)))
    (if (eql (gtk-dialog-run dialog)
             (foreign-enum-value 'gtk-response-type :accept))
      (let ((filename (gtk-file-chooser-get-filename dialog)))
        ...
      ))

(gtk-widget-destroy dialog)))
To use a dialog for saving, you can use this:
(defun create-file-chooser-dialog-save (window filename)
  (let ((dialog (gtk-file-chooser-dialog-new "Save File"
                                             window
                                             :save
                                             "gtk-cancel" :cancel
                                             "gtk-save" :accept)))
    (gtk-file-chooser-set-do-overwrite-confirmation dialog t)
    (if filename
        (gtk-file-chooser-set-filename dialog filename)
        (gtk-file-chooser-set-current-name dialog "Untitled document"))
    (if (eql (gtk-dialog-run dialog)
             (foreign-enum-value 'gtk-response-type :accept))
      (let ((filename (gtk-file-chooser-get-filename dialog)))
        ...
      ))

(gtk-widget-destroy dialog)))
Setting up a file chooser dialog
There are various cases in which you may need to use a gtk-file-chooser-dialog:
  • To select a file for opening, as for a File/Open command. Use :open.
  • To save a file for the first time, as for a File/Save command. Use :save, and suggest a name such as "Untitled" with the function gtk-file-chooser-set-current-name.
  • To save a file under a different name, as for a File/Save As command. Use :save, and set the existing filename with the function gtk-file-chooser-set-filename.
  • To choose a folder instead of a file. Use :select-folder.
Note
Old versions of the file chooser's documentation suggested using the function gtk-file-chooser-set-current-folder in various situations, with the intention of letting the application suggest a reasonable default folder. This is no longer considered to be a good policy, as now the file chooser is able to make good suggestions on its own. In general, you should only cause the file chooser to show a specific folder when it is appropriate to use the function gtk-file-chooser-set-filename, i. e. when you are doing a File/Save As command and you already have a file saved somewhere.

Response Codes
gtk-file-chooser-dialog inherits from gtk-dialog, so buttons that go in its action area have response codes such as :accept and :cancel. For example, you could call the function gtk-file-chooser-dialog-new as follows:
 (let ((dialog (gtk-file-chooser-dialog-new "Open File"
                                            parent-window
                                            :open
                                            "gtk-cancel" :cancel
                                            "gtk-open" :accept)))
   ... )    
This will create buttons for "Cancel" and "Open" that use stock response identifiers from gtk-response-type. For most dialog boxes you can use your own custom response codes rather than the ones in gtk-response-type, but gtk-file-chooser-dialog assumes that its "accept"-type action, e. g. an "Open" or "Save" button, will have one of the following response codes:
     :accept     :ok     :yes     :apply    
This is because gtk-file-chooser-dialog must intercept responses and switch to folders if appropriate, rather than letting the dialog terminate - the implementation uses these known response codes to know which responses can be blocked if appropriate.

Note
To summarize, make sure you use a stock response code when you use gtk-file-chooser-dialog to ensure proper operation.
 

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
gtk-file-chooser-action
gtk-file-chooser-create-folders
gtk-file-chooser-do-overwrite-confirmation
gtk-file-chooser-extra-widget
gtk-file-chooser-filter
gtk-file-chooser-local-only
gtk-file-chooser-preview-widget
gtk-file-chooser-preview-widget-active
gtk-file-chooser-select-multiple
gtk-file-chooser-show-hidden
gtk-file-chooser-use-preview-label
pointer
g-object-has-reference
g-object-signal-handlers

See also

2013-6-18