bacommon.docui package

Declarative UI system.

A high level way to build UIs that lives as a layer on top of engine apis such as bauiv1. UIs can easily be serialized to json data and be provided by webservers or other local or remote sources.

class bacommon.docui.DocUIRequest

Bases: IOMultiType[DocUIRequestTypeID]

A request for some UI.

classmethod get_type(type_id: DocUIRequestTypeID) → type[DocUIRequest]

Return the subclass for each of our type-ids.

classmethod get_type_id() → DocUIRequestTypeID

Return the type-id for this subclass.

classmethod get_type_id_storage_name() → str

Return the key used to store type id in serialized data.

The default is a short obscure value so that it is unlikely to conflict with members of individual type attrs, but in some cases one might prefer to serialize it to something simpler like ‘type’ by overriding this call. One just needs to make sure that no encompassed types serialize anything to that same name themself (dataclassio will error if they do).

classmethod get_unknown_type_fallback() → DocUIRequest

Return a fallback object in cases of unrecognized types.

This can allow newer data to remain readable in older environments. Use caution with this option, however, as it effectively modifies data.

class bacommon.docui.DocUIRequestTypeID(*values)

Bases: Enum

Type ID for each of our subclasses.

UNKNOWN = 'u'

V1 = 'v1'

V2 = 'v2'

class bacommon.docui.DocUIResponse

Bases: IOMultiType[DocUIResponseTypeID]

A UI provied in response to a DocUIRequest.

classmethod get_type(type_id: DocUIResponseTypeID) → type[DocUIResponse]

Return the subclass for each of our type-ids.

classmethod get_type_id() → DocUIResponseTypeID

Return the type-id for this subclass.

classmethod get_type_id_storage_name() → str

Return the key used to store type id in serialized data.

The default is a short obscure value so that it is unlikely to conflict with members of individual type attrs, but in some cases one might prefer to serialize it to something simpler like ‘type’ by overriding this call. One just needs to make sure that no encompassed types serialize anything to that same name themself (dataclassio will error if they do).

classmethod get_unknown_type_fallback() → DocUIResponse

Return a fallback object in cases of unrecognized types.

This can allow newer data to remain readable in older environments. Use caution with this option, however, as it effectively modifies data.

class bacommon.docui.DocUIResponseTypeID(*values)

Bases: Enum

Type ID for each of our subclasses.

UNKNOWN = 'u'

V1 = 'v1'

V2 = 'v2'

class bacommon.docui.DocUIWebRequest(doc_ui_request: DocUIRequest, locale: Locale, engine_build_number: int)

Bases: object

Complete data sent for doc-ui http requests.

doc_ui_request: DocUIRequest

The wrapped doc-ui request.

engine_build_number: int

Engine build number. In some cases it may make sense to adjust responses depending on available engine features.

locale: Locale

The current locale of the client. doc-ui generally deals in raw strings and expects localization to happen on the server.

class bacommon.docui.DocUIWebResponse(error: str | None = None, doc_ui_response: DocUIResponse | None = None)

Bases: object

Complete data returned for doc-ui http requests.

doc_ui_response: DocUIResponse | None = None

doc-ui response. Either this or error should be set; not both.

error: str | None = None

Human readable error string (if an error occurs). Either this or doc_ui_response should be set; not both.

class bacommon.docui.UnknownDocUIRequest

Bases: DocUIRequest

Fallback type for unrecognized UI types.

Will show the client a ‘cannot display this UI’ placeholder request.

classmethod get_type_id() → DocUIRequestTypeID

Return the type-id for this subclass.

class bacommon.docui.UnknownDocUIResponse

Bases: DocUIResponse

Fallback type for unrecognized UI types.

Will show the client a ‘cannot display this UI’ placeholder response.

classmethod get_type_id() → DocUIResponseTypeID

Return the type-id for this subclass.

class bacommon.docui.WrapParams(min_lines: int = 1, max_lines: int | None = None, max_chars_per_line: int | None = None)

Bases: object

Constraints for splitting a text value into lines client-side.

Mirrors the engine’s simple equal-width line splitter (babase.split_text_into_lines()): text is broken only at valid line-break opportunities, using the fewest lines that keep every line within max_chars_per_line (when provided) while staying between min_lines and max_lines (None means unlimited), with line lengths balanced within that count. So max_chars_per_line alone gives basic wrapping and min_lines alone gives an exact line count. Constraints are best-effort.

Default to pinning an exact line count: set min_lines to the layout’s designed count and leave max_chars_per_line unset. A max_chars_per_line-driven wrap yields a per-locale varying line count (translation lengths differ), which reads as broken in layouts designed around a specific count — and every legacy-converted string is such a layout, since the legacy pipeline hand-baked newlines at fixed counts (see D21 in the strings-asset-migration initiative). Reserve max_chars_per_line for surfaces explicitly designed to tolerate a variable number of lines.

Per decision D-t these are definition-time presentation hints: a string definition carries them optionally, they ride each locale blob, and evaluation applies them automatically. They are locale-invariant, and width-driven layout consumers may ignore them (they are a fallback presentation default).

max_chars_per_line: int | None = None

max_lines: int | None = None

min_lines: int = 1

Submodules

bacommon.docui.framefit module

Geometry for fitting a doc-ui frame’s children into its bounds.

Kept apart from the client’s prep code on purpose. Fitting splits into two halves: working out how big each child is, which needs a font and so only a client can do, and working out where that puts everything, which is arithmetic. This is the arithmetic half – no engine, no measurement, and therefore testable on its own.

See bacommon.docui.v2.Frame.size.

class bacommon.docui.framefit.Bounds(minx: float, miny: float, maxx: float, maxy: float)

Bases: object

An axis-aligned box in a frame’s local units.

property height: float

Vertical extent.

maxx: float

maxy: float

minx: float

miny: float

union(other: Bounds) → Bounds

Return the smallest box containing both.

property width: float

Horizontal extent.

class bacommon.docui.framefit.Fit(offset: tuple[float, float], scale: float)

Bases: object

How to place content in a frame’s box.

offset is in the frame’s local units and applies before scale, matching the order the prep transform composes in.

offset: tuple[float, float]

scale: float

bacommon.docui.framefit.aligned_box(position: tuple[float, float], width: float, height: float, h_align: HAlign, v_align: VAlign) → Bounds

