GI.Gtk.Objects.FileChooserNative

FileChooserNative is an abstraction of a dialog box suitable for use with “File/Open” or “File/Save as” commands. By default, this just uses a FileChooserDialog to implement the actual dialog. However, on certain platforms, such as Windows, the native platform file chooser is uses instead. When the application is running in a sandboxed environment without direct filesystem access (such as Flatpak), FileChooserNative may call the proper APIs (portals) to let the user choose a file and make it available to the application.

While the API of FileChooserNative closely mirrors FileChooserDialog, the main difference is that there is no access to any Window or Widget 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.

## {gtkfilechoosernative-typical-usage}

In the simplest of cases, you can the following code to use FileChooserDialog to select a file for opening:

GtkFileChooserNative *native;
GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;
gint res;

native = gtk_file_chooser_native_new ("Open File",
                                      parent_window,
                                      action,
                                      "_Open",
                                      "_Cancel");

res = gtk_native_dialog_run (GTK_NATIVE_DIALOG (native));
if (res == GTK_RESPONSE_ACCEPT)
  {
    char *filename;
    GtkFileChooser *chooser = GTK_FILE_CHOOSER (native);
    filename = gtk_file_chooser_get_filename (chooser);
    open_file (filename);
    g_free (filename);
  }

g_object_unref (native);

To use a dialog for saving, you can use this:

GtkFileChooserNative *native;
GtkFileChooser *chooser;
GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE;
gint res;

native = gtk_file_chooser_native_new ("Save File",
                                      parent_window,
                                      action,
                                      "_Save",
                                      "_Cancel");
chooser = GTK_FILE_CHOOSER (native);

gtk_file_chooser_set_do_overwrite_confirmation (chooser, TRUE);

if (user_edited_a_new_document)
  gtk_file_chooser_set_current_name (chooser,
                                     _("Untitled document"));
else
  gtk_file_chooser_set_filename (chooser,
                                 existing_filename);

res = gtk_native_dialog_run (GTK_NATIVE_DIALOG (native));
if (res == GTK_RESPONSE_ACCEPT)
  {
    char *filename;

    filename = gtk_file_chooser_get_filename (chooser);
    save_to_file (filename);
    g_free (filename);
  }

g_object_unref (native);

For more information on how to best set up a file dialog, see FileChooserDialog.

## {gtkfilechooserdialognative-responses}

FileChooserNative inherits from NativeDialog, which means it will return GTK_RESPONSE_ACCEPT if the user accepted, and GTK_RESPONSE_CANCEL if he pressed cancel. It can also return GTK_RESPONSE_DELETE_EVENT if the window was unexpectedly closed.

## {gtkfilechooserdialognative-differences}

There are a few things in the GtkFileChooser API that are not possible to use with FileChooserNative, as such use would prohibit the use of a native dialog.

There is no support for the signals that are emitted when the user navigates in the dialog, including: * FileChooser::current-folder-changed * FileChooser::selection-changed * FileChooser::file-activated * FileChooser::confirm-overwrite

You can also not use the methods that directly control user navigation: * fileChooserUnselectFilename * fileChooserSelectAll * fileChooserUnselectAll

If you need any of the above you will have to use FileChooserDialog directly.

No operations that change the the dialog work while the dialog is visible. Set all the properties that are required before showing the dialog.

## {gtkfilechooserdialognative-win32}

On windows the IFileDialog implementation (added in Windows Vista) is used. It supports many of the features that FileChooserDialog does, but there are some things it does not handle:

• Extra widgets added with fileChooserSetExtraWidget.
• Use of custom previews by connecting to FileChooser::update-preview.
• Any FileFilter added using a mimetype or custom filter.

If any of these features are used the regular FileChooserDialog will be used in place of the native one.

## {gtkfilechooserdialognative-portal}

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. In this situation, the following things are not supported and will be silently ignored:

• Extra widgets added with fileChooserSetExtraWidget.
• Use of custom previews by connecting to FileChooser::update-preview.
• Any FileFilter added with a custom filter.

Exported types

newtype FileChooserNative

Constructors

FileChooserNative (ManagedPtr FileChooserNative)

Instances

GObject FileChooserNative

Methods

gobjectType :: FileChooserNative -> IO GType

IsObject FileChooserNative

IsNativeDialog FileChooserNative

IsFileChooser FileChooserNative

IsFileChooserNative FileChooserNative

((~) * info (ResolveFileChooserNativeMethod t FileChooserNative), MethodInfo * info FileChooserNative p) => IsLabel t (FileChooserNative -> p)

Methods

fromLabel :: Proxy# Symbol t -> FileChooserNative -> p

((~) * info (ResolveFileChooserNativeMethod t FileChooserNative), MethodInfo * info FileChooserNative p) => IsLabelProxy t (FileChooserNative -> p)

Methods

fromLabelProxy :: Proxy Symbol t -> FileChooserNative -> p

HasAttributeList * FileChooserNative

type AttributeList FileChooserNative

type AttributeList FileChooserNative

type SignalList FileChooserNative

type SignalList FileChooserNative

class GObject o => IsFileChooserNative o

Instances

(GObject a, UnknownAncestorError Constraint FileChooserNative a) => IsFileChooserNative a

IsFileChooserNative FileChooserNative

toFileChooserNative :: IsFileChooserNative o => o -> IO FileChooserNative

noFileChooserNative :: Maybe FileChooserNative

Methods

getAcceptLabel

data FileChooserNativeGetAcceptLabelMethodInfo

Instances

((~) * signature (m (Maybe Text)), MonadIO m, IsFileChooserNative a) => MethodInfo * FileChooserNativeGetAcceptLabelMethodInfo a signature

Methods

overloadedMethod :: MethodProxy FileChooserNativeGetAcceptLabelMethodInfo a -> signature -> s

fileChooserNativeGetAcceptLabel

Arguments

:: (HasCallStack, MonadIO m, IsFileChooserNative a)

=> a

self: a GtFileChooserNative

-> m (Maybe Text)

Returns: The custom label, or Nothing for the default. This string is owned by GTK+ and should not be modified or freed

Retrieves the custom label text for the accept button.

Since: 3.20

getCancelLabel

data FileChooserNativeGetCancelLabelMethodInfo

Instances

((~) * signature (m (Maybe Text)), MonadIO m, IsFileChooserNative a) => MethodInfo * FileChooserNativeGetCancelLabelMethodInfo a signature

Methods

overloadedMethod :: MethodProxy FileChooserNativeGetCancelLabelMethodInfo a -> signature -> s

fileChooserNativeGetCancelLabel

Arguments

:: (HasCallStack, MonadIO m, IsFileChooserNative a)

=> a

self: a GtFileChooserNative

-> m (Maybe Text)

Returns: The custom label, or Nothing for the default. This string is owned by GTK+ and should not be modified or freed

Retrieves the custom label text for the cancel button.

Since: 3.20

new

fileChooserNativeNew

Arguments

:: (HasCallStack, MonadIO m, IsWindow a)

=> Maybe Text

title: Title of the native, or Nothing

-> Maybe a

parent: Transient parent of the native, or Nothing

-> FileChooserAction

action: Open or save mode for the dialog

-> Maybe Text

acceptLabel: text to go in the accept button, or Nothing for the default

-> Maybe Text

cancelLabel: text to go in the cancel button, or Nothing for the default

-> m FileChooserNative

Returns: a new FileChooserNative

Creates a new FileChooserNative.

Since: 3.20

setAcceptLabel

data FileChooserNativeSetAcceptLabelMethodInfo

Instances

((~) * signature (Maybe Text -> m ()), MonadIO m, IsFileChooserNative a) => MethodInfo * FileChooserNativeSetAcceptLabelMethodInfo a signature

Methods

overloadedMethod :: MethodProxy FileChooserNativeSetAcceptLabelMethodInfo a -> signature -> s

fileChooserNativeSetAcceptLabel

Arguments

:: (HasCallStack, MonadIO m, IsFileChooserNative a)

=> a

self: a GtFileChooserNative

-> Maybe Text

acceptLabel: custom label or Nothing for the default

