gi-gtk4-4.0.12: Gtk 4.x bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gtk.Objects.FileChooserNative

Contents

- Exported types
- Methods
  - getAcceptLabel
  - getCancelLabel
  - new
  - setAcceptLabel
  - setCancelLabel
- Properties
  - acceptLabel
  - cancelLabel

Description

`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.

Constructors

FileChooserNative (ManagedPtr FileChooserNative) |

#### Instances

Instances details

Eq FileChooserNative Source # |
Instance details Defined in GI.Gtk.Objects.FileChooserNative Methods (==) :: FileChooserNative -> FileChooserNative -> Bool Source # (/=) :: FileChooserNative -> FileChooserNative -> Bool Source #
GObject FileChooserNative Source # |
Instance details Defined in GI.Gtk.Objects.FileChooserNative
ManagedPtrNewtype FileChooserNative Source # |
Instance details Defined in GI.Gtk.Objects.FileChooserNative Methods toManagedPtr :: FileChooserNative -> ManagedPtr FileChooserNative Source #
TypedObject FileChooserNative Source # |
Instance details Defined in GI.Gtk.Objects.FileChooserNative Methods glibType :: IO GType Source #
HasParentTypes FileChooserNative Source # |
Instance details Defined in GI.Gtk.Objects.FileChooserNative
IsGValue (Maybe FileChooserNative) Source # | Convert `FileChooserNative` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gtk.Objects.FileChooserNative Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe FileChooserNative -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe FileChooserNative) Source #
type ParentTypes FileChooserNative Source # |
Instance details Defined in GI.Gtk.Objects.FileChooserNative type ParentTypes FileChooserNative = '[NativeDialog, Object, FileChooser]

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

Instances details

(GObject o, IsDescendantOf FileChooserNative o) => IsFileChooserNative o Source # |
Instance details 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

Expand

#### 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 #

Arguments

:: (HasCallStack, MonadIO m, IsFileChooserNative a) |
=> a | `self`: a `GtkFileChooserNative`
-> m (Maybe Text) | Returns: The custom label

Deprecated: (Since version 4.10)Use `FileDialog` instead

Retrieves the custom label text for the accept button.

## getCancelLabel

fileChooserNativeGetCancelLabel Source #

Arguments

:: (HasCallStack, MonadIO m, IsFileChooserNative a) |
=> a | `self`: a `GtkFileChooserNative`
-> m (Maybe Text) | Returns: The custom label

Deprecated: (Since version 4.10)Use `FileDialog` instead

Retrieves the custom label text for the cancel button.

## new

fileChooserNativeNew Source #

Arguments

:: (HasCallStack, MonadIO m, IsWindow a) |
=> Maybe Text | `title`: Title of the native
-> Maybe a | `parent`: Transient parent of the native
-> 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 `GtkFileChooserNative`

Deprecated: (Since version 4.10)Use `FileDialog` instead

Creates a new `GtkFileChooserNative`.

## setAcceptLabel

fileChooserNativeSetAcceptLabel Source #

Arguments

:: (HasCallStack, MonadIO m, IsFileChooserNative a) |
=> a | `self`: a `GtkFileChooserNative`
-> Maybe Text | `acceptLabel`: custom label
-> m () |

Deprecated: (Since version 4.10)Use `FileDialog` instead

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 #

Arguments

:: (HasCallStack, MonadIO m, IsFileChooserNative a) |
=> a | `self`: a `GtkFileChooserNative`
-> Maybe Text | `cancelLabel`: custom label
-> m () |

Deprecated: (Since version 4.10)Use `FileDialog` instead

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 ]