Return a box of this size placed at position by its alignment.

Mirrors how the decoration renderers interpret position plus alignment, so measured bounds land where the thing will draw.

bacommon.docui.framefit.fit_bounds(content: Bounds, size: tuple[float, float], h_align: HAlign = HAlign.CENTER, v_align: VAlign = VAlign.CENTER) → Fit

Place content inside a box of size centered on the origin.

Shrinks to fit but never grows – content smaller than the box is left at its own size and aligned within it. Both axes shrink together by the tighter of the two ratios, so nothing is distorted.

bacommon.docui.v1 module

Version 1 doc-ui types.

class bacommon.docui.v1.Action

Bases: IOMultiType[ActionTypeID]

Top level class for our multitype.

classmethod get_type(type_id: ActionTypeID) → type[Action]

Return the subclass for each of our type-ids.

classmethod get_type_id() → ActionTypeID

Return the type-id for this subclass.

classmethod get_type_id_storage_name() → str

Return the key used to store type id in serialized data.

The default is a short obscure value so that it is unlikely to conflict with members of individual type attrs, but in some cases one might prefer to serialize it to something simpler like ‘type’ by overriding this call. One just needs to make sure that no encompassed types serialize anything to that same name themself (dataclassio will error if they do).

classmethod get_unknown_type_fallback() → Action

Return a fallback object in cases of unrecognized types.

This can allow newer data to remain readable in older environments. Use caution with this option, however, as it effectively modifies data.

class bacommon.docui.v1.ActionTypeID(*values)

Bases: Enum

Type ID for each of our subclasses.

BROWSE = 'b'

LOCAL = 'l'

REPLACE = 'r'

UNKNOWN = 'u'

class bacommon.docui.v1.Browse(request: Request, default_sound: bool = True, immediate_client_effects: list[Effect] = <factory>, immediate_local_action: str | None = None, immediate_local_action_args: dict | None = None)

Bases: Action

Browse to a new page in a new window.

default_sound: bool = True

Plays a swish.

classmethod get_type_id() → ActionTypeID

Return the type-id for this subclass.

immediate_local_action: str | None = None

Local action to run immediately when the button is pressed. Will be handled by bauiv1lib.docui.DocUIController.local_action().

immediate_local_action_args: dict | None = None

request: Request

class bacommon.docui.v1.Button(label: str | None = None, action: Action | None = None, size: tuple[float, float] | None = None, color: tuple[float, float, float, float] | None = None, label_color: tuple[float, float, float, float] | None = None, label_flatness: float | None = None, label_scale: float | None = None, label_is_lstr: bool = False, label_is_langstr: bool = False, label_wrap: WrapParams | None = None, texture: str | None = None, scale: float = 1.0, padding_left: float = 0.0, padding_top: float = 0.0, padding_right: float = 0.0, padding_bottom: float = 0.0, decorations: list[Decoration] | None = None, style: ButtonStyle = ButtonStyle.SQUARE, default: bool = False, selected: bool = False, icon: str | None = None, icon_scale: float | None = None, icon_color: tuple[float, float, float, float] | None = None, depth_range: tuple[float, float] | None = None, widget_id: str | None = None, debug: bool = False)

Bases: object

A button in our doc-ui.

Note that size, padding, and all decorations are scaled consistently with ‘scale’.

action: Action | None = None

color: tuple[float, float, float, float] | None = None

debug: bool = False

Draw bounds of the button.

decorations: list[Decoration] | None = None

default: bool = False

depth_range: tuple[float, float] | None = None

icon: str | None = None

icon_color: tuple[float, float, float, float] | None = None

icon_scale: float | None = None

label: str | None = None

Note that doc-ui accepts only raw str values for text; use babase.Lstr.evaluate() or whatnot for multi-language support.

label_color: tuple[float, float, float, float] | None = None

label_flatness: float | None = None

label_is_langstr: bool = False

The label field holds a language-string (canonical resource-form wire JSON) to be evaluated natively at display and re-evaluated on language changes. Set by the client-side v2 transcode; mutually exclusive with label_is_lstr.

label_is_lstr: bool = False

label_scale: float | None = None

label_wrap: WrapParams | None = None

Line-wrap constraints applied to the label at widget-creation time. Set only by the client-local v2→v1 transcode; v1 producers must never send it (older clients can’t parse unknown fields — bake newlines into the label instead).

padding_bottom: float = 0.0

padding_left: float = 0.0

padding_right: float = 0.0

padding_top: float = 0.0

scale: float = 1.0

selected: bool = False

size: tuple[float, float] | None = None

style: ButtonStyle = 'q'

texture: str | None = None

widget_id: str | None = None

Custom widget id. Will be prefixed with window id, but must be unique within the window.

class bacommon.docui.v1.ButtonRow(buttons: list[Button], header_height: float = 0.0, header_scale: float = 1.0, header_decorations_left: list[Decoration] | None = None, header_decorations_center: list[Decoration] | None = None, header_decorations_right: list[Decoration] | None = None, title: str | None = None, title_color: tuple[float, float, float, float] | None = None, title_flatness: float | None = None, title_shadow: float | None = None, title_is_lstr: bool = False, title_is_langstr: bool = False, title_wrap: WrapParams | None = None, subtitle: str | None = None, subtitle_color: tuple[float, float, float, float] | None = None, subtitle_flatness: float | None = None, subtitle_shadow: float | None = None, subtitle_is_lstr: bool = False, subtitle_is_langstr: bool = False, subtitle_wrap: WrapParams | None = None, button_spacing: float = 15.0, padding_left: float = 10.0, padding_right: float = 10.0, padding_top: float = 10.0, padding_bottom: float = 10.0, spacing_top: float = 0.0, spacing_bottom: float = 0.0, center_content: bool = False, center_title: bool = False, simple_culling_h: float = 100.0, debug: bool = False)

Bases: Row

A row consisting of buttons.

button_spacing: float = 15.0

Spacing between all buttons in the row.

buttons: list[Button]

center_content: bool = False

center_title: bool = False

debug: bool = False

Draw bounds of the overall row and individual button columns (including padding). The UI will scroll to keep these areas visible in their entirety when changing selection via directional controls, so try to make sure all decorations for a button are within these bounds.

classmethod get_type_id() → RowTypeID

Return the type-id for this subclass.