-> 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 activates the button.

Since: 3.20

setCancelLabel

data FileChooserNativeSetCancelLabelMethodInfo

Instances

((~) * signature (Maybe Text -> m ()), MonadIO m, IsFileChooserNative a) => MethodInfo * FileChooserNativeSetCancelLabelMethodInfo a signature

Methods

overloadedMethod :: MethodProxy FileChooserNativeSetCancelLabelMethodInfo a -> signature -> s

fileChooserNativeSetCancelLabel

Arguments

:: (HasCallStack, MonadIO m, IsFileChooserNative a)

=> a

self: a GtFileChooserNative

-> Maybe Text

cancelLabel: custom label or Nothing for the default

-> 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 activates the button.

Since: 3.20

Properties

acceptLabel

data FileChooserNativeAcceptLabelPropertyInfo

Instances

AttrInfo FileChooserNativeAcceptLabelPropertyInfo

Associated Types

type AttrAllowedOps FileChooserNativeAcceptLabelPropertyInfo :: [AttrOpTag]

type AttrSetTypeConstraint FileChooserNativeAcceptLabelPropertyInfo :: * -> Constraint

type AttrBaseTypeConstraint FileChooserNativeAcceptLabelPropertyInfo :: * -> Constraint

type AttrGetType FileChooserNativeAcceptLabelPropertyInfo :: *

type AttrLabel FileChooserNativeAcceptLabelPropertyInfo :: Symbol

type AttrOrigin FileChooserNativeAcceptLabelPropertyInfo :: *

Methods

attrGet :: AttrBaseTypeConstraint FileChooserNativeAcceptLabelPropertyInfo o => Proxy * FileChooserNativeAcceptLabelPropertyInfo -> o -> IO (AttrGetType FileChooserNativeAcceptLabelPropertyInfo)

attrSet :: (AttrBaseTypeConstraint FileChooserNativeAcceptLabelPropertyInfo o, AttrSetTypeConstraint FileChooserNativeAcceptLabelPropertyInfo b) => Proxy * FileChooserNativeAcceptLabelPropertyInfo -> o -> b -> IO ()

attrClear :: AttrBaseTypeConstraint FileChooserNativeAcceptLabelPropertyInfo o => Proxy * FileChooserNativeAcceptLabelPropertyInfo -> o -> IO ()

attrConstruct :: (AttrBaseTypeConstraint FileChooserNativeAcceptLabelPropertyInfo o, AttrSetTypeConstraint FileChooserNativeAcceptLabelPropertyInfo b) => Proxy * FileChooserNativeAcceptLabelPropertyInfo -> b -> IO (GValueConstruct o)

type AttrOrigin FileChooserNativeAcceptLabelPropertyInfo

type AttrOrigin FileChooserNativeAcceptLabelPropertyInfo = FileChooserNative

type AttrLabel FileChooserNativeAcceptLabelPropertyInfo

type AttrLabel FileChooserNativeAcceptLabelPropertyInfo = "accept-label"

type AttrGetType FileChooserNativeAcceptLabelPropertyInfo

type AttrGetType FileChooserNativeAcceptLabelPropertyInfo = Maybe Text

type AttrBaseTypeConstraint FileChooserNativeAcceptLabelPropertyInfo

type AttrBaseTypeConstraint FileChooserNativeAcceptLabelPropertyInfo = IsFileChooserNative

type AttrSetTypeConstraint FileChooserNativeAcceptLabelPropertyInfo

type AttrSetTypeConstraint FileChooserNativeAcceptLabelPropertyInfo = * ~ Text

type AttrAllowedOps FileChooserNativeAcceptLabelPropertyInfo

type AttrAllowedOps FileChooserNativeAcceptLabelPropertyInfo = (:) AttrOpTag AttrSet ((:) AttrOpTag AttrConstruct ((:) AttrOpTag AttrGet ((:) AttrOpTag AttrClear ([] AttrOpTag))))

clearFileChooserNativeAcceptLabel :: (MonadIO m, IsFileChooserNative o) => o -> m ()

