File dialogs
menu.C from Chapter 24, Menus
gives an example of presenting a file dialog, a basic interface for
opening or creating a file.
Main window's create_file_dialog
returns a new
x::w::file_dialog
object.
menu.C creates two file dialogs, for its
“File/New” and “File/Close” menu
options.
x::w::file_dialog_config config{ [](ONLY IN_THREAD, const x::w::file_dialog &fd, const std::string &filename, const x::w::busy &mcguffin) { fd->dialog_window->hide(); }, [](ONLY IN_THREAD, const x::w::ok_cancel_callback_args &args) { }, x::w::file_dialog_type::create_file };
x::w::file_dialog_config
configures a new dialog.
Its first two parameters are callable objects. The first one gets
executed when a filename gets selected by the dialog, in one of two
ways: typing in the filename manually followed by
“Enter”, or clicking the “Ok” button;
or double-clicking on an existing file in the list of shown files.
It's also possible to use the system
file managers to drag an icon for a file into the file dialog and
drop it on top of the file directory listing (anywhere except for
the filename field, which is a text input field
that only accepts dropped plain
text content. Dropping a file icon is equivalent to
typing in its filename, followed by “Enter”.
The dialog does not get automatically closed, but the first parameter
to the lambda is the x::w::file_dialog,
in case it should be hide()-en.
The second lambda gets executed if the file dialog gets closed for
any other reason (“Cancel” button, Esc,
or using the dialog window's close button, if one is provided by the
window manager).
The third optional parameter defaults to
x::w::file_dialog_type::existing_file.
config.filename_filters.emplace_back("Text files", "\\.txt$"); config.filename_filters.emplace_back("Image files", "\\.(gif|png|jpg)$"); config.initial_filename_filter=1;
The first field in the file dialog is an input field for typing in a filename directly. Below it is the name of the current directory displayed by the file dialog. Each component in the directory's name is clickable, and shows the list of files and subdirectories below it. A combo-box with filename filters appears between the current directory's name, and the contents of the directory. This limits the list of files shown below to only the filenames that match the filename filter pattern.
x::w::file_dialog_config's
filename_filters sets the list of filename filters
shown in the combo-box. This std::vector defaults
to one entry: “All files”, for all files in the directory.
Each entry in the vector consists of:
The label shown in the combo-box, a
x::w::text_params, or a plain text string.The regular expression that a filename must match, in order to be visible. Note that this is a regular expression, and not a simple filename pattern.
The above example adds two more filters to the vector, and sets
the initial_filename_filter, that's shown initially
when the dialog opens, to “Text files”
(index #0 is the default “All files” option).
x::w::file_dialog d=main_window->create_file_dialog( {"file_open@example.libcxx", true}, config);
create_file_dialog()'s first parameter is a
dialog setting parameter.
The second parameter is the initialized
x::w::file_dialog_config.