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)

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,
)

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 kivymd.app import MDApp
from kivymd.uix.filemanager import MDFileManager
from kivymd.toast import toast


KV = '''
MDBoxLayout:
    orientation: "vertical"

    MDTopAppBar:
        title: "MDFileManager"
        left_action_items: [["menu", lambda x: None]]
        elevation: 3

    MDFloatLayout:

        MDRoundFlatIconButton:
            text: "Open manager"
            icon: "folder"
            pos_hint: {"center_x": .5, "center_y": .5}
            on_release: app.file_manager_open()
'''


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"
        self.theme_cls.primary_palette = "Orange"
        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()
        toast(path)

    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()

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 MDRelativeLayout class 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",
)

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",
)

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",
)

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",
)

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",
)

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(self)

show(self, path: str)

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(self, path: str)

get_content(self)

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

close(self)

Closes the file manager window.

select_dir_or_file(self, path: str, widget: BodyManagerWithPreview | Factory.BodyManager)

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

back(self)

Returning to the branch down in the directory tree.

select_directory_on_press_button(self, *args)

Called when a click on a floating button.

on_icon(self, instance_file_manager, icon_name: str)

Called when the icon property is changed.

on_background_color_toolbar(self, instance_file_manager, color: str | list)

Called when the background_color_toolbar property is changed.

on_pre_open(self, *args)

Default pre-open event handler.

New in version 1.1.0.

on_open(self, *args)

Default open event handler.

New in version 1.1.0.

on_pre_dismiss(self, *args)

Default pre-dismiss event handler.

New in version 1.1.0.

on_dismiss(self, *args)

Default dismiss event handler.

New in version 1.1.0.