constructFileChooserNativeAcceptLabel :: IsFileChooserNative o => Text -> IO (GValueConstruct o)

fileChooserNativeAcceptLabel :: AttrLabelProxy "acceptLabel"

getFileChooserNativeAcceptLabel :: (MonadIO m, IsFileChooserNative o) => o -> m (Maybe Text)

setFileChooserNativeAcceptLabel :: (MonadIO m, IsFileChooserNative o) => o -> Text -> m ()

cancelLabel

data FileChooserNativeCancelLabelPropertyInfo

Instances

AttrInfo FileChooserNativeCancelLabelPropertyInfo

Associated Types

type AttrAllowedOps FileChooserNativeCancelLabelPropertyInfo :: [AttrOpTag]

type AttrSetTypeConstraint FileChooserNativeCancelLabelPropertyInfo :: * -> Constraint

type AttrBaseTypeConstraint FileChooserNativeCancelLabelPropertyInfo :: * -> Constraint

type AttrGetType FileChooserNativeCancelLabelPropertyInfo :: *

type AttrLabel FileChooserNativeCancelLabelPropertyInfo :: Symbol

type AttrOrigin FileChooserNativeCancelLabelPropertyInfo :: *

Methods

attrGet :: AttrBaseTypeConstraint FileChooserNativeCancelLabelPropertyInfo o => Proxy * FileChooserNativeCancelLabelPropertyInfo -> o -> IO (AttrGetType FileChooserNativeCancelLabelPropertyInfo)

attrSet :: (AttrBaseTypeConstraint FileChooserNativeCancelLabelPropertyInfo o, AttrSetTypeConstraint FileChooserNativeCancelLabelPropertyInfo b) => Proxy * FileChooserNativeCancelLabelPropertyInfo -> o -> b -> IO ()

attrClear :: AttrBaseTypeConstraint FileChooserNativeCancelLabelPropertyInfo o => Proxy * FileChooserNativeCancelLabelPropertyInfo -> o -> IO ()

attrConstruct :: (AttrBaseTypeConstraint FileChooserNativeCancelLabelPropertyInfo o, AttrSetTypeConstraint FileChooserNativeCancelLabelPropertyInfo b) => Proxy * FileChooserNativeCancelLabelPropertyInfo -> b -> IO (GValueConstruct o)

type AttrOrigin FileChooserNativeCancelLabelPropertyInfo

type AttrOrigin FileChooserNativeCancelLabelPropertyInfo = FileChooserNative

type AttrLabel FileChooserNativeCancelLabelPropertyInfo

type AttrLabel FileChooserNativeCancelLabelPropertyInfo = "cancel-label"

type AttrGetType FileChooserNativeCancelLabelPropertyInfo

type AttrGetType FileChooserNativeCancelLabelPropertyInfo = Maybe Text

type AttrBaseTypeConstraint FileChooserNativeCancelLabelPropertyInfo

type AttrBaseTypeConstraint FileChooserNativeCancelLabelPropertyInfo = IsFileChooserNative

type AttrSetTypeConstraint FileChooserNativeCancelLabelPropertyInfo

type AttrSetTypeConstraint FileChooserNativeCancelLabelPropertyInfo = * ~ Text

type AttrAllowedOps FileChooserNativeCancelLabelPropertyInfo

type AttrAllowedOps FileChooserNativeCancelLabelPropertyInfo = (:) AttrOpTag AttrSet ((:) AttrOpTag AttrConstruct ((:) AttrOpTag AttrGet ((:) AttrOpTag AttrClear ([] AttrOpTag))))

clearFileChooserNativeCancelLabel :: (MonadIO m, IsFileChooserNative o) => o -> m ()

constructFileChooserNativeCancelLabel :: IsFileChooserNative o => Text -> IO (GValueConstruct o)

fileChooserNativeCancelLabel :: AttrLabelProxy "cancelLabel"

getFileChooserNativeCancelLabel :: (MonadIO m, IsFileChooserNative o) => o -> m (Maybe Text)

setFileChooserNativeCancelLabel :: (MonadIO m, IsFileChooserNative o) => o -> Text -> m ()