Screen Manager¶
New in version 1.4.0.
Warning
This widget is still experimental, and its API is subject to change in a future version.
The screen manager is a widget dedicated to manage multiple screens on your application. The default ScreenManager displays only one Screen at time, and use a TransitionBase to switch from one to another Screen.
Multiple transitions are supported, based of moving the screen coordinate / scale, or even do fancy animation using custom shaders.
Basic Usage¶
Let’s construct a Screen Manager with 4 named screen. When you are creating screen, you absolutely need to give a name to it:
from kivy.uix.screenmanager import ScreenManager, Screen
# Create the manager
sm = ScreenManager()
# Add few screens
for i in xrange(4):
screen = Screen(name='Title %d' % i)
sm.add_widget(screen)
# By default, the first screen added into the ScreenManager will be
# displayed. Then, you can change to another screen:
# Let's display the screen named 'Title 2'
# The transition will be automatically used.
sm.current = 'Title 2'
Please note that by default, a Screen display nothing, it’s just a RelativeLayout. You need to use that class as a root widget for your own screen. Best way is to subclass.
Here is an example with a ‘Menu Screen’, and a ‘Setting Screen’:
from kivy.app import App
from kivy.lang import Builder
from kivy.uix.screenmanager import ScreenManager, Screen
# Create both screen. Please note the root.manager.current: this is how you
# can control the ScreenManager from kv. Each screen have by default a
# property manager that give you the instance of the ScreenManager used.
Builder.load_string("""
<MenuScreen>:
BoxLayout:
Button:
text: 'Goto settings'
on_press: root.manager.current = 'settings'
Button:
text: 'Quit'
<SettingsScreen>:
BoxLayout:
Button:
text: 'My setting button'
Button:
text: 'Back to menu'
on_press: root.manager.current = 'menu'
""")
# Declare both screen
class MenuScreen(Screen):
pass
class SettingsScreen(Screen):
pass
# Create the screen manager
sm = ScreenManager()
sm.add_widget(MenuScreen(name='menu'))
sm.add_widget(SettingsScreen(name='settings'))
class TestApp(App):
def build(self):
return sm
if __name__ == '__main__':
TestApp().run()
Changing transition¶
You have multiple transition available by default, such as:
- SlideTransition - slide screen in/out, from any direction
- SwapTransition - implementation of the iOS swap transition
- FadeTransition - shader to fade in/out the screens
- WipeTransition - shader to wipe from right to left the screens
You can easily switch to a new transition by changing the ScreenManager.transition property:
sm = ScreenManager(transition=FadeTransition())
Note
Currently, all Shader based Transition doesn’t have any anti-aliasing. This is because we are using FBO, and don’t have any logic to do supersampling on them. This is a know issue, and working to have a transparent implementation that will give the same result as it would be rendered on the screen.
To be more concrete, if you see sharped-text during the animation, it’s normal.
- class kivy.uix.screenmanager.Screen(**kwargs)¶
Bases: kivy.uix.relativelayout.RelativeLayout
Screen is an element intented to be used within ScreenManager. Check module documentation for more information.
Events : - on_pre_enter: ()
Event fired when the screen is about to be used: the entering animation is started.
- on_enter: ()
Event fired when the screen is displayed: the entering animation is complete.
- on_pre_leave: ()
Event fired when the screen is about to be removed: the leaving animation is started.
- on_leave: ()
Event fired when the screen is removed: the leaving animation is finished.
Changed in version 1.6.0: Events on_pre_enter, on_enter, on_pre_leave, on_leave is added.
- manager¶
Screen manager object, set when the screen is added within a manager.
manager is a ObjectProperty, default to None, read-only.
- name¶
Name of the screen, must be unique within a ScreenManager. This is the name used for ScreenManager.current
name is a StringProperty, default to ‘’
- transition_progress¶
Value that represent the completion of the current transition, if any is occuring.
If a transition is going on, whatever is the mode, the value will got from 0 to 1. If you want to know if it’s an entering or leaving animation, check the transition_state
transition_progress is a NumericProperty, default to 0.
- transition_state¶
Value that represent the state of the transition:
- ‘in’ if the transition is going to show your screen
- ‘out’ if the transition is going to hide your screen
After the transition is done, the state will stay on the last one (in or out).
transition_state is an OptionProperty, default to ‘out’.
- class kivy.uix.screenmanager.ScreenManager(**kwargs)¶
Bases: kivy.uix.floatlayout.FloatLayout
Screen manager. This is the main class that will control your Screen stack, and memory.
By default, the manager will show only one screen at time.
- current¶
Name of the screen currently show, or the screen to show.
from kivy.uix.screenmanager import ScreenManager, Screen sm = ScreenManager() sm.add_widget(Screen(name='first')) sm.add_widget(Screen(name='second')) # by default, the first added screen will be showed. If you want to show # another one, just set the current string: sm.current = 'second'
- current_screen¶
Contain the current displayed screen. You must not change this property manually, use current instead.
current_screen is an ObjectProperty, default to None, read-only.
- get_screen(name)¶
Return the screen widget associated to the name, or raise a ScreenManagerException if not found.
- has_screen(name)¶
Return True if a screen with the name has been found.
New in version 1.6.0.
- next()¶
Return the name of the next screen from the screen list.
- previous()¶
Return the name of the previous screen from the screen list.
- screen_names¶
List of the names of all the Screen widgets added. The list is read only.
screens_names is a AliasProperty, it is read-only and updated if the screen list changes, or the name of a screen changes.
- screens¶
List of all the Screen widgets added. You must not change the list manually. Use Screen.add_widget() instead.
screens is a ListProperty, default to [], read-only.
- transition¶
Transition object to use for animate the screen that will be hidden, and the screen that will be showed. By default, an instance of SwapTransition will be given.
For example, if you want to change to a WipeTransition:
from kivy.uix.screenmanager import ScreenManager, Screen, WipeTransition sm = ScreenManager(transition=WipeTransition()) sm.add_widget(Screen(name='first')) sm.add_widget(Screen(name='second')) # by default, the first added screen will be showed. If you want to show another one, just set the current string: sm.current = 'second'
- class kivy.uix.screenmanager.ScreenManagerException¶
Bases: exceptions.Exception
Exception of the ScreenManager
- class kivy.uix.screenmanager.TransitionBase(**kw)¶
Bases: kivy.event.EventDispatcher
Transition class is used to animate 2 screens within the ScreenManager. This class act as a base for others implementation, like SlideTransition, SwapTransition.
Events : - on_progress: Transition object, progression float
Fired during the animation of the transition
- on_complete: Transition object
Fired when the transition is fininshed.
- add_screen(screen)¶
(internal) Used to add a screen into the ScreenManager
- duration¶
Duration in seconds of the transition.
duration is a NumericProperty, default to .7 (= 700ms)
- is_active¶
Indicate if the transition is currently active
is_active is a BooleanProperty, default to False, read-only.
- manager¶
Screen manager object, set when the screen is added within a manager.
manager is a ObjectProperty, default to None, read-only.
- remove_screen(screen)¶
(internal) Used to remove a screen into the ScreenManager
- screen_in¶
Property that contain the screen to show. Automatically set by the ScreenManager.
screen_in is a ObjectProperty, default to None.
- screen_out¶
Property that contain the screen to hide. Automatically set by the ScreenManager.
screen_out is a ObjectProperty, default to None.
- start(manager)¶
(internal) Start the transition. This is automatically called by the ScreenManager.
- stop()¶
(internal) Stop the transition. This is automatically called by the ScreenManager.
- class kivy.uix.screenmanager.ShaderTransition(**kw)¶
Bases: kivy.uix.screenmanager.TransitionBase
Transition class that use a Shader for animating the transition between 2 screens. By default, this class doesn’t any assign fragment/vertex shader. If you want to create your own fragment shader for transition, you need to declare the header yourself, and include the “t”, “tex_in” and “tex_out” uniform:
# Create your own transition. This is shader implement a "fading" # transition. fs = """$HEADER uniform float t; uniform sampler2D tex_in; uniform sampler2D tex_out; void main(void) { vec4 cin = texture2D(tex_in, tex_coord0); vec4 cout = texture2D(tex_out, tex_coord0); gl_FragColor = mix(cout, cin, t); } """ # And create your transition tr = ShaderTransition(fs=fs) sm = ScreenManager(transition=tr)
- fs¶
Fragment shader to use.
fs is a StringProperty, default to None.
- vs¶
Vertex shader to use.
vs is a StringProperty, default to None.
- class kivy.uix.screenmanager.SlideTransition(**kw)¶
Bases: kivy.uix.screenmanager.TransitionBase
Slide Transition, can be used to show a new screen from any direction: left, right, up or down.
- direction¶
Direction of the transition.
direction is an OptionProperty, default to left. Can be one of ‘left’, ‘right’, ‘up’ or ‘down’.
- class kivy.uix.screenmanager.SwapTransition(**kw)¶
Bases: kivy.uix.screenmanager.TransitionBase
Swap transition, that look like iOS transition, when a new window appear on the screen.
- class kivy.uix.screenmanager.FadeTransition(**kw)¶
Bases: kivy.uix.screenmanager.ShaderTransition
Fade transition, based on a fragment Shader.
- class kivy.uix.screenmanager.WipeTransition(**kw)¶
Bases: kivy.uix.screenmanager.ShaderTransition
Wipe transition, based on a fragment Shader.