Quick search

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 managing multiple screens for your application. The default ScreenManager displays only one Screen at a time and uses a TransitionBase to switch from one Screen to another.

Multiple transitions are supported based on changing the screen coordinates / scale or even performing fancy animation using custom shaders.

Basic Usage

Let’s construct a Screen Manager with 4 named screens. When you are creating a 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 range(4):
    screen = Screen(name='Title %d' % i)
    sm.add_widget(screen)

# By default, the first screen added into the ScreenManager will be
# displayed. You can then change to another screen.

# Let's display the screen named 'Title 2'
# A transition will automatically be used.
sm.current = 'Title 2'

From 1.8.0, you can now switch dynamically to a new screen, change the transition options and remove the previous one by using ScreenManager.switch_to():

sm = ScreenManager()
screens = [Screen(name='Title {}'.format(i)) for i in range(4)]

sm.switch_to(screens[0])
# later
sm.switch_to(screens[1], direction='right')

The default ScreenManager.transition is a SlideTransition with options direction and duration.

Please note that by default, a Screen displays nothing: it’s just a RelativeLayout. You need to use that class as a root widget for your own screen, the best way being to subclass.

Here is an example with a ‘Menu Screen’ and a ‘Settings Screen’:

from kivy.app import App
from kivy.lang import Builder
from kivy.uix.screenmanager import ScreenManager, Screen

# Create both screens. Please note the root.manager.current: this is how
# you can control the ScreenManager from kv. Each screen has by default a
# property manager that gives 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 settings button'
        Button:
            text: 'Back to menu'
            on_press: root.manager.current = 'menu'
