FileChooserProtocol

public protocol FileChooserProtocol

GtkFileChooser is an interface that can be implemented by file selection widgets.

In GTK, the main objects that implement this interface are [classGtk.FileChooserWidget] and [classGtk.FileChooserDialog].

You do not need to write an object that implements the GtkFileChooser interface unless you are trying to adapt an existing file selector to expose a standard programming interface.

GtkFileChooser 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. For example, a Paint program may want to add a shortcut for a Clipart folder. Shortcuts cannot be modified by the user.
Volumes: are provided by the underlying filesystem abstraction. They are the “roots” of the filesystem.

File Names and Encodings

When the user is finished selecting files in a GtkFileChooser, your program can get the selected filenames as GFiles.

Adding options

You can add extra widgets to a file chooser to provide options that are not present in the default design, by using [methodGtk.FileChooser.add_choice]. Each choice has an identifier and a user visible label; additionally, each choice can have multiple options. If a choice has no option, it will be rendered as a check button with the given label; if a choice has options, it will be rendered as a combo box.

The FileChooserProtocol protocol exposes the methods and properties of an underlying GtkFileChooser instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see FileChooser. Alternatively, use FileChooserRef as a lighweight, unowned reference if you already have an instance you just want to use.

Show on GitHub

ptr
Untyped pointer to the underlying GtkFileChooser instance.
Declaration
Swift

var ptr: UnsafeMutableRawPointer! { get }
Show on GitHub
file_chooser_ptr Default implementation
Typed pointer to the underlying GtkFileChooser instance.

Default Implementation

Return the stored, untyped pointer as a typed pointer to the GtkFileChooser instance.
Declaration
Swift

var file_chooser_ptr: UnsafeMutablePointer<GtkFileChooser>! { get }
Show on GitHub
init(raw:)
Required Initialiser for types conforming to FileChooserProtocol
Declaration
Swift

init(raw: UnsafeMutableRawPointer)
Show on GitHub

FileChooser Interface


                    
                    
                    bind(property:to:_:flags:transformFrom:transformTo:)

Extension method

Bind a FileChooserPropertyName source property to a given target object.

Declaration

Swift

@discardableResult
@inlinable
func bind<Q, T>(property source_property: FileChooserPropertyName, to target: T, _ target_property: Q, flags f: BindingFlags = .default, transformFrom transform_from: @escaping GLibObject.ValueTransformer = { $0.transform(destValue: $1) }, transformTo transform_to: @escaping GLibObject.ValueTransformer = { $0.transform(destValue: $1) }) -> BindingRef! where Q : PropertyNameProtocol, T : ObjectProtocol

Parameters

`source_property`	the source property to bind
`target`	the target object to bind to
`target_property`	the target property to bind to
`flags`	the flags to pass to the `Binding`
`transform_from`	`ValueTransformer` to use for forward transformation
`transform_to`	`ValueTransformer` to use for backwards transformation

Return Value

binding reference or nil in case of an error

Show on GitHub


                    
                    
                    get(property:)

Extension method

Get the value of a FileChooser property

Declaration

Swift

@inlinable
func get(property: FileChooserPropertyName) -> GLibObject.Value

Parameters


                                property

the property to get the value for

Return Value

the value of the named property

Show on GitHub


                    
                    
                    set(property:value:)

Extension method

Set the value of a FileChooser property. Note that this will only have an effect on properties that are writable and not construct-only!

Declaration

Swift

@inlinable
func set(property: FileChooserPropertyName, value v: GLibObject.Value)

Parameters


                                property

the property to get the value for

Return Value

the value of the named property

Show on GitHub

FileChooser Interface: FileChooserProtocol extension (methods and fields)

addChoice(id:label:options:optionLabels:) Extension method
Adds a ‘choice’ to the file chooser.

This is typically implemented as a combobox or, for boolean choices, as a checkbutton. You can select a value using [methodGtk.FileChooser.set_choice] before the dialog is shown, and you can obtain the user-selected value in the [signalGtk.Dialog::response] signal handler using [methodGtk.FileChooser.get_choice].
Declaration
Swift

@inlinable func addChoice(id: UnsafePointer<CChar>!, label: UnsafePointer<CChar>!, options: UnsafeMutablePointer<UnsafePointer<CChar>?>! = nil, optionLabels: UnsafeMutablePointer<UnsafePointer<CChar>?>! = nil)
Show on GitHub
add(filter:) Extension method
Adds filter to the list of filters that the user can select between.

When a filter is selected, only files that are passed by that filter are displayed.

Note that the chooser takes ownership of the filter if it is floating, so you have to ref and sink it if you want to keep a reference.
Declaration
Swift

@inlinable func add<FileFilterT>(filter: FileFilterT) where FileFilterT : FileFilterProtocol
Show on GitHub
addShortcut(folder:) Extension method
Adds a folder to be displayed with the shortcut folders in a file chooser.
Declaration
Swift