header_decorations_center: list[Decoration] | None = None

header_decorations_left: list[Decoration] | None = None

header_decorations_right: list[Decoration] | None = None

header_height: float = 0.0

header_scale: float = 1.0

padding_bottom: float = 10.0

Padding on the bottom of the row’s horizonally-scrollable area.

padding_left: float = 10.0

Padding on the left of the row’s horizonally-scrollable area.

padding_right: float = 10.0

Padding on the right of the row’s horizonally-scrollable area.

padding_top: float = 10.0

Padding on the top of the row’s horizonally-scrollable area.

simple_culling_h: float = 100.0

If things disappear when scrolling left/right, turn this up.

spacing_bottom: float = 0.0

Extra space below the row’s horizontally-scrollable area.

spacing_top: float = 0.0

Extra space above the row’s horizontally-scrollable area.

subtitle: str | None = None

subtitle_color: tuple[float, float, float, float] | None = None

subtitle_flatness: float | None = None

subtitle_is_langstr: bool = False

The subtitle field holds a language-string (canonical resource-form wire JSON) to be evaluated natively at display and re-evaluated on language changes. Set by the client-side v2 transcode; mutually exclusive with subtitle_is_lstr.

subtitle_is_lstr: bool = False

subtitle_shadow: float | None = None

subtitle_wrap: WrapParams | None = None

Line-wrap constraints applied to the subtitle at widget-creation time. Set only by the client-local v2→v1 transcode; v1 producers must never send it (older clients can’t parse unknown fields — bake newlines into the subtitle instead).

title: str | None = None

Note that doc-ui accepts only raw str values for text; use babase.Lstr.evaluate() or whatnot for multi-language support.

title_color: tuple[float, float, float, float] | None = None

title_flatness: float | None = None

title_is_langstr: bool = False

The title field holds a language-string (canonical resource-form wire JSON) to be evaluated natively at display and re-evaluated on language changes. Set by the client-side v2 transcode; mutually exclusive with title_is_lstr.

title_is_lstr: bool = False

title_shadow: float | None = None

title_wrap: WrapParams | None = None

Line-wrap constraints applied to the title at widget-creation time. Set only by the client-local v2→v1 transcode; v1 producers must never send it (older clients can’t parse unknown fields — bake newlines into the title instead).

class bacommon.docui.v1.ButtonStyle(*values)

Bases: Enum

Styles a button can be.

BACK = 'b'

BACK_SMALL = 'bs'

LARGE = 'l'

LARGER = 'xl'

MEDIUM = 'm'

SMALL = 's'

SQUARE = 'q'

SQUARE_WIDE = 'w'

TAB = 't'

class bacommon.docui.v1.Decoration

Bases: IOMultiType[DecorationTypeID]

Top level class for our multitype.

classmethod get_type(type_id: DecorationTypeID) → type[Decoration]

Return a specific subclass given a type-id.

Should be overridden by child classes. Generally, users of the class should call get_type_cached() instead of this, as it is more efficient.

classmethod get_type_id() → DecorationTypeID

Return the type-id for this subclass.

classmethod get_type_id_storage_name() → str

Return the key used to store type id in serialized data.

The default is a short obscure value so that it is unlikely to conflict with members of individual type attrs, but in some cases one might prefer to serialize it to something simpler like ‘type’ by overriding this call. One just needs to make sure that no encompassed types serialize anything to that same name themself (dataclassio will error if they do).

classmethod get_unknown_type_fallback() → Decoration

Return a fallback object in cases of unrecognized types.

This can allow newer data to remain readable in older environments. Use caution with this option, however, as it effectively modifies data.

class bacommon.docui.v1.DecorationTypeID(*values)

Bases: Enum

Type ID for each of our subclasses.

DISPLAY_ITEM = 'd'

IMAGE = 'i'

TEXT = 't'

UNKNOWN = 'u'

class bacommon.docui.v1.DisplayItem(wrapper: Wrapper, position: tuple[float, float], size: tuple[float, float], style: DisplayItemStyle = DisplayItemStyle.FULL, text_color: tuple[float, float, float] | None = None, highlight: bool = True, depth_range: tuple[float, float] | None = None, debug: bool = False)

Bases: Decoration

DisplayItem decoration.

debug: bool = False

depth_range: tuple[float, float] | None = None

classmethod get_type_id() → DecorationTypeID

Return the type-id for this subclass.

highlight: bool = True

position: tuple[float, float]

size: tuple[float, float]

style: DisplayItemStyle = 'f'

text_color: tuple[float, float, float] | None = None

wrapper: Wrapper

class bacommon.docui.v1.DisplayItemStyle(*values)

Bases: Enum

Styles a display-item can be drawn in.

COMPACT = 'c'

Graphics and/or text fully conveying what the item is, but condensed to fit in a 2:1 box displayed at small sizes.

FULL = 'f'

Shows graphics and/or text fully conveying what the item is. Fits in to a 4:3 box and works best with large-ish displays.

ICON = 'i'

A graphics-only representation of the item (though text may be used in fallback cases). Does not fully convey what the item is, but instead is intended to be used alongside the item’s textual description. For example, some number of coins may simply display a coin graphic here without the number. Draws in a 1:1 box and works for large or small display.

class bacommon.docui.v1.HAlign(*values)

Bases: Enum

Horizontal alignment.

CENTER = 'c'

LEFT = 'l'

RIGHT = 'r'

class bacommon.docui.v1.Image(texture: str, position: tuple[float, float], size: tuple[float, float], color: tuple[float, float, float, float] | None = None, h_align: HAlign = HAlign.CENTER, v_align: VAlign = VAlign.CENTER, tint_texture: str | None = None, tint_color: tuple[float, float, float] | None = None, tint2_color: tuple[float, float, float] | None = None, mask_texture: str | None = None, mesh_opaque: str | None = None, mesh_transparent: str | None = None, highlight: bool = True, depth_range: tuple[float, float] | None = None)

Bases: Decoration

Image decoration.

color: tuple[float, float, float, float] | None = None

depth_range: tuple[float, float] | None = None

classmethod get_type_id() → DecorationTypeID

Return the type-id for this subclass.

h_align: HAlign = 'c'

highlight: bool = True

mask_texture: str | None = None

mesh_opaque: str | None = None

mesh_transparent: str | None = None

