Rooba
/
kivy
mirror of https://github.com/kivy/kivy.git
1
1
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: revisions to uix/dropdown.py

This commit is contained in:
Richard Larkin 2013-09-15 11:29:35 +02:00
parent e844ae3282
commit 38c5defbcc
1 changed files with 35 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
kivy/uix/dropdown.py
View File

@ -4,9 +4,10 @@ Drop-Down List
.. versionadded:: 1.4.0 .. versionadded:: 1.4.0
A versatile drop-down list, that can be used with custom widget. It allow you to A versatile drop-down list that can be used with custom widgets. It allows you
display a list of widgets under a displayed widget. Unlike others toolkits, the to display a list of widgets under a displayed widget. Unlike others toolkits,
list of widgets is what you want, it can be simple button, or images etc. the list of widgets can can contain any type of widget: simple buttons,
images etc.
The positioning of the drop-down list is fully automatic: we will always try to The positioning of the drop-down list is fully automatic: we will always try to
place the dropdown list in a way that the user can select an item in the list. place the dropdown list in a way that the user can select an item in the list.
@ -14,9 +15,10 @@ place the dropdown list in a way that the user can select an item in the list.
Basic example Basic example
------------- -------------
A button with a dropdown list of 10 possibles values. All the button within the A button with a dropdown list of 10 possibles values. All the buttons within the
dropdown list will trigger the dropdown :meth:`DropDown.select` method. And dropdown list will trigger the dropdown :meth:`DropDown.select` method. After
then, the main button text will display the selection of the dropdown. :: being called, the main button text will display the selection of the
dropdown. ::
from kivy.uix.dropdown import DropDown from kivy.uix.dropdown import DropDown
from kivy.uix.button import Button from kivy.uix.button import Button
@ -38,20 +40,20 @@ then, the main button text will display the selection of the dropdown. ::
mainbutton = Button(text='Hello', size_hint=(None, None)) mainbutton = Button(text='Hello', size_hint=(None, None))
# show the dropdown menu when the main button is released # show the dropdown menu when the main button is released
# note: all the bind() always pass the instance of the caller (here, the # note: all the bind() calls pass the instance of the caller (here, the
# mainbutton instance) as first argument of the callback (here, # mainbutton instance) as the first argument of the callback (here,
# dropdown.open.). # dropdown.open.).
mainbutton.bind(on_release=dropdown.open) mainbutton.bind(on_release=dropdown.open)
# one last thing, listen to the selection done in the dropdown list. # one last thing, listen for the selection in the dropdown list and
# Assign the data to the button text. # assign the data to the button text.
dropdown.bind(on_select=lambda instance, x: setattr(mainbutton, 'text', x)) dropdown.bind(on_select=lambda instance, x: setattr(mainbutton, 'text', x))
Extending dropdown in Kv Extending dropdown in Kv
------------------------ ------------------------
You could create a dropdown directly from kv:: You could create a dropdown directly from your kv::
#:kivy 1.4.0 #:kivy 1.4.0
<CustomDropDown>: <CustomDropDown>:
@ -70,7 +72,7 @@ You could create a dropdown directly from kv::
height: 44 height: 44
on_release: root.select('item2') on_release: root.select('item2')
And then, create the associated python class, and use it:: And then, create the associated python class and use it::
class CustomDropDown(DropDown): class CustomDropDown(DropDown):
pass pass
@ -112,13 +114,13 @@ class DropDown(ScrollView):
:Events: :Events:
`on_select`: data `on_select`: data
Fired when a selection is done, with the data of the selection as Fired when a selection is done. The data of the selection is passed
first argument. Data is what you pass in the :meth:`select` method in as the first argument and is what you pass in the :meth:`select`
as first argument. method as the first argument.
`on_dismiss`: `on_dismiss`:
.. versionadded:: 1.8.0 .. versionadded:: 1.8.0
Fired when the DropDown is dismissed either on selection or on Fired when the DropDown is dismissed, either on selection or on
touching outside the widget. touching outside the widget.
''' '''
@ -129,32 +131,32 @@ class DropDown(ScrollView):
max_height = NumericProperty(None, allownone=True) max_height = NumericProperty(None, allownone=True)
'''Indicate the maximum height that the dropdown can take. If None, it will '''Indicate the maximum height that the dropdown can take. If None, it will
take the maximum height available, until the top or bottom of the screen take the maximum height available until the top or bottom of the screen
will be reached. is reached.
:data:`max_height` is a :class:`~kivy.properties.NumericProperty`, default :data:`max_height` is a :class:`~kivy.properties.NumericProperty` and
to None. defaults to None.
''' '''
dismiss_on_select = BooleanProperty(True) dismiss_on_select = BooleanProperty(True)
'''By default, the dropdown will be automatically dismissed when a selection '''By default, the dropdown will be automatically dismissed when a selection
have been done. Set to False to prevent the dismiss. has been done. Set to False to prevent the dismiss.
:data:`dismiss_on_select` is a :class:`~kivy.properties.BooleanProperty`, :data:`dismiss_on_select` is a :class:`~kivy.properties.BooleanProperty`
default to True. and defaults to True.
''' '''
attach_to = ObjectProperty(allownone=True) attach_to = ObjectProperty(allownone=True)
'''(internal) Property that will be set to the widget on which the drop down '''(internal) Property that will be set to the widget to which the drop down
list is attached to. list is attached.
The method :meth:`open` will automatically set that property, while The :meth:`open` method will automatically set this property whilst
:meth:`dismiss` will set back to None. :meth:`dismiss` will set it back to None.
''' '''
container = ObjectProperty() container = ObjectProperty()
'''(internal) Property that will be set to the container of the dropdown '''(internal) Property that will be set to the container of the dropdown
list, which is a :class:`~kivy.uix.gridlayout.GridLayout` by default. list. It is a :class:`~kivy.uix.gridlayout.GridLayout` by default.
''' '''
__events__ = ('on_select', 'on_dismiss') __events__ = ('on_select', 'on_dismiss')
@ -168,9 +170,9 @@ class DropDown(ScrollView):
self.container.bind(minimum_size=self._container_minimum_size) self.container.bind(minimum_size=self._container_minimum_size)
def open(self, widget): def open(self, widget):
'''Open the dropdown list, and attach to a specific widget. '''Open the dropdown list and attach it to a specific widget.
Depending the position of the widget on the window and the height of the Depending on the position of the widget within the window and the height
dropdown, the placement might be lower or higher off that widget. of the dropdown, the dropdown might be above or below that widget.
''' '''
# ensure we are not already attached # ensure we are not already attached
if self.attach_to is not None: if self.attach_to is not None:
@ -191,7 +193,7 @@ class DropDown(ScrollView):
self._win.add_widget(self) self._win.add_widget(self)
def dismiss(self, *largs): def dismiss(self, *largs):
'''Remove the dropdown widget from the iwndow, and detach itself from '''Remove the dropdown widget from the window and detach it from
the attached widget. the attached widget.
''' '''
if self.parent: if self.parent:
@ -205,7 +207,7 @@ class DropDown(ScrollView):
pass pass
def select(self, data): def select(self, data):
'''Call this method to trigger the `on_select` event, with the `data` '''Call this method to trigger the `on_select` event with the `data`
selection. The `data` can be anything you want. selection. The `data` can be anything you want.
''' '''
self.dispatch('on_select', data) self.dispatch('on_select', data)