FileManager#

#

A simple manager for selecting directories and files.

Usage#

path = os.path.expanduser("~")  # path to the directory that will be opened in the file manager
file_manager = MDFileManager(
    exit_manager=self.exit_manager,  # function called when the user reaches directory tree root
    select_path=self.select_path,  # function called when selecting a file/directory
)
file_manager.show(path)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/file-manager.png

Warning

Be careful! To use the ‘/’ path on Android devices, you need special permissions. Therefore, you are likely to get an error.

Or with preview mode:

file_manager = MDFileManager(
    exit_manager=self.exit_manager,
    select_path=self.select_path,
    preview=True,
)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/file-manager-preview.png

Warning

The preview mode is intended only for viewing images and will not display other types of files.

Example#

import os

from kivy.core.window import Window
from kivy.lang import Builder
from kivy.metrics import dp

from kivymd.app import MDApp
from kivymd.uix.filemanager import MDFileManager
from kivymd.uix.snackbar import MDSnackbar, MDSnackbarText

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDButton:
        pos_hint: {"center_x": .5, "center_y": .5}
        on_release: app.file_manager_open()

        MDButtonText:
            text: "Open manager"
'''


class Example(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        Window.bind(on_keyboard=self.events)
        self.manager_open = False
        self.file_manager = MDFileManager(
            exit_manager=self.exit_manager, select_path=self.select_path
        )

    def build(self):
        self.theme_cls.theme_style = "Dark"
        return Builder.load_string(KV)

    def file_manager_open(self):
        self.file_manager.show(
            os.path.expanduser("~"))  # output manager to the screen
        self.manager_open = True

    def select_path(self, path: str):
        '''
        It will be called when you click on the file name
        or the catalog selection button.

        :param path: path to the selected directory or file;
        '''

        self.exit_manager()
        MDSnackbar(
            MDSnackbarText(
                text=path,
            ),
            y=dp(24),
            pos_hint={"center_x": 0.5},
            size_hint_x=0.8,
        ).open()

    def exit_manager(self, *args):
        '''Called when the user reaches the root of the directory tree.'''

        self.manager_open = False
        self.file_manager.close()

    def events(self, instance, keyboard, keycode, text, modifiers):
        '''Called when buttons are pressed on the mobile device.'''

        if keyboard in (1001, 27):
            if self.manager_open:
                self.file_manager.back()
        return True


Example().run()

New in version 1.0.0.

Added a feature that allows you to show the available disks first, then the files contained in them. Works correctly on: Windows, Linux, OSX, Android. Not tested on iOS.

def file_manager_open(self):
    self.file_manager.show_disks()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/file-manager-show-disks.png

API - kivymd.uix.filemanager.filemanager#

class kivymd.uix.filemanager.filemanager.MDFileManager(*args, **kwargs)#

Implements a modal dialog with a file manager.

For more information, see in the ThemableBehavior and RelativeLayout classes documentation.

Events:
on_pre_open:

Called before the MDFileManager is opened.

on_open:

Called when the MDFileManager is opened.

on_pre_dismiss:

Called before the MDFileManager is closed.

on_dismiss:

Called when the MDFileManager is closed.

icon#

Icon that will be used on the directory selection button.

Deprecated since version 1.1.0: Use icon_selection_button instead.

icon is an StringProperty and defaults to check.

icon_selection_button#

Icon that will be used on the directory selection button.

New in version 1.1.0.

MDFileManager(
    ...
    icon_selection_button="pencil",
)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/file-manager-icon-selection-button.png

icon_selection_button is an StringProperty and defaults to check.

background_color_selection_button#

Background color in (r, g, b, a) or string format of the current directory/path selection button.

New in version 1.1.0.

MDFileManager(
    ...
    background_color_selection_button="brown",
)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/file-manager-background-color-selection-button.png

background_color_selection_button is an ColorProperty and defaults to None.

background_color_toolbar#

Background color in (r, g, b, a) or string format of the file manager toolbar.

New in version 1.1.0.

MDFileManager(
    ...
    background_color_toolbar="brown",
)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/file-manager-background-color-toolbar.png

background_color_toolbar is an ColorProperty and defaults to None.

icon_folder#

Icon that will be used for folder icons when using preview = True.

MDFileManager(
    ...
    preview=True,
    icon_folder="path/to/icon.png",
)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/file-manager-icon-folder.png

icon is an StringProperty and defaults to check.

icon_color#

Color in (r, g, b, a) or string format of the folder icon when the preview property is set to False.

New in version 1.1.0.

MDFileManager(
    ...
    preview=False,
    icon_color="brown",
)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/file-manager-icon-color.png

icon_color is an ColorProperty and defaults to None.

exit_manager#

Function called when the user reaches directory tree root.

exit_manager is an ObjectProperty and defaults to lambda x: None.

select_path#

Function, called when selecting a file/directory.

select_path is an ObjectProperty and defaults to lambda x: None.

ext#

List of file extensions to be displayed in the manager. For example, [‘.py’, ‘.kv’] - will filter out all files, except python scripts and Kv Language.

ext is an ListProperty and defaults to [].

search#

It can take the values ‘all’ ‘dirs’ ‘files’ - display only directories or only files or both them. By default, it displays folders, and files. Available options are: ‘all’, ‘dirs’, ‘files’.

search is an OptionProperty and defaults to all.

current_path#

Current directory.

current_path is an StringProperty and defaults to os.path.expanduser(“~”).

use_access#

Show access to files and directories.

use_access is an BooleanProperty and defaults to True.

preview#

Shows only image previews.

preview is an BooleanProperty and defaults to False.

show_hidden_files#

Shows hidden files.

show_hidden_files is an BooleanProperty and defaults to False.

sort_by#

It can take the values ‘nothing’ ‘name’ ‘date’ ‘size’ ‘type’ - sorts files by option. By default, sort by name. Available options are: ‘nothing’, ‘name’, ‘date’, ‘size’, ‘type’.

sort_by is an OptionProperty and defaults to name.

sort_by_desc#

Sort by descending.

sort_by_desc is an BooleanProperty and defaults to False.

selector#

It can take the values ‘any’ ‘file’ ‘folder’ ‘multi’ By default, any. Available options are: ‘any’, ‘file’, ‘folder’, ‘multi’.

selector is an OptionProperty and defaults to any.

selection#

Contains the list of files that are currently selected.

selection is a read-only ListProperty and defaults to [].

selection_button#

The instance of the directory/path selection button.

New in version 1.1.0.

selection_button is a read-only ObjectProperty and defaults to None.

show_disks() None#
show(path: str) None#

Forms the body of a directory tree.

Parameters:

path – The path to the directory that will be opened in the file manager.

get_access_string(path: str) str#
get_content() Tuple[List[str], List[str]] | Tuple[None, None]#

Returns a list of the type [[Folder List], [file list]].

close() None#

Closes the file manager window.

select_dir_or_file(path: str, widget: MDFileManagerItemPreview | MDFileManagerItem) None#

Called by tap on the name of the directory or file.

back() None#

Returning to the branch down in the directory tree.

select_directory_on_press_button(*args) None#

Called when a click on a floating button.

on_icon(instance_file_manager, icon_name: str) None#

Called when the icon property is changed.

on_background_color_toolbar(instance_file_manager, color: str | list) None#

Called when the background_color_toolbar property is changed.

on_pre_open(*args) None#

Default pre-open event handler.

New in version 1.1.0.

on_open(*args) None#

Default open event handler.

New in version 1.1.0.

on_pre_dismiss(*args) None#

Default pre-dismiss event handler.

New in version 1.1.0.

on_dismiss(*args) None#

Default dismiss event handler.

New in version 1.1.0.