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 |
GtkFileChooserNative
is an abstraction of a dialog suitable
for use with “File Open” or “File Save as” commands.
By default, this just uses a GtkFileChooserDialog
to implement
the actual dialog. However, on some platforms, such as Windows and
macOS, the native platform file chooser is used instead. When the
application is running in a sandboxed environment without direct
filesystem access (such as Flatpak), GtkFileChooserNative
may call
the proper APIs (portals) to let the user choose a file and make it
available to the application.
While the API of GtkFileChooserNative
closely mirrors GtkFileChooserDialog
,
the main difference is that there is no access to any GtkWindow
or GtkWidget
for the dialog. This is required, as there may not be one in the case of a
platform native dialog.
Showing, hiding and running the dialog is handled by the
NativeDialog
functions.
Note that unlike GtkFileChooserDialog
, GtkFileChooserNative
objects
are not toplevel widgets, and GTK does not keep them alive. It is your
responsibility to keep a reference until you are done with the
object.
Typical usage
In the simplest of cases, you can the following code to use
GtkFileChooserNative
to select a file for opening:
c code
static void on_response (GtkNativeDialog *native, int response) { if (response == GTK_RESPONSE_ACCEPT) { GtkFileChooser *chooser = GTK_FILE_CHOOSER (native); GFile *file = gtk_file_chooser_get_file (chooser); open_file (file); g_object_unref (file); } g_object_unref (native); } // ... GtkFileChooserNative *native; GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN; native = gtk_file_chooser_native_new ("Open File", parent_window, action, "_Open", "_Cancel"); g_signal_connect (native, "response", G_CALLBACK (on_response), NULL); gtk_native_dialog_show (GTK_NATIVE_DIALOG (native));
To use a GtkFileChooserNative
for saving, you can use this:
c code
static void on_response (GtkNativeDialog *native, int response) { if (response == GTK_RESPONSE_ACCEPT) { GtkFileChooser *chooser = GTK_FILE_CHOOSER (native); GFile *file = gtk_file_chooser_get_file (chooser); save_to_file (file); g_object_unref (file); } g_object_unref (native); } // ... GtkFileChooserNative *native; GtkFileChooser *chooser; GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE; native = gtk_file_chooser_native_new ("Save File", parent_window, action, "_Save", "_Cancel"); chooser = GTK_FILE_CHOOSER (native); if (user_edited_a_new_document) gtk_file_chooser_set_current_name (chooser, _("Untitled document")); else gtk_file_chooser_set_file (chooser, existing_file, NULL); g_signal_connect (native, "response", G_CALLBACK (on_response), NULL); gtk_native_dialog_show (GTK_NATIVE_DIALOG (native));
For more information on how to best set up a file dialog,
see the FileChooserDialog
documentation.
Response Codes
GtkFileChooserNative
inherits from NativeDialog
,
which means it will return ResponseTypeAccept
if the user accepted,
and ResponseTypeCancel
if he pressed cancel. It can also return
ResponseTypeDeleteEvent
if the window was unexpectedly closed.
Differences from GtkFileChooserDialog
There are a few things in the FileChooser
interface that
are not possible to use with GtkFileChooserNative
, as such use would
prohibit the use of a native dialog.
No operations that change the dialog work while the dialog is visible. Set all the properties that are required before showing the dialog.
Win32 details
On windows the IFileDialog
implementation (added in Windows Vista) is
used. It supports many of the features that GtkFileChooser
has, but
there are some things it does not handle:
- Any
FileFilter
added using a mimetype
If any of these features are used the regular GtkFileChooserDialog
will be used in place of the native one.
Portal details
When the org.freedesktop.portal.FileChooser
portal is available on
the session bus, it is used to bring up an out-of-process file chooser.
Depending on the kind of session the application is running in, this may
or may not be a GTK file chooser.
macOS details
On macOS the NSSavePanel
and NSOpenPanel
classes are used to provide
native file chooser dialogs. Some features provided by GtkFileChooser
are not supported:
- Shortcut folders.
Synopsis
- newtype FileChooserNative = FileChooserNative (ManagedPtr FileChooserNative)
- class (GObject o, IsDescendantOf FileChooserNative o) => IsFileChooserNative o
- toFileChooserNative :: (MonadIO m, IsFileChooserNative o) => o -> m FileChooserNative
- fileChooserNativeGetAcceptLabel :: (HasCallStack, MonadIO m, IsFileChooserNative a) => a -> m (Maybe Text)
- fileChooserNativeGetCancelLabel :: (HasCallStack, MonadIO m, IsFileChooserNative a) => a -> m (Maybe Text)
- fileChooserNativeNew :: (HasCallStack, MonadIO m, IsWindow a) => Maybe Text -> Maybe a -> FileChooserAction -> Maybe Text -> Maybe Text -> m FileChooserNative
- fileChooserNativeSetAcceptLabel :: (HasCallStack, MonadIO m, IsFileChooserNative a) => a -> Maybe Text -> m ()
- fileChooserNativeSetCancelLabel :: (HasCallStack, MonadIO m, IsFileChooserNative a) => a -> Maybe Text -> m ()
- clearFileChooserNativeAcceptLabel :: (MonadIO m, IsFileChooserNative o) => o -> m ()
- constructFileChooserNativeAcceptLabel :: (IsFileChooserNative o, MonadIO m) => Text -> m (GValueConstruct o)
- getFileChooserNativeAcceptLabel :: (MonadIO m, IsFileChooserNative o) => o -> m (Maybe Text)
- setFileChooserNativeAcceptLabel :: (MonadIO m, IsFileChooserNative o) => o -> Text -> m ()
- clearFileChooserNativeCancelLabel :: (MonadIO m, IsFileChooserNative o) => o -> m ()
- constructFileChooserNativeCancelLabel :: (IsFileChooserNative o, MonadIO m) => Text -> m (GValueConstruct o)
- getFileChooserNativeCancelLabel :: (MonadIO m, IsFileChooserNative o) => o -> m (Maybe Text)
- setFileChooserNativeCancelLabel :: (MonadIO m, IsFileChooserNative o) => o -> Text -> m ()
Exported types
newtype FileChooserNative Source #
Memory-managed wrapper type.
FileChooserNative (ManagedPtr FileChooserNative) |
Instances
Eq FileChooserNative Source # | |
Defined in GI.Gtk.Objects.FileChooserNative (==) :: FileChooserNative -> FileChooserNative -> Bool # (/=) :: FileChooserNative -> FileChooserNative -> Bool # | |
GObject FileChooserNative Source # | |
Defined in GI.Gtk.Objects.FileChooserNative | |
ManagedPtrNewtype FileChooserNative Source # | |
Defined in GI.Gtk.Objects.FileChooserNative toManagedPtr :: FileChooserNative -> ManagedPtr FileChooserNative | |
TypedObject FileChooserNative Source # | |
Defined in GI.Gtk.Objects.FileChooserNative | |
HasParentTypes FileChooserNative Source # | |
Defined in GI.Gtk.Objects.FileChooserNative | |
IsGValue (Maybe FileChooserNative) Source # | Convert |
Defined in GI.Gtk.Objects.FileChooserNative gvalueGType_ :: IO GType gvalueSet_ :: Ptr GValue -> Maybe FileChooserNative -> IO () gvalueGet_ :: Ptr GValue -> IO (Maybe FileChooserNative) | |
type ParentTypes FileChooserNative Source # | |
Defined in GI.Gtk.Objects.FileChooserNative |
class (GObject o, IsDescendantOf FileChooserNative o) => IsFileChooserNative o Source #
Type class for types which can be safely cast to FileChooserNative
, for instance with toFileChooserNative
.
Instances
(GObject o, IsDescendantOf FileChooserNative o) => IsFileChooserNative o Source # | |
Defined in GI.Gtk.Objects.FileChooserNative |
toFileChooserNative :: (MonadIO m, IsFileChooserNative o) => o -> m FileChooserNative Source #
Cast to FileChooserNative
, 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, destroy, forceFloating, freezeNotify, getv, hide, isFloating, notify, notifyByPspec, ref, refSink, removeChoice, removeFilter, removeShortcutFolder, runDispose, show, stealData, stealQdata, thawNotify, unref, watchClosure.
Getters
getAcceptLabel, getAction, getCancelLabel, getChoice, getCreateFolders, getCurrentFolder, getCurrentName, getData, getFile, getFiles, getFilter, getFilters, getModal, getProperty, getQdata, getSelectMultiple, getShortcutFolders, getTitle, getTransientFor, getVisible.
Setters
setAcceptLabel, setAction, setCancelLabel, setChoice, setCreateFolders, setCurrentFolder, setCurrentName, setData, setDataFull, setFile, setFilter, setModal, setProperty, setSelectMultiple, setTitle, setTransientFor.
getAcceptLabel
fileChooserNativeGetAcceptLabel Source #
:: (HasCallStack, MonadIO m, IsFileChooserNative a) | |
=> a |
|
-> m (Maybe Text) | Returns: The custom label |
Retrieves the custom label text for the accept button.
getCancelLabel
fileChooserNativeGetCancelLabel Source #
:: (HasCallStack, MonadIO m, IsFileChooserNative a) | |
=> a |
|
-> m (Maybe Text) | Returns: The custom label |
Retrieves the custom label text for the cancel button.
new
:: (HasCallStack, MonadIO m, IsWindow a) | |
=> Maybe Text |
|
-> Maybe a |
|
-> FileChooserAction |
|
-> Maybe Text |
|
-> Maybe Text |
|
-> m FileChooserNative | Returns: a new |
Creates a new GtkFileChooserNative
.
setAcceptLabel
fileChooserNativeSetAcceptLabel Source #
:: (HasCallStack, MonadIO m, IsFileChooserNative a) | |
=> a |
|
-> Maybe Text |
|
-> m () |
Sets the custom label text for the accept button.
If characters in label
are preceded by an underscore, they are
underlined. If you need a literal underscore character in a label,
use “__” (two underscores). The first underlined character represents
a keyboard accelerator called a mnemonic.
Pressing Alt and that key should activate the button.
setCancelLabel
fileChooserNativeSetCancelLabel Source #
:: (HasCallStack, MonadIO m, IsFileChooserNative a) | |
=> a |
|
-> Maybe Text |
|
-> m () |
Sets the custom label text for the cancel button.
If characters in label
are preceded by an underscore, they are
underlined. If you need a literal underscore character in a label,
use “__” (two underscores). The first underlined character represents
a keyboard accelerator called a mnemonic.
Pressing Alt and that key should activate the button.
Properties
acceptLabel
The text used for the label on the accept button in the dialog, or
Nothing
to use the default text.
clearFileChooserNativeAcceptLabel :: (MonadIO m, IsFileChooserNative o) => o -> m () Source #
Set the value of the “accept-label
” property to Nothing
.
When overloading is enabled, this is equivalent to
clear
#acceptLabel
constructFileChooserNativeAcceptLabel :: (IsFileChooserNative o, MonadIO m) => Text -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “accept-label
” property. This is rarely needed directly, but it is used by new
.
getFileChooserNativeAcceptLabel :: (MonadIO m, IsFileChooserNative o) => o -> m (Maybe Text) Source #
Get the value of the “accept-label
” property.
When overloading is enabled, this is equivalent to
get
fileChooserNative #acceptLabel
setFileChooserNativeAcceptLabel :: (MonadIO m, IsFileChooserNative o) => o -> Text -> m () Source #
Set the value of the “accept-label
” property.
When overloading is enabled, this is equivalent to
set
fileChooserNative [ #acceptLabel:=
value ]
cancelLabel
The text used for the label on the cancel button in the dialog, or
Nothing
to use the default text.
clearFileChooserNativeCancelLabel :: (MonadIO m, IsFileChooserNative o) => o -> m () Source #
Set the value of the “cancel-label
” property to Nothing
.
When overloading is enabled, this is equivalent to
clear
#cancelLabel
constructFileChooserNativeCancelLabel :: (IsFileChooserNative o, MonadIO m) => Text -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “cancel-label
” property. This is rarely needed directly, but it is used by new
.
getFileChooserNativeCancelLabel :: (MonadIO m, IsFileChooserNative o) => o -> m (Maybe Text) Source #
Get the value of the “cancel-label
” property.
When overloading is enabled, this is equivalent to
get
fileChooserNative #cancelLabel
setFileChooserNativeCancelLabel :: (MonadIO m, IsFileChooserNative o) => o -> Text -> m () Source #
Set the value of the “cancel-label
” property.
When overloading is enabled, this is equivalent to
set
fileChooserNative [ #cancelLabel:=
value ]