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 message was queued for processing, otherwise False.

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.