Quick search

Table Of Contents

Source code for kivy.uix.spinner

'''
Spinner
=======

.. versionadded:: 1.4.0

.. image:: images/spinner.jpg
    :align: right

Spinner is a widget that provide a quick way to select one value from a set. In
the default state, a spinner show its currently selected value. Touching the
spinner displays a dropdown menu with all other available values from which the
user can select a new one.

Example::

    from kivy.base import runTouchApp
    from kivy.uix.spinner import Spinner

    spinner = Spinner(
        # default value showed
        text='Home',
        # available values
        values=('Home', 'Work', 'Other', 'Custom'),
        # just for positioning in our example
        size_hint=(None, None),
        size=(100, 44),
        pos_hint={'center_x': .5, 'center_y': .5})

    def show_selected_value(spinner, text):
        print('The spinner', spinner, 'have text', text)

    spinner.bind(text=show_selected_value)

    runTouchApp(spinner)

'''

__all__ = ('Spinner', 'SpinnerOption')

from kivy.compat import string_types
from kivy.factory import Factory
from kivy.properties import ListProperty, ObjectProperty, BooleanProperty
from kivy.uix.button import Button
from kivy.uix.dropdown import DropDown


[docs]class SpinnerOption(Button): '''Special button used in the dropdown list. We just set the default size_hint_y and height. ''' pass
[docs]class Spinner(Button): '''Spinner class, see module documentation for more information. ''' values = ListProperty() '''Values that can be selected by the user. It must be a list of strings. :attr:`values` is a :class:`~kivy.properties.ListProperty` and defaults to []. ''' option_cls = ObjectProperty(SpinnerOption) '''Class used to display the options within the dropdown list displayed under the Spinner. The `text` property of the class will be used to represent the value. The option class requires at least: - a `text` property, used to display the value. - an `on_release` event, used to trigger the option when pressed/touched. :attr:`option_cls` is an :class:`~kivy.properties.ObjectProperty` and defaults to :class:`SpinnerOption`. .. versionchanged:: 1.8.0 If you set a string, the :class:`~kivy.factory.Factory` will be used to resolve the class. ''' dropdown_cls = ObjectProperty(DropDown) '''Class used to display the dropdown list when the Spinner is pressed. :attr:`dropdown_cls` is an :class:`~kivy.properties.ObjectProperty` and defaults to :class:`~kivy.uix.dropdown.DropDown`. .. versionchanged:: 1.8.0 If you set a string, the :class:`~kivy.factory.Factory` will be used to resolve the class. ''' is_open = BooleanProperty(False) '''By default, the spinner is not open. Set to True to open it. :attr:`is_open` is a :class:`~kivy.properties.BooleanProperty` and defaults to False. .. versionadded:: 1.4.0 ''' def __init__(self, **kwargs): self._dropdown = None super(Spinner, self).__init__(**kwargs) self.bind( on_release=self._toggle_dropdown, dropdown_cls=self._build_dropdown, option_cls=self._build_dropdown, values=self._update_dropdown) self._build_dropdown() def _build_dropdown(self, *largs): if self._dropdown: self._dropdown.unbind(on_select=self._on_dropdown_select) self._dropdown.unbind(on_dismiss=self._toggle_dropdown) self._dropdown.dismiss() self._dropdown = None cls = self.dropdown_cls if isinstance(cls, string_types): cls = Factory.get(cls) self._dropdown = cls() self._dropdown.bind(on_select=self._on_dropdown_select) self._dropdown.bind(on_dismiss=self._toggle_dropdown) self._update_dropdown() def _update_dropdown(self, *largs): dp = self._dropdown cls = self.option_cls if isinstance(cls, string_types): cls = Factory.get(cls) dp.clear_widgets() for value in self.values: item = cls(text=value) item.bind(on_release=lambda option: dp.select(option.text)) dp.add_widget(item) def _toggle_dropdown(self, *largs): self.is_open = not self.is_open def _on_dropdown_select(self, instance, data, *largs): self.text = data self.is_open = False def on_is_open(self, instance, value): if value: self._dropdown.open(self) else: if self._dropdown.attach_to: self._dropdown.dismiss()