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)
            [](ONLY IN_THREAD,
               const x::w::ok_cancel_callback_args &args)

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)$");

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