wijjit.elements.display.pager.Pager

class wijjit.elements.display.pager.Pager(id=None, classes=None, tab_index=None, width=60, height=20, border_style='single', nav_position='bottom', show_indicator=True, show_titles=False, loop=False, current_page=0, bind=True)

Pager element for linear pagination through multiple pages.

This element provides prev/next navigation for switching between pages. Each page is wrapped in an implicit Frame and can contain any content.

Parameters:

• id (str, optional) – Element identifier

• classes (str or list of str or set of str, optional) – CSS class names for styling

• width (int, optional) – Total pager width (default: 60)

• height (int, optional) – Total pager height (default: 20)

• border_style (str, optional) – Border style: “single”, “double”, “rounded”, “none” (default: “single”)

• nav_position (str, optional) – Navigation position: “top”, “bottom”, “both” (default: “bottom”)

• show_indicator (bool, optional) – Show “Page X of Y” indicator (default: True)

• show_titles (bool, optional) – Show page title in indicator (default: False)

• loop (bool, optional) – Wrap from last to first page (default: False)

• current_page (int, optional) – Initially active page index (default: 0)

• tab_index (int | None)

• bind (bool | str)

Variables:

• pages (list of Page) – List of pages

• current_page (int) – Index of currently displayed page (0-based)

• width (int) – Total pager width

• height (int) – Total pager height

• border_style (BorderStyle) – Border style for pager

• nav_position (str) – Navigation bar position

• show_indicator (bool) – Whether to show page indicator

• show_titles (bool) – Whether to show page title

• loop (bool) – Whether to loop at ends

• on_page_change (Callable or None) – Callback when page changes: on_page_change(old_index, new_index)

Notes

Navigation: - Left/PgUp: Previous page - Right/PgDown: Next page - Home: First page - End: Last page - Mouse click on Prev/Next buttons

__init__(id=None, classes=None, tab_index=None, width=60, height=20, border_style='single', nav_position='bottom', show_indicator=True, show_titles=False, loop=False, current_page=0, bind=True)

Parameters:

• id (str | None)

• classes (str | list[str] | set[str] | None)

• tab_index (int | None)

• width (int)

• height (int)

• border_style (str)

• nav_position (str)

• show_indicator (bool)

• show_titles (bool)

• loop (bool)

• current_page (int)

• bind (bool | str)

Return type:

None

Methods

__init__([id, classes, tab_index, width, ...])
add_child(element)	Add a child element.
add_class(class_name)	Add a CSS class to this element.
add_page([page, title, content])	Add a page to the pager.
apply_props(props)	Apply props from a VNode, skipping ephemeral props.
clear_pages()	Remove all pages.
collect_child_elements()	Collect all child elements from the active page's content.
collect_focusable_children()	Collect focusable elements from the active page's content.
first_page()	Navigate to the first page.
get_ephemeral_state()	Get ephemeral state for reconciliation.
get_focusable_children()	Get all focusable child elements.
get_hardware_cursor_position()	Absolute screen cell where the hardware terminal cursor should park.
get_height_for_width(width)	Return the height this element needs when laid out at width.
get_intrinsic_size()	Get the intrinsic (preferred) size of the pager.
go_to_page(index)	Navigate to a specific page.
handle_key(key)	Handle keyboard input for page navigation and content scrolling.
handle_mouse(event)	Handle mouse input for button clicks and scroll wheel.
has_class(class_name)	Check if element has a CSS class.
last_page()	Navigate to the last page.
next_page()	Navigate to the next page.
on_blur()	Called when element loses focus.
on_focus()	Called when element gains focus.
on_hover_enter()	Called when mouse enters element.
on_hover_exit()	Called when mouse exits element.
on_mount()	Called when element is first added to the element tree.
on_unmount()	Called when element is removed from the element tree.
on_update(changed_props)	Called when element props are updated during reconciliation.
prev_page()	Navigate to the previous page.
remove_child(element)	Remove a child element.
remove_class(class_name)	Remove a CSS class from this element.
remove_page(index)	Remove a page by index.
render_signature()	Hashable/comparable capture of everything render_to() reads.
render_to(ctx)	Render pager using cell-based rendering.
restore_ephemeral_state(state)	Restore ephemeral state after reconciliation.
set_bounds(bounds)	Set the element's screen bounds.
toggle_class(class_name)	Toggle a CSS class on this element.

