bauiv1lib.docui package

Functionality for using doc-ui on top of bauiv1.

Threading design

Doc-ui deliberately offloads as much processing as possible to background threads, keeping logic-thread work to the bare minimum (instantiating widgets and running actions/effects). A request’s whole journey — controller fulfillment (including cloud/web round-trips), response validation, asset-package resolution (marshalled to the logic thread only for the async resolve await itself), l-string decode, and full page prep — runs via DocUIController._process_request_in_bg on a capped, self-retiring background thread (see _bgrunner), kept off the shared threadpool because this prep is long and blocking (an asset-package construct/download can tie a thread up for seconds). Only the final prepped page is pushed back to the logic thread for widget instantiation.

Code called from that flow (controller fulfill_request overrides especially) should preserve this: do the heavy lifting where you are called (the bg thread) rather than pushing work to the logic thread, and never assume logic-thread context without checking.

class bauiv1lib.docui.DocUIController

Bases: object

Manages interactions between DocUI clients and servers.

Can include logic to handle all requests locally or can submit them to be handled by some server or can do some combination thereof.

class ErrorType(*values)

Bases: Enum

Types of errors that can occur in request processing.

COMMUNICATION_ERROR = 'communication'

GENERIC = 'generic'

NEED_UPDATE = 'need_update'

UNDER_CONSTRUCTION = 'under_construction'

create_window(request: DocUIRequest, *, transition: str | None = 'in_right', origin_widget: bui.Widget | None = None, auxiliary_style: bool = True, uiopenstateid: str | None = None, suppress_win_extra_type_warning: bool = False) → DocUIWindow

Create a new window to handle a request.

error_response(request: DocUIRequest, error_type: ErrorType = ErrorType.GENERIC, custom_message: str | None = None) → DocUIResponse

Build a simple error message page.

A message is included based on error_type. Pass custom_message to override this.

Messages are language-agnostic (bundled-package strings), so error pages localize like any other doc-ui content; a custom_message shows verbatim (untranslated).

fulfill_request(request: DocUIRequest) → DocUIResponse

Handle request fulfillment.

Expected to be overridden by child classes.

Be aware that this will always be called in a background thread.

This method is expected to always return a response, even in the case of errors. Use error_response() to translate error conditions to responses.

The one exception to this rule (no pun intended) is the efro.error.CleanError exception. This can be raised as a quick and dirty way to show custom error messages. The code raise CleanError('Something broke.') will have the same effect as return self.error_response(custom_message='Something broke.').

fulfill_request_web(request: DocUIRequest, url: str) → DocUIResponse

Fulfill a request by sending it to a webserver.

classmethod get_window_extra_type_id() → str

Return a string suitable for the window_extra_type_id arg to auxiliary_window_activate().

This ensures your doc-ui window is identified distinctly from other doc-ui windows for navigation purposes.

local_action(action: DocUILocalAction) → None

Do something locally on behalf of the doc-ui.

Controller classes can override this to expose named actions that can be triggered by doc-ui button presses, responses, etc.

Of course controllers can also perform arbitrary local actions alongside their normal request fulfillment; this is simply a way to do so without needing to provide actual ui pages alongside.

Be very careful and focused with what you expose here, especially if your doc-ui pages are coming from untrusted sources. Generally things like launching or joining games are good candidates for local actions.

replace(win: DocUIWindow, request: DocUIRequest, *, origin_widget: bui.Widget | None = None, is_refresh: bool = False) → None

Kick off a request to replace existing window contents.

restore(win: DocUIWindow, *, last_response: DocUIResponse | None, has_had_response: bool) → DocUIWindow

Restore a window from previous state.

May immediately display old results or may kick off a new request.

restore_window_shared_state(window: DocUIWindow, state: dict) → None

Called when a window shared state is being restored.

run_action(window: DocUIWindow, widgetid: str | None, action: bacommon.docui.v2.Action | None, is_timed: bool = False) → None

Called when a button is pressed in a doc-ui.

save_window_shared_state(window: DocUIWindow, state: dict) → None

Called when a window shared state is being saved.

class bauiv1lib.docui.DocUILocalAction(name: str, args: dict, widget: bui.Widget | None, window: DocUIWindow)

Bases: object

Context for a local-action.

args: dict

name: str

widget: bui.Widget | None

window: DocUIWindow

class bauiv1lib.docui.DocUIWindow(controller: DocUIController, request: DocUIRequest, *, transition: str | None = 'in_right', origin_widget: bui.Widget | None = None, auxiliary_style: bool = True, restored: bool = False, uiopenstateid: str | None = None, suppress_win_extra_type_warning: bool = False, has_had_response: bool = False)

Bases: MainWindow

Window showing doc-ui content.

get_main_window_shared_state_id() → str | None

Provide a custom id for window shared state.

Unlike MainWindowState, which is used to save and restore a single main-window instance, shared-state is intended to hold values that can apply to multiple instances of a window.

By default, shared state uses the window class as an index (so is shared by all windows of the same class), but this method can be overridden to provide more distinct states. For example, a store-page main-window class might want to keep distinct states for different sub-pages it can display instead of having a single state for the whole class.

Note that shared state only persists for the current run of the app.

get_main_window_state() → MainWindowState

Return a WindowState to recreate this specific window.

Used to gracefully return to a window from another window or ui system.

lock_ui(origin_widget: Widget | None = None) → None

Stop UI interactions during some operation.

property locked: bool

Are we locked?

main_window_do_restore_shared_state(state: dict) → None

Restore state from the provided shared state dict.

Can be overridden by subclasses to restore custom data.

main_window_do_save_shared_state(state: dict) → None

Save state into the provided shared state dict.

Can be overridden by subclasses to save custom data.

main_window_should_preserve_selection() → bool

Whether this window should auto-save/restore selection.

If enabled, selection will be stored in the window’s shared state. See get_main_window_shared_state_id() for more info about main-window shared-state.

The default value of None results in a warning to explicitly override this (as the implicit default will change from False to True after api 9 support ends).

property request: DocUIRequest

The current request.

Should only be accessed from the logic thread while the ui is unlocked.

property scroll_height: float

Height of our scroll area.

property scroll_width: float

Width of our scroll area.

set_last_response(response: DocUIResponse, success: bool) → None

Set a response to a request.

unlock_ui() → None

Resume normal UI interactions.

Subpackages

• bauiv1lib.docui.prep package