NavigatorView API Reference#

NavigatorView #

NavigatorView(
    *,
    pages: t.Sequence[
        str
        | hikari.Embed
        | t.Sequence[hikari.Embed]
        | Page
    ],
    buttons: t.Sequence[NavButton] | None = None,
    items: t.Sequence[NavItem] | None = None,
    timeout: (
        float | int | datetime.timedelta | None
    ) = 120.0,
    autodefer: bool | AutodeferOptions = True
)

Bases: View

A specialized view built for paginated button-menus, navigators.

PARAMETER	DESCRIPTION
`pages`	A list of strings, embeds or page objects that this navigator should paginate. TYPE: `list[str \| hikari.Embed \| t.Sequence[hikari.Embed] \| Page]`
`buttons`	A list of navigation buttons to override the default ones with TYPE: `list[NavButton] \| None` DEFAULT: `None`
`timeout`	The duration after which the view times out, in seconds TYPE: `float \| int \| datetime.timedelta \| None` DEFAULT: `120.0`
`autodefer`	If enabled, interactions will be automatically deferred if not responded to within 2 seconds TYPE: `bool \| AutodeferOptions` DEFAULT: `True`

RAISES	DESCRIPTION
`TypeError`	One or more pages are not an instance of str or hikari.Embed

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.

pages `property` #

pages: t.Sequence[
    str | hikari.Embed | t.Sequence[hikari.Embed] | Page
]

The pages the navigator is iterating through.

current_page `property` `writable` #

current_page: int

The current page of the navigator, zero-indexed integer.

ephemeral `property` #

ephemeral: bool

Value determining if the navigator is sent ephemerally or not. This value will be ignored if the navigator is not sent on an interaction.

children `property` #

children: t.Sequence[NavItem]

A list of all items attached to the item handler.

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.

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.

get_default_buttons #

get_default_buttons() -> t.Sequence[NavButton]

Returns the default set of buttons.

RETURNS	DESCRIPTION
`List[NavButton]`	A list of the default navigation buttons.

add_item #

add_item(item: NavItem) -> te.Self

Adds a new item to the navigator. Item must be of type NavItem.

PARAMETER	DESCRIPTION
`item`	An instance of NavItem TYPE: `ViewItem`

RAISES	DESCRIPTION
`TypeError`	Parameter item was not an instance of NavItem

RETURNS	DESCRIPTION
`ItemHandler`	The item handler the item was added to.

remove_item #

remove_item(item: NavItem) -> 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.

send_page `async` #

send_page(
    context: Context[t.Any], page_index: int | None = None
) -> None

Send a page, editing the original message.

PARAMETER	DESCRIPTION
`context`	The context object that should be used to send this page TYPE: `Context`
`page_index`	The index of the page to send, if not specified, sends the current page TYPE: `Optional[int]` DEFAULT: `None`

swap_pages `async` #

swap_pages(
    context: Context[t.Any],
    new_pages: t.Sequence[
        str
        | hikari.Embed
        | t.Sequence[hikari.Embed]
        | Page
    ],
    start_at: int = 0,
) -> None

Swap out the pages of the navigator to the newly provided pages. By default, the navigator will reset to the first page.

PARAMETER	DESCRIPTION
`context`	The context object that should be used to send the updated pages TYPE: `Context`
`new_pages`	The new sequence of pages to swap to TYPE: `Sequence[Union[str, Embed, Sequence[Embed] \| Page]]`
`start_at`	The page to start at TYPE: `int` DEFAULT: `0`

build_response_async `async` #

build_response_async(
    client: Client,
    *,
    start_at: int = 0,
    ephemeral: bool = False
) -> MessageBuilder

Create a response builder out of this Navigator. This also invokes all before_page_change() methods.

Tip

If it takes too long to invoke all before_page_change() methods, 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`
`ephemeral`	Determines if the navigator will be sent ephemerally or not. TYPE: `bool` DEFAULT: `False`
`start_at`	The page index to start at TYPE: `int` DEFAULT: `0`

Page #

Allows for the building of more complex pages for use with NavigatorView.

content `class-attribute` `instance-attribute` #

content: hikari.UndefinedOr[t.Any] = hikari.UNDEFINED

The content of the message. Anything passed here will be cast to str.

attachment `class-attribute` `instance-attribute` #

attachment: hikari.UndefinedOr[hikari.Resourceish] = (
    hikari.UNDEFINED
)

An attachment to add to this page.

attachments `class-attribute` `instance-attribute` #

attachments: hikari.UndefinedOr[
    t.Sequence[hikari.Resourceish]
] = hikari.UNDEFINED

A sequence of attachments to add to this page.

embed `class-attribute` `instance-attribute` #

embed: hikari.UndefinedOr[hikari.Embed] = hikari.UNDEFINED

An embed to add to this page.

embeds `class-attribute` `instance-attribute` #

embeds: hikari.UndefinedOr[t.Sequence[hikari.Embed]] = (
    hikari.UNDEFINED
)

A sequence of embeds to add to this page.

mentions_everyone `class-attribute` `instance-attribute` #

mentions_everyone: hikari.UndefinedOr[bool] = (
    hikari.UNDEFINED
)

If True, mentioning @everyone will be allowed in this page's message.

user_mentions `class-attribute` `instance-attribute` #

user_mentions: hikari.UndefinedOr[
    hikari.SnowflakeishSequence[hikari.PartialUser] | bool
] = hikari.UNDEFINED

The set of allowed user mentions in this page's message. Set to True to allow all.

role_mentions `class-attribute` `instance-attribute` #

role_mentions: hikari.UndefinedOr[
    hikari.SnowflakeishSequence[hikari.PartialRole] | bool
] = hikari.UNDEFINED

The set of allowed role mentions in this page's message. Set to True to allow all.

NavigatorView API Reference#

NavigatorView #

timeout property #

client property #

last_context property #

message property #

is_bound property #

autodefer property #

pages property #

current_page property writable #

ephemeral property #

children property #

is_persistent property #

clear_items #

get_item_by #

get_item_by_id #

build #

stop #

wait async #

from_message classmethod #

view_check async #

on_error async #

wait_for_input async #

on_timeout async #