Class: Gtk::FileChooserDialog

Inherits:
Dialog show all
Extended by:
GLib::Deprecatable
Defined in:
lib/gtk4/deprecated.rb,
lib/gtk4/file-chooser-dialog.rb

Overview

GtkFileChooserDialog is a dialog suitable for use with “File Open” or “File Save” commands.

An example GtkFileChooserDialog

This widget works by putting a [classGtk.FileChooserWidget] inside a [classGtk.Dialog]. It exposes the [ifaceGtk.FileChooser] interface, so you can use all of the [ifaceGtk.FileChooser] functions on the file chooser dialog as well as those for [classGtk.Dialog].

Note that GtkFileChooserDialog does not have any methods of its own. Instead, you should use the functions that work on a [ifaceGtk.FileChooser].

If you want to integrate well with the platform you should use the [classGtk.FileChooserNative] API, which will use a platform-specific dialog if available and fall back to GtkFileChooserDialog otherwise.

Typical usage

In the simplest of cases, you can the following code to use GtkFileChooserDialog to select a file for opening:

static void
on_open_response (GtkDialog *dialog,
                  int        response)
{
  if (response == GTK_RESPONSE_ACCEPT)
    {
      GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog);

      g_autoptr(GFile) file = gtk_file_chooser_get_file (chooser);

      open_file (file);
    }

  gtk_window_destroy (GTK_WINDOW (dialog));
}

  // ...
  GtkWidget *dialog;
  GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;

  dialog = gtk_file_chooser_dialog_new ("Open File",
                                        parent_window,
                                        action,
                                        _("_Cancel"),
                                        GTK_RESPONSE_CANCEL,
                                        _("_Open"),
                                        GTK_RESPONSE_ACCEPT,
                                        NULL);

  gtk_window_present (GTK_WINDOW (dialog));

  g_signal_connect (dialog, "response",
                    G_CALLBACK (on_open_response),
                    NULL);

To use a dialog for saving, you can use this:

static void
on_save_response (GtkDialog *dialog,
                  int        response)
{
  if (response == GTK_RESPONSE_ACCEPT)
    {
      GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog);

      g_autoptr(GFile) file = gtk_file_chooser_get_file (chooser);

      save_to_file (file);
    }

  gtk_window_destroy (GTK_WINDOW (dialog));
}

  // ...
  GtkWidget *dialog;
  GtkFileChooser *chooser;
  GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE;

  dialog = gtk_file_chooser_dialog_new ("Save File",
                                        parent_window,
                                        action,
                                        _("_Cancel"),
                                        GTK_RESPONSE_CANCEL,
                                        _("_Save"),
                                        GTK_RESPONSE_ACCEPT,
                                        NULL);
  chooser = GTK_FILE_CHOOSER (dialog);

  if (user_edited_a_new_document)
    gtk_file_chooser_set_current_name (chooser, _("Untitled document"));
  else
    gtk_file_chooser_set_file (chooser, existing_filename);

  gtk_window_present (GTK_WINDOW (dialog));

  g_signal_connect (dialog, "response",
                    G_CALLBACK (on_save_response),
                    NULL);

Setting up a file chooser dialog

There are various cases in which you may need to use a GtkFileChooserDialog:

  • To select a file for opening, use %GTK_FILE_CHOOSER_ACTION_OPEN.

  • To save a file for the first time, use %GTK_FILE_CHOOSER_ACTION_SAVE, and suggest a name such as “Untitled” with [methodGtk.FileChooser.set_current_name].

  • To save a file under a different name, use %GTK_FILE_CHOOSER_ACTION_SAVE, and set the existing file with [methodGtk.FileChooser.set_file].

  • To choose a folder instead of a filem use %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.

In general, you should only cause the file chooser to show a specific folder when it is appropriate to use [methodGtk.FileChooser.set_file], i.e. when you are doing a “Save As” command and you already have a file saved somewhere.

Response Codes

GtkFileChooserDialog inherits from [classGtk.Dialog], so buttons that go in its action area have response codes such as %GTK_RESPONSE_ACCEPT and %GTK_RESPONSE_CANCEL. For example, you could call [ctorGtk.FileChooserDialog.new] as follows:

