Copyright | Will Thompson and Iñaki García Etxebarria |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
- Exported types
- Methods
- addChoice
- addFilter
- addShortcutFolder
- getAction
- getChoice
- getCreateFolders
- getCurrentFolder
- getCurrentName
- getFile
- getFiles
- getFilter
- getFilters
- getSelectMultiple
- getShortcutFolders
- removeChoice
- removeFilter
- removeShortcutFolder
- setAction
- setChoice
- setCreateFolders
- setCurrentFolder
- setCurrentName
- setFile
- setFilter
- setSelectMultiple
- Properties
GtkFileChooser
is an interface that can be implemented by file
selection widgets.
In GTK, the main objects that implement this interface are
FileChooserWidget
and 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 GFile
s.
Adding options
You can add extra widgets to a file chooser to provide options
that are not present in the default design, by using
fileChooserAddChoice
. 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.
Synopsis
- newtype FileChooser = FileChooser (ManagedPtr FileChooser)
- class (GObject o, IsDescendantOf FileChooser o) => IsFileChooser o
- toFileChooser :: (MonadIO m, IsFileChooser o) => o -> m FileChooser
- fileChooserAddChoice :: (HasCallStack, MonadIO m, IsFileChooser a) => a -> Text -> Text -> Maybe [Text] -> Maybe [Text] -> m ()
- fileChooserAddFilter :: (HasCallStack, MonadIO m, IsFileChooser a, IsFileFilter b) => a -> b -> m ()
- fileChooserAddShortcutFolder :: (HasCallStack, MonadIO m, IsFileChooser a, IsFile b) => a -> b -> m ()
- fileChooserGetAction :: (HasCallStack, MonadIO m, IsFileChooser a) => a -> m FileChooserAction
- fileChooserGetChoice :: (HasCallStack, MonadIO m, IsFileChooser a) => a -> Text -> m (Maybe Text)
- fileChooserGetCreateFolders :: (HasCallStack, MonadIO m, IsFileChooser a) => a -> m Bool
- fileChooserGetCurrentFolder :: (HasCallStack, MonadIO m, IsFileChooser a) => a -> m (Maybe File)
- fileChooserGetCurrentName :: (HasCallStack, MonadIO m, IsFileChooser a) => a -> m (Maybe Text)
- fileChooserGetFile :: (HasCallStack, MonadIO m, IsFileChooser a) => a -> m (Maybe File)
- fileChooserGetFiles :: (HasCallStack, MonadIO m, IsFileChooser a) => a -> m ListModel
- fileChooserGetFilter :: (HasCallStack, MonadIO m, IsFileChooser a) => a -> m (Maybe FileFilter)
- fileChooserGetFilters :: (HasCallStack, MonadIO m, IsFileChooser a) => a -> m ListModel
- fileChooserGetSelectMultiple :: (HasCallStack, MonadIO m, IsFileChooser a) => a -> m Bool
- fileChooserGetShortcutFolders :: (HasCallStack, MonadIO m, IsFileChooser a) => a -> m ListModel
- fileChooserRemoveChoice :: (HasCallStack, MonadIO m, IsFileChooser a) => a -> Text -> m ()
- fileChooserRemoveFilter :: (HasCallStack, MonadIO m, IsFileChooser a, IsFileFilter b) => a -> b -> m ()
- fileChooserRemoveShortcutFolder :: (HasCallStack, MonadIO m, IsFileChooser a, IsFile b) => a -> b -> m ()
- fileChooserSetAction :: (HasCallStack, MonadIO m, IsFileChooser a) => a -> FileChooserAction -> m ()
- fileChooserSetChoice :: (HasCallStack, MonadIO m, IsFileChooser a) => a -> Text -> Text -> m ()
- fileChooserSetCreateFolders :: (HasCallStack, MonadIO m, IsFileChooser a) => a -> Bool -> m ()
- fileChooserSetCurrentFolder :: (HasCallStack, MonadIO m, IsFileChooser a, IsFile b) => a -> Maybe b -> m ()
- fileChooserSetCurrentName :: (HasCallStack, MonadIO m, IsFileChooser a) => a -> Text -> m ()
- fileChooserSetFile :: (HasCallStack, MonadIO m, IsFileChooser a, IsFile b) => a -> b -> m ()
- fileChooserSetFilter :: (HasCallStack, MonadIO m, IsFileChooser a, IsFileFilter b) => a -> b -> m ()
- fileChooserSetSelectMultiple :: (HasCallStack, MonadIO m, IsFileChooser a) => a -> Bool -> m ()
- constructFileChooserAction :: (IsFileChooser o, MonadIO m) => FileChooserAction -> m (GValueConstruct o)
- getFileChooserAction :: (MonadIO m, IsFileChooser o) => o -> m FileChooserAction
- setFileChooserAction :: (MonadIO m, IsFileChooser o) => o -> FileChooserAction -> m ()
- constructFileChooserCreateFolders :: (IsFileChooser o, MonadIO m) => Bool -> m (GValueConstruct o)
- getFileChooserCreateFolders :: (MonadIO m, IsFileChooser o) => o -> m Bool
- setFileChooserCreateFolders :: (MonadIO m, IsFileChooser o) => o -> Bool -> m ()
- constructFileChooserFilter :: (IsFileChooser o, MonadIO m, IsFileFilter a) => a -> m (GValueConstruct o)
- getFileChooserFilter :: (MonadIO m, IsFileChooser o) => o -> m (Maybe FileFilter)
- setFileChooserFilter :: (MonadIO m, IsFileChooser o, IsFileFilter a) => o -> a -> m ()
- getFileChooserFilters :: (MonadIO m, IsFileChooser o) => o -> m (Maybe ListModel)
- constructFileChooserSelectMultiple :: (IsFileChooser o, MonadIO m) => Bool -> m (GValueConstruct o)
- getFileChooserSelectMultiple :: (MonadIO m, IsFileChooser o) => o -> m Bool
- setFileChooserSelectMultiple :: (MonadIO m, IsFileChooser o) => o -> Bool -> m ()
- getFileChooserShortcutFolders :: (MonadIO m, IsFileChooser o) => o -> m (Maybe ListModel)
Exported types
newtype FileChooser Source #
Deprecated: (Since version 4.10)Use FileDialog
instead
Memory-managed wrapper type.
FileChooser (ManagedPtr FileChooser) | Deprecated: (Since version 4.10)Use |
Instances
Eq FileChooser Source # | |
Defined in GI.Gtk.Interfaces.FileChooser (==) :: FileChooser -> FileChooser -> Bool # (/=) :: FileChooser -> FileChooser -> Bool # | |
GObject FileChooser Source # | |
Defined in GI.Gtk.Interfaces.FileChooser | |
ManagedPtrNewtype FileChooser Source # | |
Defined in GI.Gtk.Interfaces.FileChooser toManagedPtr :: FileChooser -> ManagedPtr FileChooser | |
TypedObject FileChooser Source # | |
Defined in GI.Gtk.Interfaces.FileChooser | |
HasParentTypes FileChooser Source # | |
Defined in GI.Gtk.Interfaces.FileChooser | |
IsGValue (Maybe FileChooser) Source # | Convert |
Defined in GI.Gtk.Interfaces.FileChooser gvalueGType_ :: IO GType gvalueSet_ :: Ptr GValue -> Maybe FileChooser -> IO () gvalueGet_ :: Ptr GValue -> IO (Maybe FileChooser) | |
type ParentTypes FileChooser Source # | |
Defined in GI.Gtk.Interfaces.FileChooser type ParentTypes FileChooser = '[Object] |
class (GObject o, IsDescendantOf FileChooser o) => IsFileChooser o Source #
Type class for types which can be safely cast to FileChooser
, for instance with toFileChooser
.
Instances
(GObject o, IsDescendantOf FileChooser o) => IsFileChooser o Source # | |
Defined in GI.Gtk.Interfaces.FileChooser |
toFileChooser :: (MonadIO m, IsFileChooser o) => o -> m FileChooser Source #
Cast to FileChooser
, for types for which this is known to be safe. For general casts, use castTo
.
Methods
Click to display all available methods, including inherited ones
Methods
addChoice, addFilter, addShortcutFolder, bindProperty, bindPropertyFull, forceFloating, freezeNotify, getv, isFloating, notify, notifyByPspec, ref, refSink, removeChoice, removeFilter, removeShortcutFolder, runDispose, stealData, stealQdata, thawNotify, unref, watchClosure.
Getters
getAction, getChoice, getCreateFolders, getCurrentFolder, getCurrentName, getData, getFile, getFiles, getFilter, getFilters, getProperty, getQdata, getSelectMultiple, getShortcutFolders.
Setters
setAction, setChoice, setCreateFolders, setCurrentFolder, setCurrentName, setData, setDataFull, setFile, setFilter, setProperty, setSelectMultiple.
addChoice
:: (HasCallStack, MonadIO m, IsFileChooser a) | |
=> a |
|
-> Text |
|
-> Text |
|
-> Maybe [Text] |
|
-> Maybe [Text] |
|
-> m () |
Deprecated: (Since version 4.10)Use FileDialog
instead
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
fileChooserSetChoice
before the dialog is shown,
and you can obtain the user-selected value in the
Dialog::response signal handler using
fileChooserGetChoice
.
addFilter
:: (HasCallStack, MonadIO m, IsFileChooser a, IsFileFilter b) | |
=> a |
|
-> b |
|
-> m () |
Deprecated: (Since version 4.10)Use FileDialog
instead
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.
addShortcutFolder
fileChooserAddShortcutFolder Source #
:: (HasCallStack, MonadIO m, IsFileChooser a, IsFile b) | |
=> a |
|
-> b |
|
-> m () | (Can throw |
Deprecated: (Since version 4.10)Use FileDialog
instead
Adds a folder to be displayed with the shortcut folders in a file chooser.
getAction
:: (HasCallStack, MonadIO m, IsFileChooser a) | |
=> a |
|
-> m FileChooserAction | Returns: the action that the file selector is performing |
Deprecated: (Since version 4.10)Use FileDialog
instead
Gets the type of operation that the file chooser is performing.
getChoice
:: (HasCallStack, MonadIO m, IsFileChooser a) | |
=> a |
|
-> Text |
|
-> m (Maybe Text) | Returns: the ID of the currently selected option |
Deprecated: (Since version 4.10)Use FileDialog
instead
Gets the currently selected option in the 'choice' with the given ID.
getCreateFolders
fileChooserGetCreateFolders Source #
:: (HasCallStack, MonadIO m, IsFileChooser a) | |
=> a |
|
-> m Bool | Returns: |
Deprecated: (Since version 4.10)Use FileDialog
instead
Gets whether file chooser will offer to create new folders.
getCurrentFolder
fileChooserGetCurrentFolder Source #
:: (HasCallStack, MonadIO m, IsFileChooser a) | |
=> a |
|
-> m (Maybe File) | Returns: the |
Deprecated: (Since version 4.10)Use FileDialog
instead
Gets the current folder of chooser
as GFile
.
getCurrentName
fileChooserGetCurrentName Source #
:: (HasCallStack, MonadIO m, IsFileChooser a) | |
=> a |
|
-> m (Maybe Text) | Returns: The raw text from the file chooser’s “Name” entry. Free with
|
Deprecated: (Since version 4.10)Use FileDialog
instead
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.
getFile
:: (HasCallStack, MonadIO m, IsFileChooser a) | |
=> a |
|
-> m (Maybe File) | Returns: a selected |
Deprecated: (Since version 4.10)Use FileDialog
instead
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.
getFiles
:: (HasCallStack, MonadIO m, IsFileChooser a) | |
=> a |
|
-> m ListModel | Returns: a list model containing a |
Deprecated: (Since version 4.10)Use FileDialog
instead
Lists all the selected files and subfolders in the current folder
of chooser
as GFile
.
getFilter
:: (HasCallStack, MonadIO m, IsFileChooser a) | |
=> a |
|
-> m (Maybe FileFilter) | Returns: the current filter |
Deprecated: (Since version 4.10)Use FileDialog
instead
Gets the current filter.
getFilters
fileChooserGetFilters Source #
:: (HasCallStack, MonadIO m, IsFileChooser a) | |
=> a |
|
-> m ListModel | Returns: a |
Deprecated: (Since version 4.10)Use FileDialog
instead
Gets the current set of user-selectable filters, as a list model.
See fileChooserAddFilter
and
fileChooserRemoveFilter
for changing individual filters.
You should not modify the returned list model. Future changes to
chooser
may or may not affect the returned model.
getSelectMultiple
fileChooserGetSelectMultiple Source #
:: (HasCallStack, MonadIO m, IsFileChooser a) | |
=> a |
|
-> m Bool | Returns: |
Deprecated: (Since version 4.10)Use FileDialog
instead
Gets whether multiple files can be selected in the file chooser.
getShortcutFolders
fileChooserGetShortcutFolders Source #
:: (HasCallStack, MonadIO m, IsFileChooser a) | |
=> a |
|
-> m ListModel | Returns: A list model of |
Deprecated: (Since version 4.10)Use FileDialog
instead
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.
removeChoice
fileChooserRemoveChoice Source #
:: (HasCallStack, MonadIO m, IsFileChooser a) | |
=> a |
|
-> Text |
|
-> m () |
Deprecated: (Since version 4.10)Use FileDialog
instead
Removes a 'choice' that has been added with fileChooserAddChoice
.
removeFilter
fileChooserRemoveFilter Source #
:: (HasCallStack, MonadIO m, IsFileChooser a, IsFileFilter b) | |
=> a |
|
-> b |
|
-> m () |
Deprecated: (Since version 4.10)Use FileDialog
instead
Removes filter
from the list of filters that the user can select between.
removeShortcutFolder
fileChooserRemoveShortcutFolder Source #
:: (HasCallStack, MonadIO m, IsFileChooser a, IsFile b) | |
=> a |
|
-> b |
|
-> m () | (Can throw |
Deprecated: (Since version 4.10)Use FileDialog
instead
Removes a folder from the shortcut folders in a file chooser.
setAction
:: (HasCallStack, MonadIO m, IsFileChooser a) | |
=> a |
|
-> FileChooserAction |
|
-> m () |
Deprecated: (Since version 4.10)Use FileDialog
instead
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 FileChooserActionSave
but not if the
action is FileChooserActionOpen
.
setChoice
:: (HasCallStack, MonadIO m, IsFileChooser a) | |
=> a |
|
-> Text |
|
-> Text |
|
-> m () |
Deprecated: (Since version 4.10)Use FileDialog
instead
Selects an option in a 'choice' that has been added with
fileChooserAddChoice
.
For a boolean choice, the possible options are "true" and "false".
setCreateFolders
fileChooserSetCreateFolders Source #
:: (HasCallStack, MonadIO m, IsFileChooser a) | |
=> a |
|
-> Bool |
|
-> m () |
Deprecated: (Since version 4.10)Use FileDialog
instead
Sets whether file chooser will offer to create new folders.
This is only relevant if the action is not set to be
FileChooserActionOpen
.
setCurrentFolder
fileChooserSetCurrentFolder Source #
:: (HasCallStack, MonadIO m, IsFileChooser a, IsFile b) | |
=> a |
|
-> Maybe b |
|
-> m () | (Can throw |
Deprecated: (Since version 4.10)Use FileDialog
instead
Sets the current folder for chooser
from a GFile
.
setCurrentName
fileChooserSetCurrentName Source #
:: (HasCallStack, MonadIO m, IsFileChooser a) | |
=> a |
|
-> Text |
|
-> m () |
Deprecated: (Since version 4.10)Use FileDialog
instead
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 fileChooserSetFile
instead.
Please see the documentation for those functions for an example
of using fileChooserSetCurrentName
as well.
setFile
:: (HasCallStack, MonadIO m, IsFileChooser a, IsFile b) | |
=> a |
|
-> b |
|
-> m () | (Can throw |
Deprecated: (Since version 4.10)Use FileDialog
instead
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 FileChooserActionSave
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:
c code
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); } }
setFilter
:: (HasCallStack, MonadIO m, IsFileChooser a, IsFileFilter b) | |
=> a |
|
-> b |
|
-> m () |
Deprecated: (Since version 4.10)Use FileDialog
instead
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.
setSelectMultiple
fileChooserSetSelectMultiple Source #
:: (HasCallStack, MonadIO m, IsFileChooser a) | |
=> a |
|
-> Bool |
|
-> m () |
Deprecated: (Since version 4.10)Use FileDialog
instead
Sets whether multiple files can be selected in the file chooser.
This is only relevant if the action is set to be
FileChooserActionOpen
or
FileChooserActionSelectFolder
.
Properties
action
The type of operation that the file chooser is performing.
constructFileChooserAction :: (IsFileChooser o, MonadIO m) => FileChooserAction -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “action
” property. This is rarely needed directly, but it is used by new
.
getFileChooserAction :: (MonadIO m, IsFileChooser o) => o -> m FileChooserAction Source #
Get the value of the “action
” property.
When overloading is enabled, this is equivalent to
get
fileChooser #action
setFileChooserAction :: (MonadIO m, IsFileChooser o) => o -> FileChooserAction -> m () Source #
Set the value of the “action
” property.
When overloading is enabled, this is equivalent to
set
fileChooser [ #action:=
value ]
createFolders
Whether a file chooser not in FileChooserActionOpen
mode
will offer the user to create new folders.
constructFileChooserCreateFolders :: (IsFileChooser o, MonadIO m) => Bool -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “create-folders
” property. This is rarely needed directly, but it is used by new
.
getFileChooserCreateFolders :: (MonadIO m, IsFileChooser o) => o -> m Bool Source #
Get the value of the “create-folders
” property.
When overloading is enabled, this is equivalent to
get
fileChooser #createFolders
setFileChooserCreateFolders :: (MonadIO m, IsFileChooser o) => o -> Bool -> m () Source #
Set the value of the “create-folders
” property.
When overloading is enabled, this is equivalent to
set
fileChooser [ #createFolders:=
value ]
filter
The current filter for selecting files that are displayed.
constructFileChooserFilter :: (IsFileChooser o, MonadIO m, IsFileFilter a) => a -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “filter
” property. This is rarely needed directly, but it is used by new
.
getFileChooserFilter :: (MonadIO m, IsFileChooser o) => o -> m (Maybe FileFilter) Source #
Get the value of the “filter
” property.
When overloading is enabled, this is equivalent to
get
fileChooser #filter
setFileChooserFilter :: (MonadIO m, IsFileChooser o, IsFileFilter a) => o -> a -> m () Source #
Set the value of the “filter
” property.
When overloading is enabled, this is equivalent to
set
fileChooser [ #filter:=
value ]
filters
A GListModel
containing the filters that have been
added with fileChooserAddFilter
.
The returned object should not be modified. It may or may not be updated for later changes.
getFileChooserFilters :: (MonadIO m, IsFileChooser o) => o -> m (Maybe ListModel) Source #
Get the value of the “filters
” property.
When overloading is enabled, this is equivalent to
get
fileChooser #filters
selectMultiple
Whether to allow multiple files to be selected.
constructFileChooserSelectMultiple :: (IsFileChooser o, MonadIO m) => Bool -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “select-multiple
” property. This is rarely needed directly, but it is used by new
.
getFileChooserSelectMultiple :: (MonadIO m, IsFileChooser o) => o -> m Bool Source #
Get the value of the “select-multiple
” property.
When overloading is enabled, this is equivalent to
get
fileChooser #selectMultiple
setFileChooserSelectMultiple :: (MonadIO m, IsFileChooser o) => o -> Bool -> m () Source #
Set the value of the “select-multiple
” property.
When overloading is enabled, this is equivalent to
set
fileChooser [ #selectMultiple:=
value ]
shortcutFolders
A GListModel
containing the shortcut folders that have been
added with fileChooserAddShortcutFolder
.
The returned object should not be modified. It may or may not be updated for later changes.
getFileChooserShortcutFolders :: (MonadIO m, IsFileChooser o) => o -> m (Maybe ListModel) Source #
Get the value of the “shortcut-folders
” property.
When overloading is enabled, this is equivalent to
get
fileChooser #shortcutFolders