Skip to content

Message pump

A message pump is a class that processes messages.

It is a base class for the App, Screen, and Widget classes.

app() property

Get the current app.

Returns:

Name Type Description
App App

The current app.

Raises:

Type Description
NoActiveAppError

if no active app could be found for the current asyncio context

call_after_refresh(callback, *args, **kwargs)

Schedule a callback to run after all messages are processed and the screen has been refreshed. Positional and keyword arguments are passed to the callable.

Parameters:

Name Type Description Default
callback Callable

A callable.

required

call_later(callback, *args, **kwargs)

Schedule a callback to run after all messages are processed in this object. Positional and keywords arguments are passed to the callable.

Parameters:

Name Type Description Default
callback Callable

Callable to call next.

required

check_idle()

Prompt the message pump to call idle if the queue is empty.

disable_messages(*messages)

Disable message types from being processed.

dispatch_key(event) async

Dispatch a key event to method.

This method will call the method named 'key_' if it exists. Some keys have aliases. The first alias found will be invoked if it exists. If multiple handlers exist that match the key, an exception is raised.

Parameters:

Name Type Description Default
event events.Key

A key event.

required

Returns:

Name Type Description
bool bool

True if key was handled, otherwise False.

Raises:

Type Description
DuplicateKeyHandlers

When there's more than 1 handler that could handle this key.

emit(message) async

Send a message to the parent.

Parameters:

Name Type Description Default
message Message

A message object.

required

Returns:

Name Type Description
bool bool

True if the message was posted successfully.

emit_no_wait(message)

Send a message to the parent, non async version.

Parameters:

Name Type Description Default
message Message

A message object.

required

Returns:

Name Type Description
bool bool

True if the message was posted successfully.

enable_messages(*messages)

Enable processing of messages types.

log() property

Get a logger for this object.

Returns:

Name Type Description
Logger Logger

A logger.

on_event(event) async

Called to process an event.

Parameters:

Name Type Description Default
event events.Event

An Event object.

required

post_message(message) async

Post a message or an event to this message pump.

Parameters:

Name Type Description Default
message Message

A message object.

required

Returns:

Name Type Description
bool bool

True if the messages was posted successfully, False if the message was not posted (because the message pump was in the process of closing).

post_message_no_wait(message)

Posts a message on the queue.

Parameters:

Name Type Description Default
message Message

A message (or Event).

required

Returns:

Name Type Description
bool bool

True if the messages was processed, False if it wasn't.

set_interval(interval, callback=None, *, name=None, repeat=0, pause=False)

Call a function at periodic intervals.

Parameters:

Name Type Description Default
interval float

Time between calls.

required
callback TimerCallback | None

Function to call. Defaults to None.

None
name str | None

Name of the timer object. Defaults to None.

None
repeat int

Number of times to repeat the call or 0 for continuous. Defaults to 0.

0
pause bool

Start the timer paused. Defaults to False.

False

Returns:

Name Type Description
Timer Timer

A timer object.

set_timer(delay, callback=None, *, name=None, pause=False)

Make a function call after a delay.

Parameters:

Name Type Description Default
delay float

Time to wait before invoking callback.

required
callback TimerCallback | None

Callback to call after time has expired. Defaults to None.

None
name str | None

Name of the timer (for debug). Defaults to None.

None
pause bool

Start timer paused. Defaults to False.

False

Returns:

Name Type Description
Timer Timer

A timer object.