position: tuple[float, float]

size: tuple[float, float]

texture: str

tint2_color: tuple[float, float, float] | None = None

tint_color: tuple[float, float, float] | None = None

tint_texture: str | None = None

v_align: VAlign = 'c'

class bacommon.docui.v1.Local(close_window: bool = False, default_sound: bool = True, immediate_client_effects: list[Effect] = <factory>, immediate_local_action: str | None = None, immediate_local_action_args: dict | None = None)

Bases: Action

Perform only local actions; no new requests or page changes.

close_window: bool = False

default_sound: bool = True

Plays a swish if closing the window or a click if triggered by a button press.

classmethod get_type_id() → ActionTypeID

Return the type-id for this subclass.

immediate_local_action: str | None = None

Local action to run immediately when the button is pressed. Will be handled by bauiv1lib.docui.DocUIController.local_action().

immediate_local_action_args: dict | None = None

class bacommon.docui.v1.Page(title: str, rows: list[Row], center_vertically: bool = False, row_spacing: float = 10.0, simple_culling_v: float = 100.0, title_is_lstr: bool = False, title_is_langstr: bool = False, title_wrap: WrapParams | None = None, padding_bottom: float = 0.0, padding_left: float = 0.0, padding_top: float = 0.0, padding_right: float = 0.0)

Bases: object

Doc-UI page version 1.

center_vertically: bool = False

If True, content smaller than the available height will be centered vertically. This can look natural for certain types of content such as confirmation dialogs.

padding_bottom: float = 0.0

padding_left: float = 0.0

padding_right: float = 0.0

padding_top: float = 0.0

row_spacing: float = 10.0

rows: list[Row]

simple_culling_v: float = 100.0

If things disappear when scrolling up and down, turn this up.

title: str

Note that doc-ui accepts only raw str values for text; use babase.Lstr.evaluate() or whatnot for multi-language support.

title_is_langstr: bool = False

The title field holds a language-string (canonical resource-form wire JSON) to be evaluated natively at display and re-evaluated on language changes. Set by the client-side v2 transcode; mutually exclusive with title_is_lstr.

title_is_lstr: bool = False

Whether the title is a json dict representing an Lstr. Generally doc-ui translation should be handled server-side, but this can allow client-side translation.

title_wrap: WrapParams | None = None

Line-wrap constraints applied to the title at widget-creation time. Set only by the client-local v2→v1 transcode; v1 producers must never send it (older clients can’t parse unknown fields — bake newlines into the title instead).

class bacommon.docui.v1.Replace(request: Request, default_sound: bool = True, immediate_client_effects: list[Effect] = <factory>, immediate_local_action: str | None = None, immediate_local_action_args: dict | None = None)

Bases: Action

Replace current page with a new one.

Should be used to effectively ‘modify’ existing UIs by replacing them with something slightly different. Things like scroll position and selection will be carried across to the new layout when possible to make for a seamless transition.

default_sound: bool = True

Plays a click if triggered by a button press.

classmethod get_type_id() → ActionTypeID

Return the type-id for this subclass.

immediate_local_action: str | None = None

Local action to run immediately when the button is pressed. Will be handled by bauiv1lib.docui.DocUIController.local_action().

immediate_local_action_args: dict | None = None

request: Request

class bacommon.docui.v1.Request(path: str, method: RequestMethod = RequestMethod.GET, args: dict = <factory>)

Bases: DocUIRequest

Full request to doc-ui.

args: dict

classmethod get_type_id() → DocUIRequestTypeID

Return the type-id for this subclass.

method: RequestMethod = 'g'

path: str

class bacommon.docui.v1.RequestMethod(*values)

Bases: Enum

Typeof of requests that can be made to doc-ui servers.

GET = 'g'

Fetch some resource. This can be retried and its results can optionally be cached for some amount of time.

POST = 'p'

Change some resource. This cannot be implicitly retried (at least without deduplication), nor can it be cached.

UNKNOWN = 'u'

An unknown request method. This can appear if a newer client is requesting some method from an older server that is not known to the server.

class bacommon.docui.v1.Response(page: Page, status: ResponseStatus = ResponseStatus.SUCCESS, client_effects: list[Effect] = <factory>, local_action: str | None = None, local_action_args: dict | None = None, timed_action: Action | None = None, timed_action_delay: float = 0.0, minimum_engine_build: int | None = None, shared_state_id: str | None = None)

Bases: DocUIResponse

Full docui response.

classmethod get_type_id() → DocUIResponseTypeID

Return the type-id for this subclass.

local_action: str | None = None

Local action to run after this response is initially received. Will be handled by bauiv1lib.docui.DocUIController.local_action(). Note that these actions will not re-run if the page is automatically refreshed later (due to window resizing, back navigation, etc).

local_action_args: dict | None = None

minimum_engine_build: int | None = None

If provided, error on builds older than this (can be used to gate functionality without bumping entire docui version).

page: Page

shared_state_id: str | None = None

The client maintains some persistent state (such as widget selection) for all pages viewed. The default index for these states is the path of the request. If a server returns a significant variety of responses for a single path, however, (based on args, etc) then it may make sense for the server to provide explicit state ids for those different variations.

status: ResponseStatus = 0

timed_action: Action | None = None

New overall action to have the client schedule after this response is received. Useful for redirecting to other pages or closing the doc-ui window.

timed_action_delay: float = 0.0

class bacommon.docui.v1.ResponseStatus(*values)

Bases: Enum

The overall result of a request.

COMMUNICATION_ERROR = 2

Something went wrong talking to the server. A ‘Retry’ button may be appropriate to show here (for GET requests at least).

NOT_SIGNED_IN_ERROR = 3

This requires the user to be signed in, and they aint.

SUCCESS = 0

UNKNOWN_ERROR = 1

Something went wrong. That’s all we know.

class bacommon.docui.v1.Row

Bases: IOMultiType[RowTypeID]

Top level class for our multitype.

classmethod get_type(type_id: RowTypeID) → type[Row]

Return the subclass for each of our type-ids.

classmethod get_type_id() → RowTypeID

Return the type-id for this subclass.

classmethod get_type_id_storage_name() → str

Return the key used to store type id in serialized data.

The default is a short obscure value so that it is unlikely to conflict with members of individual type attrs, but in some cases one might prefer to serialize it to something simpler like ‘type’ by overriding this call. One just needs to make sure that no encompassed types serialize anything to that same name themself (dataclassio will error if they do).