Attributes

captures_tab	Whether this element wants the Tab key instead of focus movement.
page_count	Get the total number of pages.
page_state_key	Get the state key for current page index.
parent_frame	Get the parent Frame if this element is inside a scrollable frame.
supports_dynamic_sizing	Whether this element supports dynamic sizing.

property page_state_key: str | None

Get the state key for current page index.

Returns the explicitly set key if provided, otherwise auto-generates from the element id using the convention “{id}:page”.

Returns:

State key for current page, or None if no id

Return type:

str or None

property page_count: int

Get the total number of pages.

Returns:

Number of pages

Return type:

int

add_page(page=None, title='', content='')

Add a page to the pager.

Parameters:

• page (Page, optional) – Page object to add. If None, creates from title/content.

• title (str, optional) – Page title (used if page is None)

• content (PageContent, optional) – Page content (used if page is None)

Return type:

None

remove_page(index)

Remove a page by index.

Parameters:

index (int) – Index of page to remove

Returns:

Removed page, or None if index invalid

Return type:

Page or None

clear_pages()

Remove all pages.

Return type:

None

go_to_page(index)

Navigate to a specific page.

Parameters:

index (int) – Page index to navigate to

Returns:

True if page changed, False otherwise

Return type:

bool

next_page()

Navigate to the next page.

Returns:

True if page changed, False otherwise

Return type:

bool

prev_page()

Navigate to the previous page.

Returns:

True if page changed, False otherwise

Return type:

bool

first_page()

Navigate to the first page.

Returns:

True if page changed, False otherwise

Return type:

bool

last_page()

Navigate to the last page.

Returns:

True if page changed, False otherwise

Return type:

bool

handle_key(key)

Handle keyboard input for page navigation and content scrolling.

Parameters:

key (Key) – Key press to handle

Returns:

True if key was handled

Return type:

bool

Notes

Page navigation keys: - Left/Right: Previous/Next page - PgUp/PgDown: Previous/Next page - Home/End: First/Last page

Content scrolling keys (delegated to active frame): - Up/Down: Scroll content line by line

async handle_mouse(event)

Handle mouse input for button clicks and scroll wheel.

Parameters:

event (MouseEvent) – Mouse event to handle

Returns:

True if event was handled

Return type:

bool

Notes

Handles: - Left clicks on Prev/Next buttons - Scroll wheel events delegated to active frame

get_ephemeral_state()

Get ephemeral state for reconciliation.

Returns:

Current page index that should survive re-renders.

Return type:

dict

restore_ephemeral_state(state)

Restore ephemeral state after reconciliation.

Parameters:

state (dict) – State dict from get_ephemeral_state()

Return type:

None

get_intrinsic_size()

Get the intrinsic (preferred) size of the pager.

Returns:

(width, height) in characters/lines

Return type:

tuple of int

render_to(ctx)

Render pager using cell-based rendering.

Parameters:

ctx (PaintContext) – Paint context with buffer, style resolver, and bounds

Return type:

None

Notes

Renders the pager with: 1. Border (if enabled) 2. Navigation bar(s) with Prev/Next buttons and page indicator 3. Current page content in a Frame

Theme styles:

This element uses the following theme style classes: - pager: Base pager style - pager:focus: When pager has focus - pager.border: Border style - pager.nav: Navigation bar style - pager.button: Navigation button style - pager.button:disabled: Disabled button style - pager.indicator: Page indicator style

collect_focusable_children()

Collect focusable elements from the active page’s content.

Returns:

List of focusable elements in the active page

Return type:

list

collect_child_elements()

Collect all child elements from the active page’s content.

Returns:

List of all elements in the active page

Return type:

list