Package: gtk

Class gtk-file-chooser-dialog

Superclasses

gtk-dialog, gtk-window, gtk-bin, gtk-container, gtk-widget, gtk-buildable, gtk-file-chooser, g-object, common-lisp:standard-object, common-lisp:t

Documented Subclasses

None

Direct Slots

None

Details

The gtk-file-chooser-dialog widget 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 widget inside a gtk-dialog widget. It exposes the gtk-file-chooser interface, so you can use all of the gtk-file-chooser functions on the file chooser dialog as well as those for the gtk-dialog widget.

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

Example: Typical usage
In the simplest of cases, you can the following code to use the gtk-file-chooser-dialog widget 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 (eq :accept (gtk-dialog-run dialog))
      (let ((filename (gtk-file-chooser-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)))
    (setf (gtk-file-chooser-do-overwrite-confirmation dialog) t)
    (if filename
        (setf (gtk-file-chooser-filename dialog) filename)
        (setf (gtk-file-chooser-current-name dialog) "Untitled document"))
    (if (eq :accept (gtk-dialog-run dialog))
      (let ((filename (gtk-file-chooser-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 widget:
  • 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-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-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-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-filename, i.e. when you are doing a File/Save As command and you already have a file saved somewhere.

Response Codes
The gtk-file-chooser-dialog widget inherits from the gtk-dialog widget, 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 the gtk-response-type enumeration. For most dialog boxes you can use your own custom response codes rather than the ones in the gtk-response-type enumeration, but the gtk-file-chooser-dialog widget 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 the gtk-file-chooser-dialog widget 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 the gtk-file-chooser-dialog widget to ensure proper operation.
 

Inherited Slot Access Functions

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
gtk-container-border-width
gtk-container-child
gtk-container-resize-mode
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-dialog-use-header-bar
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-focus-on-click
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
g-object-has-reference
g-object-pointer
g-object-signal-handlers

See also

*2021-2-4