ae.kivy_file_chooser

extended kivy file chooser widget

this ae namespace portion provides the FileChooserPopup widget (chooser_popup) which is embedding Kivy’s FileChooser class in a dropdown window (FlowDropDown), and extending it with a path selector and a button to switch between list and icon view.

file chooser dropdown usage

the FileChooserPopup widget can be used like any Kivy DropDown widget - see the python and kv lang examples in the doc strings of the dropdown module. Additionally, all the features of the FlowDropDown like e.g., the child_data_maps are available.

alternatively (and without the need to explicitly instantiate the file chooser dropdown widget) you simply have to change the application flow to id_of_flow(‘open’, ‘file_chooser’) to open this file chooser (see also the section application flow):

main_app.change_flow(id_of_flow('open', 'file_chooser'),
                     **update_tap_kwargs(open_button))

the variable open_button in this example represents a button widget instance that opens the file chooser dropdown (and to which the file chooser gets attached to).

use the submit_to property to distinguish multiple usages of the file chooser in a single app:

main_app.change_flow(id_of_flow('open', 'file_chooser'),
                     **update_tap_kwargs(open_button,
                                         popup_kwargs=dict(submit_to=submit_to_str_or_callable))

the variable submit_to_str_or_callable of the above example can be either a string or a callable. if you pass a callable, FileChooserPopup will call it if the user has selected a file (by touching or double-clicking on a file entry). this callback receives two arguments: the file path of the just selected file and the FileChooser dropdown widget instance and can be declared like:

def submit_to_callable(file_path: str, chooser_popup: Widget):

passing a string to submit_to (or if it gets not specified at all), the hard-coded on_file_chooser_submit event handler callback method of your main app instance will be executed with the same two arguments:

def on_file_chooser_submit(self, file_path: str, chooser_popup: Widget):
    if chooser_popup.submit_to == 'usage1':
        usage1_object_or_process.file_path = file_path
        chooser_popup.dismiss()
    elif chooser_popup.submit_to == 'usage2':
        ...
    elif chooser_popup.submit_to == '': # w/o specifying `submit_to`
        ...

use the key of the tap_flow_id property of the FlowButton to provide a separate i18n help text for each individual button.

the filters property of Kivy’s kivy.uix.filechooser.FileChooser can be used to filter the files displayed in this file chooser widget.

the path selector dropdown (FileChooserPathSelectPopup) situated at the top of this file chooser dropdown is providing all common OS and app specific paths that are registered in the PATH_PLACEHOLDERS dict. the keys of this dict will be displayed as shortcut path names instead of the full path strings. Additionally, translation texts can be provided for the shortcut path names to display them in the language selected by the app user.

to extend the path selector dropdown with additional paths, you can either register them within PATH_PLACEHOLDERS, or you add them to the optional app state variable file_chooser_paths by calling the method register_file_path().

by adding the list file_chooser_paths to the app state variables of your app, the paths provided by the path selector widget will automatically maintain and keep the OS and user paths persistent between app runs.

to record and remember the last selected path, add also the app state file_chooser_initial_path to the :ref:`app state variables of your app.

override the method _init_default_user_cfg_vars() within the main app instance of your app to make these two persistent app state variables user-specific:

def _init_default_user_cfg_vars(self):
    super()._init_default_user_cfg_vars()
    self.user_specific_cfg_vars |= {
        (APP_STATE_SECTION_NAME, 'file_chooser_initial_path'),
        (APP_STATE_SECTION_NAME, 'file_chooser_paths'),
    }

Hint

you don’t need to override _init_default_user_cfg_vars() if your app is embedding the ae portion ae.kivy_sideloading.

Classes

FileChooserPathSelectPopup(**kwargs)	file chooser path selector dropdown.
FileChooserPopup(**kwargs)	file chooser DropDown container.

class FileChooserPopup(**kwargs)

Bases: FlowDropDown

file chooser DropDown container.

initial_path

initial file path displayed on opening

submit_to

callable or string to identify which action/part requested the selected file

filters

see kivy.uix.filechooser.FileChooser.filters.

static on_file_chooser_entry_added(view_entries)

on_entry_added/on_subentry_to_entry event handler to patch theme-related properties of Kivy FileChooser.

Parameters:

view_entries (List[Widget]) – list of view entries for a node (icon or label) of the file chooser.

Note

this method gets called for each node when a file entry widget (FileListEntry or FileIconEntry) gets added to an instance of Kivy’s FileChooser widget class.

therefore, the patches done here are not affected if the user preferences (e.g., the font size or light/dark theme) get changed while a file chooser instance is displayed. in this case the user has to simply close and reopen/re-instantiate the file chooser to display the nodes with the just changed user preferences.

theme adaption is still missing for the file chooser progress: all font sizes and colors of the currently used FileChooserProgressBase are hard-coded, so a theme-aware progress class has to be implemented (and assigned to the progress_cls property).

static register_file_path(file_path, main_app)

set the folder of the passed file path as the new initial path and add it to path history.

Parameters:

• file_path (str) – file path (mostly the last just selected file) of which the folder will be registered.

• main_app (Any) – main app instance.

class FileChooserPathSelectPopup(**kwargs)

Bases: FlowDropDown

file chooser path selector dropdown.

paths

list of file paths in the path selection dropdown