class root.RootWidget(Widget)

For the GUI to function, there must be exactly one instance of RootWidget. It implements the main event loop and serves as the ultimate container for all other visible widgets.

The root widget can be found using the get_root() function of the root module.


The root module contains the following module-level functions.
Returns the root widget.

schedule_call(delay, function, repeat = False)
Arranges for the given function to be called after the specified delay in milliseconds. Scheduled functions are called synchronously from the event loop, and only when the frame timer is running. If repeat is true, the function is called repeatedly at the specified interval, otherwise it is only called once. Returns a token that can be passed to cancel_ call().

schedule_event(delay, function, repeat = False)
Like schedule_call except that the function is passed an event containing the current timestamp and the state of the modifier keys.

Cancels a call previously scheduled by schedule_call() or schedule_event() given a token returned by one of those functions.


Initialises the root widget with the given surface, which will normally be the PyGame screen, but could be a subsurface of it.


If true, all widgets will be redrawn on every animation frame (i.e. after every call to begin_frame()). If false, redrawing only occurs after user input events, such as mouse clicks and keystrokes, or if a widget calls its invalidate() method. The default is false.


Arranges for timer events to be generated every interval milliseconds. See timer_event().

Runs the main event loop. Control is retained until a QUIT event is received, whereupon the quit() method is called.

Runs a modal event loop. The widget is run as a modal dialog until its dismiss() method is called.
This method is called when a QUIT event is received. The default implementation first calls confirm_quit(), and if it returns true, calls sys.exit(0).

Abstract Methods

Called when a timer event occurs. See set_timer(). If it returns true, a display update is performed. The default implementation returns true.

Note: If multiple timer events occur during a single pass through the event loop, only the most recent one is passed to timer_event() and the others are discarded. Also, if other types of event occur during the same pass through the event loop, all the other events are processed before calling timer_event(), even if the timer event was not the last to occur chronologically.

Called to give an opportunity to ask the user to confirm quitting the main event loop. If it returns true, sys.exit(0) is performed, otherwise nothing is done. The default implementation unconditionally returns true.

If this method returns true, pending display updates are only performed when a timer event occurs and the timer_event() method of the root widget returns true. Otherwise, the display is updated after every input event except for mouse-move events. The default implementation returns false.