Skip to content

textual.message_pump

A MessagePump is a base class for any object which processes messages, which includes Widget, Screen, and App.

Tip

Most of the method here are useful in general app development.

MessagePump

MessagePump(parent=None)

Base class which supplies a message pump.

app property

app

Get the current app.

Returns:

Type Description
'App[object]'

The current app.

Raises:

Type Description
NoActiveAppError

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

has_parent property

has_parent

Does this object have a parent?

is_attached property

is_attached

Is this node linked to the app through the DOM?

is_dom_root property

is_dom_root

Is this a root node (i.e. the App)?

is_parent_active property

is_parent_active

Is the parent active?

is_running property

is_running

Is the message pump running (potentially processing messages)?

log property

log

Get a logger for this object.

Returns:

Type Description
Logger

A logger.

message_queue_size property

message_queue_size

The current size of the message queue.

message_signal instance-attribute

message_signal = Signal(self, 'messages')

Subscribe to this signal to be notified of all messages sent to this widget.

This is a fairly low-level mechanism, and shouldn't replace regular message handling.

call_after_refresh

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

Callback

A callable.

required

Returns:

Type Description
bool

True if the callback was scheduled, or False if the callback could not be scheduled (may occur if the message pump was closed or closing).

call_later

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

Callback

Callable to call next.

required

*args

Any

Positional arguments to pass to the callable.

()

**kwargs

Any

Keyword arguments to pass to the callable.

{}

Returns:

Type Description
bool

True if the callback was scheduled, or False if the callback could not be scheduled (may occur if the message pump was closed or closing).

call_next

call_next(callback, *args, **kwargs)

Schedule a callback to run immediately after processing the current message.

Parameters:

Name Type Description Default

callback

Callback

Callable to run after current event.

required

*args

Any

Positional arguments to pass to the callable.

()

**kwargs

Any

Keyword arguments to pass to the callable.

{}

check_idle

check_idle()

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

check_message_enabled

check_message_enabled(message)

Check if a given message is enabled (allowed to be sent).

Parameters:

Name Type Description Default

message

Message

A message object.

required

Returns:

Type Description
bool

True if the message will be sent, or False if it is disabled.

disable_messages

disable_messages(*messages)

Disable message types from being processed.

enable_messages

enable_messages(*messages)

Enable processing of messages types.

on_event async

on_event(event)

Called to process an event.

Parameters:

Name Type Description Default

event

Event

An Event object.

required

post_message

post_message(message)

Posts a message on to this widget's queue.

Parameters:

Name Type Description Default

message

Message

A message (including Event).

required

Returns:

Type Description
bool

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

prevent

prevent(*message_types)

A context manager to temporarily prevent the given message types from being posted.

Example
input = self.query_one(Input)
with self.prevent(Input.Changed):
    input.value = "foo"

set_interval

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 (in seconds) between calls.

required

callback

TimerCallback | None

Function to call.

None

name

str | None

Name of the timer object.

None

repeat

int

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

0

pause

bool

Start the timer paused.

False

Returns:

Type Description
Timer

A timer object.

set_timer

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

Call a function after a delay.

Example
def ready():
    self.notify("Your soft boiled egg is ready!")
# Call ready() after 3 minutes
self.set_timer(3 * 60, ready)

Parameters:

Name Type Description Default

delay

float

Time (in seconds) to wait before invoking callback.

required

callback

TimerCallback | None

Callback to call after time has expired.

None

name

str | None

Name of the timer (for debug).

None

pause

bool

Start timer paused.

False

Returns:

Type Description
Timer

A timer object.