gi-gtk3-3.0.44: Gtk 3.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

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

## Typical usage ## {`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`.

## Response Codes ## {`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.

## Differences from `FileChooserDialog` ## {`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::currentFolderChanged * FileChooser::selectionChanged * FileChooser::fileActivated * FileChooser::confirmOverwrite

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.

## Win32 details ## {`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::updatePreview.
- 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.

## Portal details ## {`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::updatePreview.
- Any `FileFilter` added with a custom filter.

## macOS details ## {`gtkfilechooserdialognative`-macos}

On macOS the NSSavePanel and NSOpenPanel classes are used to provide native file chooser dialogs. Some features provided by `FileChooserDialog` are not supported:

- Extra widgets added with `fileChooserSetExtraWidget`, unless the widget is an instance of GtkLabel, in which case the label text will be used to set the NSSavePanel message instance property.
- Use of custom previews by connecting to FileChooser::updatePreview.
- Any `FileFilter` added with a custom filter.
- 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, addShortcutFolderUri, bindProperty, bindPropertyFull, destroy, forceFloating, freezeNotify, getv, hide, isFloating, listFilters, listShortcutFolderUris, listShortcutFolders, notify, notifyByPspec, ref, refSink, removeChoice, removeFilter, removeShortcutFolder, removeShortcutFolderUri, run, runDispose, selectAll, selectFile, selectFilename, selectUri, show, stealData, stealQdata, thawNotify, unref, unselectAll, unselectFile, unselectFilename, unselectUri, watchClosure.

#### Getters

getAcceptLabel, getAction, getCancelLabel, getChoice, getCreateFolders, getCurrentFolder, getCurrentFolderFile, getCurrentFolderUri, getCurrentName, getData, getDoOverwriteConfirmation, getExtraWidget, getFile, getFilename, getFilenames, getFiles, getFilter, getLocalOnly, getModal, getPreviewFile, getPreviewFilename, getPreviewUri, getPreviewWidget, getPreviewWidgetActive, getProperty, getQdata, getSelectMultiple, getShowHidden, getTitle, getTransientFor, getUri, getUris, getUsePreviewLabel, getVisible.

#### Setters

setAcceptLabel, setAction, setCancelLabel, setChoice, setCreateFolders, setCurrentFolder, setCurrentFolderFile, setCurrentFolderUri, setCurrentName, setData, setDataFull, setDoOverwriteConfirmation, setExtraWidget, setFile, setFilename, setFilter, setLocalOnly, setModal, setPreviewWidget, setPreviewWidgetActive, setProperty, setSelectMultiple, setShowHidden, setTitle, setTransientFor, setUri, setUsePreviewLabel.

## getAcceptLabel

fileChooserNativeGetAcceptLabel Source #

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

fileChooserNativeGetCancelLabel Source #

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

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

fileChooserNativeSetAcceptLabel Source #

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

fileChooserNativeSetCancelLabel Source #

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

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 ]