Menu API Reference#

Menu #

Menu(
    *,
    timeout: (
        float | int | datetime.timedelta | None
    ) = 300.0,
    autodefer: bool | miru.AutodeferOptions = True
)

Bases: miru.View

A menu that can be used to display multiple nested screens of components.

PARAMETER	DESCRIPTION
`timeout`	The duration after which the menu times out, in seconds TYPE: `Optional[Union[float, int, datetime.timedelta]]` DEFAULT: `300.0`
`autodefer`	If enabled, interactions will be automatically deferred if not responded to within 2 seconds TYPE: `bool` DEFAULT: `True`

children `property` #

children: t.Sequence[ItemT]

A list of all items attached to the item handler.

timeout `property` #

timeout: float | None

The amount of time the item handler is allowed to idle for, in seconds. Must be None for persistent views.

client `property` #

client: Client

The client that started this handler.

last_context `property` #

last_context: ContextT | None

The last context that was received by the item handler.

message `property` #

message: hikari.Message | None

The message this view is bound to. Will be None if the view is not bound.

is_bound `property` #

is_bound: bool

Determines if the view should be bound to a message or not.

autodefer `property` #

autodefer: AutodeferOptions

The autodefer configuration of this view.

is_persistent `property` #

is_persistent: bool

Determines if this view is persistent or not. A view is persistent only if it has no timeout and all of it's items have explicitly set custom_ids.

ephemeral `property` #

ephemeral: bool

If true, the menu will be sent ephemerally.

current_screen `property` #

current_screen: Screen

The current screen being displayed.

add_item #

add_item(item: ViewItem) -> te.Self

Adds a new item to the view.

PARAMETER	DESCRIPTION
`item`	The item to be added. TYPE: `ViewItem`

RAISES	DESCRIPTION
`ValueError`	A view already has 25 components attached.
`TypeError`	Parameter item is not an instance of ViewItem.
`RuntimeError`	The item is already attached to this view.
`RuntimeError`	The item is already attached to another view.

RETURNS	DESCRIPTION
`View`	The view the item was added to.

remove_item #

remove_item(item: ViewItem) -> te.Self

Removes an item from the view.

PARAMETER	DESCRIPTION
`item`	The item to be removed. TYPE: `ViewItem`

RAISES	DESCRIPTION
`ValueError`	The item is not attached to this view.

RETURNS	DESCRIPTION
`View`	The view the item was removed from.

clear_items #

clear_items() -> te.Self

Removes all items from the view.

RETURNS	DESCRIPTION
`View`	The view the items were removed from.

get_item_by #

get_item_by(
    predicate: t.Callable[[ItemT], bool],
    *,
    default: T | hikari.UndefinedType = hikari.UNDEFINED
) -> ItemT | T

Get the first item that matches the given predicate.

PARAMETER	DESCRIPTION
`predicate`	A predicate to match the item. TYPE: `Callable[[Item[Any]], bool]`
`default`	The default value to return if the item doesn't exist. TYPE: `T` DEFAULT: `hikari.UNDEFINED`

RETURNS	DESCRIPTION
`ItemT \| T`	The item that matched the predicate or default.

RAISES	DESCRIPTION
`KeyError`	No item that matches predicate was found and no default was provided.

get_item_by_id #

get_item_by_id(
    custom_id: str,
    default: T | hikari.UndefinedType = hikari.UNDEFINED,
) -> ItemT | T

Get the first item that matches the given custom ID.

PARAMETER	DESCRIPTION
`custom_id`	The custom_id of the component. TYPE: `str`
`default`	The default value to return if the item doesn't exist. TYPE: `T` DEFAULT: `hikari.UNDEFINED`

RETURNS	DESCRIPTION
`ItemT \| T`	The item that matched the custom ID or the default.

RAISES	DESCRIPTION
`KeyError`	No item that matches the custom ID was found and no default was provided.

build #

build() -> t.Sequence[BuilderT]

Creates the action rows the item handler represents.

RETURNS	DESCRIPTION
`List[hikari.impl.MessageActionRowBuilder]`	A list of action rows containing all items attached to this item handler, converted to hikari component objects. If the item handler has no items attached, this returns an empty list.

stop #

stop() -> None

Stop listening for interactions.

wait `async` #

wait(timeout: float | None = None) -> None