@inlinable func addShortcut<FileT>(folder: FileT) throws -> Bool where FileT : FileProtocol
Show on GitHub
getAction() Extension method
Gets the type of operation that the file chooser is performing.
Declaration
Swift

@inlinable func getAction() -> GtkFileChooserAction
Show on GitHub
getChoice(id:) Extension method
Gets the currently selected option in the ‘choice’ with the given ID.
Declaration
Swift

@inlinable func getChoice(id: UnsafePointer<CChar>!) -> String!
Show on GitHub
getCreateFolders() Extension method
Gets whether file chooser will offer to create new folders.
Declaration
Swift

@inlinable func getCreateFolders() -> Bool
Show on GitHub
getCurrentFolder() Extension method
Gets the current folder of chooser as GFile.
Declaration
Swift

@inlinable func getCurrentFolder() -> GIO.FileRef!
Show on GitHub
getCurrentName() Extension method
Gets the current name in the file selector, as entered by the user.

This is meant to be used in save dialogs, to get the currently typed filename when the file itself does not exist yet.
Declaration
Swift

@inlinable func getCurrentName() -> String!
Show on GitHub
getFile() Extension method
Gets the GFile for the currently selected file in the file selector.

If multiple files are selected, one of the files will be returned at random.

If the file chooser is in folder mode, this function returns the selected folder.
Declaration
Swift

@inlinable func getFile() -> GIO.FileRef!
Show on GitHub
getFiles() Extension method
Lists all the selected files and subfolders in the current folder of chooser as GFile.
Declaration
Swift

@inlinable func getFiles() -> GIO.ListModelRef!
Show on GitHub
getFilter() Extension method
Gets the current filter.
Declaration
Swift

@inlinable func getFilter() -> FileFilterRef!
Show on GitHub
getFilters() Extension method
Gets the current set of user-selectable filters, as a list model.

See [methodGtk.FileChooser.add_filter] and [methodGtk.FileChooser.remove_filter] for changing individual filters.

You should not modify the returned list model. Future changes to chooser may or may not affect the returned model.
Declaration
Swift

@inlinable func getFilters() -> GIO.ListModelRef!
Show on GitHub
getSelectMultiple() Extension method
Gets whether multiple files can be selected in the file chooser.
Declaration
Swift

@inlinable func getSelectMultiple() -> Bool
Show on GitHub
getShortcutFolders() Extension method
Queries the list of shortcut folders in the file chooser.

You should not modify the returned list model. Future changes to chooser may or may not affect the returned model.
Declaration
Swift

@inlinable func getShortcutFolders() -> GIO.ListModelRef!
Show on GitHub
removeChoice(id:) Extension method
Removes a ‘choice’ that has been added with gtk_file_chooser_add_choice().
Declaration
Swift

@inlinable func removeChoice(id: UnsafePointer<CChar>!)
Show on GitHub
remove(filter:) Extension method
Removes filter from the list of filters that the user can select between.
Declaration
Swift

@inlinable func remove<FileFilterT>(filter: FileFilterT) where FileFilterT : FileFilterProtocol
Show on GitHub
removeShortcut(folder:) Extension method
Removes a folder from the shortcut folders in a file chooser.
Declaration
Swift

@inlinable func removeShortcut<FileT>(folder: FileT) throws -> Bool where FileT : FileProtocol
Show on GitHub
set(action:) Extension method
Sets the type of operation that the chooser is performing.

The user interface is adapted to suit the selected action.

For example, an option to create a new folder might be shown if the action is GTK_FILE_CHOOSER_ACTION_SAVE but not if the action is GTK_FILE_CHOOSER_ACTION_OPEN.
Declaration
Swift

@inlinable func set(action: GtkFileChooserAction)
Show on GitHub
setChoice(id:option:) Extension method
Selects an option in a ‘choice’ that has been added with gtk_file_chooser_add_choice().

For a boolean choice, the possible options are “true” and “false”.
Declaration
Swift

@inlinable func setChoice(id: UnsafePointer<CChar>!, option: UnsafePointer<CChar>!)
Show on GitHub
set(createFolders:) Extension method
Sets whether file chooser will offer to create new folders.

This is only relevant if the action is not set to be GTK_FILE_CHOOSER_ACTION_OPEN.
Declaration
Swift

@inlinable func set(createFolders: Bool)
Show on GitHub
setCurrentFolder(file:) Extension method
Sets the current folder for chooser from a GFile.
Declaration
Swift

@inlinable func setCurrentFolder<FileT>(file: FileT) throws -> Bool where FileT : FileProtocol
Show on GitHub
setCurrent(name:) Extension method
Sets the current name in the file selector, as if entered by the user.

Note that the name passed in here is a UTF-8 string rather than a filename. This function is meant for such uses as a suggested name in a “Save As…” dialog. You can pass “Untitled.doc” or a similarly suitable suggestion for the name.

If you want to preselect a particular existing file, you should use [methodGtk.FileChooser.set_file] instead.