classmethod get_unknown_type_fallback() → Row

Return a fallback object in cases of unrecognized types.

This can allow newer data to remain readable in older environments. Use caution with this option, however, as it effectively modifies data.

class bacommon.docui.v1.RowTypeID(*values)

Bases: Enum

Type ID for each of our subclasses.

BUTTON_ROW = 'b'

UNKNOWN = 'u'

class bacommon.docui.v1.Text(text: str, position: tuple[float, float], size: tuple[float, float], scale: float = 1.0, h_align: HAlign = HAlign.CENTER, v_align: VAlign = VAlign.CENTER, color: tuple[float, float, float, float] | None = None, flatness: float | None = None, shadow: float | None = None, is_lstr: bool = False, is_langstr: bool = False, wrap: WrapParams | None = None, highlight: bool = True, depth_range: tuple[float, float] | None = None, debug: bool = False)

Bases: Decoration

Text decoration.

color: tuple[float, float, float, float] | None = None

debug: bool = False

Show max-width/height bounds; useful during development.

depth_range: tuple[float, float] | None = None

flatness: float | None = None

classmethod get_type_id() → DecorationTypeID

Return the type-id for this subclass.

h_align: HAlign = 'c'

highlight: bool = True

is_langstr: bool = False

The text field holds a language-string (canonical resource-form wire JSON) to be evaluated natively at display and re-evaluated on language changes. Set by the client-side v2 transcode; mutually exclusive with is_lstr.

is_lstr: bool = False

position: tuple[float, float]

scale: float = 1.0

shadow: float | None = None

size: tuple[float, float]

Note that this effectively is max-width and max-height.

text: str

Note that doc-ui accepts only raw str values for text; use babase.Lstr.evaluate() or whatnot for multi-language support.

v_align: VAlign = 'c'

wrap: WrapParams | None = None

Line-wrap constraints applied to the text at widget-creation time. Set only by the client-local v2→v1 transcode; v1 producers must never send it (older clients can’t parse unknown fields — bake newlines into the string instead).

class bacommon.docui.v1.UnknownAction

Bases: Action

Action type we don’t recognize.

classmethod get_type_id() → ActionTypeID

Return the type-id for this subclass.

class bacommon.docui.v1.UnknownDecoration

Bases: Decoration

An unknown decoration.

In practice these should never show up since the master-server generates these on the fly for the client and so should not send clients one they can’t digest.

classmethod get_type_id() → DecorationTypeID

Return the type-id for this subclass.

class bacommon.docui.v1.UnknownRow

Bases: Row

A row type we don’t have.

classmethod get_type_id() → RowTypeID

Return the type-id for this subclass.

class bacommon.docui.v1.VAlign(*values)

Bases: Enum

Vertical alignment.

BOTTOM = 'b'

CENTER = 'c'

TOP = 't'

bacommon.docui.v2 module

Version 2 doc-ui types – language-agnostic (l-string) text.

Where v1 carries pre-localized raw str text (optionally a JSON-encoded legacy babase.Lstr via *_is_lstr flags) and expects the server to localize, v2 text is always a language-agnostic LangStrSpec. The server ships one response to every client regardless of language; the client resolves the referenced asset-packages in its own locale and decodes the strings at render time.

See docs/initiatives/docui-v2-lstrings.md (ballistica-internal). This is the milestone-1 slice: a minimal but real subset of the v1 element set, with text typed as LangStrSpec (the name-based form – subs are flat for now). Non-text fields mirror v1’s names/keys so client render code can stay close to v1prep.

class bacommon.docui.v2.Action

Bases: IOMultiType[ActionTypeID]

Something that happens when a button is pressed.

classmethod get_type(type_id: ActionTypeID) → type[Action]

Return a specific subclass given a type-id.

Should be overridden by child classes. Generally, users of the class should call get_type_cached() instead of this, as it is more efficient.

classmethod get_type_id() → ActionTypeID

Return the type-id for this subclass.

classmethod get_type_id_storage_name() → str

Return the key used to store type id in serialized data.

The default is a short obscure value so that it is unlikely to conflict with members of individual type attrs, but in some cases one might prefer to serialize it to something simpler like ‘type’ by overriding this call. One just needs to make sure that no encompassed types serialize anything to that same name themself (dataclassio will error if they do).

classmethod get_unknown_type_fallback() → Action

Return a fallback object in cases of unrecognized types.

This can allow newer data to remain readable in older environments. Use caution with this option, however, as it effectively modifies data.

class bacommon.docui.v2.ActionTypeID(*values)

Bases: Enum

Type ID for each of our subclasses.

BROWSE = 'b'

LOCAL = 'l'

REPLACE = 'r'

UNKNOWN = 'u'

class bacommon.docui.v2.Browse(request: Request, default_sound: bool = True)

Bases: Action

Browse to a new page in a new window.

default_sound: bool = True

Plays a swish.

classmethod get_type_id() → ActionTypeID

Return the type-id for this subclass.

request: Request

class bacommon.docui.v2.Button(label: LangStrSpec | int | None = None, action: Action | None = None, size: tuple[float, float] | None = None, color: tuple[float, float, float, float] | None = None, label_color: tuple[float, float, float, float] | None = None, label_scale: float | None = None, label_flatness: float | None = None, texture: TextureSpec | int | None = None, scale: float = 1.0, padding_left: float = 0.0, padding_top: float = 0.0, padding_right: float = 0.0, padding_bottom: float = 0.0, decorations: list[Decoration] | None = None, style: ButtonStyle = ButtonStyle.SQUARE, default: bool = False, selected: bool = False, icon: TextureSpec | int | None = None, icon_scale: float | None = None, icon_color: tuple[float, float, float, float] | None = None, depth_range: tuple[float, float] | None = None, widget_id: str | None = None, debug: bool = False)

Bases: object

A button in our doc-ui.

label is a language-agnostic LangStrSpec. Size, padding, and all decorations scale consistently with scale.

action: Action | None = None

color: tuple[float, float, float, float] | None = None

debug: bool = False

Draw bounds of the button.

decorations: list[Decoration] | None = None

default: bool = False

depth_range: tuple[float, float] | None = None

icon: TextureSpec | int | None = None

icon_color: tuple[float, float, float, float] | None = None

icon_scale: float | None = None

label: LangStrSpec | int | None = None

label_color: tuple[float, float, float, float] | None = None

label_flatness: float | None = None

label_scale: float | None = None

padding_bottom: float = 0.0

padding_left: float = 0.0

padding_right: float = 0.0

padding_top: float = 0.0

scale: float = 1.0

selected: bool = False

size: tuple[float, float] | None = None

style: ButtonStyle = 'q'

texture: TextureSpec | int | None = None

widget_id: str | None = None

Custom widget id. Prefixed with the window id; unique within window.

class bacommon.docui.v2.ButtonRow(buttons: list[Button], header_height: float = 0.0, header_scale: float = 1.0, header_decorations_left: list[Decoration] | None = None, header_decorations_center: list[Decoration] | None = None, header_decorations_right: list[Decoration] | None = None, title: LangStrSpec | int | None = None, title_color: tuple[float, float, float, float] | None = None, title_flatness: float | None = None, title_shadow: float | None = None, subtitle: LangStrSpec | int | None = None, subtitle_color: tuple[float, float, float, float] | None = None, subtitle_flatness: float | None = None, subtitle_shadow: float | None = None, button_spacing: float = 15.0, padding_left: float = 10.0, padding_right: float = 10.0, padding_top: float = 10.0, padding_bottom: float = 10.0, spacing_top: float = 0.0, spacing_bottom: float = 0.0, center_content: bool = False, center_title: bool = False, simple_culling_h: float = 100.0, debug: bool = False)

Bases: Row

A row consisting of buttons.

title/subtitle are LangStrSpec.

button_spacing: float = 15.0

Spacing between all buttons in the row.

buttons: list[Button]

center_content: bool = False

center_title: bool = False

debug: bool = False

Draw bounds of the row and its button columns.

classmethod get_type_id() → RowTypeID

Return the type-id for this subclass.

header_decorations_center: list[Decoration] | None = None

header_decorations_left: list[Decoration] | None = None

header_decorations_right: list[Decoration] | None = None

header_height: float = 0.0

header_scale: float = 1.0

padding_bottom: float = 10.0

padding_left: float = 10.0

padding_right: float = 10.0

padding_top: float = 10.0

simple_culling_h: float = 100.0

If things disappear when scrolling left/right, turn this up.

spacing_bottom: float = 0.0

Extra space below the row’s horizontally-scrollable area.

spacing_top: float = 0.0

Extra space above the row’s horizontally-scrollable area.

subtitle: LangStrSpec | int | None = None

subtitle_color: tuple[float, float, float, float] | None = None

subtitle_flatness: float | None = None

subtitle_shadow: float | None = None

title: LangStrSpec | int | None = None

title_color: tuple[float, float, float, float] | None = None

title_flatness: float | None = None

title_shadow: float | None = None

class bacommon.docui.v2.ButtonStyle(*values)

Bases: Enum

Styles a button can be.

BACK = 'b'

BACK_SMALL = 'bs'

LARGE = 'l'

LARGER = 'xl'

MEDIUM = 'm'

SMALL = 's'

SQUARE = 'q'

SQUARE_WIDE = 'w'

TAB = 't'

class bacommon.docui.v2.Decoration

Bases: IOMultiType[DecorationTypeID]

Top level class for our decoration multitype.

classmethod get_type(type_id: DecorationTypeID) → type[Decoration]

Return a specific subclass given a type-id.

Should be overridden by child classes. Generally, users of the class should call get_type_cached() instead of this, as it is more efficient.

classmethod get_type_id() → DecorationTypeID

Return the type-id for this subclass.

classmethod get_type_id_storage_name() → str

Return the key used to store type id in serialized data.

The default is a short obscure value so that it is unlikely to conflict with members of individual type attrs, but in some cases one might prefer to serialize it to something simpler like ‘type’ by overriding this call. One just needs to make sure that no encompassed types serialize anything to that same name themself (dataclassio will error if they do).

classmethod get_unknown_type_fallback() → Decoration

Return a fallback object in cases of unrecognized types.

This can allow newer data to remain readable in older environments. Use caution with this option, however, as it effectively modifies data.

class bacommon.docui.v2.DecorationTypeID(*values)

Bases: Enum

Type ID for each of our subclasses.

DISPLAY_ITEM = 'd'

FRAME = 'f'

IMAGE = 'i'

TEXT = 't'

UNKNOWN = 'u'

class bacommon.docui.v2.DisplayItem(wrapper: Wrapper, position: tuple[float, float], size: tuple[float, float], style: DisplayItemStyle = DisplayItemStyle.FULL, text_color: tuple[float, float, float] | None = None, highlight: bool = True, depth_range: tuple[float, float] | None = None, debug: bool = False)

Bases: Decoration

DisplayItem decoration.

The wrapped Wrapper already localizes its own text client-side, so it carries over from v1 unchanged.

debug: bool = False

depth_range: tuple[float, float] | None = None

classmethod get_type_id() → DecorationTypeID

Return the type-id for this subclass.

highlight: bool = True

position: tuple[float, float]

size: tuple[float, float]

style: DisplayItemStyle = 'f'

text_color: tuple[float, float, float] | None = None

wrapper: Wrapper

class bacommon.docui.v2.DisplayItemStyle(*values)

Bases: Enum

Styles a display-item can be drawn in (mirrors v1).

COMPACT = 'c'

Fully conveys the item, condensed into a 2x1 box for small sizes.

FULL = 'f'

Fully conveys what the item is. Draws in a 4x3 box and works best with large-ish displays.

ICON = 'i'

Graphics-only representation in a 1x1 box, for use alongside a textual description.

class bacommon.docui.v2.Frame(decorations: list[Decoration], position: tuple[float, float], scale: float = 1.0, highlight: bool = True, size: tuple[float, float] | None = None, h_align: HAlign = HAlign.CENTER, v_align: VAlign = VAlign.CENTER, debug: bool = False)

Bases: Decoration

A self-contained grouping of non-interactive decorations.

A frame lets a producer describe how something looks — an item, a badge, a composed graphic — instead of naming a thing the client must already know how to draw. Its children are positioned relative to the frame’s own origin and are transformed as a group, so the same frame can be placed anywhere at any size.

