Commit 95670f39 authored by Emmanuele Bassi's avatar Emmanuele Bassi 👣
Browse files

Merge branch 'ebassi/for-main' into 'main'

beginners: Add the section on the file selection dialog

See merge request !45
parents 769e6d29 a69e8441
Pipeline #355140 passed with stages
in 2 minutes and 53 seconds
......@@ -31,7 +31,6 @@ Buttons
- :doc:`Radio buttons <radio_button>`
- :doc:`Spin buttons <spin_button>`
- :doc:`Link buttons <link_button>`
- Volume buttons
- :doc:`Switches <switch>`
Text entries
......@@ -46,7 +45,7 @@ Dialogs
~~~~~~~
- :doc:`Messages <message_dialog>`
- Files selection
- :doc:`Files selection <file_dialog>`
- Colors selection
- Fonts selection
- Applications selection
......@@ -99,5 +98,6 @@ Information and progressive disclosure
entry.rst
password_entry.rst
message_dialog.rst
file_dialog.rst
spinner.rst
level_bar.rst
File Dialogs
============
..
image:: ../../img/tutorials/component.png
You can use the file selection dialog to allow the user to select a file to
load its contents into their application, or to save the current contents of
their application.
.. note::
GTK has two types of file selection dialogs: one is the "internal" dialog,
provided by the toolkit itself; and the other is a "native" dialog, which
will use the platform's own file selection dialog.
We are going to always use "native" file selection dialogs as they are
also the preferred way to interact with sandboxed environments.
.. important::
Native file selection dialogs are **not** widgets; you must manage their
lifetime yourself.
Opening files
-------------
.. tabs::
.. code-tab:: c
static void
on_file_open_response (GtkNativeDialog *native,
int response_id)
{
if (response_id == GTK_RESPONSE_ACCEPT) {
GtkFileChooser *chooser = GTK_FILE_CHOOSER (native);
g_autoptr (GFile) file = gtk_file_chooser_get_file (chooser);
open_file (file);
}
g_object_unref (native);
}
// ...
GtkFileChooserNative *native =
gtk_file_chooser_native_new ("Open File",
parent_window,
GTK_FILE_CHOOSER_ACTION_OPEN,
"_Open",
"_Cancel");
g_signal_connect (native, "response",
G_CALLBACK (on_file_open_response),
NULL);
gtk_native_dialog_show (GTK_NATIVE_DIALOG (native));
.. code-tab:: python
# Keep a reference on the native dialog; "self", in this case, is
# the application singleton instance
self._native = Gtk.FileChooserNative(
title="Open File",
# "self.main_window" is defined elsewhere as a Gtk.Window
transient_for=self.main_window,
action=Gtk.FileChooserAction.OPEN,
accept_label="_Open",
cancel_label="_Cancel",
)
def on_file_open_response(native, response):
if response == Gtk.Response.ACCEPT:
self.open_file(native.get_file())
self._native = None
self._native.connect("response", on_file_open_response)
self._native.show()
Saving files
------------
.. tabs::
.. code-tab:: c
static void
on_file_save_response (GtkNativeDialog *native,
int response_id)
{
if (response_id == GTK_RESPONSE_ACCEPT) {
GtkFileChooser *chooser = GTK_FILE_CHOOSER (native);
g_autoptr (GFile) file = gtk_file_chooser_get_file (chooser);
save_file (file);
}
g_object_unref (native);
}
// ...
GtkFileChooserNative *native =
gtk_file_chooser_native_new ("Save File",
parent_window,
GTK_FILE_CHOOSER_ACTION_SAVE,
"_Save",
"_Cancel");
g_signal_connect (native, "response",
G_CALLBACK (on_file_save_response),
NULL);
gtk_native_dialog_show (GTK_NATIVE_DIALOG (native));
.. code-tab:: python
# Keep a reference on the native dialog; "self", in this case, is
# the application singleton instance
self._native = Gtk.FileChooserNative(
title="Save File",
# "self.main_window" is defined elsewhere as a Gtk.Window
transient_for=self.main_window,
action=Gtk.FileChooserAction.SAVE,
accept_label="_Save",
cancel_label="_Cancel",
)
def on_file_save_response(native, response):
if response == Gtk.Response.ACCEPT:
self.save_file(native.get_file())
self._native = None
self._native.connect("response", on_file_save_response)
self._native.show()
Choices
-------
File selection dialogs can expose additional controls to the user in the
form of "choices". A choice can either be a boolean "yes or no" option, or
a set of possible values:
.. tabs::
.. code-tab:: c
// Boolean choice
gtk_file_chooser_add_choice (file_chooser, "validate",
"Enable validation on load",
NULL, NULL);
// Multiple choices
gtk_file_chooser_add_choice (file_chooser, "action",
"Action when loading",
(const char *[]) {
"live",
"laugh",
"love",
NULL,
},
(const char *[]) {
"Live",
"Laugh",
"Love",
NULL,
});
.. code-tab:: python
# Boolean choice
file_chooser.add_choice("validate", "Enable validation on load", None, None)
# Multiple choices
file_chooser.add_choice("action", "Action when loading",
["live", "laugh", "love"],
["Live", "Laugh", "Love"])
You can then use the ``get_choice()`` method in the "response" signal handler
to retrieve the value of the given choice.
Filters
-------
You can use filters to control what kind of files the dialog should display
to the user. File filters can use:
- MIME types
- patterns matching the file name
- suffixes for matching file extensions
Useful methods for the component
--------------------------------
* When saving files, you can use the ``set_current_name()`` method to suggest
a file name to the user.
* In order to select multiple files to open, you can use the
``set_select_multiple()`` method, and then call ``get_files()`` instead of
``get_file()`` to retrieve the list of all selected files as a list model.
API references
--------------
In the examples we used the following classes:
* `GtkFileChooserNative <https://docs.gtk.org/gtk4/class.FileChooserNative.html>`__
* `GtkNativeDialog <https://docs.gtk.org/gtk4/class.NativeDialog.html>`__
* `GtkFileChooser <https://docs.gtk.org/gtk4/iface.FileChooser.html>`__
* `GtkFileFilter <https://docs.gtk.org/gtk4/class.FileFilter.html>`__
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment