Kivy.garden.NavigationDrawer

totally copied from github opensource code. Just a translation and ideas with idividuals ideas to share its use for all people using chinese.

Copyright © 2013 Alexander Taylor
开源免责免费使用声明:
#Permission is hereby granted, free of charge, to any person obtaining a copy
#of this software and associated documentation files (the “Software”), to deal
#in the Software without restriction, including without limitation the rights
#to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
#copies of the Software, and to permit persons to whom the Software is

#furnished to do so, subject to the following conditions:

#The above copyright notice and this permission notice shall be included in
#all copies or substantial portions of the Software.
substantial 美/səbˈstænʃ(ə)l/  adj 真实的； 
portion 美/ˈpɔːrʃ(ə)n/ n.（责任、过失、职责等的）一份，一部分；<法律>（根据法律赠与或遗留给继承人的）一份财产；

#THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
#IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
#FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
#AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
#LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
#OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
#THE SOFTWARE.

‘’'NavigationDrawer

The NavigationDrawer widget provides a hidden panel view designed to
duplicate the popular Android layout. The user views one main widget
but can slide from the left of the screen to view a second, previously
hidden widget. The transition between open/closed is smoothly
animated, with the parameters (anim time, panel width, touch
detection) all user configurable. If the panel is released without
being fully open or closed, it animates to an appropriate
configuration.
这NavigationDrawer组件儿提供了一个隐藏的panel view仪表盘视图，这
视图是被设计来复制流行的Android布局的。使用者观看一个主要的组件，
但是可以在一秒内从屏幕的左边滑动到视图，先前地被隐藏的组件。
【就是说咱看着当前一个屏幕呢，可以滑动到另一个之前被隐藏好的组件儿】
这在打开/关闭地滑动转变间是顺畅的动画儿，掺和着一些元素儿（anim time,
动画时间，panel width, 仪表盘宽度，touch detection触发事件）所有的是
使用者可构建的。如果这仪表盘儿被展示没全乎或者没关全乎，（留着一绺子）
，它动画到一个合适的配置。【就说配置可以调】

NavigationDrawer supports many different animation properties,
including moving one or both of the side/main panels, darkening
either/both widgets, changing side panel opacity, and changing which
widget is on top. The user can edit these individually to taste (this
is enough rope to hang oneself, it’s easy to make a useless or silly
configuration!), or use one of a few preset animations.

NavigationDrawer支持许多不同的动画属性，包括移动一个或多个的
幻灯片/主仪表盘，也可也已使这两者变黑1个或多个组件，改变幻灯片
仪表盘透明度，和改变哪个组件在上。使用者可以自己改变这些来尝试
（这是足够的大圈儿来掉某个东西了，也非常简单来制作一个没啥用或
呆板的配置），或使用些许里的一个原开发者已经事先准备好的动画儿。

The hidden panel might normally a set of navigation buttons, but the
implementation lets the user use any widget(s).

隐藏的仪表盘可能主要使一些导航按钮，但执行

The first widget added to the NavigationDrawer is automatically used
as the side panel, and the second widget as the main panel. No further
widgets can be added, further changes are left to the user via editing
the panel widgets.

Usage summary

The first widget added to a NavigationDrawer is used as the hidden
side panel.
The second widget added is used as the main panel.
Both widgets can be removed with remove_widget, or alternatively
set/removed with set_main_panel and set_side_panel.
The hidden side panel can be revealed by dragging from the left of
the NavigationDrawer. The touch detection width is the
touch_accept_width property.
Every animation property is user-editable, or default animations
can be chosen by setting anim_type.

See the example and docstrings for information on individual properties.

Example::

class ExampleApp(App):

