bauiv1lib.docui.prep package

Functionality related to prepping a doc-ui page for display.

Consumes native (v2 / language-agnostic) doc-ui documents: text rides as bacommon.langstr.LangStrSpec (handed to widgets as native handles that re-evaluate on language changes) and assets as typed refs.

Warning

This is an internal api and subject to change at any time. Do not use it in mod code.

class bauiv1lib.docui.prep.ButtonPrep(buttoncall: Callable[..., bauiv1.Widget], buttoneditcall: Callable | None, decorations: list[DecorationPrep], textures: dict[str, str], widgetid: str, action: bacommon.docui.v2.Action | None)

Bases: object

Prep for a button in a doc-ui.

action: bacommon.docui.v2.Action | None

buttoncall: Callable[..., bauiv1.Widget]

buttoneditcall: Callable | None

decorations: list[DecorationPrep]

textures: dict[str, str]

widgetid: str

class bauiv1lib.docui.prep.DecorationPrep(call: Callable[..., bauiv1.Widget | None], textures: dict[str, str], meshes: dict[str, str], highlight: bool)

Bases: object

Prep for a decoration in a doc-ui.

call: Callable[..., bauiv1.Widget | None]

Creates the widget(s). A frame’s call creates several and returns None; single-widget decorations return theirs.

highlight: bool

meshes: dict[str, str]

textures: dict[str, str]

class bauiv1lib.docui.prep.PagePrep(rootcall: Callable[..., bauiv1.Widget] | None, rows: list[RowPrep], width: float, height: float, simple_culling_v: float, center_vertically: bool, title: bauiv1.LangStr, root_post_calls: list[Callable[[bauiv1.Widget], None]], immediate: bool, client_effects: list[bacommon.clienteffect.Effect] = <factory>)

Bases: object

Prep for a page in a doc-ui.

center_vertically: bool

client_effects: list[bacommon.clienteffect.Effect]

Effects to run when this page is first displayed, de-indexed ready to run. They ride here rather than being read back off the response because the response is cached un-de-indexed; prep is what produces the runnable form. Attached by the caller rather than built by prep_page(), which preps a page – effects belong to the response around it. Button-press effects need no equivalent: they hang off ButtonPrep.action, which already points into the de-indexed copy.

height: float

immediate: bool

Whether this page was prepped to appear with no transitions (a refresh in place, a back-nav to a page we already have). Carried here so instantiation can match – a page that snaps in should snap its scroll position too rather than gliding to the restored selection.

root_post_calls: list[Callable[[bauiv1.Widget], None]]

rootcall: Callable[..., bauiv1.Widget] | None

rows: list[RowPrep]

simple_culling_v: float

title: bauiv1.LangStr

Native language-string title handle.

width: float

class bauiv1lib.docui.prep.RowPrep(width: float, height: float, titlecalls: list[Callable[..., bauiv1.Widget]], hscrollcall: Callable[..., bauiv1.Widget] | None, hscrolleditcall: Callable | None, hsubcall: Callable[..., bauiv1.Widget] | None, buttons: list[ButtonPrep], simple_culling_h: float, decorations: list[DecorationPrep])

Bases: object

Prep for a row in a doc-ui.

buttons: list[ButtonPrep]

decorations: list[DecorationPrep]

height: float

hscrollcall: Callable[..., bauiv1.Widget] | None

hscrolleditcall: Callable | None

hsubcall: Callable[..., bauiv1.Widget] | None

simple_culling_h: float

titlecalls: list[Callable[..., bauiv1.Widget]]

width: float

bauiv1lib.docui.prep.instantiate_decorations(decorations: list[DecorationPrep], *, parent: bui.Widget, draw_controller: bui.Widget | None = None) → None

Instantiate prepped decorations under a parent widget.

The one place prepped decorations turn into live widgets. Asset refs are resolved here rather than at prep time because prep generally runs off the logic thread.

