class Gtk::FileChooserNative

Overview

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

WARNING ⚠️ The following code is in 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:

WARNING ⚠️ The following code is in 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 Gtk#FileChooserDialog documentation.

Response Codes

GtkFileChooserNative inherits from 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 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:

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:

Included Modules

Defined in:

lib/gi-crystal/src/auto/gtk-4.0/file_chooser_native.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from module Gtk::FileChooser

action : Gtk::FileChooserAction action, action=(action : Gtk::FileChooserAction) : Nil action=, add_choice(id : String, label : String, options : Enumerable(String)?, option_labels : Enumerable(String)?) : Nil add_choice, add_filter(filter : Gtk::FileFilter) : Nil add_filter, add_shortcut_folder(folder : Gio::File) : Bool add_shortcut_folder, choice(id : String) : String? choice, create_folders : Bool create_folders, create_folders=(create_folders : Bool) : Nil create_folders=, create_folders? : Bool create_folders?, current_folder : Gio::File? current_folder, current_folder=(file : Gio::File?) : Bool current_folder=, current_name : String? current_name, current_name=(name : String) : Nil current_name=, file : Gio::File? file, file=(file : Gio::File) : Bool file=, files : Gio::ListModel files, filter : Gtk::FileFilter? filter, filter=(filter : Gtk::FileFilter) : Nil filter=, filters : Gio::ListModel filters, remove_choice(id : String) : Nil remove_choice, remove_filter(filter : Gtk::FileFilter) : Nil remove_filter, remove_shortcut_folder(folder : Gio::File) : Bool remove_shortcut_folder, select_multiple : Bool select_multiple, select_multiple=(select_multiple : Bool) : Nil select_multiple=, select_multiple? : Bool select_multiple?, set_choice(id : String, option : String) : Nil set_choice, shortcut_folders : Gio::ListModel shortcut_folders, to_unsafe to_unsafe

Class methods inherited from module Gtk::FileChooser

g_type : UInt64 g_type

Instance methods inherited from class Gtk::NativeDialog

destroy : Nil destroy, hide : Nil hide, modal : Bool modal, modal=(modal : Bool) : Nil modal=, modal? : Bool modal?, response_signal response_signal, show : Nil show, title : String? title, title=(title : String) : Nil title=, transient_for : Gtk::Window? transient_for, transient_for=(parent : Gtk::Window?) : Nil transient_for=, visible : Bool visible, visible=(value : Bool) : Bool visible=, visible? : Bool visible?

Constructor methods inherited from class Gtk::NativeDialog

new
new(*, modal : Bool? = nil, title : String? = nil, transient_for : Gtk::Window? = nil, visible : Bool? = nil)
new

Class methods inherited from class Gtk::NativeDialog

g_type : UInt64 g_type

Instance methods inherited from class GObject::Object

bind_property(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags) : GObject::Binding bind_property, bind_property_full(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags, transform_to : GObject::Closure, transform_from : GObject::Closure) : GObject::Binding bind_property_full, data(key : String) : Pointer(Void)? data, finalize finalize, freeze_notify : Nil freeze_notify, getv(names : Enumerable(String), values : Enumerable(_)) : Nil getv, notify(property_name : String) : Nil notify, notify_by_pspec(pspec : GObject::ParamSpec) : Nil notify_by_pspec, notify_signal notify_signal, property(property_name : String, value : _) : Nil property, qdata(quark : UInt32) : Pointer(Void)? qdata, ref_count : UInt32 ref_count, run_dispose : Nil run_dispose, set_data(key : String, data : Pointer(Void)?) : Nil set_data, set_property(property_name : String, value : _) : Nil set_property, steal_data(key : String) : Pointer(Void)? steal_data, steal_qdata(quark : UInt32) : Pointer(Void)? steal_qdata, thaw_notify : Nil thaw_notify, to_unsafe : Pointer(Void) to_unsafe, watch_closure(closure : GObject::Closure) : Nil watch_closure

Constructor methods inherited from class GObject::Object

cast(obj : GObject::Object) : self cast, cast?(obj : GObject::Object) : self? cast?, new(pointer, transfer : GICrystal::Transfer)
new
new
, newv(object_type : UInt64, parameters : Enumerable(GObject::Parameter)) : self newv

Class methods inherited from class GObject::Object

compat_control(what : UInt64, data : Pointer(Void)?) : UInt64 compat_control, g_type : UInt64 g_type, interface_find_property(g_iface : GObject::TypeInterface, property_name : String) : GObject::ParamSpec interface_find_property, interface_list_properties(g_iface : GObject::TypeInterface) : Enumerable(GObject::ParamSpec) interface_list_properties

Constructor Detail

def self.new(title : String?, parent : Gtk::Window?, action : Gtk::FileChooserAction, accept_label : String?, cancel_label : String?) : self #

Creates a new GtkFileChooserNative.


def self.new #

Initialize a new FileChooserNative.


def self.new(*, accept_label : String? = nil, action : Gtk::FileChooserAction? = nil, cancel_label : String? = nil, create_folders : Bool? = nil, filter : Gtk::FileFilter? = nil, filters : Gio::ListModel? = nil, modal : Bool? = nil, select_multiple : Bool? = nil, shortcut_folders : Gio::ListModel? = nil, title : String? = nil, transient_for : Gtk::Window? = nil, visible : Bool? = nil) #

Class Method Detail

def self.g_type : UInt64 #

Returns the type id (GType) registered in GLib type system.


Instance Method Detail

def accept_label : String? #

Retrieves the custom label text for the accept button.


def accept_label=(value : String) : String #

def accept_label=(accept_label : String?) : Nil #

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.


def cancel_label : String? #

Retrieves the custom label text for the cancel button.


def cancel_label=(value : String) : String #

def cancel_label=(cancel_label : String?) : Nil #

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.