mirror of https://github.com/kivy/kivy.git
doc: revisions to uix/dropdown.py
This commit is contained in:
Richard Larkin
parent
e844ae3282
commit
38c5defbcc
|
|
@ -4,9 +4,10 @@ Drop-Down List
|
|||
|
||||
.. versionadded:: 1.4.0
|
||||
|
||||
A versatile drop-down list, that can be used with custom widget. It allow you to
|
||||
display a list of widgets under a displayed widget. Unlike others toolkits, the
|
||||
list of widgets is what you want, it can be simple button, or images etc.
|
||||
A versatile drop-down list that can be used with custom widgets. It allows you
|
||||
to display a list of widgets under a displayed widget. Unlike others toolkits,
|
||||
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
|
||||
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
|
||||
-------------
|
||||
|
||||
A button with a dropdown list of 10 possibles values. All the button within the
|
||||
dropdown list will trigger the dropdown :meth:`DropDown.select` method. And
|
||||
then, the main button text will display the selection of the dropdown. ::
|
||||
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. After
|
||||
being called, the main button text will display the selection of the
|
||||
dropdown. ::
|
||||
|
||||
from kivy.uix.dropdown import DropDown
|
||||
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))
|
||||
|
||||
# show the dropdown menu when the main button is released
|
||||
# note: all the bind() always pass the instance of the caller (here, the
|
||||
# mainbutton instance) as first argument of the callback (here,
|
||||
# note: all the bind() calls pass the instance of the caller (here, the
|
||||
# mainbutton instance) as the first argument of the callback (here,
|
||||
# dropdown.open.).
|
||||
mainbutton.bind(on_release=dropdown.open)
|
||||
|
||||
# one last thing, listen to the selection done in the dropdown list.
|
||||
# Assign the data to the button text.
|
||||
# one last thing, listen for the selection in the dropdown list and
|
||||
# assign the data to the button text.
|
||||
dropdown.bind(on_select=lambda instance, x: setattr(mainbutton, 'text', x))
|
||||
|
||||
|
||||
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
|
||||
<CustomDropDown>:
|
||||
|
|
@ -70,7 +72,7 @@ You could create a dropdown directly from kv::
|
|||
height: 44
|
||||
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):
|
||||
pass
|
||||
|
|
@ -112,13 +114,13 @@ class DropDown(ScrollView):
|
|||
|
||||
:Events:
|
||||
`on_select`: data
|
||||
Fired when a selection is done, with the data of the selection as
|
||||
first argument. Data is what you pass in the :meth:`select` method
|
||||
as first argument.
|
||||
Fired when a selection is done. The data of the selection is passed
|
||||
in as the first argument and is what you pass in the :meth:`select`
|
||||
method as the first argument.
|
||||
`on_dismiss`:
|
||||
.. 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.
|
||||
'''
|
||||
|
||||
|
|
@ -129,32 +131,32 @@ class DropDown(ScrollView):
|
|||
|
||||
max_height = NumericProperty(None, allownone=True)
|
||||
'''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
|
||||
will be reached.
|
||||
take the maximum height available until the top or bottom of the screen
|
||||
is reached.
|
||||
|
||||
:data:`max_height` is a :class:`~kivy.properties.NumericProperty`, default
|
||||
to None.
|
||||
:data:`max_height` is a :class:`~kivy.properties.NumericProperty` and
|
||||
defaults to None.
|
||||
'''
|
||||
|
||||
dismiss_on_select = BooleanProperty(True)
|
||||
'''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`,
|
||||
default to True.
|
||||
:data:`dismiss_on_select` is a :class:`~kivy.properties.BooleanProperty`
|
||||
and defaults to True.
|
||||
'''
|
||||
|
||||
attach_to = ObjectProperty(allownone=True)
|
||||
'''(internal) Property that will be set to the widget on which the drop down
|
||||
list is attached to.
|
||||
'''(internal) Property that will be set to the widget to which the drop down
|
||||
list is attached.
|
||||
|
||||
The method :meth:`open` will automatically set that property, while
|
||||
:meth:`dismiss` will set back to None.
|
||||
The :meth:`open` method will automatically set this property whilst
|
||||
:meth:`dismiss` will set it back to None.
|
||||
'''
|
||||
|
||||
container = ObjectProperty()
|
||||
'''(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')
|
||||
|
|
@ -168,9 +170,9 @@ class DropDown(ScrollView):
|
|||
self.container.bind(minimum_size=self._container_minimum_size)
|
||||
|
||||
def open(self, widget):
|
||||
'''Open the dropdown list, and attach to a specific widget.
|
||||
Depending the position of the widget on the window and the height of the
|
||||
dropdown, the placement might be lower or higher off that widget.
|
||||
'''Open the dropdown list and attach it to a specific widget.
|
||||
Depending on the position of the widget within the window and the height
|
||||
of the dropdown, the dropdown might be above or below that widget.
|
||||
'''
|
||||
# ensure we are not already attached
|
||||
if self.attach_to is not None:
|
||||
|
|
@ -191,7 +193,7 @@ class DropDown(ScrollView):
|
|||
self._win.add_widget(self)
|
||||
|
||||
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.
|
||||
'''
|
||||
if self.parent:
|
||||
|
|
@ -205,7 +207,7 @@ class DropDown(ScrollView):
|
|||
pass
|
||||
|
||||
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.
|
||||
'''
|
||||
self.dispatch('on_select', data)
|
||||
|
|
|
|||
Loading…
Reference in New Issue