Frames are decorations themselves, so they embed in doc-ui pages like any other; they can also be drawn straight into a plain container widget. They are deliberately non-interactive for now.

By default a frame imposes no bounds – it knows only where its center is and how big to draw. Give it a size and it instead fits its children into that box; see there.

debug: bool = False

Draw this frame’s bounds; useful during development. Shows the size box and, inside it, the extent the children actually occupy – so a composition that does not sit where it was meant to is visible rather than inferred.

decorations: list[Decoration]

Child decorations, positioned relative to this frame’s origin. Nested frames are allowed – except under size.

classmethod get_type_id() → DecorationTypeID

Return the type-id for this subclass.

h_align: HAlign = 'c'

Where the fitted content sits in size. Only matters when the content is smaller than the box, since content that had to shrink already fills it on the binding axis.

highlight: bool = True

position: tuple[float, float]

scale: float = 1.0

size: tuple[float, float] | None = None

Fit the children into this box – measure their combined extent, center that on the frame’s position, and scale it down (never up) if it would not otherwise fit.

This exists so a producer can compose things whose size it cannot know. Centering a count beside its currency icon needs the count’s rendered width, which only the client can measure – so the producer says “these two, together, in this box” and the client works out the rest at prep time, where it is already measuring text.

Children must be text and images only. Their combined extent has to be computable before anything is drawn, which rules out nested frames and display-items. A frame that breaks this draws unfitted rather than silently mis-centering.

v_align: VAlign = 'c'

class bacommon.docui.v2.HAlign(*values)

Bases: Enum

Horizontal alignment.

CENTER = 'c'

LEFT = 'l'

RIGHT = 'r'

class bacommon.docui.v2.Image(texture: TextureSpec | int, position: tuple[float, float], size: tuple[float, float], color: tuple[float, float, float, float] | None = None, h_align: HAlign = HAlign.CENTER, v_align: VAlign = VAlign.CENTER, tint_texture: TextureSpec | int | None = None, tint_color: tuple[float, float, float] | None = None, tint2_color: tuple[float, float, float] | None = None, mask_texture: TextureSpec | int | None = None, mesh_opaque: MeshSpec | int | None = None, mesh_transparent: MeshSpec | int | None = None, highlight: bool = True, depth_range: tuple[float, float] | None = None, debug: bool = False)

Bases: Decoration

Image decoration. Textures/meshes are language-independent refs.

Unlike text, image assets need no per-locale decode; each ref (TextureSpec / MeshSpec) is resolved by the client and rendered directly.

color: tuple[float, float, float, float] | None = None

debug: bool = False

Show this image’s bounds; useful during development. Worth having separately from the art because a texture with a transparent margin gives no clue where its box really is.

depth_range: tuple[float, float] | None = None

classmethod get_type_id() → DecorationTypeID

Return the type-id for this subclass.

h_align: HAlign = 'c'

highlight: bool = True

mask_texture: TextureSpec | int | None = None

mesh_opaque: MeshSpec | int | None = None

mesh_transparent: MeshSpec | int | None = None

position: tuple[float, float]

size: tuple[float, float]

texture: TextureSpec | int

The image’s texture. An int is the indexed form – a flat index into the textures domain of Response.packages (see bacommon.assetspec._index); the client swaps it for a TextureSpec while resolving, so everything downstream of resolve sees only specs. Old clients are served the spec form.

tint2_color: tuple[float, float, float] | None = None

tint_color: tuple[float, float, float] | None = None

tint_texture: TextureSpec | int | None = None

v_align: VAlign = 'c'

class bacommon.docui.v2.Local(close_window: bool = False, default_sound: bool = True, immediate_client_effects: list[Effect] = <factory>, immediate_local_action: str | None = None, immediate_local_action_args: dict | None = None)

Bases: Action

Perform only local actions; no new requests or page changes.

close_window: bool = False

default_sound: bool = True

Plays a swish if closing the window, else a click.

classmethod get_type_id() → ActionTypeID

Return the type-id for this subclass.

immediate_local_action: str | None = None

Local action to run immediately when the button is pressed. Will be handled by bauiv1lib.docui.DocUIController.local_action().

immediate_local_action_args: dict | None = None

class bacommon.docui.v2.Page(title: LangStrSpec | int, rows: list[Row], center_vertically: bool = False, row_spacing: float = 10.0, simple_culling_v: float = 100.0, padding_bottom: float = 0.0, padding_left: float = 0.0, padding_top: float = 0.0, padding_right: float = 0.0)

Bases: object

Doc-UI page version 2.

title is a language-agnostic LangStrSpec.

center_vertically: bool = False

Center content vertically when it’s smaller than the available height.

padding_bottom: float = 0.0

padding_left: float = 0.0

padding_right: float = 0.0

padding_top: float = 0.0

row_spacing: float = 10.0

rows: list[Row]

simple_culling_v: float = 100.0

If things disappear when scrolling up/down, turn this up.

title: LangStrSpec | int

class bacommon.docui.v2.Replace(request: Request, default_sound: bool = True)

Bases: Action

Replace the current page with a new one (seamless transition).

default_sound: bool = True

Plays a click if triggered by a button press.

classmethod get_type_id() → ActionTypeID

Return the type-id for this subclass.

request: Request

class bacommon.docui.v2.Request(path: str, method: RequestMethod = RequestMethod.GET, args: dict = <factory>)

Bases: DocUIRequest

Full request to doc-ui (v2).

args: dict

classmethod get_type_id() → DocUIRequestTypeID

Return the type-id for this subclass.

method: RequestMethod = 'g'

path: str

class bacommon.docui.v2.RequestMethod(*values)

Bases: Enum

Type of requests that can be made to doc-ui servers.

GET = 'g'

Fetch some resource. Retriable; results optionally cacheable.

POST = 'p'

Change some resource. Not implicitly retriable, not cacheable.

UNKNOWN = 'u'

An unknown request method (newer client -> older server).

class bacommon.docui.v2.Response(page: Page, status: ResponseStatus = ResponseStatus.SUCCESS, for_build: int | None = None, packages: list[str] = <factory>, asset_index_digest: str | None = None, langstr_index_digest: str | None = None, client_effects: list[Effect] = <factory>, local_action: str | None = None, local_action_args: dict | None = None, timed_action: Action | None = None, timed_action_delay: float = 0.0, minimum_engine_build: int | None = None, shared_state_id: str | None = None)