Decorations carry no knowledge of where they live, so parent fully determines that; this is what lets the same prepped decorations be drawn into a doc-ui page or into any plain container widget.

draw_controller, when passed, is applied to decorations whose highlight is set, tying their draw state to that widget (used for decorations layered over a button). Decorations drawn outside of a button context simply pass nothing here.

bauiv1lib.docui.prep.instantiate_page_prep(pageprep: PagePrep, *, rootwidget: bui.Widget, scrollwidget: bui.Widget, backbutton: bui.Widget, windowbackbutton: bui.Widget | None, window: DocUIWindow) → bui.Widget

Create a UI using prepped data.

bauiv1lib.docui.prep.prep_button_debug(bsize: tuple[float, float], bcenter: tuple[float, float], tdelay: float | None, out_decoration_preps: list[DecorationPrep]) → None

Prep debug decorations for a button.

bauiv1lib.docui.prep.prep_decorations(decorations: list[Decoration], center_x: float, center_y: float, scale: float, tdelay: float | None, *, packages: list[str], highlight: bool, out_decoration_preps: list[DecorationPrep]) → None

Prep appropriate decoration types for a list of decorations.

bauiv1lib.docui.prep.prep_frame(frame: Frame, bcenter: tuple[float, float], bscale: float, tdelay: float | None, out_decoration_preps: list[DecorationPrep], *, packages: list[str], highlight: bool) → None

Prep a frame and everything inside it.

The frame’s children are prepped into their own list and wrapped in a single self-contained call, so the frame survives prep as one thing rather than dissolving into its siblings. That is what lets frame-level properties (a group transition, clipping, an eventual rotation) have somewhere to live; flattening would silently drop them.

The result is an ordinary DecorationPrep, so the doc-ui instantiate path runs frames with no special case. Its texture and mesh maps are empty because the wrapped call resolves its own children’s assets.

bauiv1lib.docui.prep.prep_frames(frames: Sequence[Frame], *, packages: list[str], allow_logic_thread: bool = False) → Callable[[...], None]

Prep frames for drawing into a plain container widget.

Does every bit of layout math up front and returns a single call that instantiates the whole batch at once; run that on the logic thread with parent=<container widget>. Each frame carries its own center position and scale, so placement is decided here rather than at instantiate time.

This takes a sequence deliberately. A single-frame entry point invites being called in a loop, which is the inefficient shape this batching exists to avoid, so callers drawing one frame should pass a one-element sequence.

Prep is meant to run off the logic thread; doing otherwise reintroduces exactly the stutter the prep/instantiate split exists to prevent, so it logs a warning. Pass allow_logic_thread only if a caller genuinely has no other option. (Note this is unrelated to prep_page’s immediate, which concerns transition delays.)

bauiv1lib.docui.prep.prep_image(image: Image, bcenter: tuple[float, float], bscale: float, tdelay: float | None, out_decoration_preps: list[DecorationPrep], *, highlight: bool) → None

Prep decorations for an image.

bauiv1lib.docui.prep.prep_page(page: Page, *, packages: list[str], uiscale: UIScale, scroll_width: float, scroll_height: float, margins: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0), idprefix: str, immediate: bool = False) → PagePrep

Prep a page.

bauiv1lib.docui.prep.prep_row_debug(size: tuple[float, float], pos: tuple[float, float], tdelay: float | None, out_decoration_preps: list[DecorationPrep]) → None

Prep debug decorations for a row.

bauiv1lib.docui.prep.prep_row_debug_button(bsize: tuple[float, float], bcorner: tuple[float, float], tdelay: float | None, out_decoration_preps: list[DecorationPrep]) → None

Prep debug decorations for a button.

bauiv1lib.docui.prep.prep_text(text: Text, bcenter: tuple[float, float], bscale: float, tdelay: float | None, out_decoration_preps: list[DecorationPrep], *, packages: list[str], highlight: bool) → None

Prep decorations for text.