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)

New in version 1.0.5.

Changed in version 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.FileChooser(**kwargs)¶

Bases: 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

New in version 1.9.0.

add_widget(widget, *args, **kwargs)¶

Add a new widget as a child of this widget.

Parameters:

widget: Widget
Widget to add to our list of children.

index: int, defaults to 0
Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.

New in version 1.0.5.

canvas: str, defaults to None
Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.

New in version 1.9.0.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)

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

Bases: 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 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.

New in version 1.2.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.

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

on_touch_down(touch)¶

Receive a touch down event.

Parameters:

touch: MotionEvent class: Touch received. The touch is in parent coordinates. See relativelayout for a discussion on coordinate systems.

Returns:

bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.

on_touch_up(touch)¶

Receive a touch up event. The touch is in parent coordinates.

See on_touch_down() for more information.

class kivy.uix.filechooser.FileChooserIconLayout(**kwargs)¶

Bases: kivy.uix.filechooser.FileChooserLayout

File chooser layout using an icon view.

New in version 1.9.0.

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

Bases: kivy.uix.filechooser.FileChooserController

Implementation of a FileChooserController using an icon view.

New in version 1.9.0.

class kivy.uix.filechooser.FileChooserListLayout(**kwargs)¶

Bases: kivy.uix.filechooser.FileChooserLayout

File chooser layout using a list view.

New in version 1.9.0.

class kivy.uix.filechooser.FileChooserListView(**kwargs)¶

Bases: kivy.uix.filechooser.FileChooserController

Implementation of a FileChooserController using a list view.

New in version 1.9.0.

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.

on_touch_down(touch)¶

Receive a touch down event.

Parameters:

touch: MotionEvent class: Touch received. The touch is in parent coordinates. See relativelayout for a discussion on coordinate systems.

Returns:

bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.

on_touch_move(touch)¶

Receive a touch move event. The touch is in parent coordinates.

See on_touch_down() for more information.

on_touch_up(touch)¶

Receive a touch up event. The touch is in parent coordinates.

See on_touch_down() for more information.

class kivy.uix.filechooser.FileSystemAbstract¶

Bases: builtins.object

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

New in version 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¶

Bases: kivy.uix.filechooser.FileSystemAbstract

Implementation of FileSystemAbstract for local files.

New in version 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

« EffectWidget

Float Layout »

Version

Quick search

Table Of Contents

FileChooser¶

Simple widgets¶

Widget composition¶

Usage example¶