Bases: DocUIResponse

Full docui response (v2).

asset_index_digest: str | None = None

Digest of the exact asset-index domain the producer indexed against, from domain_digest(). The two ends build that domain from different sources, and a disagreement is invisible on its own – an index that is wrong but still in range simply names a different asset, so the page renders with the wrong art and nothing logs. A consumer whose own digest differs must refuse to de-index rather than trust it; leaving the integers in place makes the failure loud and names the packages involved. Set only when asset refs were indexed.

for_build: int | None = None

The engine build this response was built for, as a sanity check: responses can be tailored per-build (client-effect forms etc.), so a consumer seeing a mismatch with its own build should treat the response as stale (e.g. toss cached data) rather than use it.

classmethod get_type_id() → DocUIResponseTypeID

Return the type-id for this subclass.

langstr_index_digest: str | None = None

The same guard for folded language-string references, from domain_digest(). Separate from the asset digest so a mismatch says which of the two domains drifted. Set only when string refs were folded.

local_action: str | None = None

Local action to run after this response is initially received (not re-run on automatic page refreshes). Will be handled by bauiv1lib.docui.DocUIController.local_action().

local_action_args: dict | None = None

minimum_engine_build: int | None = None

If provided, error on builds older than this.

packages: list[str]

Asset-package-versions the response’s integer-indexed language-strings resolve against (position = package index). Present only on wire responses finalized to the indexed form by the server; its presence declares the page + contained client effects fully indexed (consumers may flag resource-form leaks), and it doubles as the client’s resolve/pre-warm manifest. Locally-authored responses never carry it (indexing is a wire compression; local pages stay in the authored resource form).

page: Page

shared_state_id: str | None = None

Explicit shared-state id (defaults to the request path client-side).

status: ResponseStatus = 0

timed_action: Action | None = None

New overall action to have the client schedule after this response is received. Useful for redirecting to other pages or closing the doc-ui window.

timed_action_delay: float = 0.0

class bacommon.docui.v2.ResponseStatus(*values)

Bases: Enum

The overall result of a request.

COMMUNICATION_ERROR = 2

Something went wrong talking to the server. A ‘Retry’ may be apt.

NOT_SIGNED_IN_ERROR = 3

This requires the user to be signed in, and they aint.

SUCCESS = 0

UNKNOWN_ERROR = 1

Something went wrong. That’s all we know.

class bacommon.docui.v2.Row

Bases: IOMultiType[RowTypeID]

Top level class for our row multitype.

classmethod get_type(type_id: RowTypeID) → type[Row]

Return a specific subclass given a type-id.

Should be overridden by child classes. Generally, users of the class should call get_type_cached() instead of this, as it is more efficient.

classmethod get_type_id() → RowTypeID

Return the type-id for this subclass.

classmethod get_type_id_storage_name() → str

Return the key used to store type id in serialized data.

The default is a short obscure value so that it is unlikely to conflict with members of individual type attrs, but in some cases one might prefer to serialize it to something simpler like ‘type’ by overriding this call. One just needs to make sure that no encompassed types serialize anything to that same name themself (dataclassio will error if they do).

classmethod get_unknown_type_fallback() → Row

Return a fallback object in cases of unrecognized types.

This can allow newer data to remain readable in older environments. Use caution with this option, however, as it effectively modifies data.

class bacommon.docui.v2.RowTypeID(*values)

Bases: Enum

Type ID for each of our subclasses.

BUTTON_ROW = 'b'

UNKNOWN = 'u'

class bacommon.docui.v2.Text(text: LangStrSpec | int, position: tuple[float, float], size: tuple[float, float], scale: float = 1.0, h_align: HAlign = HAlign.CENTER, v_align: VAlign = VAlign.CENTER, color: tuple[float, float, float, float] | None = None, flatness: float | None = None, shadow: float | None = None, highlight: bool = True, depth_range: tuple[float, float] | None = None, debug: bool = False)

Bases: Decoration

Text decoration.

text is a language-agnostic LangStrSpec.

color: tuple[float, float, float, float] | None = None

debug: bool = False

Show max-width/height bounds; useful during development.

depth_range: tuple[float, float] | None = None

flatness: float | None = None

classmethod get_type_id() → DecorationTypeID

Return the type-id for this subclass.

h_align: HAlign = 'c'

highlight: bool = True

position: tuple[float, float]

scale: float = 1.0

shadow: float | None = None

size: tuple[float, float]

Effectively max-width and max-height.

text: LangStrSpec | int

The text. An int is the indexed form – a flat index into the string domain of Response.packages (see bacommon.langstr._flatindex); the client unfolds it into the two-integer form the native decoder consumes while resolving. Strings carrying substitutions never fold.

v_align: VAlign = 'c'

class bacommon.docui.v2.UnknownAction

Bases: Action

Action type we don’t recognize.

classmethod get_type_id() → ActionTypeID

Return the type-id for this subclass.

class bacommon.docui.v2.UnknownDecoration

Bases: Decoration

An unknown decoration (should never reach a client in practice).

classmethod get_type_id() → DecorationTypeID

Return the type-id for this subclass.

class bacommon.docui.v2.UnknownRow

Bases: Row

A row type we don’t have.

classmethod get_type_id() → RowTypeID

Return the type-id for this subclass.

class bacommon.docui.v2.VAlign(*values)

Bases: Enum

Vertical alignment.

BOTTOM = 'b'

CENTER = 'c'

TOP = 't'

bacommon.docui.walk module

One traversal of a doc-ui page’s language-strings and asset refs.

Several things need to visit every string slot or every asset reference in a page: the client resolves the packages they name before rendering, the server rewrites them to their indexed wire forms, and so on. Each of those used to walk the page itself.

That went wrong the same way three times. Every walk matched decorations with an isinstance chain and no final else, so a decoration type a given walk had not been taught about contributed nothing and the walk returned a plausible answer – silently short of the truth. Adding Frame missed three of the four places that needed it.

So the traversal lives here once, and it dispatches on DecorationTypeID with assert_never on the end. A new decoration type is now a type error in a single file rather than a silent omission in an unknown number of them.

Callbacks may return a replacement value (or None to leave a slot alone), which is what lets one traversal serve both the read-only consumers and the ones that rewrite in place.