def build(self):navigationdrawer = NavigationDrawer()side_panel = BoxLayout(orientation='vertical')side_panel.add_widget(Label(text='Panel label'))side_panel.add_widget(Button(text='A button'))side_panel.add_widget(Button(text='Another button'))navigationdrawer.add_widget(side_panel)label_head = ('[b]Example label filling main panel[/b]\n\n[color=ff0000](p''ull from left to right!)[/color]\n\nIn this example, the le''ft panel is a simple boxlayout menu, and this main panel is'' a BoxLayout with a label and example image.\n\nSeveral pre''set layouts are available (see buttons below), but users ma''y edit every parameter for much more customisation.')main_panel = BoxLayout(orientation='vertical')label_bl = BoxLayout(orientation='horizontal')label = Label(text=label_head, font_size='15sp',markup=True, valign='top')label_bl.add_widget(Widget(size_hint_x=None, width=dp(10)))label_bl.add_widget(label)label_bl.add_widget(Widget(size_hint_x=None, width=dp(10)))main_panel.add_widget(Widget(size_hint_y=None, height=dp(10)))main_panel.add_widget(label_bl)main_panel.add_widget(Widget(size_hint_y=None, height=dp(10)))navigationdrawer.add_widget(main_panel)label.bind(size=label.setter('text_size'))def set_anim_type(name):navigationdrawer.anim_type = namemodes_layout = BoxLayout(orientation='horizontal')modes_layout.add_widget(Label(text='preset\nanims:'))slide_an = Button(text='slide_\nabove_\nanim')slide_an.bind(on_press=lambda j: set_anim_type('slide_above_anim'))slide_sim = Button(text='slide_\nabove_\nsimple')slide_sim.bind(on_press=lambda j: set_anim_type('slide_above_simple'))fade_in_button = Button(text='fade_in')fade_in_button.bind(on_press=lambda j: set_anim_type('fade_in'))reveal_button = Button(text='reveal_\nbelow_\nanim')reveal_button.bind(on_press=lambda j: set_anim_type('reveal_below_anim'))slide_button = Button(text='reveal_\nbelow_\nsimple')slide_button.bind(on_press=lambda j: set_anim_type('reveal_below_simple'))modes_layout.add_widget(slide_an)modes_layout.add_widget(slide_sim)modes_layout.add_widget(fade_in_button)modes_layout.add_widget(reveal_button)modes_layout.add_widget(slide_button)main_panel.add_widget(modes_layout)button = Button(text='toggle NavigationDrawer state (animate)',size_hint_y=0.2)button.bind(on_press=lambda j: navigationdrawer.toggle_state())button2 = Button(text='toggle NavigationDrawer state (jump)',size_hint_y=0.2)button2.bind(on_press=lambda j: navigationdrawer.toggle_state(False))button3 = Button(text='toggle _main_above', size_hint_y=0.2)button3.bind(on_press=navigationdrawer.toggle_main_above)main_panel.add_widget(button)main_panel.add_widget(button2)main_panel.add_widget(button3)return navigationdrawerExampleApp().run()

‘’’

all = (‘NavigationDrawer’, )

from kivy.animation import Animation
from kivy.uix.widget import Widget
from kivy.uix.stencilview import StencilView
from kivy.metrics import dp
from kivy.clock import Clock
from kivy.properties import (ObjectProperty, NumericProperty, OptionProperty,
BooleanProperty, StringProperty)
from kivy.resources import resource_add_path
from kivy.lang import Builder
import os.path

resource_add_path(os.path.dirname(file))