Please see the documentation for those functions for an example of using [methodGtk.FileChooser.set_current_name] as well.
Declaration
Swift

@inlinable func setCurrent(name: UnsafePointer<CChar>!)
Show on GitHub
set(file:) Extension method
Sets file as the current filename for the file chooser.

This includes changing to the file’s parent folder and actually selecting the file in list. If the chooser is in GTK_FILE_CHOOSER_ACTION_SAVE mode, the file’s base name will also appear in the dialog’s file name entry.

If the file name isn’t in the current folder of chooser, then the current folder of chooser will be changed to the folder containing file.

Note that the file must exist, or nothing will be done except for the directory change.

If you are implementing a save dialog, you should use this function if you already have a file name to which the user may save; for example, when the user opens an existing file and then does “Save As…”. If you don’t have a file name already — for example, if the user just created a new file and is saving it for the first time, do not call this function.

Instead, use something similar to this:
```
static void
prepare_file_chooser (GtkFileChooser *chooser,
                      GFile          *existing_file)
{
  gboolean document_is_new = (existing_file == NULL);

  if (document_is_new)
    {
      GFile *default_file_for_saving = g_file_new_for_path ("./out.txt");
      // the user just created a new document
      gtk_file_chooser_set_current_folder (chooser, default_file_for_saving, NULL);
      gtk_file_chooser_set_current_name (chooser, "Untitled document");
      g_object_unref (default_file_for_saving);
    }
  else
    {
      // the user edited an existing document
      gtk_file_chooser_set_file (chooser, existing_file, NULL);
    }
}
```
Declaration
Swift

@inlinable func set<FileT>(file: FileT) throws -> Bool where FileT : FileProtocol
Show on GitHub
set(filter:) Extension method
Sets the current filter.

Only the files that pass the filter will be displayed. If the user-selectable list of filters is non-empty, then the filter should be one of the filters in that list.

Setting the current filter when the list of filters is empty is useful if you want to restrict the displayed set of files without letting the user change it.
Declaration
Swift

@inlinable func set<FileFilterT>(filter: FileFilterT) where FileFilterT : FileFilterProtocol
Show on GitHub
set(selectMultiple:) Extension method
Sets whether multiple files can be selected in the file chooser.

This is only relevant if the action is set to be GTK_FILE_CHOOSER_ACTION_OPEN or GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.
Declaration
Swift

@inlinable func set(selectMultiple: Bool)
Show on GitHub
action Extension method
The type of operation that the file chooser is performing.
Declaration
Swift

@inlinable var action: GtkFileChooserAction { get nonmutating set }
Show on GitHub
createFolders Extension method
Gets whether file chooser will offer to create new folders.
Declaration
Swift

@inlinable var createFolders: Bool { get nonmutating set }
Show on GitHub
currentFolder Extension method
Gets the current folder of chooser as GFile.
Declaration
Swift

@inlinable var currentFolder: GIO.FileRef! { get nonmutating set }
Show on GitHub
currentName Extension method
Gets the current name in the file selector, as entered by the user.

This is meant to be used in save dialogs, to get the currently typed filename when the file itself does not exist yet.
Declaration
Swift

@inlinable var currentName: String! { get nonmutating set }
Show on GitHub
file Extension method
Gets the GFile for the currently selected file in the file selector.

If multiple files are selected, one of the files will be returned at random.

If the file chooser is in folder mode, this function returns the selected folder.
Declaration
Swift

@inlinable var file: GIO.FileRef! { get nonmutating set }
Show on GitHub
files Extension method
Lists all the selected files and subfolders in the current folder of chooser as GFile.
Declaration
Swift

@inlinable var files: GIO.ListModelRef! { get }
Show on GitHub
filter Extension method
The current filter for selecting files that are displayed.
Declaration
Swift

@inlinable var filter: FileFilterRef! { get nonmutating set }
Show on GitHub
filters Extension method
A GListModel containing the filters that have been added with gtk_file_chooser_add_filter().

The returned object should not be modified. It may or may not be updated for later changes.
Declaration
Swift

@inlinable var filters: GIO.ListModelRef! { get }
Show on GitHub
selectMultiple Extension method
Gets whether multiple files can be selected in the file chooser.
Declaration
Swift

@inlinable var selectMultiple: Bool { get nonmutating set }
Show on GitHub
shortcutFolders Extension method
Queries the list of shortcut folders in the file chooser.

You should not modify the returned list model. Future changes to chooser may or may not affect the returned model.
Declaration
Swift

@inlinable var shortcutFolders: GIO.ListModelRef! { get }
Show on GitHub

FileChooserProtocol

File Names and Encodings

Adding options

Declaration

Default Implementation

Declaration

Declaration

FileChooser Interface

Declaration

Parameters

Return Value

Declaration

Parameters

Return Value

Declaration

Parameters

Return Value

FileChooser Interface: FileChooserProtocol extension (methods and fields)

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration