FileChooser¶

The FileChooser module provides various classes for describing, displaying and browsing file systems.

Simple widgets¶

There are two ready-to-use widgets that provide views of the file system. Each of these present the files and folders in a different style.

The FileChooserListView displays file entries as text items in a vertical list, where folders can be collapsed and expanded.

The FileChooserIconView presents icons and text from left to right, wrapping them as required.

They both provide for scrolling, selection and basic user interaction. Please refer to the FileChooserController for details on supported events and properties.

Widget composition¶

FileChooser classes adopt a MVC design. They are exposed so that you to extend and customize your file chooser according to your needs.

The FileChooser classes can be categorized as follows:

Models are represented by concrete implementations of the FileSystemAbstract class, such as the FileSystemLocal.
Views are represented by the FileChooserListLayout and FileChooserIconLayout classes. These are used by the FileChooserListView and FileChooserIconView widgets respectively.
Controllers are represented by concrete implementations of the FileChooserController, namely the FileChooser, FileChooserIconView and FileChooserListView classes.

This means you can define your own views or provide FileSystemAbstract implementations for alternative file systems for use with these widgets. The FileChooser can be used as a controller for handling multiple, synchronized views of the same path. By combining these elements, you can add your own views and file systems and have them easily interact with the existing components.

Usage example¶

main.py

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)

バージョン 1.0.5 で追加.

バージョン 1.2.0 で変更: In the chooser template, the controller is no longer a direct reference but a weak-reference. If you are upgrading, you should change the notation root.controller.xxx to root.controller().xxx.

class kivy.uix.filechooser.FileChooserListView(**kwargs)[ソース]¶

ベースクラス: kivy.uix.filechooser.FileChooserController

Implementation of a FileChooserController using a list view.

バージョン 1.9.0 で追加.

class kivy.uix.filechooser.FileChooserIconView(**kwargs)[ソース]¶

ベースクラス: kivy.uix.filechooser.FileChooserController

Implementation of a FileChooserController using an icon view.

バージョン 1.9.0 で追加.

class kivy.uix.filechooser.FileChooserListLayout(**kwargs)[ソース]¶

ベースクラス: kivy.uix.filechooser.FileChooserLayout

File chooser layout using a list view.

バージョン 1.9.0 で追加.

class kivy.uix.filechooser.FileChooserIconLayout(**kwargs)[ソース]¶

ベースクラス: kivy.uix.filechooser.FileChooserLayout

File chooser layout using an icon view.

バージョン 1.9.0 で追加.

class kivy.uix.filechooser.FileChooser(**kwargs)[ソース]¶

ベースクラス: kivy.uix.filechooser.FileChooserController

Implementation of a FileChooserController which supports switching between multiple, synced layout views.

The FileChooser can be used as follows:

BoxLayout:
    orientation: 'vertical'

    BoxLayout:
        size_hint_y: None
        height: sp(52)

        Button:
            text: 'Icon View'
            on_press: fc.view_mode = 'icon'
        Button:
            text: 'List View'
            on_press: fc.view_mode = 'list'

    FileChooser:
        id: fc
        FileChooserIconLayout
        FileChooserListLayout

バージョン 1.9.0 で追加.

manager¶

Reference to the ScreenManager instance.

manager is an ObjectProperty.

view_list¶

List of views added to this FileChooser.

view_list is an AliasProperty of type list.

view_mode¶

Current layout view mode.

view_mode is an AliasProperty of type str.

class kivy.uix.filechooser.FileChooserController(**kwargs)[ソース]¶

ベースクラス: kivy.uix.relativelayout.RelativeLayout

Base for implementing a FileChooser. Don’t use this class directly, but prefer using an implementation such as the FileChooser, FileChooserListView or FileChooserIconView.

Events:

on_entry_added: entry, parent: Fired when a root-level entry is added to the file list. If you return True from this event, the entry is not added to FileChooser.
on_entries_cleared: Fired when the the entries list is cleared, usually when the root is refreshed.
on_subentry_to_entry: entry, parent: Fired when a sub-entry is added to an existing entry or when entries are removed from an entry e.g. 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.

バージョン 1.2.0 で追加.

dirselect¶

Determines whether directories are valid selections or not.

dirselect is a BooleanProperty and defaults to False.

バージョン 1.1.0 で追加.

entry_released(entry, touch)[ソース]¶: (internal) This method must be called by the template when an entry is touched by the user.

バージョン 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 non-ascii 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.

file_encodings is a ListProperty and defaults to [‘utf-8’, ‘latin1’, ‘cp1252’].

バージョン 1.3.0 で追加.

バージョン 1.8.0 で撤廃: This property is no longer used as the filechooser no longer decodes the file names.

file_system¶

The file system object used to access the file system. This should be a subclass of FileSystemAbstract.

file_system is an ObjectProperty and defaults to FileSystemLocal()

バージョン 1.8.0 で追加.

files¶

The list of files in the directory specified by path after applying the filters.

files is a read-only ListProperty.

filter_dirs¶: Indicates whether filters should also apply to directories. filter_dirs is a BooleanProperty and defaults to False.

filters¶

filters specifies the filters to be applied to the files in the directory. filters is a ListProperty and defaults to []. This is equivalent to ‘*’ i.e. nothing is filtered.

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

There are two kinds of filters: patterns and callbacks.

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
Callbacks

You can specify a function that will be called for each file. The callback will be passed the folder and file name as the first and second parameters respectively. It should return True to indicate a match and False otherwise.

バージョン 1.4.0 で変更: Added the option to specify the filter as a callback.

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

layout¶

Reference to the layout widget instance.

layout is an ObjectProperty.

バージョン 1.9.0 で追加.

multiselect¶

Determines whether the user is able to select multiple files or not.

multiselect is a BooleanProperty and defaults to False.

path¶: path is a StringProperty and defaults to the current working directory as a unicode string. It specifies the path on the filesystem that this controller should refer to.

警告

If a unicode path is specified, all the files returned will be in unicode, allowing the display of unicode files and paths. If a bytes path is specified, only files and paths with ascii names will be displayed properly: non-ascii filenames will be displayed and listed with questions marks (?) instead of their unicode characters.

progress_cls¶

Class to use for displaying a progress indicator for filechooser loading.

progress_cls is an ObjectProperty and defaults to FileChooserProgress.

バージョン 1.2.0 で追加.

バージョン 1.8.0 で変更: If set to a string, the Factory will be used to resolve the class name.

rootpath¶

Root path to use instead of the system root path. If set, it will not show a ”..” directory to go up to 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.

rootpath is a StringProperty and defaults to None.

バージョン 1.2.0 で追加.

注釈

Similarly to path, whether rootpath is specified as bytes or a unicode string determines the type of the filenames and paths read.

selection¶

Contains the list of files that are currently selected.

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

show_hidden¶

Determines whether hidden files and folders should be shown.

show_hidden is a BooleanProperty and defaults to False.

sort_func¶

Provides a function to be called with a list of filenames as the first argument and the filesystem implementation as the second argument. It returns a list of filenames sorted for display in the view.

sort_func is an ObjectProperty and defaults to a function returning alphanumerically named folders first.

バージョン 1.8.0 で変更: The signature needs now 2 arguments: first the list of files, second the filesystem class to use.

class kivy.uix.filechooser.FileChooserProgressBase(**kwargs)[ソース]¶

ベースクラス: 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.

バージョン 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.

class kivy.uix.filechooser.FileSystemAbstract[ソース]¶

ベースクラス: builtins.object

Class for implementing a File System view that can be used with the FileChooser.

バージョン 1.8.0 で追加.

getsize(fn)[ソース]¶: Return the size in bytes of a file

is_dir(fn)[ソース]¶: Return True if the argument passed to this method is a directory

is_hidden(fn)[ソース]¶: Return True if the file is hidden

listdir(fn)[ソース]¶: Return the list of files in the directory fn

class kivy.uix.filechooser.FileSystemLocal[ソース]¶

ベースクラス: kivy.uix.filechooser.FileSystemAbstract

Implementation of FileSystemAbstract for local files.

バージョン 1.8.0 で追加.

« EffectWidget

Float Layout »

Quick search

Table Of Contents

FileChooser¶

Simple widgets¶

Widget composition¶

Usage example¶

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