gi-gtk-4.0.4: Gtk bindings
CopyrightWill Thompson Iñaki García Etxebarria and Jonas Platte
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria
Safe HaskellSafe-Inferred
LanguageHaskell2010

GI.Gtk.Objects.FileChooserNative

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.

Note that unlike FileChooserDialog, FileChooserNative 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 ## {gtkfilechoosernative-typical-usage}

In the simplest of cases, you can the following code to use FileChooserDialog 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 dialog 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 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.

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

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.

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

  • Shortcut folders.
Synopsis

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

GObject FileChooserNative Source # 
Instance details

Defined in GI.Gtk.Objects.FileChooserNative

ManagedPtrNewtype FileChooserNative Source # 
Instance details

Defined in GI.Gtk.Objects.FileChooserNative

TypedObject FileChooserNative Source # 
Instance details

Defined in GI.Gtk.Objects.FileChooserNative

Methods

glibType :: IO GType

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

gvalueSet_ :: Ptr GValue -> Maybe FileChooserNative -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe FileChooserNative)

type ParentTypes FileChooserNative Source # 
Instance details

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

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

getAcceptLabel

fileChooserNativeGetAcceptLabel Source #

Arguments

:: (HasCallStack, MonadIO m, IsFileChooserNative a) 
=> a

self: a FileChooserNative

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

getCancelLabel

fileChooserNativeGetCancelLabel Source #

Arguments

:: (HasCallStack, MonadIO m, IsFileChooserNative a) 
=> a

self: a FileChooserNative

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

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.

setAcceptLabel

fileChooserNativeSetAcceptLabel Source #

Arguments

:: (HasCallStack, MonadIO m, IsFileChooserNative a) 
=> a

self: a FileChooserNative

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

setCancelLabel

fileChooserNativeSetCancelLabel Source #

Arguments

:: (HasCallStack, MonadIO m, IsFileChooserNative a) 
=> a

self: a FileChooserNative

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

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 ]