Wait until the item handler has stopped receiving interactions.

PARAMETER	DESCRIPTION
`timeout`	The amount of time to wait, in seconds TYPE: `Optional[float]` DEFAULT: `None`

from_message `classmethod` #

from_message(
    message: hikari.Message,
    *,
    timeout: (
        float | int | datetime.timedelta | None
    ) = 120.0,
    autodefer: bool = True
) -> te.Self

Create a new view from the components included in the passed message. Returns an empty view if the message has no components attached.

PARAMETER	DESCRIPTION
`message`	The message to read components from TYPE: `hikari.Message`
`timeout`	The timeout of the created view TYPE: `Optional[float]` DEFAULT: `120.0`
`autodefer`	If enabled, interactions will be automatically deferred if not responded to within 2 seconds TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`View`	The view that represents the components attached to this message.
`!!! warning`	This function constructs a completely new view based on the information available in the message object. Any custom behaviour (such as callbacks) will not be re-created, if you want to access an already running view that is bound to a message, use `Client.get_bound_view()` instead.

view_check `async` #

view_check(context: ViewContext) -> bool

Called before any callback in the view is called. Must evaluate to a truthy value to pass. Override for custom check logic.

PARAMETER	DESCRIPTION
`context`	The context for this check. TYPE: `ViewContextT`

RETURNS	DESCRIPTION
`bool`	A boolean indicating if the check passed or not.

on_error `async` #

on_error(
    error: Exception,
    item: InteractiveViewItem | None = None,
    context: ViewContext | None = None,
) -> None

Called when an error occurs in a callback function or the built-in timeout function. Override for custom error-handling logic.

PARAMETER	DESCRIPTION
`error`	The exception encountered. TYPE: `Exception`
`item`	The item this exception originates from, if any. TYPE: `Optional[MessageItem[ViewT]]` DEFAULT: `None`
`context`	The context associated with this exception, if any. TYPE: `Optional[Context]` DEFAULT: `None`

wait_for_input `async` #

wait_for_input(timeout: float | None = None) -> None

Wait for any input to be received. This will also unblock if the view was stopped, thus it is recommended to check for the presence of a value after this function returns.

PARAMETER	DESCRIPTION
`timeout`	The amount of time to wait for input, in seconds TYPE: `Optional[float]` DEFAULT: `None`

on_timeout `async` #

on_timeout() -> None

Called when the item handler times out. Override for custom timeout logic.

update_message `async` #

update_message(
    new_content: ScreenContent | None = None,
) -> None

Update the message with the current state of the menu.

PARAMETER	DESCRIPTION
`new_content`	The new content to use, if left as None, only the components will be updated TYPE: `Optional[ScreenContent]` DEFAULT: `None`

push `async` #

push(screen: Screen) -> None

Push a screen onto the menu stack and display it.

PARAMETER	DESCRIPTION
`screen`	The screen to push onto the stack and display. TYPE: `Screen`

pop `async` #

pop(*, count: int = 1) -> None

Pop 'count' screen off the menu stack and display the screen on top of the stack. This can be used to go back to the previous screen(s).

PARAMETER	DESCRIPTION
`count`	The number of screens to pop off the stack. Defaults to 1 TYPE: `int` DEFAULT: `1`

RAISES	DESCRIPTION
`ValueError`	Cannot pop less than 1 screen.
`ValueError`	Cannot pop the last screen.

pop_until_root `async` #

pop_until_root() -> None

Pop all screens off the menu stack until the root screen is reached.

build_response_async `async` #

build_response_async(
    client: miru.Client,
    starting_screen: Screen,
    *,
    ephemeral: bool = False
) -> miru.MessageBuilder

Create a REST response builder out of this Menu.

Tip

If it takes too long to build the starting screen, you may want to defer the interaction before calling this method.

PARAMETER	DESCRIPTION
`client`	The client instance to use to build the response TYPE: `Client`
`starting_screen`	The screen to start the menu with. TYPE: `Screen`
`ephemeral`	Determines if the navigator will be sent ephemerally or not. TYPE: `bool` DEFAULT: `False`

Menu API Reference#

Menu #

children property #

timeout property #

client property #

last_context property #

message property #

is_bound property #

autodefer property #

is_persistent property #

ephemeral property #

current_screen property #