NavigatorView API Reference#

class miru.ext.nav.navigator.NavigatorView(*, pages: t.Sequence[t.Union[str, hikari.Embed, t.Sequence[hikari.Embed], Page]], buttons: t.Optional[t.Sequence[NavButton]] = None, timeout: t.Optional[t.Union[float, int, datetime.timedelta]] = 120.0, autodefer: bool = True)[source]#

Bases: View

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

Parameters:

pages (List[Union[str, hikari.Embed, Sequence[hikari.Embed], Page]]) – A list of strings, embeds or page objects that this navigator should paginate.
buttons (Optional[List[NavButton[NavigatorViewT]]], optional) – A list of navigation buttons to override the default ones with, by default None
timeout (Optional[Union[float, int, datetime.timedelta]], optional) – The duration after which the view times out, in seconds, by default 120.0
autodefer (bool, optional) – If enabled, interactions will be automatically deferred if not responded to within 2 seconds, by default True

Raises:

TypeError – One or more pages are not an instance of str or hikari.Embed

add_item(item: Item[hikari.impl.MessageActionRowBuilder]) → te.Self[source]#

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

Parameters:: item (Item[MessageActionRowBuilder]) – An instance of NavItem
Raises:: TypeError – Parameter item was not an instance of NavItem
Returns:: The item handler the item was added to.
Return type:: ItemHandler

get_default_buttons() → Sequence[NavButton][source]#

Returns the default set of buttons.

Returns:: A list of the default navigation buttons.
Return type:: List[NavButton[NavigatorViewT]]

async on_timeout() → None[source]#: Called when the item handler times out. Override for custom timeout logic.

async send(to: TextableChannel | Snowflake | int | MessageResponseMixin[Any] | Context[Any], *, start_at: int = 0, ephemeral: bool = False, responded: bool = False) → None[source]#

Start up the navigator, send the first page, and start listening for interactions.

Parameters:

to (Union[hikari.SnowflakeishOr[hikari.PartialChannel], hikari.MessageResponseMixin[Any], miru.Context]) – The channel, interaction, or miru context to send the navigator to.
start_at (int) – If provided, the page number to start the pagination at.
ephemeral (bool) – If an interaction or context was provided, determines if the navigator will be sent ephemerally or not. This is ignored if a channel was provided, as regular messages cannot be ephemeral.
responded (bool) – If an interaction was provided, determines if the interaction was previously acknowledged or not. This is ignored if a channel or context was provided.

async send_page(context: Context[Any], page_index: int | None = None) → None[source]#

Send a page, editing the original message.

Parameters:

context (Context) – The context object that should be used to send this page
page_index (Optional[int], optional) – The index of the page to send, if not specified, sends the current page, by default None

Start up the navigator listener. This should not be called directly, use send() instead.

Parameters:

message (Union[hikari.Message, Awaitable[hikari.Message]]) – If provided, the view will be bound to this message, and if the message is edited with a new view, this view will be stopped. Unbound views do not support message editing with additional views.
start_at (int, optional) – The page index to start at, by default 0

async swap_pages(context: Context[Any], new_pages: Sequence[str | Embed | Sequence[Embed] | Page], start_at: int = 0) → None[source]#

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

Parameters:

context (Context) – The context object that should be used to send the updated pages
new_pages (Sequence[Union[str, Embed, Sequence[Embed] | Page]]) – The new sequence of pages to swap to
start_at (int, optional) – The page to start at, by default 0

property children: Sequence[NavItem]#: A list of all items attached to the item handler.

property current_page: int#: The current page of the navigator, zero-indexed integer.

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.

property is_persistent: bool#: Determines if this view is persistent or not.

property pages: Sequence[str | Embed | Sequence[Embed] | Page]#: The pages the navigator is iterating through.

class miru.ext.nav.navigator.Page(content: hikari.UndefinedOr[t.Any] = UNDEFINED, attachment: hikari.UndefinedOr[hikari.Resourceish] = UNDEFINED, attachments: hikari.UndefinedOr[t.Sequence[hikari.Resourceish]] = UNDEFINED, embed: hikari.UndefinedOr[hikari.Embed] = UNDEFINED, embeds: hikari.UndefinedOr[t.Sequence[hikari.Embed]] = UNDEFINED, mentions_everyone: hikari.UndefinedOr[bool] = UNDEFINED, user_mentions: hikari.UndefinedOr[t.Union[hikari.SnowflakeishSequence[hikari.PartialUser], bool]] = UNDEFINED, role_mentions: hikari.UndefinedOr[t.Union[hikari.SnowflakeishSequence[hikari.PartialRole], bool]] = UNDEFINED)[source]#

Bases: object

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

attachment: hikari.UndefinedOr[hikari.Resourceish]#: An attachment to add to this page.

attachments: hikari.UndefinedOr[t.Sequence[hikari.Resourceish]]#: A sequence of attachments to add to this page.

content: hikari.UndefinedOr[t.Any]#: The content of the message. Anything passed here will be cast to str.

embed: hikari.UndefinedOr[hikari.Embed]#: An embed to add to this page.

embeds: hikari.UndefinedOr[t.Sequence[hikari.Embed]]#: A sequence of embeds to add to this page.

mentions_everyone: hikari.UndefinedOr[bool]#: If True, mentioning @everyone will be allowed in this page’s message.

role_mentions: hikari.UndefinedOr[t.Union[hikari.SnowflakeishSequence[hikari.PartialRole], bool]]#: The set of allowed role mentions in this page’s message. Set to True to allow all.

user_mentions: hikari.UndefinedOr[t.Union[hikari.SnowflakeishSequence[hikari.PartialUser], bool]]#: The set of allowed user mentions in this page’s message. Set to True to allow all.