Package ch.bailu.gtk.gtk

Class FileChooserNative

java.lang.Object
ch.bailu.gtk.type.Type
ch.bailu.gtk.type.Pointer
ch.bailu.gtk.gobject.Object
ch.bailu.gtk.gtk.NativeDialog
ch.bailu.gtk.gtk.FileChooserNative
All Implemented Interfaces:
PointerInterface
public class FileChooserNative extends NativeDialog
`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
[class@Gtk.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
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
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 [class@Gtk.FileChooserDialog] documentation.

## Response Codes

`GtkFileChooserNative` inherits from [class@Gtk.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 `GtkFileChooserDialog`

There are a few things in the [iface@Gtk.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 [class@Gtk.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.

https://docs.gtk.org/gtk4/class.FileChooserNative.html

  • Constructor Details

    • FileChooserNative

      public FileChooserNative(PointerContainer pointer)

    • FileChooserNative

      public FileChooserNative(@Nullable Str title, @Nullable Window parent, int action, @Nullable Str accept_label, @Nullable Str cancel_label)
      Creates a new `GtkFileChooserNative`.
      Parameters:
      title - Title of the native
      parent - Transient parent of the native
      action - Open or save mode for the dialog
      accept_label - text to go in the accept button, or %NULL for the default
      cancel_label - text to go in the cancel button, or %NULL for the default

    • FileChooserNative

      public FileChooserNative(String title, @Nullable Window parent, int action, String accept_label, String cancel_label)
      Creates a new `GtkFileChooserNative`.
      Parameters:
      title - Title of the native
      parent - Transient parent of the native
      action - Open or save mode for the dialog
      accept_label - text to go in the accept button, or %NULL for the default
      cancel_label - text to go in the cancel button, or %NULL for the default

  • Method Details

    • getClassHandler

      public static ClassHandler getClassHandler()

    • getAcceptLabel

      public Str getAcceptLabel()
      Retrieves the custom label text for the accept button.
      Returns:
      The custom label

    • getCancelLabel

      public Str getCancelLabel()
      Retrieves the custom label text for the cancel button.
      Returns:
      The custom label

    • setAcceptLabel

      public void setAcceptLabel(@Nullable Str accept_label)
      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.
      Parameters:
      accept_label - custom label

    • setAcceptLabel

      public void setAcceptLabel(String accept_label)
      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.
      Parameters:
      accept_label - custom label

    • setCancelLabel

      public void setCancelLabel(@Nullable Str cancel_label)
      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.
      Parameters:
      cancel_label - custom label

    • setCancelLabel

      public void setCancelLabel(String cancel_label)
      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.
      Parameters:
      cancel_label - custom label

    • asFileChooser

      public FileChooser asFileChooser()
      Implements interface FileChooser. Call this to get access to interface functions.
      Returns:
      FileChooser

    • getTypeID

      public static long getTypeID()

    • getParentTypeID

      public static long getParentTypeID()

    • getTypeSize

      public static TypeSystem.TypeSize getTypeSize()

    • getParentTypeSize

      public static TypeSystem.TypeSize getParentTypeSize()

    • getInstanceSize

      public static int getInstanceSize()