GtkWidget *dialog;
GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;

dialog = gtk_file_chooser_dialog_new ("Open File",
                                      parent_window,
                                      action,
                                      _("_Cancel"),
                                      GTK_RESPONSE_CANCEL,
                                      _("_Open"),
                                      GTK_RESPONSE_ACCEPT,
                                      NULL);

This will create buttons for “Cancel” and “Open” that use predefined response identifiers from [enumGtk.ResponseType]. For most dialog boxes you can use your own custom response codes rather than the ones in [enumGtk.ResponseType], but GtkFileChooserDialog assumes that its “accept”-type action, e.g. an “Open” or “Save” button, will have one of the following response codes:

  • %GTK_RESPONSE_ACCEPT
  • %GTK_RESPONSE_OK
  • %GTK_RESPONSE_YES
  • %GTK_RESPONSE_APPLY

This is because GtkFileChooserDialog must intercept responses and switch to folders if appropriate, rather than letting the dialog terminate — the implementation uses these known response codes to know which responses can be blocked if appropriate.

To summarize, make sure you use a predefined response code when you use GtkFileChooserDialog to ensure proper operation.

CSS nodes

GtkFileChooserDialog has a single CSS node with the name window and style class .filechooser.

Instance Method Summary collapse

Methods inherited from Dialog

#add_action_widget, #add_button, #add_button_raw, #add_buttons, #content_area, #get_response_for_widget, #get_widget_for_response, #get_widget_for_response_raw, #header_bar, #response, #set_default_response, #set_default_response_raw, #set_response_sensitive, #use_header_bar, #use_header_bar=, #use_header_bar?

Methods inherited from Window

#application, #application=, auto_startup_notification=, #child, #child=, #close, #decorated, #decorated=, #decorated?, #default_height, #default_height=, default_icon_name, default_icon_name=, #default_widget, #default_widget=, #default_width, #default_width=, #deletable, #deletable=, #deletable?, #destroy, #destroy_with_parent, #destroy_with_parent=, #destroy_with_parent?, #display, #display=, #focus, #focus=, #focus_visible, #focus_visible=, #focus_visible?, #focus_widget, #focus_widget=, #fullscreen, #fullscreen_on_monitor, #fullscreened=, #fullscreened?, #get_default_size, #group, #handle_menubar_accel, #handle_menubar_accel=, #handle_menubar_accel?, #has_group, #hide_on_close, #hide_on_close=, #hide_on_close?, #icon_name, #icon_name=, interactive_debugging=, #is_active, #is_active=, #is_active?, #is_fullscreen, #is_maximized, #is_suspended, list_toplevels, #maximize, #maximized=, #maximized?, #minimize, #mnemonics_visible, #mnemonics_visible=, #mnemonics_visible?, #modal, #modal=, #modal?, #present, #present_with_time, #resizable, #resizable=, #resizable?, #set_default_size, #startup_id=, #suspended=, #suspended?, #title, #title=, #titlebar, #titlebar=, toplevels, #transient_for, #transient_for=, #unfullscreen, #unmaximize, #unminimize

Methods inherited from Widget

