Source code for _bauiv1
# Released under the MIT License. See LICENSE for details.
#
"""A dummy stub module for the real _bauiv1.
The real _bauiv1 is a compiled extension module and only available
in the live engine. This dummy-module allows Pylint/Mypy/etc. to
function reasonably well outside of that environment.
Make sure this file is never included in dirs seen by the engine!
In the future perhaps this can be a stub (.pyi) file, but we will need
to make sure that it works with all our tools (mypy, pylint).
NOTE: This file was autogenerated by batools.dummymodule; do not edit by hand.
"""
from __future__ import annotations # Docs-generation hack.
# I'm sorry Pylint. I know this file saddens you. Be strong.
# pylint: disable=useless-suppression
# pylint: disable=unnecessary-pass
# pylint: disable=use-dict-literal
# pylint: disable=use-list-literal
# pylint: disable=unused-argument
# pylint: disable=missing-docstring
# pylint: disable=too-many-locals
# pylint: disable=redefined-builtin
# pylint: disable=too-many-lines
# pylint: disable=redefined-outer-name
# pylint: disable=invalid-name
# pylint: disable=no-value-for-parameter
# pylint: disable=unused-import
# pylint: disable=too-many-positional-arguments
from typing import TYPE_CHECKING, override
from warnings import deprecated
if TYPE_CHECKING:
from typing import Any, Callable, Literal, Sequence
import babase
import bacommon.langstr
import bauiv1
def _uninferrable() -> Any:
"""Get an "Any" in mypy and "uninferrable" in Pylint."""
# pylint: disable=undefined-variable
return _not_a_real_variable # type: ignore
class MeshViewer:
"""A few meshes drawn turning in a picture of their own.
What a mesh-viewer depiction shows: give it one with
:meth:`set_depiction` and show it by handing its :attr:`source`
to whatever draws viewers. It frames its meshes to fill the
picture, turns them slowly, and can be swung around
(:meth:`orbit`). It runs only while its picture is being drawn.
Size is in pixels; whatever shows the picture sets it to the
size it shows it at.
The viewer lives as long as this object does.
:meta private:
"""
def __init__(self, width: int, height: int) -> None:
pass
@property
def source(self) -> bauiv1.ViewerSource:
"""Us as something a live depiction can show. It holds no claim
on us; showing it once we are gone shows nothing.
"""
raise NotImplementedError()
def orbit(self, dx: float, dy: float) -> None:
"""Swing the view around by a drag.
Motion is in fractions of the picture's width and height, up
being positive; a full width across is half a turn.
"""
# This is a dummy stub; the actual implementation is native code.
return None
def set_default_background(self, color: tuple[float, float, float]) -> None:
"""Set what shows behind the meshes when a depiction doesn't say.
Whoever shows the viewer knows what blends in where (a doc-ui
viewer pane's own blank color, say).
"""
# This is a dummy stub; the actual implementation is native code.
return None
def set_depiction(self, json: str) -> bool:
"""Show what a mesh-viewer depiction's json describes.
Returns False (and shows nothing) if the json can't be used.
Showing the same json again does nothing; showing other meshes
reframes to fit them.
"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def shutdown(self) -> None:
"""Let go of the viewer for good.
Its source shows nothing from here on and most calls on this
object raise. Happens by itself when this object goes away;
call it to not depend on when that is.
"""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
class Sound:
"""Sound asset for local user interface purposes."""
[docs]
def play(self, volume: float = 1.0) -> None:
"""Play the sound locally."""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
def stop(self) -> None:
"""Stop the sound if it is playing."""
# This is a dummy stub; the actual implementation is native code.
return None
class ViewerSource:
"""Something that makes a picture for a live depiction to show.
These come from whatever provides such pictures (a scene viewer,
for instance) and are drawn by the depictions showing them.
They are made to outlast the widgets showing them, so a rebuilt
window can carry on showing what the old one was.
:meta private:
"""
def get_idle_time(self) -> float:
"""Return seconds (of display time) since a widget last showed us,
or since we were created if none ever has.
"""
# This is a dummy stub; the actual implementation is native code.
return float()
def mark_retired(self) -> None:
"""Note that our owner has retired us for good, so anything still
showing us asks for a viewer again (the viewer registry calls
this as it shuts a viewer down).
"""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
class Widget:
"""Internal type for low level UI elements; buttons, windows, etc.
This class represents a weak reference to a widget object
in the internal C++ layer. Currently, functions such as
bauiv1.buttonwidget() must be used to instantiate or edit these.
"""
#: Whether this widget is in the process of dying (read only).
#:
#: It can be useful to check this on a window's root widget to
#: prevent multiple window actions from firing simultaneously,
#: potentially leaving the UI in a broken state.
transitioning_out: bool
#: ID for this widget (if any).
id: str | None
#: Whether this widget should participate in auto selection
#: save/restore.
allow_preserve_selection: bool
#: The center of this widget in its parent widget's space.
center: tuple[float, float]
#: The parent widget (if any).
parent: bauiv1.Widget | None
#: Whether this widget can be selected.
selectable: bool
#: The widget that visually 'owns' this one — typically
#: set when an overlay textwidget represents the label of
#: an underlying buttonwidget; activating the draw
#: controller is the right way to act on the visual
#: widget. None for widgets with no draw controller set.
draw_controller: bauiv1.Widget | None
def __bool__(self) -> bool:
"""Support for bool evaluation."""
return bool(True) # Slight obfuscation.
[docs]
def activate(self) -> None:
"""Activates a widget; the same as if it had been clicked."""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
def add_delete_callback(self, call: Callable) -> None:
"""Add a call to be run immediately after this widget is destroyed."""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
def delete(self, ignore_missing: bool = True) -> None:
"""Delete the Widget. Ignores already-deleted Widgets if ignore_missing
is True; otherwise an Exception is thrown.
"""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
def exists(self) -> bool:
"""Returns whether the Widget still exists.
Most functionality will fail on a nonexistent widget.
Note that you can also use the boolean operator for this same
functionality, so a statement such as "if mywidget" will do
the right thing both for Widget objects and values of None.
"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def get_backing_opaque_rect(
self,
) -> tuple[float, float, float, float] | None:
"""For a container drawing a standard window backing, return
(left, bottom, right, top) of a rect known to lie within the
backing's fully-opaque pixels, in the space its children are
positioned in; None otherwise.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return (0.0, 0.0, 0.0, 0.0)
[docs]
def get_children(self) -> list[bauiv1.Widget]:
"""Returns any child Widgets of this Widget."""
# This is a dummy stub; the actual implementation is native code.
import bauiv1
return [bauiv1.Widget()]
[docs]
def get_screen_space_center(self) -> tuple[float, float]:
"""Returns the coords of the bauiv1.Widget center relative to the center
of the screen. This can be useful for placing pop-up windows and other
special cases.
"""
# This is a dummy stub; the actual implementation is native code.
return (0.0, 0.0)
[docs]
def get_scroll_state(self) -> tuple[float, float, float] | None:
"""For a scrolling widget, return (offset, content_extent,
visible_extent) along its scroll axis; None for other widgets.
The offset is in the widget's own terms, meaningful only to
:meth:`set_scroll_offset` on the same kind of widget. The extents
tell whether it still means the same thing: an offset saved from
one widget applies to another only if both extents match.
"""
# This is a dummy stub; the actual implementation is native code.
return (0.0, 0.0, 0.0)
[docs]
def get_selected_child(self) -> bauiv1.Widget | None:
"""Returns the selected child Widget or None if nothing is selected."""
# This is a dummy stub; the actual implementation is native code.
import bauiv1
return bauiv1.Widget()
[docs]
def get_slider_value(self) -> float | None:
"""Returns a slider Widget's current value, or None if this is not a
slider.
Slider callbacks announce every change, so UI code can simply track
the value it is given; this exists for callers that would rather ask
the widget than shadow it -- automation and tests especially. Note
that callbacks are deferred to the end of the current UI operation,
so within one operation this reports the live value while a
callback-tracked copy may not have caught up yet.
"""
# This is a dummy stub; the actual implementation is native code.
return 0.0
[docs]
def get_widget_type(self) -> str:
"""Return the internal type of the Widget as a string. Note that this
is different from the Python bauiv1.Widget type, which is the same for
all widgets.
"""
# This is a dummy stub; the actual implementation is native code.
return str()
def global_select(self) -> None:
"""Select this widget globally.
This should be used with caution. In general it is better to set
selected-child on container widgets.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
def scroll_into_view(self, animate: bool = True) -> None:
"""Scroll to show this widget if possible.
Pass animate=False to snap straight to the destination instead of
gliding. Use that when the scrolled content was itself just built,
since there is then nothing on screen for the motion to read as
movement from.
"""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
def set_scroll_offset(self, offset: float) -> None:
"""Jump a scrolling widget straight to an offset.
Takes an offset from :meth:`get_scroll_state`; clamped to the
content, with no glide and any inertia stopped. Raises TypeError
for widgets that don't scroll.
"""
# This is a dummy stub; the actual implementation is native code.
return None
def apmeshget(apvernum: int, name: str) -> bauiv1.Mesh:
"""Load a ui mesh from an asset-package (internal).
Do not call this directly; asset-package assets should be accessed
through their package's generated Python wrapper module, which routes
through this call. Requires a fully-qualified '<apvernum>:<path>'
asset name.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
import bauiv1 # pylint: disable=cyclic-import
return bauiv1.Mesh()
def apsoundget(apvernum: int, name: str) -> bauiv1.Sound:
"""Load a ui sound from an asset-package (internal).
Do not call this directly; asset-package assets should be accessed
through their package's generated Python wrapper module, which routes
through this call. Requires a fully-qualified '<apvernum>:<path>'
asset name.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
import bauiv1 # pylint: disable=cyclic-import
return bauiv1.Sound()
def aptextureget(apvernum: int, name: str) -> bauiv1.Texture:
"""Load a ui texture from an asset-package (internal).
Do not call this directly; asset-package assets should be accessed
through their package's generated Python wrapper module, which routes
through this call. Requires a fully-qualified '<apvernum>:<path>'
asset name.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
import bauiv1 # pylint: disable=cyclic-import
return bauiv1.Texture()
[docs]
def buttonwidget(
*,
edit: bauiv1.Widget | None = None,
parent: bauiv1.Widget | None = None,
id: str | None = None,
size: Sequence[float] | None = None,
position: Sequence[float] | None = None,
on_activate_call: Callable | None = None,
label: str | bauiv1.Lstr | bauiv1.LangStr | None = None,
color: Sequence[float] | None = None,
down_widget: bauiv1.Widget | None = None,
up_widget: bauiv1.Widget | None = None,
left_widget: bauiv1.Widget | None = None,
right_widget: bauiv1.Widget | None = None,
texture: bauiv1.Texture | None = None,
text_scale: float | None = None,
textcolor: Sequence[float] | None = None,
enable_sound: bool | None = None,
mesh_transparent: bauiv1.Mesh | None = None,
mesh_opaque: bauiv1.Mesh | None = None,
repeat: bool | None = None,
scale: float | None = None,
transition_delay: float | None = None,
on_select_call: Callable | None = None,
button_type: str | None = None,
extra_touch_border_scale: float | None = None,
selectable: bool | None = None,
show_buffer_top: float | None = None,
icon: bauiv1.Texture | None = None,
iconscale: float | None = None,
icon_tint: float | None = None,
icon_color: Sequence[float] | None = None,
autoselect: bool | None = None,
mask_texture: bauiv1.Texture | None = None,
tint_texture: bauiv1.Texture | None = None,
tint_color: Sequence[float] | None = None,
tint2_color: Sequence[float] | None = None,
text_flatness: float | None = None,
text_res_scale: float | None = None,
enabled: bool | None = None,
text_literal: bool | None = None,
opacity: float | None = None,
rotate: float | None = None,
better_bg_fit: bool | None = None,
transition_type: Literal['in_left', 'scale'] | None = None,
query: bauiv1.Widget | None = None,
on_actions_complete_call: Callable[[], None] | None = None,
text_h_align: Literal['left', 'center', 'right'] | None = None,
accessory: Literal['none', 'popup'] | None = None,
depiction: str | None = None,
depiction_key: str | None = None,
depiction_h_align: Literal['left', 'center', 'right'] | None = None,
depiction_v_align: Literal['top', 'center', 'bottom'] | None = None,
depiction_hit_area: bool | None = None,
depiction_debug: bool | None = None,
tint3_color: Sequence[float] | None = None,
depiction_suffix: str | None = None,
depiction_color_override: Sequence[float] | None = None,
depiction_use_color_override: bool | None = None,
) -> bauiv1.Widget:
"""Create or edit a button widget.
Pass a valid existing bauiv1.Widget as 'edit' to modify it; otherwise
a new one is created and returned. Arguments that are not set to None
are applied to the Widget.
Pass a button as 'query' to instead return its current label text as
a str (the translated form when the label is a language-string). This
mirrors textwidget's 'query' and is the only way to read a label that
was set directly on the button rather than via a separate overlaid
text widget.
'on_actions_complete_call' runs once after a press sequence that
activated the button is over: right after the activation for a
normal press or a key/controller press, and on release after the
last repeat of a held 'repeat' button. Use it to react to every
activation cheaply in 'on_activate_call' and do something costly
(a server round trip, say) only once at the end.
'text_h_align' places the label: centered (the default) or hugging
the left or right edge. 'accessory' draws a small indicator at the
right edge saying what a press does ('popup': opens a menu of
choices); the label's space shrinks to make room for it.
A button with 'enabled' False draws greyed out and can't be
activated, but remains selectable (if it otherwise would be), so
navigation around it is unaffected; a tap selects it, and a tap or
activation that would have fired it plays an error sound instead.
A button can show a depiction (a json-serialized
:class:`bacommon.depiction.Depiction`) as its body, in place of its
texture or standard look (pass an empty string to go back); the
label and icon still draw over it. The depiction flashes, pulses
and greys out with the button, and never takes its presses. The
depiction args work as for :func:`bauiv1.imagewidget`. To show one
elsewhere on a button, use an image with the button as its
``draw_controller``. With ``depiction_hit_area`` set, mouse and
touch only land on the button where its depiction actually draws
(an icon hugging one end of a wide button, say), grown to a
minimum size so small ones stay easy to tap; keyboard and
controller selection are unaffected.
"""
# This is a dummy stub; the actual implementation is native code.
import bauiv1 # pylint: disable=cyclic-import
return bauiv1.Widget()
[docs]
def checkboxwidget(
*,
edit: bauiv1.Widget | None = None,
parent: bauiv1.Widget | None = None,
id: str | None = None,
size: Sequence[float] | None = None,
position: Sequence[float] | None = None,
text: str | bauiv1.Lstr | bauiv1.LangStr | None = None,
value: bool | None = None,
on_value_change_call: Callable[[bool], None] | None = None,
on_select_call: Callable[[], None] | None = None,
text_scale: float | None = None,
textcolor: Sequence[float] | None = None,
scale: float | None = None,
is_radio_button: bool | None = None,
maxwidth: float | None = None,
autoselect: bool | None = None,
color: Sequence[float] | None = None,
style: Literal['default', 'right'] | None = None,
transition_delay: float | None = None,
transition_type: Literal['in_left', 'scale'] | None = None,
enabled: bool | None = None,
) -> bauiv1.Widget:
"""Create or edit a check-box widget.
Pass a valid existing bauiv1.Widget as 'edit' to modify it; otherwise
a new one is created and returned. Arguments that are not set to None
are applied to the Widget.
The ``'default'`` style places the box at the left with text
following it. The ``'right'`` style places text at the left bounds
of the widget and the box at the right bounds, and uses a uniform
selection glow. In that style the text is always fit to the space
left of the box, so ``maxwidth`` is unnecessary (if passed, it can
only shrink the text further).
A check box with ``enabled`` False draws greyed out and can't be
toggled, but remains selectable, so navigation around it is
unaffected; a tap selects it, and a tap or activation that would
have toggled it plays an error sound instead.
"""
# This is a dummy stub; the actual implementation is native code.
import bauiv1 # pylint: disable=cyclic-import
return bauiv1.Widget()
def clear_ui_asset_set_native() -> None:
"""(internal) Drop any app-mode-supplied ui asset set.
Called by UIV1AppSubsystem.reset() at each app-mode switch so an
incoming app-mode can never inherit the outgoing one's art.
"""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
def columnwidget(
*,
edit: bauiv1.Widget | None = None,
parent: bauiv1.Widget | None = None,
id: str | None = None,
size: Sequence[float] | None = None,
position: Sequence[float] | None = None,
background: bool | None = None,
selected_child: bauiv1.Widget | None = None,
visible_child: bauiv1.Widget | None = None,
single_depth: bool | None = None,
print_list_exit_instructions: bool | None = None,
left_border: float | None = None,
top_border: float | None = None,
bottom_border: float | None = None,
selection_loops_to_parent: bool | None = None,
border: float | None = None,
margin: float | None = None,
claims_left_right: bool | None = None,
) -> bauiv1.Widget:
"""Create or edit a column widget.
Pass a valid existing bauiv1.Widget as 'edit' to modify it; otherwise
a new one is created and returned. Arguments that are not set to None
are applied to the Widget.
"""
# This is a dummy stub; the actual implementation is native code.
import bauiv1 # pylint: disable=cyclic-import
return bauiv1.Widget()
[docs]
def containerwidget(
*,
edit: bauiv1.Widget | None = None,
parent: bauiv1.Widget | None = None,
id: str | None = None,
size: Sequence[float] | None = None,
position: Sequence[float] | None = None,
background: bool | None = None,
selected_child: bauiv1.Widget | None = None,
transition: str | None = None,
cancel_button: bauiv1.Widget | None = None,
start_button: bauiv1.Widget | None = None,
root_selectable: bool | None = None,
on_activate_call: Callable[[], None] | None = None,
claims_left_right: bool | None = None,
selection_loops: bool | None = None,
selection_loops_to_parent: bool | None = None,
scale: float | None = None,
on_outside_click_call: Callable[[], None] | None = None,
single_depth: bool | None = None,
visible_child: bauiv1.Widget | None = None,
stack_offset: Sequence[float] | None = None,
color: Sequence[float] | None = None,
on_cancel_call: Callable[[], None] | None = None,
print_list_exit_instructions: bool | None = None,
click_activate: bool | None = None,
always_highlight: bool | None = None,
selectable: bool | None = None,
scale_origin_stack_offset: Sequence[float] | None = None,
toolbar_visibility: (
Literal[
'menu_minimal',
'menu_minimal_no_back',
'menu_full',
'menu_full_no_back',
'menu_store',
'menu_store_no_back',
'menu_in_game',
'menu_tokens',
'no_menu_minimal',
'inherit',
]
| None
) = None,
toolbar_cancel_button_style: (
Literal[
'back',
'close',
]
| None
) = None,
on_select_call: Callable[[], None] | None = None,
claim_outside_clicks: bool | None = None,
claims_up_down: bool | None = None,
darken_behind: bool | None = None,
darken_behind_is_permanent: bool | None = None,
background_offset: Sequence[float] | None = None,
background_scale: Sequence[float] | None = None,
clean_layout: bool | None = None,
background_art: Literal['auto', 'tall', 'squat'] | None = None,
) -> bauiv1.Widget:
"""Create or edit a container widget.
Pass a valid existing bauiv1.Widget as 'edit' to modify it; otherwise
a new one is created and returned. Arguments that are not set to None
are applied to the Widget.
With 'clean_layout', the widget's bounds are exactly an area known to
lie within its background art's fully-opaque pixels, the art hanging
out around them by an amount set by the art alone, rather than being
placed around the bounds by historical fudge factors; size and place
such a container around whatever must sit on solid art. It also
scales in and out about its true center.
'background_art' picks which window backing art to draw: 'tall'
(boxier, for taller windows), 'squat' (rounder, for squatter ones),
or 'auto' (the default), which picks by the widget's shape.
'background_offset' shifts where the background art draws (x, y)
without moving anything else, for art whose placement doesn't suit
a particular window shape. 'background_scale' likewise scales it
(x, y) about its own center.
"""
# This is a dummy stub; the actual implementation is native code.
import bauiv1 # pylint: disable=cyclic-import
return bauiv1.Widget()
def flash_party_icon(duration: float) -> None:
"""Flash the party icon for a while (0 to stop).
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def get_depiction_control(widget: bauiv1.Widget) -> bauiv1.Viewer | None:
"""Get the object for driving an image's or button's depiction.
Some depictions have a live object behind them whose methods adjust
what is shown locally, without a new depiction from the server --
a live character viewer is its :class:`bauiv1.Viewer`, for
instance (a slider could recolor its character as it moves).
Returns None for depictions offering nothing (or not yet shown;
live objects are made the first time a depiction is drawn). What
is shown remains the server's to decide: the next depiction it
sends replaces local tweaks. Don't hold the object long; a
depiction can be replaced at any time.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
def get_qrcode_texture(url: str) -> bauiv1.Texture:
"""Return a QR code texture.
The provided url must be 64 bytes or less.
"""
# This is a dummy stub; the actual implementation is native code.
import bauiv1 # pylint: disable=cyclic-import
return bauiv1.Texture()
[docs]
def get_selected_widget() -> bauiv1.Widget | None:
"""Return the current globally selected widget, if any."""
# This is a dummy stub; the actual implementation is native code.
import bauiv1
return bauiv1.Widget()
[docs]
def get_special_widget(
name: Literal[
'squad_button',
'back_button',
'menu_button',
'account_button',
'achievements_button',
'settings_button',
'inbox_button',
'store_button',
'get_tokens_button',
'inventory_button',
'tickets_meter',
'tokens_meter',
'trophy_meter',
'level_meter',
'overlay_stack',
'chest_0_button',
'chest_1_button',
'chest_2_button',
'chest_3_button',
],
) -> bauiv1.Widget:
"""Return special widgets located in system toolbars."""
# This is a dummy stub; the actual implementation is native code.
import bauiv1 # pylint: disable=cyclic-import
return bauiv1.Widget()
[docs]
def getmesh(name: str) -> bauiv1.Mesh:
"""Load a mesh for use solely in the local user interface."""
# This is a dummy stub; the actual implementation is native code.
import bauiv1 # pylint: disable=cyclic-import
return bauiv1.Mesh()
[docs]
def getsound(name: str) -> bauiv1.Sound:
"""Load a sound for use in the ui."""
# This is a dummy stub; the actual implementation is native code.
import bauiv1 # pylint: disable=cyclic-import
return bauiv1.Sound()
[docs]
def gettexture(name: str) -> bauiv1.Texture:
"""Load a texture for use in the ui."""
# This is a dummy stub; the actual implementation is native code.
import bauiv1 # pylint: disable=cyclic-import
return bauiv1.Texture()
[docs]
def hscrollwidget(
*,
edit: bauiv1.Widget | None = None,
parent: bauiv1.Widget | None = None,
size: Sequence[float] | None = None,
position: Sequence[float] | None = None,
background: bool | None = None,
selected_child: bauiv1.Widget | None = None,
capture_arrows: bool | None = None,
on_select_call: Callable[[], None] | None = None,
center_small_content: bool | None = None,
color: Sequence[float] | None = None,
highlight: bool | None = None,
border_opacity: float | None = None,
simple_culling_h: float | None = None,
claims_left_right: bool | None = None,
claims_up_down: bool | None = None,
button_inset_left: float | None = None,
button_inset_right: float | None = None,
transition_in: bool | None = None,
scrollbar_visible: bool | None = None,
clean_layout: bool | None = None,
) -> bauiv1.Widget:
"""Create or edit a horizontal scroll widget.
The button insets nudge the page-left/page-right buttons in from
the widget's edges; scrolls extended across screen margins use
them to keep the buttons anchored to the virtual rect.
With 'scrollbar_visible' False, the scroll bar is neither drawn nor
mouse-grabbable; scrolling itself and layout are unaffected.
With 'clean_layout', content is laid out with none of the widget's
historical fudge offsets: it spans the full width (no inset at the
ends), sits right on the bottom edge (not lifted to clear the scroll
bar, which fades in over it), and is clipped exactly to the
widget's bounds.
Set 'transition_in' to have the page-left/page-right buttons animate
in when the widget first appears. Off by default, so they simply
start in their final form; turn it on only in ui that animates its
own contents in, so the buttons arrive along with everything else.
Pass a valid existing bauiv1.Widget as 'edit' to modify it; otherwise
a new one is created and returned. Arguments that are not set to None
are applied to the Widget.
"""
# This is a dummy stub; the actual implementation is native code.
import bauiv1 # pylint: disable=cyclic-import
return bauiv1.Widget()
[docs]
def imagewidget(
*,
edit: bauiv1.Widget | None = None,
parent: bauiv1.Widget | None = None,
size: Sequence[float] | None = None,
position: Sequence[float] | None = None,
color: Sequence[float] | None = None,
texture: bauiv1.Texture | None = None,
opacity: float | None = None,
rotate: float | None = None,
mesh_transparent: bauiv1.Mesh | None = None,
mesh_opaque: bauiv1.Mesh | None = None,
has_alpha_channel: bool = True,
tint_texture: bauiv1.Texture | None = None,
tint_color: Sequence[float] | None = None,
transition_delay: float | None = None,
draw_controller: bauiv1.Widget | None = None,
tint2_color: Sequence[float] | None = None,
tilt_scale: float | None = None,
mask_texture: bauiv1.Texture | None = None,
radial_amount: float | None = None,
draw_controller_mult: float | None = None,
depth_range: tuple[float, float] | None = None,
transition_type: Literal['in_left', 'scale', 'fade'] | None = None,
match_backing_glow: bool | None = None,
depiction: str | None = None,
depiction_key: str | None = None,
depiction_h_align: Literal['left', 'center', 'right'] | None = None,
depiction_v_align: Literal['top', 'center', 'bottom'] | None = None,
depiction_take_input: bool | None = None,
depiction_frame_color: Sequence[float] | None = None,
depiction_backing_color: Sequence[float] | None = None,
depiction_debug: bool | None = None,
tint3_color: Sequence[float] | None = None,
nine_patch_insets: Sequence[float] | None = None,
nine_patch_borders: Sequence[float] | None = None,
nine_patch_tile: Sequence[bool] | None = None,
depiction_suffix: str | None = None,
depiction_color_override: Sequence[float] | None = None,
depiction_use_color_override: bool | None = None,
depiction_overlay: bool | None = None,
depiction_small_placeholder: bool | None = None,
depiction_layered_mask: bool | None = None,
depiction_layer1_color: Sequence[float] | None = None,
depiction_layer2_color: Sequence[float] | None = None,
) -> bauiv1.Widget:
"""Create or edit an image widget.
Pass a valid existing bauiv1.Widget as 'edit' to modify it; otherwise
a new one is created and returned. Arguments that are not set to None
are applied to the Widget.
Set ``match_backing_glow`` on images drawn to blend into their
parent window's backing; their color then follows the backing's
brief glow as the window scales in (only the direct parent is
consulted).
Pass ``nine_patch_insets`` and ``nine_patch_borders`` together to
draw the texture as a 9-patch filling the image's box exactly:
the insets say where the texture splits into corners, edges and
middle (fractions of its width/height from the left, bottom,
right and top), the borders how big those edges draw (in the
image's own units, same order; a pair too big for the box shrinks
to fit). ``nine_patch_tile`` (horizontal, vertical) repeats the
middle at the corners' scale, fitted to a whole number of copies,
rather than stretching it; its art must tile seamlessly. Tint,
mask and color textures share the 9-patch's layout.
An image can show a depiction -- a json-serialized
:class:`bacommon.depiction.Depiction` (a character's icon, a name,
an image, a live 3d character, ...) -- in place of its texture
(pass an empty string to go back to the texture). One with a shape
of its own is fitted inside the image's box by
``depiction_h_align``/``depiction_v_align``; one without fills it.
Art that isn't local yet shows a standin and upgrades in place once
it arrives; a kind this build can't draw shows a placeholder (an
outlined box with a question mark). An unchanged depiction is kept
as is. The image's opacity, transitions, ``mask_texture`` and
``draw_controller`` apply to it, so one sitting on a button dims,
highlights and greys out with it.
``depiction_key`` names what the image shows (unique to it by
default): depictions with something long-lived behind them, like a
live viewer, carry on with it when given a new depiction under the
same key -- including by a new widget, as when a window is rebuilt.
Set it before (or along with) the depiction it applies to.
Images take no input; with ``depiction_take_input`` set, presses
and drags go to depictions that take some (a live viewer's).
``depiction_backing_color`` (rgb or rgba) draws beneath the
depiction (all that shows while there is none), cut by
``mask_texture``, whose green channel adds a frame in
``depiction_frame_color``; a live viewer's picture honors the mask
too. With ``depiction_layered_mask`` set the mask is a layered one
instead: its red channel is how much of the depiction (over the
backing) shows, green and blue how much of
``depiction_layer1_color`` and ``depiction_layer2_color`` (rgb or
rgba; black and white by default: shadows, then highlights) are
painted over that in turn, and alpha how much of the whole is
drawn. Painted layers add coverage where there's nothing, so a
shadow cast over a clear backing darkens what's behind it; a
layered mask should be built as a data texture (its channels are
independent values). ``depiction_debug`` tints the box the
depiction reports covering (what a hit-tested button takes presses
over), to check it against what is drawn. See also
``get_depiction_control()``.
``depiction_overlay`` tells the depiction it is shown straight over
whatever is behind (no backing or frame around it); kinds able to
then draw with transparency where there's nothing (a live mesh
viewer composites over the window), and others draw as usual.
``depiction_small_placeholder`` draws the placeholder for a
depiction that can't be shown (an unknown kind, or one whose
load failed) small in the middle of the box rather than filling
it, for boxes that are panes (doc-ui viewers).
``depiction_suffix`` is text drawn right after the depiction (a
player's '(ready)' after their name, say; empty for none), sized to
its height and fitted into the box along with it.
``depiction_color_override`` (rgb) is a color imposed on the
depiction while ``depiction_use_color_override`` is set; each kind
decides what it applies to (a name: its text, or the capsule parts
its override targets name; never glyphs with colors of their own).
The suffix draws in it too.
"""
# This is a dummy stub; the actual implementation is native code.
import bauiv1 # pylint: disable=cyclic-import
return bauiv1.Widget()
def is_available() -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def on_ui_scale_change() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
def play_swish() -> None:
"""Play the standard ui swish.
A random pick of the current ui asset set's swish variants -- the
same sound buttons make when pressed. Use this for any ui
transition sound (opening or closing a window, say) rather than
playing a particular swish sound yourself.
"""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
def reload_hooks() -> None:
"""Reload functions and other objects held by the native layer.
Call this if you replace things in a hooks module to get the
native layer to see your changes.
"""
# This is a dummy stub; the actual implementation is native code.
return None
def root_ui_back_press() -> None:
"""Handle a press of the global back button.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
def root_ui_pause_updates() -> None:
"""Temporarily pause updates to the root ui for animation purposes.
Make sure that each call to this is matched by a call to
root_ui_resume_updates().
"""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
def root_ui_resume_updates() -> None:
"""Resume paused updates to the root ui for animation purposes."""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
def rowwidget(
edit: bauiv1.Widget | None = None,
parent: bauiv1.Widget | None = None,
size: Sequence[float] | None = None,
position: Sequence[float] | None = None,
background: bool | None = None,
selected_child: bauiv1.Widget | None = None,
visible_child: bauiv1.Widget | None = None,
claims_left_right: bool | None = None,
selection_loops_to_parent: bool | None = None,
) -> bauiv1.Widget:
"""Create or edit a row widget.
Pass a valid existing bauiv1.Widget as 'edit' to modify it; otherwise
a new one is created and returned. Arguments that are not set to None
are applied to the Widget.
"""
# This is a dummy stub; the actual implementation is native code.
import bauiv1 # pylint: disable=cyclic-import
return bauiv1.Widget()
[docs]
def scrollwidget(
*,
edit: bauiv1.Widget | None = None,
parent: bauiv1.Widget | None = None,
id: str | None = None,
size: Sequence[float] | None = None,
position: Sequence[float] | None = None,
background: bool | None = None,
selected_child: bauiv1.Widget | None = None,
capture_arrows: bool = False,
on_select_call: Callable | None = None,
center_small_content: bool | None = None,
center_small_content_horizontally: bool | None = None,
color: Sequence[float] | None = None,
highlight: bool | None = None,
border_opacity: float | None = None,
simple_culling_v: float | None = None,
selection_loops_to_parent: bool | None = None,
claims_left_right: bool | None = None,
claims_up_down: bool | None = None,
autoselect: bool | None = None,
hide_border_when_fits: bool | None = None,
scrollbar_visible: bool | None = None,
fading_scrollbar: bool | None = None,
clean_layout: bool | None = None,
edge_style: Literal['outline', 'fade'] | None = None,
edge_fade: Sequence[float] | None = None,
edge_fade_inset: Sequence[float] | None = None,
move_out_at_ends: bool | None = None,
) -> bauiv1.Widget:
"""Create or edit a scroll widget.
Pass a valid existing bauiv1.Widget as 'edit' to modify it; otherwise
a new one is created and returned. Arguments that are not set to None
are applied to the Widget.
With 'hide_border_when_fits', the border (and selection glow) is not
drawn at all while all content fits, since there is then nothing to
scroll.
With 'scrollbar_visible' False, the scroll bar (trough and thumb) is
neither drawn nor mouse-grabbable; scrolling itself and layout are
unaffected.
With 'fading_scrollbar', the scroll bar is a thin translucent thumb
drawn over the content that fades in while scrolling, hovered or
dragged (as horizontal scroll widgets' do) instead of a trough and
thumb; only the thumb itself can be grabbed.
With 'clean_layout', content is laid out with none of the widget's
historical fudge offsets: it starts at the left edge (or is exactly
centered), spans the full height, and is clipped exactly to the
widget's bounds.
With 'edge_style' 'fade', no outline is drawn; instead the parent
container's window backing is redrawn in a band along the widget's
inside edges so content fades out as it scrolls under them. This
requires the parent to be a container drawing a backing.
'edge_fade' gives how far the band reaches in from each edge as
(left, bottom, right, top); zero means no fade on that side. It
defaults to 40 all around.
'edge_fade_inset' (same order) keeps the band fully drawn that far
in from each edge before its fade begins, for strips content never
shows in (under toolbars, say). The style pairs naturally with
'clean_layout' and 'fading_scrollbar', which let content (and the
fade) run right out to the edges.
With 'move_out_at_ends', an up press while scrolled all the way up
(or a down press while scrolled all the way down) goes unclaimed, so
selection moves on to a neighboring widget the usual way (an
explicit up/down widget, or autoselect's search, toolbars included)
instead of stopping at the scroll widget.
"""
# This is a dummy stub; the actual implementation is native code.
import bauiv1 # pylint: disable=cyclic-import
return bauiv1.Widget()
def set_party_notice(text: babase.LangStr | None) -> None:
"""Set the text shown below the party icon (None for none).
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def set_ui_asset_set_native(
*args: bauiv1.Texture | bauiv1.Mesh | bauiv1.Sound,
) -> None:
"""(internal) Supply the assets the widget layer draws itself with.
Do not call this directly -- bauiv1.set_ui_asset_set() is the
entry point. Args arrive positionally in spec order; both sides
are generated from src/codegen/bauiv1codegen/ui_assets.py, so
they cannot drift.
"""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
def sliderwidget(
*,
edit: bauiv1.Widget | None = None,
parent: bauiv1.Widget | None = None,
id: str | None = None,
size: Sequence[float] | None = None,
position: Sequence[float] | None = None,
color: Sequence[float] | None = None,
value: float | None = None,
min_value: float | None = None,
max_value: float | None = None,
increment: float | None = None,
on_drag_call: Callable[[float], None] | None = None,
on_change_call: Callable[[float], None] | None = None,
autoselect: bool | None = None,
transition_delay: float | None = None,
transition_type: Literal['in_left', 'scale'] | None = None,
enabled: bool | None = None,
) -> bauiv1.Widget:
"""Create or edit a slider widget.
Pass a valid existing bauiv1.Widget as 'edit' to modify it; otherwise
a new one is created and returned. Arguments that are not set to None
are applied to the Widget.
'on_drag_call' is passed the value repeatedly while the nub is being
dragged, and for each key or controller step; 'on_change_call' is
passed it when a drag is released having changed it, or when a run
of key or controller steps that changed it settles (half a second
after the last step, or at once if the slider loses selection).
A slider with 'enabled' False draws dimmed and ignores input but
remains selectable, so navigation around it is unaffected.
"""
# This is a dummy stub; the actual implementation is native code.
import bauiv1 # pylint: disable=cyclic-import
return bauiv1.Widget()
[docs]
def spinnerwidget(
*,
edit: bauiv1.Widget | None = None,
parent: bauiv1.Widget | None = None,
size: float | None = None,
position: Sequence[float] | None = None,
style: Literal['bomb', 'simple'] | None = None,
visible: bool | None = None,
fade: bool | None = None,
fade_delay: float | None = None,
fade_duration: float | None = None,
) -> bauiv1.Widget:
"""Create or edit a spinner widget.
Pass a valid existing bauiv1.Widget as 'edit' to modify it; otherwise
a new one is created and returned. Arguments that are not set to None
are applied to the Widget.
With 'fade' on (the default), the spinner stays invisible for
'fade_delay' seconds after becoming visible and then fades in over
'fade_duration' seconds (both default to 0.5), so one that goes away
within the delay never shows at all. With 'fade' off it appears at
once.
"""
# This is a dummy stub; the actual implementation is native code.
import bauiv1 # pylint: disable=cyclic-import
return bauiv1.Widget()
[docs]
def textwidget(
*,
edit: bauiv1.Widget | None = None,
parent: bauiv1.Widget | None = None,
id: str | None = None,
size: Sequence[float] | None = None,
position: Sequence[float] | None = None,
text: str | bauiv1.Lstr | bauiv1.LangStr | None = None,
v_align: str | None = None,
h_align: str | None = None,
editable: bool | None = None,
padding: float | None = None,
on_submit_call: Callable[[], None] | None = None,
on_apply_call: Callable[[str], None] | None = None,
on_activate_call: Callable[[], None] | None = None,
selectable: bool | None = None,
query: bauiv1.Widget | None = None,
max_chars: int | None = None,
color: Sequence[float] | None = None,
click_activate: bool | None = None,
on_select_call: Callable[[], None] | None = None,
always_highlight: bool | None = None,
draw_controller: bauiv1.Widget | None = None,
scale: float | None = None,
corner_scale: float | None = None,
description: str | bauiv1.Lstr | bauiv1.LangStr | None = None,
transition_delay: float | None = None,
maxwidth: float | None = None,
max_height: float | None = None,
flatness: float | None = None,
shadow: float | None = None,
autoselect: bool | None = None,
rotate: float | None = None,
enabled: bool | None = None,
force_internal_editing: bool | None = None,
always_show_carat: bool | None = None,
big: bool | None = None,
extra_touch_border_scale: float | None = None,
res_scale: float | None = None,
query_max_chars: bauiv1.Widget | None = None,
query_description: bauiv1.Widget | None = None,
adapter_finished: bool | None = None,
glow_type: str | None = None,
allow_clear_button: bool | None = None,
literal: bool | None = None,
depth_range: tuple[float, float] | None = None,
transition_type: Literal['in_left', 'scale'] | None = None,
password: bool | None = None,
query_password: bauiv1.Widget | None = None,
string_edit_kind: str | None = None,
query_string_edit_kind: bauiv1.Widget | None = None,
invoke_submit: bool | None = None,
on_return_press_call: Callable[[], None] | None = None,
invoke_return_press: bool | None = None,
) -> bauiv1.Widget:
"""Create or edit a text widget.
Pass a valid existing bauiv1.Widget as 'edit' to modify it; otherwise
a new one is created and returned. Arguments that are not set to None
are applied to the Widget.
A text widget with ``enabled`` False draws dimmed and can't be
edited or activated, but remains selectable (if it otherwise would
be), so navigation around it is unaffected.
``on_submit_call`` runs when the text is *submitted*: an enter press
while editing inline, or the action key / commit button of a
platform string-edit dialog for string_edit_kinds that submit
(see babase.StringEditKind). It is not a change notification; text
can be edited without it ever running. ``invoke_submit`` runs it on
demand.
``on_apply_call`` runs whenever an edit is *applied* to the widget:
a platform string-edit dialog closing with a value, inline editing
ending (return, or focus leaving the widget), or the clear button.
Not per character, and only when the text actually changed since it
was last applied. It is passed the new text (as of the apply; the
call runs deferred). Applies precede submits, so an enter press runs
this and then ``on_submit_call``. Setting ``text`` from code does not
count as an apply.
``on_return_press_call`` and ``invoke_return_press`` are deprecated
aliases of those two and will be removed when api 9 support ends.
"""
# This is a dummy stub; the actual implementation is native code.
import bauiv1 # pylint: disable=cyclic-import
return bauiv1.Widget()
def ui_open_state_change(tag: str, change: int) -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
def uibounds() -> tuple[float, float, float, float]:
"""Returns ui-bounds values: (x-min, x-max, y-min, y-max).
This is the range of values that can be plugged into 'stack_offset' for
a :meth:`bauiv1.containerwidget()` call while guaranteeing that its
center remains onscreen.
"""
# This is a dummy stub; the actual implementation is native code.
return (0.0, 0.0, 0.0, 0.0)
[docs]
def widget(
*,
edit: bauiv1.Widget,
up_widget: bauiv1.Widget | None = None,
down_widget: bauiv1.Widget | None = None,
left_widget: bauiv1.Widget | None = None,
right_widget: bauiv1.Widget | None = None,
show_buffer_top: float | None = None,
show_buffer_bottom: float | None = None,
show_buffer_left: float | None = None,
show_buffer_right: float | None = None,
depth_range: tuple[float, float] | None = None,
autoselect: bool | None = None,
allow_preserve_selection: bool | None = None,
auto_select_toolbars_only: bool | None = None,
draw_behind: bool | None = None,
) -> None:
"""Edit common attributes of any widget.
Unlike other UI calls, this can only be used to edit, not to create.
``draw_behind`` puts a widget in a single-depth container (such as a scroll area's contents) behind its siblings, which otherwise share one depth slice and can fight where they overlap; for backings laid beneath other widgets.
"""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
def widget_by_id(id: str) -> bauiv1.Widget | None:
"""Return a widget with the given ID, or None if there is none."""
# This is a dummy stub; the actual implementation is native code.
import bauiv1
return bauiv1.Widget()
# Docs-generation hack; import some stuff that we likely only forward-declared
# in our actual source code so that docs tools can find it.
from typing import (Coroutine, Any, Literal, Callable,
Generator, Awaitable, Sequence, Self, TypeIs)
import asyncio
from concurrent.futures import Future
from pathlib import Path
from enum import Enum