Builder.load_string(‘’’
:
size_hint: (1,1)
_side_panel: sidepanel
_main_panel: mainpanel
_join_image: joinimage
side_panel_width: min(dp(250), 0.5self.width)
BoxLayout:
id: sidepanel
y: root.y
x: root.x -
(1-root._anim_progress)
root.side_panel_init_offset*root.side_panel_width
height: root.height
width: root.side_panel_width
opacity: root.side_panel_opacity +
(1-root.side_panel_opacity)root._anim_progress
canvas:
Color:
rgba: (0,0,0,1)
Rectangle:
pos: self.pos
size: self.size
canvas.after:
Color:
rgba: (0,0,0,(1-root._anim_progress)root.side_panel_darkness)
Rectangle:
size: self.size
pos: self.pos
BoxLayout:
id: mainpanel
x: root.x +
root._anim_progress *
root.side_panel_width *
root.main_panel_final_offset
y: root.y
size: root.size
canvas:
Color:
rgba: (0,0,0,1)
Rectangle:
pos: self.pos
size: self.size
canvas.after:
Color:
rgba: (0,0,0,root._anim_progressroot.main_panel_darkness)
Rectangle:
size: self.size
pos: self.pos
Image:
id: joinimage
opacity: min(sidepanel.opacity, 0 if root._anim_progress < 0.00001
else min(root._anim_progress40,1))
source: root._choose_image(root._main_above, root.separator_image)
mipmap: False
width: root.separator_image_width
height: root._side_panel.height
x: (mainpanel.x - self.width + 1) if root._main_above
else (sidepanel.x + sidepanel.width - 1)
y: root.y
allow_stretch: True
keep_ratio: False
‘’')

class NavigationDrawerException(Exception):
‘’'Raised when add_widget or remove_widget called incorrectly on a
NavigationDrawer.

'''

class NavigationDrawer(StencilView):
‘’'Widget taking two children, a side panel and a main panel,
displaying them in a way that replicates the popular Android
functionality. See module documentation for more info.

'''# Internal references for side, main and image widgets
_side_panel = ObjectProperty()
_main_panel = ObjectProperty()
_join_image = ObjectProperty()side_panel = ObjectProperty(None, allownone=True)
'''Automatically bound to whatever widget is added as the hidden panel.'''
main_panel = ObjectProperty(None, allownone=True)
'''Automatically bound to whatever widget is added as the main panel.'''# Appearance properties
side_panel_width = NumericProperty()
'''The width of the hidden side panel. Defaults to the minimum of
250dp or half the NavigationDrawer width.'''
separator_image = StringProperty('')
'''The path to an image that will be placed between the side and main
panels. If set to `''`, defaults to a gradient from black to
transparent in an appropriate direction (left->right if side panel
above main, right->left if main panel on top).'''
separator_image_width = NumericProperty(dp(10))
'''The width of the separator image. Defaults to 10dp'''# Touch properties
touch_accept_width = NumericProperty('14dp')
'''Distance from the left of the NavigationDrawer in which to grab the
touch and allow revealing of the hidden panel.'''
_touch = ObjectProperty(None, allownone=True)  # The currently active touch# Animation properties
state = OptionProperty('closed', options=('open', 'closed'))
'''Specifies the state of the widget. Must be one of 'open' or
'closed'. Setting its value automatically jumps to the relevant state,
or users may use the anim_to_state() method to animate the
transition.'''

设定动画页面转变所用时间 anim_time

anim_time = NumericProperty(0.3)
'''The time taken for the panel to slide to the open/closed state when
released or manually animated with anim_to_state.'''
min_dist_to_open = NumericProperty(0.7)
'''Must be between 0 and 1. Specifies the fraction of the hidden panel
width beyond which the NavigationDrawer will relax to open state when
released. Defaults to 0.7.'''
_anim_progress = NumericProperty(0)  # Internal state controlling# widget positions
_anim_init_progress = NumericProperty(0)# Animation controls
top_panel = OptionProperty('main', options=['main', 'side'])
'''Denotes which panel should be drawn on top of the other. Must be
one of 'main' or 'side'. Defaults to 'main'.'''
_main_above = BooleanProperty(True)side_panel_init_offset = NumericProperty(0.5)
'''Intial offset (to the left of the widget) of the side panel, in
units of its total width. Opening the panel moves it smoothly to its
final position at the left of the screen.'''side_panel_darkness = NumericProperty(0.8)
'''Controls the fade-to-black of the side panel in its hidden
state. Must be between 0 (no fading) and 1 (fades to totally
black).'''side_panel_opacity = NumericProperty(1)
'''Controls the opacity of the side panel in its hidden state. Must be
between 0 (fade to transparent) and 1 (no transparency)'''main_panel_final_offset = NumericProperty(1)
'''Final offset (to the right of the normal position) of the main
panel, in units of the side panel width.'''main_panel_darkness = NumericProperty(0)
'''Controls the fade-to-black of the main panel when the side panel is
in its hidden state. Must be between 0 (no fading) and 1 (fades to
totally black).
'''opening_transition = StringProperty('out_cubic')
'''The name of the animation transition type to use when animating to
an open state. Defaults to 'out_cubic'.'''closing_transition = StringProperty('in_cubic')
'''The name of the animation transition type to use when animating to
a closed state. Defaults to 'out_cubic'.'''

设定动画转变效果 anim_type

anim_type = OptionProperty('reveal_from_below',options=['slide_above_anim','slide_above_simple','fade_in','reveal_below_anim','reveal_below_simple',])
'''The default animation type to use. Several options are available,
modifying all possibly animation properties including darkness,
opacity, movement and draw height. Users may also (and are
encouaged to) edit these properties individually, for a vastly
larger range of possible animations. Defaults to reveal_below_anim.
'''def __init__(self, **kwargs):super(NavigationDrawer, self).__init__(**kwargs)Clock.schedule_once(self.on__main_above, 0)def on_anim_type(self, *args):anim_type = self.anim_typeif anim_type == 'slide_above_anim':self.top_panel = 'side'self.side_panel_darkness = 0self.side_panel_opacity = 1self.main_panel_final_offset = 0.5self.main_panel_darkness = 0.5self.side_panel_init_offset = 1if anim_type == 'slide_above_simple':self.top_panel = 'side'self.side_panel_darkness = 0self.side_panel_opacity = 1self.main_panel_final_offset = 0self.main_panel_darkness = 0self.side_panel_init_offset = 1elif anim_type == 'fade_in':self.top_panel = 'side'self.side_panel_darkness = 0self.side_panel_opacity = 0self.main_panel_final_offset = 0self.main_panel_darkness = 0self.side_panel_init_offset = 0.5elif anim_type == 'reveal_below_anim':self.top_panel = 'main'self.side_panel_darkness = 0.8self.side_panel_opacity = 1self.main_panel_final_offset = 1self.main_panel_darkness = 0self.side_panel_init_offset = 0.5elif anim_type == 'reveal_below_simple':self.top_panel = 'main'self.side_panel_darkness = 0self.side_panel_opacity = 1self.main_panel_final_offset = 1self.main_panel_darkness = 0self.side_panel_init_offset = 0def on_top_panel(self, *args):if self.top_panel == 'main':self._main_above = Trueelse:self._main_above = Falsedef on__main_above(self, *args):newval = self._main_abovemain_panel = self._main_panelside_panel = self._side_panelself.canvas.remove(main_panel.canvas)self.canvas.remove(side_panel.canvas)if newval:self.canvas.insert(0, main_panel.canvas)self.canvas.insert(0, side_panel.canvas)else:self.canvas.insert(0, side_panel.canvas)self.canvas.insert(0, main_panel.canvas)def toggle_main_above(self, *args):if self._main_above:self._main_above = Falseelse:self._main_above = Truedef add_widget(self, widget):if len(self.children) == 0:super(NavigationDrawer, self).add_widget(widget)self._side_panel = widgetelif len(self.children) == 1:super(NavigationDrawer, self).add_widget(widget)self._main_panel = widgetelif len(self.children) == 2:super(NavigationDrawer, self).add_widget(widget)self._join_image = widgetelif self.side_panel is None:self._side_panel.add_widget(widget)self.side_panel = widgetelif self.main_panel is None:self._main_panel.add_widget(widget)self.main_panel = widgetelse:raise NavigationDrawerException('Can\'t add more than two widgets''directly to NavigationDrawer')def remove_widget(self, widget):if widget is self.side_panel:self._side_panel.remove_widget(widget)self.side_panel = Noneelif widget is self.main_panel:self._main_panel.remove_widget(widget)self.main_panel = Noneelse:raise NavigationDrawerException('Widget is neither the side or main panel, can\'t remove it.')def set_side_panel(self, widget):'''Removes any existing side panel widgets, and replaces them with theargument `widget`.'''# Clear existing side panel entriesif len(self._side_panel.children) > 0:for child in self._side_panel.children:self._side_panel.remove(child)# Set new side panelself._side_panel.add_widget(widget)self.side_panel = widgetdef set_main_panel(self, widget):'''Removes any existing main panel widgets, and replaces them with theargument `widget`.'''# Clear existing side panel entriesif len(self._main_panel.children) > 0:for child in self._main_panel.children:self._main_panel.remove_widget(child)# Set new side panelself._main_panel.add_widget(widget)self.main_panel = widgetdef on__anim_progress(self, *args):if self._anim_progress > 1:self._anim_progress = 1elif self._anim_progress < 0:self._anim_progress = 0if self._anim_progress >= 1:self.state = 'open'elif self._anim_progress <= 0:self.state = 'closed'def on_state(self, *args):Animation.cancel_all(self)if self.state == 'open':self._anim_progress = 1else:self._anim_progress = 0def anim_to_state(self, state):'''If not already in state `state`, animates smoothly to it, takingthe time given by self.anim_time. State may be either 'open'or 'closed'.'''if state == 'open':anim = Animation(_anim_progress=1,duration=self.anim_time,t=self.closing_transition)anim.start(self)elif state == 'closed':anim = Animation(_anim_progress=0,duration=self.anim_time,t=self.opening_transition)anim.start(self)else:raise NavigationDrawerException('Invalid state received, should be one of `open` or `closed`')def toggle_state(self, animate=True):'''Toggles from open to closed or vice versa, optionally animating orsimply jumping.'''if self.state == 'open':if animate:self.anim_to_state('closed')else:self.state = 'closed'elif self.state == 'closed':if animate:self.anim_to_state('open')else:self.state = 'open'def on_touch_down(self, touch):col_self = self.collide_point(*touch.pos)col_side = self._side_panel.collide_point(*touch.pos)col_main = self._main_panel.collide_point(*touch.pos)if self._anim_progress < 0.001:  # i.e. closedvalid_region = (self.x <=touch.x <=(self.x + self.touch_accept_width))if not valid_region:self._main_panel.on_touch_down(touch)return Falseelse:if col_side and not self._main_above:self._side_panel.on_touch_down(touch)return Falsevalid_region = (self._main_panel.x <=touch.x <=(self._main_panel.x + self._main_panel.width))if not valid_region:if self._main_above:if col_main:self._main_panel.on_touch_down(touch)elif col_side:self._side_panel.on_touch_down(touch)else:if col_side:self._side_panel.on_touch_down(touch)elif col_main:self._main_panel.on_touch_down(touch)return FalseAnimation.cancel_all(self)self._anim_init_progress = self._anim_progressself._touch = touchtouch.ud['type'] = self.statetouch.ud['panels_jiggled'] = False  # If user moved panels back# and forth, don't default# to close on touch releasetouch.grab(self)return Truedef on_touch_move(self, touch):if touch is self._touch:dx = touch.x - touch.oxself._anim_progress = max(0, min(self._anim_init_progress +(dx / self.side_panel_width), 1))if self._anim_progress < 0.975:touch.ud['panels_jiggled'] = Trueelse:super(NavigationDrawer, self).on_touch_move(touch)returndef on_touch_up(self, touch):if touch is self._touch:self._touch = Noneinit_state = touch.ud['type']touch.ungrab(self)jiggled = touch.ud['panels_jiggled']if init_state == 'open' and not jiggled:if self._anim_progress >= 0.975:self.anim_to_state('closed')else:self._anim_relax()else:self._anim_relax()else:super(NavigationDrawer, self).on_touch_up(touch)returndef _anim_relax(self):'''Animates to the open or closed position, depending on whether thecurrent position is past self.min_dist_to_open.'''if self._anim_progress > self.min_dist_to_open:self.anim_to_state('open')else:self.anim_to_state('closed')def _choose_image(self, *args):'''Chooses which image to display as the main/side separator, based on_main_above.'''if self.separator_image:return self.separator_imageif self._main_above:return 'navigationdrawer_gradient_rtol.png'else:return 'navigationdrawer_gradient_ltor.png'

if name == ‘main’:
from kivy.base import runTouchApp
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.label import Label
from kivy.uix.button import Button
from kivy.uix.popup import Popup
from kivy.uix.image import Image
from kivy.core.window import Window

navigationdrawer = NavigationDrawer()side_panel = BoxLayout(orientation='vertical')
side_panel.add_widget(Label(text='Panel label'))
popup = Popup(title='Sidebar popup',content=Label(text='You clicked the sidebar\npopup button'),size_hint=(0.7, 0.7))
first_button = Button(text='Popup\nbutton')
first_button.bind(on_release=popup.open)
side_panel.add_widget(first_button)
side_panel.add_widget(Button(text='Another\nbutton'))
navigationdrawer.add_widget(side_panel)label_head = ('[b]Example label filling main panel[/b]\n\n[color=ff0000](p''ull from left to right!)[/color]\n\nIn this example, the le''ft panel is a simple boxlayout menu, and this main panel is'' a BoxLayout with a label and example image.\n\nSeveral pre''set layouts are available (see buttons below), but users ma''y edit every parameter for much more customisation.')
main_panel = BoxLayout(orientation='vertical')
label_bl = BoxLayout(orientation='horizontal')
label = Label(text=label_head, font_size='15sp',markup=True, valign='top')
label_bl.add_widget(Widget(size_hint_x=None, width=dp(10)))
label_bl.add_widget(label)
label_bl.add_widget(Widget(size_hint_x=None, width=dp(10)))
main_panel.add_widget(Widget(size_hint_y=None, height=dp(10)))
main_panel.add_widget(label_bl)
main_panel.add_widget(Widget(size_hint_y=None, height=dp(10)))
navigationdrawer.add_widget(main_panel)
label.bind(size=label.setter('text_size'))def set_anim_type(name):navigationdrawer.anim_type = namedef set_transition(name):navigationdrawer.opening_transition = namenavigationdrawer.closing_transition = namemodes_layout = BoxLayout(orientation='horizontal')
modes_layout.add_widget(Label(text='preset\nanims:'))
slide_an = Button(text='slide_\nabove_\nanim')
slide_an.bind(on_press=lambda j: set_anim_type('slide_above_anim'))
slide_sim = Button(text='slide_\nabove_\nsimple')
slide_sim.bind(on_press=lambda j: set_anim_type('slide_above_simple'))
fade_in_button = Button(text='fade_in')
fade_in_button.bind(on_press=lambda j: set_anim_type('fade_in'))
reveal_button = Button(text='reveal_\nbelow_\nanim')
reveal_button.bind(on_press=lambda j: set_anim_type('reveal_below_anim'))
slide_button = Button(text='reveal_\nbelow_\nsimple')
slide_button.bind(on_press=lambda j: set_anim_type('reveal_below_simple'))
modes_layout.add_widget(slide_an)
modes_layout.add_widget(slide_sim)
modes_layout.add_widget(fade_in_button)
modes_layout.add_widget(reveal_button)
modes_layout.add_widget(slide_button)
main_panel.add_widget(modes_layout)transitions_layout = BoxLayout(orientation='horizontal')
transitions_layout.add_widget(Label(text='anim\ntransitions'))
out_cubic = Button(text='out_cubic')
out_cubic.bind(on_press=lambda j: set_transition('out_cubic'))
in_quint = Button(text='in_quint')
in_quint.bind(on_press=lambda j: set_transition('in_quint'))
linear = Button(text='linear')
linear.bind(on_press=lambda j: set_transition('linear'))
out_sine = Button(text='out_sine')
out_sine.bind(on_press=lambda j: set_transition('out_sine'))
transitions_layout.add_widget(out_cubic)
transitions_layout.add_widget(in_quint)
transitions_layout.add_widget(linear)
transitions_layout.add_widget(out_sine)
main_panel.add_widget(transitions_layout)button = Button(text='toggle NavigationDrawer state (animate)',size_hint_y=0.2)
button.bind(on_press=lambda j: navigationdrawer.toggle_state())
button2 = Button(text='toggle NavigationDrawer state (jump)',size_hint_y=0.2)
button2.bind(on_press=lambda j: navigationdrawer.toggle_state(False))
button3 = Button(text='toggle _main_above', size_hint_y=0.2)
button3.bind(on_press=navigationdrawer.toggle_main_above)
main_panel.add_widget(button)
main_panel.add_widget(button2)
main_panel.add_widget(button3)Window.add_widget(navigationdrawer)runTouchApp()