#accessible_role, #accessible_role=, #action_set_enabled, #activate, #activate_action, #activate_action_variant, #activate_default, #activate_signal, #activate_signal=, #activate_signal_from_name=, #add_binding, #add_binding_action, #add_binding_signal, #add_controller, #add_css_class, #add_mnemonic_label, #add_shortcut, #add_tick_callback, #allocate, #allocated_baseline, #allocated_height, #allocated_width, #baseline, #bind_template_callback_full, #bind_template_child, #bind_template_child_full, #can_focus, #can_focus=, #can_focus?, #can_target, #can_target=, #can_target?, #child_focus, #child_visible, #child_visible=, #children, #clipboard, #compute_bounds, #compute_expand, #compute_point, #compute_transform, #contains, #create_pango_context, #create_pango_layout, #css_classes, #css_classes=, #css_name, #css_name=, #cursor, #cursor=, #cursor_from_name=, default_direction, default_direction=, #direction, #direction=, #display, #dispose_template, #drag_check_threshold, #error_bell, #first_child, #focus_child, #focus_child=, #focus_on_click, #focus_on_click=, #focus_on_click?, #focusable, #focusable=, #focusable?, #font_map, #font_map=, #font_options, #font_options=, #frame_clock, #get_allocation, #get_ancestor, #get_color, #get_preferred_size, #get_size, #get_size_request, #get_template_child, #grab_focus, #halign, #halign=, #has_css_class, #has_default, #has_default=, #has_default?, #has_focus, #has_focus=, #has_focus?, #has_tooltip, #has_tooltip=, #has_tooltip?, #has_visible_focus, have_template?, #height, #height_request, #height_request=, #hexpand, #hexpand=, #hexpand?, #hexpand_set, #hexpand_set=, #hexpand_set?, #hide, #in_destruction, #init_template, #insert_action_group, #insert_action_group_raw, #insert_after, #insert_before, #install_action, #install_property_action, #is_ancestor, #is_drawable, #is_focus, #is_sensitive, #is_visible, #keynav_failed, #last_child, #layout_manager, #layout_manager=, #layout_manager_type, #layout_manager_type=, #list_mnemonic_labels, #map, #mapped, #margin_bottom, #margin_bottom=, #margin_end, #margin_end=, #margin_start, #margin_start=, #margin_top, #margin_top=, #measure, #mnemonic_activate, #name, #name=, #native, #next_sibling, #observe_children, #observe_controllers, #opacity, #opacity=, #overflow, #overflow=, #pango_context, #parent, #parent=, #pick, #prev_sibling, #primary_clipboard, #query_action, #queue_allocate, #queue_draw, #queue_resize, #realize, #realized, #receives_default, #receives_default=, #receives_default?, #remove_controller, #remove_css_class, #remove_mnemonic_label, #remove_tick_callback, #request_mode, #root, #root=, #scale_factor, #scale_factor=, #sensitive, #sensitive=, #sensitive?, #set_size_request, #set_size_request_raw, #set_state_flags, #set_template, #set_template_raw, #settings, #should_layout, #show, #size_allocate, #snapshot_child, #state_flags, #style_context, #style_context_raw, #template=, template_children, #template_from_resource=, #template_scope=, #tooltip_markup, #tooltip_markup=, #tooltip_text, #tooltip_text=, #translate_coordinates, #translate_coordinates_raw, #trigger_tooltip_query, #unmap, #unparent, #unrealize, #unset_state_flags, #valign, #valign=, #vexpand, #vexpand=, #vexpand?, #vexpand_set, #vexpand_set=, #vexpand_set?, #visible, #visible=, #visible?, #width, #width_request, #width_request=

Constructor Details

#initialize(options = {}) ⇒ Gtk::Widget

Creates a new GtkFileChooserDialog.

This function is analogous to [ctorGtk.Dialog.new_with_buttons].

Parameters:

  • title (String) —

    Title of the dialog

  • parent (Gtk::Window) —

    Transient parent of the dialog

  • action (Gtk::FileChooserAction) —

    Open or save mode for the dialog

  • first_button_text (String) —

    text to go in the first button

  • array (Array) —

    response ID for the first button, then additional (button, id) pairs, ending with nil



20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
 
# File 'lib/gtk4/file-chooser-dialog.rb', line 20

def initialize(options={})
  GLib::Object.instance_method(:initialize).bind(self).call
  Loader.reference_gobject(self, :sink => true)

  title = options[:title]
  parent = options[:parent]
  action = options[:action] || :open
  buttons = options[:buttons]

  set_title(title) if title
  set_action(action) if action
  set_transient_for(parent) if parent

  add_buttons(*buttons) if buttons
end

Instance Method Details

#initialize_raw ⇒ Gtk::Widget

Creates a new GtkFileChooserDialog.

This function is analogous to [ctorGtk.Dialog.new_with_buttons].

Parameters:

  • title (String) —

    Title of the dialog

  • parent (Gtk::Window) —

    Transient parent of the dialog

  • action (Gtk::FileChooserAction) —

    Open or save mode for the dialog

  • first_button_text (String) —

    text to go in the first button

  • array (Array) —

    response ID for the first button, then additional (button, id) pairs, ending with nil

Returns:




# File 'lib/gtk4/file-chooser-dialog.rb', line 19