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 an obscure value so that it does not 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 ‘type’ themself.

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'

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 an obscure value so that it does not 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 ‘type’ themself.

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'

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.

Submodules

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 an obscure value so that it does not 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 ‘type’ themself.

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: ~bacommon.docui.v1.Request, default_sound: bool = True, immediate_client_effects: list[~bacommon.clienteffect.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, 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_lstr: bool = False

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: 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, 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, 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_lstr: bool = False

subtitle_shadow: float | None = None

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_lstr: bool = False

title_shadow: float | None = None

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.

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 an obscure value so that it does not 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 ‘type’ themself.

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[~bacommon.clienteffect.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, 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_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.

class bacommon.docui.v1.Replace(request: ~bacommon.docui.v1.Request, default_sound: bool = True, immediate_client_effects: list[~bacommon.clienteffect.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: ~bacommon.docui.v1.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: ~bacommon.docui.v1.Page, status: ~bacommon.docui.v1.ResponseStatus = ResponseStatus.SUCCESS, client_effects: list[~bacommon.clienteffect.Effect] = <factory>, local_action: str | None = None, local_action_args: dict | None = None, timed_action: ~bacommon.docui.v1.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 an obscure value so that it does not 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 ‘type’ themself.

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, 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_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'

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'