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 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 just selected file and the FileChooser
dropdown widget instance an and can be declared like:
def submit_to_callable(file_path: str, chooser_popup: Widget):
Passing a string to submit_to (or if it get 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
|
file chooser path selector dropdown. |
|
file chooser drop down container. |
- class FileChooserPopup(**kwargs)[source]
Bases:
FlowDropDown
file chooser drop down 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)[source]
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 get called for each node in the moment 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 theprogress_cls
property).
- static register_file_path(file_path, main_app)[source]
set folder of the passed file path as new initial path and add it to path history.
- _container: Widget
- _layout_finished: bool
- _opened_item: Optional[Widget]
- _touch_moved_outside: bool