""")

# Declare both screens
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 transitions

You have multiple transitions available by default, such as:

  • NoTransition - switches screens instantly with no animation
  • SlideTransition - slide the screen in/out, from any direction
  • SwapTransition - implementation of the iOS swap transition
  • FadeTransition - shader to fade the screen in/out
  • WipeTransition - shader to wipe the screens from right to left
  • FallOutTransition - shader where the old screen ‘falls’ and becomes transparent, revealing the new one behind it.
  • RiseInTransition - shader where the new screen rises from the screen centre while fading from transparent to opaque.

You can easily switch transitions by changing the ScreenManager.transition property:

sm = ScreenManager(transition=FadeTransition())

Note

Currently, none of Shader based Transitions use anti-aliasing. This is because they use the FBO which doesn’t have any logic to handle supersampling. This is a known issue and we are working on a transparent implementation that will give the same results as if it had been rendered on screen.

To be more concrete, if you see sharp edged text during the animation, it’s normal.

class kivy.uix.screenmanager.Screen(**kw)[source]

Bases: kivy.uix.relativelayout.RelativeLayout

Screen is an element intended to be used with a 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 and on_leave were added.

manager

ScreenManager object, set when the screen is added to a manager.

manager is an ObjectProperty and defaults to None, read-only.

name

Name of the screen which must be unique within a ScreenManager. This is the name used for ScreenManager.current.

name is a StringProperty and defaults to ‘’.

transition_progress

Value that represents the completion of the current transition, if any is occuring.

If a transition is in progress, whatever the mode, the value will change 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 and defaults to 0.

transition_state

Value that represents 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 complete, the state will retain it’s last value (in or out).

transition_state is an OptionProperty and defaults to ‘out’.

class kivy.uix.screenmanager.ScreenManager(**kwargs)[source]

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 a time.

current

Name of the screen currently shown, 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 shown. If you want to
# show another one, just set the 'current' property.
sm.current = 'second'
current_screen

Contains the currently displayed screen. You must not change this property manually, use current instead.

current_screen is an ObjectProperty and defaults to None, read-only.

get_screen(name)[source]

Return the screen widget associated with the name or raise a ScreenManagerException if not found.

has_screen(name)[source]

Return True if a screen with the name has been found.

New in version 1.6.0.

next()[source]

Return the name of the next screen from the screen list.

previous()[source]

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 an AliasProperty and is read-only. It is 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 and defaults to [], read-only.

switch_to(screen, **options)[source]

Add a new screen to the ScreenManager and switch to it. The previous screen will be removed from the children. options are the transition options that will be changed before the animation happens.

If no previous screens are available, the screen will be used as the main one:

sm = ScreenManager()
sm.switch_to(screen1)
# later
sm.switch_to(screen2, direction='left')
# later
sm.switch_to(screen3, direction='right', duration=1.)

If any animation is in progress, it will be stopped and replaced by this one: you should avoid this because the animation will just look weird. Use either switch_to() or current but not both.

The screen name will be changed if there is any conflict with the current screen.

transition

Transition object to use for animating the screen that will be hidden and the screen that will be shown. By default, an instance of SlideTransition 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 shown. If you want to
# show another one, just set the 'current' property.
sm.current = 'second'

Changed in version 1.8.0: Default transition has been changed from SwapTransition to SlideTransition.

class kivy.uix.screenmanager.ScreenManagerException[source]

Bases: exceptions.Exception

Exception for the ScreenManager.

class kivy.uix.screenmanager.TransitionBase[source]

Bases: kivy.event.EventDispatcher

TransitionBase is used to animate 2 screens within the ScreenManager. This class acts as a base for other implementations like the SlideTransition and 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)[source]

(internal) Used to add a screen to the ScreenManager.

duration

Duration in seconds of the transition.

duration is a NumericProperty and defaults to .4 (= 400ms).

Changed in version 1.8.0: Default duration has been changed from 700ms to 400ms.

is_active

Indicate whether the transition is currently active or not.

is_active is a BooleanProperty and defaults to False, read-only.

manager

ScreenManager object, set when the screen is added to a manager.

manager is an ObjectProperty and defaults to None, read-only.

remove_screen(screen)[source]

(internal) Used to remove a screen from the ScreenManager.

screen_in

Property that contains the screen to show. Automatically set by the ScreenManager.

screen_in is an ObjectProperty and defaults to None.

screen_out

Property that contains the screen to hide. Automatically set by the ScreenManager.

screen_out is an ObjectProperty and defaults to None.

start(manager)[source]

(internal) Starts the transition. This is automatically called by the ScreenManager.

stop()[source]

(internal) Stops the transition. This is automatically called by the ScreenManager.

class kivy.uix.screenmanager.ShaderTransition[source]

Bases: kivy.uix.screenmanager.TransitionBase

Transition class that uses a Shader for animating the transition between 2 screens. By default, this class doesn’t assign any fragment/vertex shader. If you want to create your own fragment shader for the transition, you need to declare the header yourself and include the “t”, “tex_in” and “tex_out” uniform:

# Create your own transition. This shader implements 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)
clearcolor

Sets the color of Fbo ClearColor.

New in version 1.9.0.

clearcolor is a ListProperty and defaults to [0, 0, 0, 1].

fs

Fragment shader to use.

fs is a StringProperty and defaults to None.

vs

Vertex shader to use.

vs is a StringProperty and defaults to None.

class kivy.uix.screenmanager.SlideTransition[source]

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 and defaults to ‘left’. Can be one of ‘left’, ‘right’, ‘up’ or ‘down’.

class kivy.uix.screenmanager.SwapTransition[source]

Bases: kivy.uix.screenmanager.TransitionBase

Swap transition that looks like iOS transition when a new window appears on the screen.

class kivy.uix.screenmanager.FadeTransition[source]

Bases: kivy.uix.screenmanager.ShaderTransition

Fade transition, based on a fragment Shader.

class kivy.uix.screenmanager.WipeTransition[source]

Bases: kivy.uix.screenmanager.ShaderTransition

Wipe transition, based on a fragment Shader.

class kivy.uix.screenmanager.FallOutTransition[source]

Bases: kivy.uix.screenmanager.ShaderTransition

Transition where the new screen ‘falls’ from the screen centre, becoming smaller and more transparent until it disappears, and revealing the new screen behind it. Mimics the popular/standard Android transition.

New in version 1.8.0.

duration

Duration in seconds of the transition, replacing the default of TransitionBase.

duration is a NumericProperty and defaults to .15 (= 150ms).

class kivy.uix.screenmanager.RiseInTransition[source]

Bases: kivy.uix.screenmanager.ShaderTransition

Transition where the new screen rises from the screen centre, becoming larger and changing from transparent to opaque until it fills the screen. Mimics the popular/standard Android transition.

New in version 1.8.0.

duration

Duration in seconds of the transition, replacing the default of TransitionBase.

duration is a NumericProperty and defaults to .2 (= 200ms).

class kivy.uix.screenmanager.NoTransition[source]

Bases: kivy.uix.screenmanager.TransitionBase

No transition, instantly switches to the next screen with no delay or animation.

New in version 1.8.0.