Class
GtkFileChooserDialog
Description [src]
final class Gtk.FileChooserDialog : Gtk.Dialog {
/* No available fields */
}
GtkFileChooserDialog
is a dialog suitable for use with
“File Open” or “File Save” commands.
This widget works by putting a GtkFileChooserWidget
inside a GtkDialog
. It exposes the GtkFileChooser
interface, so you can use all of the GtkFileChooser
functions
on the file chooser dialog as well as those for GtkDialog
.
Note that GtkFileChooserDialog
does not have any methods of its
own. Instead, you should use the functions that work on a
GtkFileChooser
.
If you want to integrate well with the platform you should use the
GtkFileChooserNative
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_widget_show (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_widget_show (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” withgtk_file_chooser_set_current_name()
. -
To save a file under a different name, use
GTK_FILE_CHOOSER_ACTION_SAVE
, and set the existing file withgtk_file_chooser_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 gtk_file_chooser_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 GtkDialog
, 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
gtk_file_chooser_dialog_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 GtkResponseType
. For most dialog
boxes you can use your own custom response codes rather than the
ones in GtkResponseType
, 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.
Constructors
gtk_file_chooser_dialog_new
Creates a new GtkFileChooserDialog
.
Instance methods
Methods inherited from GtkDialog (10)
gtk_dialog_add_action_widget
Adds an activatable widget to the action area of a GtkDialog
.
gtk_dialog_add_button
Adds a button with the given text.
gtk_dialog_add_buttons
Adds multiple buttons.
gtk_dialog_get_content_area
Returns the content area of dialog
.
gtk_dialog_get_header_bar
Returns the header bar of dialog
.
gtk_dialog_get_response_for_widget
Gets the response id of a widget in the action area of a dialog.
gtk_dialog_get_widget_for_response
Gets the widget button that uses the given response ID in the action area of a dialog.
gtk_dialog_response
Emits the ::response signal with the given response ID.
gtk_dialog_set_default_response
Sets the default widget for the dialog based on the response ID.
gtk_dialog_set_response_sensitive
A convenient way to sensitize/desensitize dialog buttons.
Methods inherited from GtkWindow (54)
gtk_window_close
Requests that the window is closed.
gtk_window_destroy
Drop the internal reference GTK holds on toplevel windows.
gtk_window_fullscreen
Asks to place window
in the fullscreen state.
gtk_window_fullscreen_on_monitor
Asks to place window
in the fullscreen state on the given monitor
.
gtk_window_get_application
Gets the GtkApplication
associated with the window.
gtk_window_get_child
Gets the child widget of window
.
gtk_window_get_decorated
Returns whether the window has been set to have decorations.
gtk_window_get_default_size
Gets the default size of the window.
gtk_window_get_default_widget
Returns the default widget for window
.
gtk_window_get_deletable
Returns whether the window has been set to have a close button.
gtk_window_get_destroy_with_parent
Returns whether the window will be destroyed with its transient parent.
gtk_window_get_focus
Retrieves the current focused widget within the window.
gtk_window_get_focus_visible
Gets whether “focus rectangles” are supposed to be visible.
gtk_window_get_group
Returns the group for window
.
gtk_window_get_handle_menubar_accel
Returns whether this window reacts to F10 key presses by activating a menubar it contains.
Available since: 4.2
gtk_window_get_hide_on_close
Returns whether the window will be hidden when the close button is clicked.
gtk_window_get_icon_name
Returns the name of the themed icon for the window.
gtk_window_get_mnemonics_visible
Gets whether mnemonics are supposed to be visible.
gtk_window_get_modal
Returns whether the window is modal.
gtk_window_get_resizable
Gets the value set by gtk_window_set_resizable()
.
gtk_window_get_title
Retrieves the title of the window.
gtk_window_get_titlebar
Returns the custom titlebar that has been set with
gtk_window_set_titlebar()
.
gtk_window_get_transient_for
Fetches the transient parent for this window.
Methods inherited from GtkWidget (159)
gtk_widget_action_set_enabled
Enable or disable an action installed with
gtk_widget_class_install_action()
.
gtk_widget_activate
For widgets that can be “activated” (buttons, menu items, etc.), this function activates them.
gtk_widget_activate_action
Looks up the action in the action groups associated
with widget
and its ancestors, and activates it.
gtk_widget_activate_action_variant
Looks up the action in the action groups associated with
widget
and its ancestors, and activates it.
gtk_widget_activate_default
Activates the default.activate
action from widget
.
gtk_widget_add_controller
Adds controller
to widget
so that it will receive events.
gtk_widget_add_css_class
Adds a style class to widget
.
gtk_widget_add_mnemonic_label
Adds a widget to the list of mnemonic labels for this widget.
gtk_widget_add_tick_callback
Queues an animation frame update and adds a callback to be called before each frame.
gtk_widget_allocate
This function is only used by GtkWidget
subclasses, to
assign a size, position and (optionally) baseline to their
child widgets.
gtk_widget_child_focus
Called by widgets as the user moves around the window using keyboard shortcuts.
gtk_widget_compute_bounds
Computes the bounds for widget
in the coordinate space of target
.
gtk_widget_compute_expand
Computes whether a container should give this widget extra space when possible.
gtk_widget_compute_point
Translates the given point
in widget
‘s coordinates to coordinates
relative to target
’s coordinate system.
gtk_widget_compute_transform
Computes a matrix suitable to describe a transformation from
widget
‘s coordinate system into target
‘s coordinate system.
gtk_widget_contains
Tests if the point at (x
, y
) is contained in widget
.
gtk_widget_create_pango_context
Creates a new PangoContext
with the appropriate font map,
font options, font description, and base direction for drawing
text for this widget.
gtk_widget_create_pango_layout
Creates a new PangoLayout
with the appropriate font map,
font description, and base direction for drawing text for
this widget.
gtk_drag_check_threshold
Checks to see if a drag movement has passed the GTK drag threshold.
gtk_widget_error_bell
Notifies the user about an input-related error on this widget.
gtk_widget_get_allocated_baseline
Returns the baseline that has currently been allocated to widget
.
gtk_widget_get_allocated_height
Returns the height that has currently been allocated to widget
.
gtk_widget_get_allocated_width
Returns the width that has currently been allocated to widget
.
Methods inherited from GObject (42)
Methods inherited from GtkAccessible (10)
gtk_accessible_get_accessible_role
Retrieves the GtkAccessibleRole
for the given GtkAccessible
.
gtk_accessible_reset_property
Resets the accessible property
to its default value.
gtk_accessible_reset_relation
Resets the accessible relation
to its default value.
gtk_accessible_reset_state
Resets the accessible state
to its default value.
gtk_accessible_update_property
Updates a list of accessible properties.
gtk_accessible_update_property_value
Updates an array of accessible properties.
gtk_accessible_update_relation
Updates a list of accessible relations.
gtk_accessible_update_relation_value
Updates an array of accessible relations.
gtk_accessible_update_state
Updates a list of accessible states. See the GtkAccessibleState
documentation for the value types of accessible states.
gtk_accessible_update_state_value
Updates an array of accessible states.
Methods inherited from GtkBuildable (1)
gtk_buildable_get_buildable_id
Gets the ID of the buildable
object.
Methods inherited from GtkFileChooser (25)
gtk_file_chooser_add_choice
Adds a ‘choice’ to the file chooser.
gtk_file_chooser_add_filter
Adds filter
to the list of filters that the user can select between.
gtk_file_chooser_add_shortcut_folder
Adds a folder to be displayed with the shortcut folders in a file chooser.
gtk_file_chooser_get_action
Gets the type of operation that the file chooser is performing.
gtk_file_chooser_get_choice
Gets the currently selected option in the ‘choice’ with the given ID.
gtk_file_chooser_get_create_folders
Gets whether file chooser will offer to create new folders.
gtk_file_chooser_get_current_folder
Gets the current folder of chooser
as GFile
.
gtk_file_chooser_get_current_name
Gets the current name in the file selector, as entered by the user.
gtk_file_chooser_get_file
Gets the GFile
for the currently selected file in
the file selector.
gtk_file_chooser_get_files
Lists all the selected files and subfolders in the current folder
of chooser
as GFile
.
gtk_file_chooser_get_filter
Gets the current filter.
gtk_file_chooser_get_filters
Gets the current set of user-selectable filters, as a list model.
gtk_file_chooser_get_select_multiple
Gets whether multiple files can be selected in the file chooser.
gtk_file_chooser_get_shortcut_folders
Queries the list of shortcut folders in the file chooser.
gtk_file_chooser_remove_choice
Removes a ‘choice’ that has been added with gtk_file_chooser_add_choice()
.
gtk_file_chooser_remove_filter
Removes filter
from the list of filters that the user can select between.
gtk_file_chooser_remove_shortcut_folder
Removes a folder from the shortcut folders in a file chooser.
gtk_file_chooser_set_action
Sets the type of operation that the chooser is performing.
gtk_file_chooser_set_choice
Selects an option in a ‘choice’ that has been added with
gtk_file_chooser_add_choice()
.
gtk_file_chooser_set_create_folders
Sets whether file chooser will offer to create new folders.
gtk_file_chooser_set_current_folder
Sets the current folder for chooser
from a GFile
.
gtk_file_chooser_set_current_name
Sets the current name in the file selector, as if entered by the user.
gtk_file_chooser_set_file
Sets file
as the current filename for the file chooser.
Methods inherited from GtkNative (5)
gtk_native_get_renderer
Returns the renderer that is used for this GtkNative
.
gtk_native_get_surface
Returns the surface of this GtkNative
.
gtk_native_get_surface_transform
Retrieves the surface transform of self
.
gtk_native_realize
Realizes a GtkNative
.
gtk_native_unrealize
Unrealizes a GtkNative
.
Methods inherited from GtkRoot (3)
gtk_root_get_display
Returns the display that this GtkRoot
is on.
gtk_root_get_focus
Retrieves the current focused widget within the root.
gtk_root_set_focus
If focus
is not the current focus widget, and is focusable, sets
it as the focus widget for the root.
Properties
Properties inherited from GtkDialog (1)
Gtk.Dialog:use-header-bar
TRUE
if the dialog uses a headerbar for action buttons
instead of the action-area.
Properties inherited from GtkWindow (23)
Gtk.Window:application
The GtkApplication
associated with the window.
Gtk.Window:child
The child widget.
Gtk.Window:decorated
Whether the window should have a frame (also known as decorations).
Gtk.Window:default-height
The default height of the window.
Gtk.Window:default-widget
The default widget.
Gtk.Window:default-width
The default width of the window.
Gtk.Window:deletable
Whether the window frame should have a close button.
Gtk.Window:destroy-with-parent
If this window should be destroyed when the parent is destroyed.
Gtk.Window:display
The display that will display this window.
Gtk.Window:focus-visible
Whether ‘focus rectangles’ are currently visible in this window.
Gtk.Window:focus-widget
The focus widget.
Gtk.Window:fullscreened
Whether the window is fullscreen.
Gtk.Window:handle-menubar-accel
Whether the window frame should handle F10 for activating menubars.
Available since: 4.2
Gtk.Window:hide-on-close
If this window should be hidden when the users clicks the close button.
Gtk.Window:icon-name
Specifies the name of the themed icon to use as the window icon.
Gtk.Window:is-active
Whether the toplevel is the currently active window.
Gtk.Window:maximized
Whether the window is maximized.
Gtk.Window:mnemonics-visible
Whether mnemonics are currently visible in this window.
Gtk.Window:modal
If TRUE
, the window is modal.
Gtk.Window:resizable
If TRUE
, users can resize the window.
Gtk.Window:startup-id
A write-only property for setting window’s startup notification identifier.
Gtk.Window:title
The title of the window.
Gtk.Window:transient-for
The transient parent of the window.
Properties inherited from GtkWidget (34)
Gtk.Widget:can-focus
Whether the widget or any of its descendents can accept the input focus.
Gtk.Widget:can-target
Whether the widget can receive pointer events.
Gtk.Widget:css-classes
A list of css classes applied to this widget.
Gtk.Widget:css-name
The name of this widget in the CSS tree.
Gtk.Widget:cursor
The cursor used by widget
.
Gtk.Widget:focus-on-click
Whether the widget should grab focus when it is clicked with the mouse.
Gtk.Widget:focusable
Whether this widget itself will accept the input focus.
Gtk.Widget:halign
How to distribute horizontal space if widget gets extra space.
Gtk.Widget:has-default
Whether the widget is the default widget.
Gtk.Widget:has-focus
Whether the widget has the input focus.
Gtk.Widget:has-tooltip
Enables or disables the emission of the ::query-tooltip signal on widget
.
Gtk.Widget:height-request
Override for height request of the widget.
Gtk.Widget:hexpand
Whether to expand horizontally.
Gtk.Widget:hexpand-set
Whether to use the hexpand
property.
Gtk.Widget:layout-manager
The GtkLayoutManager
instance to use to compute the preferred size
of the widget, and allocate its children.
Gtk.Widget:margin-bottom
Margin on bottom side of widget.
Gtk.Widget:margin-end
Margin on end of widget, horizontally.
Gtk.Widget:margin-start
Margin on start of widget, horizontally.
Gtk.Widget:margin-top
Margin on top side of widget.
Gtk.Widget:name
The name of the widget.
Gtk.Widget:opacity
The requested opacity of the widget.
Gtk.Widget:overflow
How content outside the widget’s content area is treated.
Gtk.Widget:parent
The parent widget of this widget.
Gtk.Widget:receives-default
Whether the widget will receive the default action when it is focused.
Gtk.Widget:root
The GtkRoot
widget of the widget tree containing this widget.
Gtk.Widget:scale-factor
The scale factor of the widget.
Gtk.Widget:sensitive
Whether the widget responds to input.
Gtk.Widget:tooltip-markup
Sets the text of tooltip to be the given string, which is marked up with Pango markup.
Gtk.Widget:tooltip-text
Sets the text of tooltip to be the given string.
Gtk.Widget:valign
How to distribute vertical space if widget gets extra space.
Gtk.Widget:vexpand
Whether to expand vertically.
Gtk.Widget:vexpand-set
Whether to use the vexpand
property.
Gtk.Widget:visible
Whether the widget is visible.
Gtk.Widget:width-request
Override for width request of the widget.
Properties inherited from GtkAccessible (1)
Gtk.Accessible:accessible-role
The accessible role of the given GtkAccessible
implementation.
Properties inherited from GtkFileChooser (6)
Gtk.FileChooser:action
The type of operation that the file chooser is performing.
Gtk.FileChooser:create-folders
Whether a file chooser not in GTK_FILE_CHOOSER_ACTION_OPEN
mode
will offer the user to create new folders.
Gtk.FileChooser:filter
The current filter for selecting files that are displayed.
Gtk.FileChooser:filters
A GListModel
containing the filters that have been
added with gtk_file_chooser_add_filter()
.
Gtk.FileChooser:select-multiple
Whether to allow multiple files to be selected.
Gtk.FileChooser:shortcut-folders
A GListModel
containing the shortcut folders that have been
added with gtk_file_chooser_add_shortcut_folder()
.
Signals
Signals inherited from GtkDialog (2)
Gtk.Dialog::close
Emitted when the user uses a keybinding to close the dialog.
Gtk.Dialog::response
Emitted when an action widget is clicked.
Signals inherited from GtkWindow (5)
Gtk.Window::activate-default
Emitted when the user activates the default widget
of window
.
Gtk.Window::activate-focus
Emitted when the user activates the currently focused
widget of window
.
Gtk.Window::close-request
Emitted when the user clicks on the close button of the window.
Gtk.Window::enable-debugging
Emitted when the user enables or disables interactive debugging.
Gtk.Window::keys-changed
Emitted when the set of accelerators or mnemonics that
are associated with window
changes.
Signals inherited from GtkWidget (13)
Gtk.Widget::destroy
Signals that all holders of a reference to the widget should release the reference that they hold.
Gtk.Widget::direction-changed
Emitted when the text direction of a widget changes.
Gtk.Widget::hide
Emitted when widget
is hidden.
Gtk.Widget::keynav-failed
Emitted if keyboard navigation fails.
Gtk.Widget::map
Emitted when widget
is going to be mapped.
Gtk.Widget::mnemonic-activate
Emitted when a widget is activated via a mnemonic.
Gtk.Widget::move-focus
Emitted when the focus is moved.
Gtk.Widget::query-tooltip
Emitted when the widgets tooltip is about to be shown.
Gtk.Widget::realize
Emitted when widget
is associated with a GdkSurface
.
Gtk.Widget::show
Emitted when widget
is shown.
Gtk.Widget::state-flags-changed
Emitted when the widget state changes.
Gtk.Widget::unmap
Emitted when widget
is going to be unmapped.
Gtk.Widget::unrealize
Emitted when the GdkSurface
associated with widget
is destroyed.