Quick search

Table Of Contents

FileChooser

New in version 1.0.5.

Warning

This is experimental and subject to change as long as this warning notice is present.

Changed in version 1.2.0: In chooser template, the controller is not a direct reference anymore, but a weak-reference. You must update all the notation root.controller.xxx to root.controller().xxx.

Simple example

main.py

#!/usr/bin/env python
from kivy.app import App
from kivy.uix.floatlayout import FloatLayout
from kivy.factory import Factory
from kivy.properties import ObjectProperty
from kivy.uix.popup import Popup

import os

class LoadDialog(FloatLayout):
    load = ObjectProperty(None)
    cancel = ObjectProperty(None)


class SaveDialog(FloatLayout):
    save = ObjectProperty(None)
    text_input = ObjectProperty(None)
    cancel = ObjectProperty(None)


class Root(FloatLayout):
    loadfile = ObjectProperty(None)
    savefile = ObjectProperty(None)
    text_input = ObjectProperty(None)

    def dismiss_popup(self):
        self._popup.dismiss()

    def show_load(self):
        content = LoadDialog(load=self.load, cancel=self.dismiss_popup)
        self._popup = Popup(title="Load file", content=content, size_hint=(0.9, 0.9))
        self._popup.open()

    def show_save(self):
        content = SaveDialog(save=self.save, cancel=self.dismiss_popup)
        self._popup = Popup(title="Save file", content=content, size_hint=(0.9, 0.9))
        self._popup.open()

    def load(self, path, filename):
        with open(os.path.join(path, filename[0])) as stream:
            self.text_input.text = stream.read()

        self.dismiss_popup()

    def save(self, path, filename):
        with open(os.path.join(path, filename), 'w') as stream:
            stream.write(self.text_input.text)

        self.dismiss_popup()


class Editor(App):
    pass


Factory.register('Root', cls=Root)
Factory.register('LoadDialog', cls=LoadDialog)
Factory.register('SaveDialog', cls=SaveDialog)

if __name__ == '__main__':
    Editor().run()

editor.kv

#:kivy 1.1.0

Root:
    text_input: text_input

    BoxLayout:
        orientation: 'vertical'
        BoxLayout:
            size_hint_y: None
            height: 30
            Button:
                text: 'Load'
                on_release: root.show_load()
            Button:
                text: 'Save'
                on_release: root.show_save()

        BoxLayout:
            TextInput:
                id: text_input
                text: ''

            RstDocument:
                text: text_input.text
                show_errors: True

<LoadDialog>:
    BoxLayout:
        size: root.size
        pos: root.pos
        orientation: "vertical"
        FileChooserListView:
            id: filechooser

        BoxLayout:
            size_hint_y: None
            height: 30
            Button:
                text: "Cancel"
                on_release: root.cancel()

            Button:
                text: "Load"
                on_release: root.load(filechooser.path, filechooser.selection)

<SaveDialog>:
    text_input: text_input
    BoxLayout:
        size: root.size
        pos: root.pos
        orientation: "vertical"
        FileChooserListView:
            id: filechooser
            on_selection: text_input.text = self.selection and self.selection[0] or ''

        TextInput:
            id: text_input
            size_hint_y: None
            height: 30
            multiline: False

        BoxLayout:
            size_hint_y: None
            height: 30
            Button:
                text: "Cancel"
                on_release: root.cancel()

            Button:
                text: "Save"
                on_release: root.save(filechooser.path, text_input.text)
class kivy.uix.filechooser.FileChooserListView(**kwargs)

Bases: kivy.uix.filechooser.FileChooserController

Implementation of FileChooserController using a list view.

class kivy.uix.filechooser.FileChooserIconView(**kwargs)

Bases: kivy.uix.filechooser.FileChooserController

Implementation of FileChooserController using an icon view.

class kivy.uix.filechooser.FileChooserController(**kwargs)

Bases: kivy.uix.floatlayout.FloatLayout

Base for implementing a FileChooser. Don’t use that class directly, preferring to use an implementation like FileChooserListView or FileChooserIconView.

Events :
on_entry_added: entry, parent

Fired when a root-level entry is added to the file list.

on_entries_cleared

Fired when the the entries list is cleared. Usally when the root is refreshed.

on_subentry_to_entry: entry, parent

Fired when a sub-entry is added to an existing entry.

on_remove_subentry: entry, parent

Fired when entries are removed from an entry. Usually when a node is closed.

on_submit: selection, touch

Fired when a file has been selected with a double-tap.

cancel(*largs)

Cancel any background action started by filechooser, such as loading a new directory.

New in version 1.2.0.

dirselect

BooleanProperty, defaults to False. Determines whether directories are valid selections.

New in version 1.1.0.

entry_released(entry, touch)

(internal) This method must be called by the template when an entry is touched by the user.

New in version 1.1.0.

entry_touched(entry, touch)

(internal) This method must be called by the template when an entry is touched by the user.

file_encodings

Possible encodings for decoding a filename to unicode. In the case that the user has a weird filename, undecodable without knowing it’s initial encoding, we have no other choice than to guess it.

Please note that if you encounter an issue because of a missing encoding here, we’ll be glad to add it to this list.

New in version 1.3.0.

ListProperty, defaults to [‘utf-8’, ‘latin1’, ‘cp1252’]

files

Read-only ListProperty. The list of files in the directory specified by path after applying the filters.

filter_dirs

BooleanProperty, defaults to False. Indicates whether filters should also apply to directories.

filters

ListProperty, defaults to [], equal to ‘*’. The filters to be applied to the files in the directory.

The filters are not reset when the path changes. You need to do that yourself if desired.

There are two kinds of filters :

filename patterns : e.g. [‘*.png’]. You can use the following patterns:

Pattern Meaning
* matches everything
? matches any single character
[seq] matches any character in seq
[!seq] matches any character not in seq

Changed in version 1.4.0: if the filter is a callable (function or method). It will be called with the path and the file name as arguments for each file in dir. The callable should returns True to indicate a match and False overwise.

get_nice_size(fn)

Pass the filepath. Returns the size in the best human readable format or ‘’ if it is a directory (Don’t recursively calculate size.).

multiselect

BooleanProperty, defaults to False. Determines whether user is able to select multiple files.

path

StringProperty, defaults to current working directory as unicode string. Specifies the path on the filesystem that this controller should refer to.

progress_cls

Class to use for displaying a progress indicator for filechooser loading

New in version 1.2.0.

ObjectProperty, defaults to FileChooserProgress

rootpath

Root path to use, instead of the system root path. If set, it will not show a ”..” directory to go upper the root path. For example, if you set rootpath to /Users/foo, the user will be unable to go to /Users, or to any other directory not starting with /Users/foo.

New in version 1.2.0.

StringProperty, defaults to None.

selection

Read-only ListProperty. The list of files that are currently selected.

show_hidden

BooleanProperty, defaults to False. Determines whether hidden files and folders should be shown.

sort_func

ObjectProperty. Provides a function to be called with a list of filenames as the only argument. Returns a list of filenames sorted for display in the view.

class kivy.uix.filechooser.FileChooserProgressBase(**kwargs)

Bases: kivy.uix.floatlayout.FloatLayout

Base for implementing a progress view. This view is used when too many entries need to be created, and are delayed over multiple frames.

New in version 1.2.0.

cancel(*largs)

Cancel any action from the FileChooserController.

index

Current index of total entries to be loaded.

path

Current path of the FileChooser, read-only.

total

Total number of entries to load.