bauiv1 package¶
Submodules¶
bauiv1.onscreenkeyboard module¶
Provides the built-in on screen keyboard UI.
- class bauiv1.onscreenkeyboard.OnScreenKeyboardWindow(adapter: StringEditAdapter)[source]¶
Bases:
Window
Simple built-in on-screen keyboard.
Module contents¶
Ballistica user interface api version 1
- class bauiv1.AppIntent¶
Bases:
object
A high level directive given to the app.
Category: App Classes
- class bauiv1.AppMode¶
Bases:
object
A high level mode for the app.
Category: App Classes
- classmethod can_handle_intent(intent: AppIntent) bool [source]¶
Return whether this mode can handle the provided intent.
For this to return True, the AppMode must claim to support the provided intent (via its _supports_intent() method) AND the AppExperience associated with the AppMode must be supported by the current app and runtime environment.
- classmethod get_app_experience() AppExperience [source]¶
Return the overall experience provided by this mode.
- class bauiv1.AppTimer(time: float, call: Callable[[], Any], repeat: bool = False)[source]¶
Bases:
object
Timers are used to run code at later points in time.
Category: General Utility Classes
This class encapsulates a timer based on app-time. The underlying timer will be destroyed when this object is no longer referenced. If you do not want to worry about keeping a reference to your timer around, use the babase.apptimer() function instead to get a one-off timer.
##### Arguments ###### time > Length of time in seconds that the timer will wait before firing.
###### call > A callable Python object. Remember that the timer will retain a strong reference to the callable for as long as it exists, so you may want to look into concepts such as babase.WeakCall if that is not desired.
###### repeat > If True, the timer will fire repeatedly, with each successive firing having the same delay as the first.
##### Example
Use a Timer object to print repeatedly for a few seconds: … def say_it(): … babase.screenmessage(‘BADGER!’) … def stop_saying_it(): … global g_timer … g_timer = None … babase.screenmessage(‘MUSHROOM MUSHROOM!’) … # Create our timer; it will run as long as we have the self.t ref. … g_timer = babase.AppTimer(0.3, say_it, repeat=True) … # Now fire off a one-shot timer to kill it. … babase.apptimer(3.89, stop_saying_it)
- class bauiv1.Call(*args: Any, **keywds: Any)¶
Bases:
object
Wraps a callable and arguments into a single callable object.
Category: General Utility Classes
The callable is strong-referenced so it won’t die until this object does.
Note that a bound method (ex:
myobj.dosomething
) contains a reference toself
(myobj
in that case), so you will be keeping that object alive too. Use babase.WeakCall if you want to pass a method to callback without keeping its object alive.
- class bauiv1.ContextRef[source]¶
Bases:
object
Store or use a ballistica context.
Category: General Utility Classes
Many operations such as bascenev1.newnode() or bascenev1.gettexture() operate implicitly on a current ‘context’. A context is some sort of state that functionality can implicitly use. Context determines, for example, which scene nodes or textures get added to without having to specify it explicitly in the newnode()/gettexture() call. Contexts can also affect object lifecycles; for example a babase.ContextCall will become a no-op when the context it was created in is destroyed.
In general, if you are a modder, you should not need to worry about contexts; mod code should mostly be getting run in the correct context and timers and other callbacks will take care of saving and restoring contexts automatically. There may be rare cases, however, where you need to deal directly with contexts, and that is where this class comes in.
Creating a babase.ContextRef() will capture a reference to the current context. Other modules may provide ways to access their contexts; for example a bascenev1.Activity instance has a ‘context’ attribute. You can also use babase.ContextRef.empty() to create a reference to no context. Some code such as UI calls may expect this and may complain if you try to use them within a context.
##### Usage ContextRefs are generally used with the Python ‘with’ statement, which sets the context they point to as current on entry and resets it to the previous value on exit.
##### Example Explicitly create a few UI bits with no context set. (UI stuff may complain if called within a context): >>> with bui.ContextRef.empty(): … my_container = bui.containerwidget()
- classmethod empty() ContextRef [source]¶
Return a ContextRef pointing to no context.
This is useful when code should be run free of a context. For example, UI code generally insists on being run this way. Otherwise, callbacks set on the UI could inadvertently stop working due to a game activity ending, which would be unintuitive behavior.
- class bauiv1.DisplayTimer(time: float, call: Callable[[], Any], repeat: bool = False)[source]¶
Bases:
object
Timers are used to run code at later points in time.
Category: General Utility Classes
This class encapsulates a timer based on display-time. The underlying timer will be destroyed when this object is no longer referenced. If you do not want to worry about keeping a reference to your timer around, use the babase.displaytimer() function instead to get a one-off timer.
Display-time is a time value intended to be used for animation and other visual purposes. It will generally increment by a consistent amount each frame. It will pass at an overall similar rate to AppTime, but trades accuracy for smoothness.
##### Arguments ###### time > Length of time in seconds that the timer will wait before firing.
###### call > A callable Python object. Remember that the timer will retain a strong reference to the callable for as long as it exists, so you may want to look into concepts such as babase.WeakCall if that is not desired.
###### repeat > If True, the timer will fire repeatedly, with each successive firing having the same delay as the first.
##### Example
Use a Timer object to print repeatedly for a few seconds: … def say_it(): … babase.screenmessage(‘BADGER!’) … def stop_saying_it(): … global g_timer … g_timer = None … babase.screenmessage(‘MUSHROOM MUSHROOM!’) … # Create our timer; it will run as long as we have the self.t ref. … g_timer = babase.DisplayTimer(0.3, say_it, repeat=True) … # Now fire off a one-shot timer to kill it. … babase.displaytimer(3.89, stop_saying_it)
- class bauiv1.Keyboard¶
Bases:
object
Chars definitions for on-screen keyboard.
Category: App Classes
Keyboards are discoverable by the meta-tag system and the user can select which one they want to use. On-screen keyboard uses chars from active babase.Keyboard.
- chars: list[tuple[str, ...]]¶
- name: str¶
- nums: tuple[str, ...]¶
- pages: dict[str, tuple[str, ...]]¶
- class bauiv1.LoginAdapter(login_type: LoginType)¶
Bases:
object
Allows using implicit login types in an explicit way.
Some login types such as Google Play Game Services or Game Center are basically always present and often do not provide a way to log out from within a running app, so this adapter exists to use them in a flexible manner by ‘attaching’ and ‘detaching’ from an always-present login, allowing for its use alongside other login types. It also provides common functionality for server-side account verification and other handy bits.
- class ImplicitLoginState(login_id: str, display_name: str)[source]¶
Bases:
object
Describes the current state of an implicit login.
- display_name: str¶
- login_id: str¶
- class SignInResult(credentials: str)[source]¶
Bases:
object
Describes the final result of a sign-in attempt.
- credentials: str¶
- get_sign_in_token(completion_cb: Callable[[str | None], None]) None [source]¶
Get a sign-in token from the adapter back end.
This token is then passed to the master-server to complete the sign-in process. The adapter can use this opportunity to bring up account creation UI, call its internal sign_in function, etc. as needed. The provided completion_cb should then be called with either a token or None if sign in failed or was cancelled.
- on_back_end_active_change(active: bool) None [source]¶
Called when active state for the back-end is (possibly) changing.
Meant to be overridden by subclasses. Being active means that the implicit login provided by the back-end is actually being used by the app. It should therefore register unlocked achievements, leaderboard scores, allow viewing native UIs, etc. When not active it should ignore everything and behave as if signed out, even if it technically is still signed in.
- set_active_logins(logins: dict[LoginType, str]) None [source]¶
Keep the adapter informed of actively used logins.
This should be called by the app’s account subsystem to keep adapters up to date on the full set of logins attached to the currently-in-use account. Note that the logins dict passed in should be immutable as only a reference to it is stored, not a copy.
- set_implicit_login_state(state: ImplicitLoginState | None) None [source]¶
Keep the adapter informed of implicit login states.
This should be called by the adapter back-end when an account of their associated type gets logged in or out.
- sign_in(result_cb: Callable[[LoginAdapter, SignInResult | Exception], None], description: str) None [source]¶
Attempt to sign in via this adapter.
This can be called even if the back-end is not implicitly signed in; the adapter will attempt to sign in if possible. An exception will be returned if the sign-in attempt fails.
- class bauiv1.LoginInfo(name: str)¶
Bases:
object
Basic info about a login available in the app.plus.accounts section.
- name: str¶
- class bauiv1.Lstr(*args: Any, **keywds: Any)¶
Bases:
object
Used to define strings in a language-independent way.
Category: General Utility Classes
These should be used whenever possible in place of hard-coded strings so that in-game or UI elements show up correctly on all clients in their currently-active language.
To see available resource keys, look at any of the bs_language_*.py files in the game or the translations pages at legacy.ballistica.net/translate.
##### Examples EXAMPLE 1: specify a string from a resource path >>> mynode.text = babase.Lstr(resource=’audioSettingsWindow.titleText’)
EXAMPLE 2: specify a translated string via a category and english value; if a translated value is available, it will be used; otherwise the english value will be. To see available translation categories, look under the ‘translations’ resource section. >>> mynode.text = babase.Lstr(translate=(‘gameDescriptions’, … ‘Defeat all enemies’))
EXAMPLE 3: specify a raw value and some substitutions. Substitutions can be used with resource and translate modes as well. >>> mynode.text = babase.Lstr(value=’${A} / ${B}’, … subs=[(‘${A}’, str(score)), (‘${B}’, str(total))])
EXAMPLE 4: babase.Lstr’s can be nested. This example would display the resource at res_a but replace ${NAME} with the value of the resource at res_b >>> mytextnode.text = babase.Lstr( … resource=’res_a’, … subs=[(‘${NAME}’, babase.Lstr(resource=’res_b’))])
- evaluate() str [source]¶
Evaluate the Lstr and returns a flat string in the current language.
You should avoid doing this as much as possible and instead pass and store Lstr values.
- static from_json(json_string: str) babase.Lstr [source]¶
Given a json string, returns a babase.Lstr. Does no validation.
- exception bauiv1.NotFoundError¶
Bases:
Exception
Exception raised when a referenced object does not exist.
Category: Exception Classes
- class bauiv1.Permission(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶
Bases:
Enum
Permissions that can be requested from the OS.
Category: Enums
- STORAGE = 0¶
- class bauiv1.Plugin¶
Bases:
object
A plugin to alter app behavior in some way.
Category: App Classes
Plugins are discoverable by the meta-tag system and the user can select which ones they want to enable. Enabled plugins are then called at specific times as the app is running in order to modify its behavior in some way.
- class bauiv1.PluginSpec(class_path: str, loadable: bool)¶
Bases:
object
Represents a plugin the engine knows about.
Category: App Classes
The ‘enabled’ attr represents whether this plugin is set to load. Getting or setting that attr affects the corresponding app-config key. Remember to commit the app-config after making any changes.
The ‘attempted_load’ attr will be True if the engine has attempted to load the plugin. If ‘attempted_load’ is True for a PluginSpec but the ‘plugin’ attr is None, it means there was an error loading the plugin. If a plugin’s api-version does not match the running app, if a new plugin is detected with auto-enable-plugins disabled, or if the user has explicitly disabled a plugin, the engine will not even attempt to load it.
- property enabled: bool¶
Whether the user wants this plugin to load.
- class bauiv1.QuitType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶
Bases:
Enum
Types of input a controller can send to the game.
Category: Enums
- ‘soft’ may hide/reset the app but keep the process running, depending
on the platform.
- ‘back’ is a variant of ‘soft’ which may give ‘back-button-pressed’
behavior depending on the platform. (returning to some previous activity instead of dumping to the home screen, etc.)
- ‘hard’ leads to the process exiting. This generally should be avoided
on platforms such as mobile.
- BACK = 1¶
- HARD = 2¶
- SOFT = 0¶
- class bauiv1.SpecialChar(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶
Bases:
Enum
Special characters the game can print.
Category: Enums
- BACK = 10¶
- BOTTOM_BUTTON = 7¶
- CROWN = 64¶
- DELETE = 8¶
- DICE_BUTTON1 = 31¶
- DICE_BUTTON2 = 32¶
- DICE_BUTTON3 = 33¶
- DICE_BUTTON4 = 34¶
- DOWN_ARROW = 0¶
- DPAD_CENTER_BUTTON = 15¶
- DRAGON = 69¶
- EXPLODINARY_LOGO = 46¶
- EYE_BALL = 66¶
- FAST_FORWARD_BUTTON = 14¶
- FEDORA = 62¶
- FIREBALL = 76¶
- FLAG_ALGERIA = 81¶
- FLAG_ARGENTINA = 92¶
- FLAG_AUSTRALIA = 85¶
- FLAG_BRAZIL = 50¶
- FLAG_CANADA = 54¶
- FLAG_CHILE = 94¶
- FLAG_CHINA = 52¶
- FLAG_CZECH_REPUBLIC = 84¶
- FLAG_EGYPT = 79¶
- FLAG_FRANCE = 57¶
- FLAG_GERMANY = 49¶
- FLAG_INDIA = 55¶
- FLAG_INDONESIA = 58¶
- FLAG_IRAN = 90¶
- FLAG_ITALY = 59¶
- FLAG_JAPAN = 56¶
- FLAG_KUWAIT = 80¶
- FLAG_MALAYSIA = 83¶
- FLAG_MEXICO = 48¶
- FLAG_NETHERLANDS = 61¶
- FLAG_PHILIPPINES = 93¶
- FLAG_POLAND = 91¶
- FLAG_QATAR = 78¶
- FLAG_RUSSIA = 51¶
- FLAG_SAUDI_ARABIA = 82¶
- FLAG_SINGAPORE = 86¶
- FLAG_SOUTH_KOREA = 60¶
- FLAG_UNITED_ARAB_EMIRATES = 77¶
- FLAG_UNITED_KINGDOM = 53¶
- FLAG_UNITED_STATES = 47¶
- GAME_CENTER_LOGO = 30¶
- GAME_CIRCLE_LOGO = 35¶
- GOOGLE_PLAY_GAMES_LOGO = 29¶
- HAL = 63¶
- HEART = 68¶
- HELMET = 70¶
- LEFT_ARROW = 2¶
- LEFT_BUTTON = 5¶
- LOCAL_ACCOUNT = 45¶
- LOGO = 27¶
- LOGO_FLAT = 11¶
- MIKIROG = 95¶
- MOON = 74¶
- MUSHROOM = 71¶
- NINJA_STAR = 72¶
- NVIDIA_LOGO = 89¶
- OCULUS_LOGO = 87¶
- OUYA_BUTTON_A = 25¶
- OUYA_BUTTON_O = 22¶
- OUYA_BUTTON_U = 23¶
- OUYA_BUTTON_Y = 24¶
- OUYA_LOGO = 26¶
- PARTY_ICON = 36¶
- PAUSE_BUTTON = 21¶
- PLAY_BUTTON = 20¶
- PLAY_PAUSE_BUTTON = 13¶
- PLAY_STATION_CIRCLE_BUTTON = 17¶
- PLAY_STATION_CROSS_BUTTON = 16¶
- PLAY_STATION_SQUARE_BUTTON = 19¶
- PLAY_STATION_TRIANGLE_BUTTON = 18¶
- REWIND_BUTTON = 12¶
- RIGHT_ARROW = 3¶
- RIGHT_BUTTON = 6¶
- SHIFT = 9¶
- SKULL = 67¶
- SPIDER = 75¶
- STEAM_LOGO = 88¶
- TEST_ACCOUNT = 37¶
- TICKET = 28¶
- TICKET_BACKING = 38¶
- TOP_BUTTON = 4¶
- TROPHY0A = 42¶
- TROPHY0B = 43¶
- TROPHY1 = 39¶
- TROPHY2 = 40¶
- TROPHY3 = 41¶
- TROPHY4 = 44¶
- UP_ARROW = 1¶
- V2_LOGO = 96¶
- VIKING_HELMET = 73¶
- YIN_YANG = 65¶
- class bauiv1.UIScale(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶
Bases:
Enum
The overall scale the UI is being rendered for. Note that this is independent of pixel resolution. For example, a phone and a desktop PC might render the game at similar pixel resolutions but the size they display content at will vary significantly.
Category: Enums
- ‘large’ is used for devices such as desktop PCs where fine details can
be clearly seen. UI elements are generally smaller on the screen and more content can be seen at once.
- ‘medium’ is used for devices such as tablets, TVs, or VR headsets.
This mode strikes a balance between clean readability and amount of content visible.
- ‘small’ is used primarily for phones or other small devices where
content needs to be presented as large and clear in order to remain readable from an average distance.
- LARGE = 0¶
- MEDIUM = 1¶
- SMALL = 2¶
- class bauiv1.UIV1Subsystem¶
Bases:
AppSubsystem
Consolidated UI functionality for the app.
Category: App Classes
To use this class, access the single instance of it at ‘ba.app.ui’.
(internal)
- property available: bool¶
Can uiv1 currently be used?
Code that may run in headless mode, before the UI has been spun up, while other ui systems are active, etc. can check this to avoid likely erroring.
Clear any existing ‘main’ window with the provided transition.
Return the current named main menu location, if any.
Return whether a main menu window is present.
- on_app_loading() None [source]¶
Called when the app reaches the loading state.
Note that subsystems created after the app switches to the loading state will not receive this callback. Subsystems created by plugins are an example of this.
Set the location represented by the current main menu window.
Set the current ‘main’ window, replacing any existing.
If ‘from_window’ is passed as a bauiv1.Widget or None, a warning will be issued if it that value does not match the current main window. This can help clean up flawed code that can lead to bad UI states. A value of False will disable the check.
- class bauiv1.WeakCall(*args: Any, **keywds: Any)¶
Bases:
object
Wrap a callable and arguments into a single callable object.
Category: General Utility Classes
When passed a bound method as the callable, the instance portion of it is weak-referenced, meaning the underlying instance is free to die if all other references to it go away. Should this occur, calling the WeakCall is simply a no-op.
Think of this as a handy way to tell an object to do something at some point in the future if it happens to still exist.
##### Examples EXAMPLE A: this code will create a FooClass instance and call its bar() method 5 seconds later; it will be kept alive even though we overwrite its variable with None because the bound method we pass as a timer callback (foo.bar) strong-references it >>> foo = FooClass() … babase.apptimer(5.0, foo.bar) … foo = None
EXAMPLE B: This code will not keep our object alive; it will die when we overwrite it with None and the timer will be a no-op when it fires >>> foo = FooClass() … babase.apptimer(5.0, ba.WeakCall(foo.bar)) … foo = None
EXAMPLE C: Wrap a method call with some positional and keyword args: >>> myweakcall = babase.WeakCall(self.dostuff, argval1, … namedarg=argval2) … # Now we have a single callable to run that whole mess. … # The same as calling myobj.dostuff(argval1, namedarg=argval2) … # (provided my_obj still exists; this will do nothing … # otherwise). … myweakcall()
Note: additional args and keywords you provide to the WeakCall() constructor are stored as regular strong-references; you’ll need to wrap them in weakrefs manually if desired.
- class bauiv1.Widget[source]¶
Bases:
object
Internal type for low level UI elements; buttons, windows, etc.
Category: User Interface Classes
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.
- add_delete_callback(call: Callable) None [source]¶
Add a call to be run immediately after this widget is destroyed.
- delete(ignore_missing: bool = True) None [source]¶
Delete the Widget. Ignores already-deleted Widgets if ignore_missing is True; otherwise an Exception is thrown.
- exists() bool [source]¶
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.
- get_children() list[bauiv1.Widget] [source]¶
Returns any child Widgets of this Widget.
- get_screen_space_center() tuple[float, float] [source]¶
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.
- get_selected_child() bauiv1.Widget | None [source]¶
Returns the selected child Widget or None if nothing is selected.
- get_widget_type() str [source]¶
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.
- transitioning_out: bool¶
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.
- class bauiv1.Window(root_widget: bauiv1.Widget, cleanupcheck: bool = True)¶
Bases:
object
A basic window.
Category: User Interface Classes
- get_root_widget() bauiv1.Widget [source]¶
Return the root widget.
- bauiv1.add_clean_frame_callback(call: Callable) None [source]¶
(internal)
Provide an object to be called once the next non-progress-bar-frame has been rendered. Useful for queueing things to load in the background without elongating any current progress-bar-load.
- bauiv1.appnameupper() str [source]¶
(internal)
Return whether this build of the game can display full unicode such as Emoji, Asian languages, etc.
- bauiv1.apptime() babase.AppTime [source]¶
Return the current app-time in seconds.
Category: General Utility Functions
App-time is a monotonic time value; it starts at 0.0 when the app launches and will never jump by large amounts or go backwards, even if the system time changes. Its progression will pause when the app is in a suspended state.
Note that the AppTime returned here is simply float; it just has a unique type in the type-checker’s eyes to help prevent it from being accidentally used with time functionality expecting other time types.
- bauiv1.apptimer(time: float, call: Callable[[], Any]) None [source]¶
Schedule a callable object to run based on app-time.
Category: General Utility Functions
This function creates a one-off timer which cannot be canceled or modified once created. If you require the ability to do so, or need a repeating timer, use the babase.AppTimer class instead.
##### Arguments ###### time (float) > Length of time in seconds that the timer will wait before firing.
###### call (Callable[[], Any]) > A callable Python object. Note that the timer will retain a strong reference to the callable for as long as the timer exists, so you may want to look into concepts such as babase.WeakCall if that is not desired.
##### Examples Print some stuff through time: >>> babase.screenmessage(‘hello from now!’) >>> babase.apptimer(1.0, babase.Call(babase.screenmessage,
‘hello from the future!’))
>>> babase.apptimer(2.0, babase.Call(babase.screenmessage, ... 'hello from the future 2!'))
- bauiv1.buttonwidget(edit: bauiv1.Widget | None = None, parent: bauiv1.Widget | None = None, size: Sequence[float] | None = None, position: Sequence[float] | None = None, on_activate_call: Callable | None = None, label: str | bauiv1.Lstr | 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) bauiv1.Widget [source]¶
Create or edit a button widget.
Category: User Interface Functions
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.
- bauiv1.charstr(char_id: babase.SpecialChar) str [source]¶
Get a unicode string representing a special character.
Category: General Utility Functions
Note that these utilize the private-use block of unicode characters (U+E000-U+F8FF) and are specific to the game; exporting or rendering them elsewhere will be meaningless.
See babase.SpecialChar for the list of available characters.
- bauiv1.checkboxwidget(edit: bauiv1.Widget | None = None, parent: bauiv1.Widget | None = None, size: Sequence[float] | None = None, position: Sequence[float] | None = None, text: str | bauiv1.Lstr | 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) bauiv1.Widget [source]¶
Create or edit a check-box widget.
Category: User Interface Functions
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.
- bauiv1.clipboard_is_supported() bool [source]¶
Return whether this platform supports clipboard operations at all.
Category: General Utility Functions
If this returns False, UIs should not show ‘copy to clipboard’ buttons, etc.
- bauiv1.clipboard_set_text(value: str) None [source]¶
Copy a string to the system clipboard.
Category: General Utility Functions
- Ensure that babase.clipboard_is_supported() returns True before adding
buttons/etc. that make use of this functionality.
- bauiv1.columnwidget(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, 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, claims_tab: bool | None = None) bauiv1.Widget [source]¶
Create or edit a column widget.
Category: User Interface Functions
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.
- bauiv1.commit_app_config() None ¶
Commit the config to persistent storage.
Category: General Utility Functions
(internal)
- bauiv1.containerwidget(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, 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, claims_tab: 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: str | None = None, on_select_call: Callable[[], None] | None = None, claim_outside_clicks: bool | None = None, claims_up_down: bool | None = None) bauiv1.Widget [source]¶
Create or edit a container widget.
Category: User Interface Functions
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.
- bauiv1.displaytime() babase.DisplayTime [source]¶
Return the current display-time in seconds.
Category: General Utility Functions
Display-time is a time value intended to be used for animation and other visual purposes. It will generally increment by a consistent amount each frame. It will pass at an overall similar rate to AppTime, but trades accuracy for smoothness.
Note that the value returned here is simply a float; it just has a unique type in the type-checker’s eyes to help prevent it from being accidentally used with time functionality expecting other time types.
- bauiv1.displaytimer(time: float, call: Callable[[], Any]) None [source]¶
Schedule a callable object to run based on display-time.
Category: General Utility Functions
This function creates a one-off timer which cannot be canceled or modified once created. If you require the ability to do so, or need a repeating timer, use the babase.DisplayTimer class instead.
Display-time is a time value intended to be used for animation and other visual purposes. It will generally increment by a consistent amount each frame. It will pass at an overall similar rate to AppTime, but trades accuracy for smoothness.
##### Arguments ###### time (float) > Length of time in seconds that the timer will wait before firing.
###### call (Callable[[], Any]) > A callable Python object. Note that the timer will retain a strong reference to the callable for as long as the timer exists, so you may want to look into concepts such as babase.WeakCall if that is not desired.
##### Examples Print some stuff through time: >>> babase.screenmessage(‘hello from now!’) >>> babase.displaytimer(1.0, babase.Call(babase.screenmessage, … ‘hello from the future!’)) >>> babase.displaytimer(2.0, babase.Call(babase.screenmessage, … ‘hello from the future 2!’))
- bauiv1.do_once() bool [source]¶
Return whether this is the first time running a line of code.
Category: General Utility Functions
This is used by ‘print_once()’ type calls to keep from overflowing logs. The call functions by registering the filename and line where The call is made from. Returns True if this location has not been registered already, and False if it has.
##### Example This print will only fire for the first loop iteration: >>> for i in range(10): … if babase.do_once(): … print(‘HelloWorld once from loop!’)
- bauiv1.fade_screen(to: int = 0, time: float = 0.25, endcall: Callable[[], None] | None = None) None [source]¶
(internal)
Fade the local game screen in our out from black over a duration of time. if “to” is 0, the screen will fade out to black. Otherwise it will fade in from black. If endcall is provided, it will be run after a completely faded frame is drawn.
- bauiv1.get_display_resolution() tuple[int, int] | None [source]¶
(internal)
Return the currently selected display resolution for fullscreen display. Returns None if resolutions cannot be directly set.
- bauiv1.get_input_idle_time() float [source]¶
Return seconds since any local input occurred (touch, keypress, etc.).
- bauiv1.get_ip_address_type(addr: str) socket.AddressFamily ¶
Return socket.AF_INET6 or socket.AF_INET4 for the provided address.
- bauiv1.get_max_graphics_quality() str [source]¶
(internal)
Return the max graphics-quality supported on the current hardware.
- bauiv1.get_qrcode_texture(url: str) bauiv1.Texture [source]¶
Return a QR code texture.
The provided url must be 64 bytes or less.
- bauiv1.get_remote_app_name() babase.Lstr ¶
(internal)
- bauiv1.get_special_widget(name: str) bauiv1.Widget [source]¶
(internal)
- bauiv1.get_string_height(string: str, suppress_warning: bool = False) float [source]¶
(internal)
Given a string, returns its height using the standard small app font.
- bauiv1.get_string_width(string: str, suppress_warning: bool = False) float [source]¶
(internal)
Given a string, returns its width using the standard small app font.
- bauiv1.get_type_name(cls: type) str ¶
Return a full type name including module for a class.
- bauiv1.getclass(name: str, subclassof: type[T]) type[T] ¶
Given a full class name such as foo.bar.MyClass, return the class.
Category: General Utility Functions
The class will be checked to make sure it is a subclass of the provided ‘subclassof’ class, and a TypeError will be raised if not.
- bauiv1.getmesh(name: str) bauiv1.Mesh [source]¶
Load a mesh for use solely in the local user interface.
- bauiv1.getsound(name: str) bauiv1.Sound [source]¶
Load a sound for use in the ui.
- bauiv1.gettexture(name: str) bauiv1.Texture [source]¶
Load a texture for use in the ui.
- bauiv1.have_permission(permission: babase.Permission) bool [source]¶
(internal)
- bauiv1.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, claims_tab: bool | None = None) bauiv1.Widget [source]¶
Create or edit a horizontal scroll widget.
Category: User Interface Functions
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.
- bauiv1.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, 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) bauiv1.Widget [source]¶
Create or edit an image widget.
Category: User Interface Functions
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.
- bauiv1.in_logic_thread() bool [source]¶
(internal)
Returns whether or not the current thread is the logic thread.
- bauiv1.is_browser_likely_available() bool ¶
Return whether a browser likely exists on the current device.
category: General Utility Functions
If this returns False you may want to avoid calling babase.show_url() with any lengthy addresses. (ba.show_url() will display an address as a string in a window if unable to bring up a browser, but that is only useful for simple URLs.)
- bauiv1.lock_all_input() None [source]¶
(internal)
Prevents all keyboard, mouse, and gamepad events from being processed.
- bauiv1.open_file_externally(path: str) None [source]¶
(internal)
Open the provided file in the default external app.
- bauiv1.open_url(address: str, force_fallback: bool = False) None [source]¶
Open the provided URL.
Category: General Utility Functions
Attempts to open the provided url in a web-browser. If that is not possible (or force_fallback is True), instead displays the url as a string and/or qrcode.
- bauiv1.overlay_web_browser_close() bool [source]¶
Close any open overlay web browser.
Category: General Utility Functions
- bauiv1.overlay_web_browser_is_open() bool [source]¶
Return whether an overlay web browser is open currently.
Category: General Utility Functions
- bauiv1.overlay_web_browser_is_supported() bool [source]¶
Return whether an overlay web browser is supported here.
Category: General Utility Functions
An overlay web browser is a small dialog that pops up over the top of the main engine window. It can be used for performing simple tasks such as sign-ins.
- bauiv1.overlay_web_browser_open_url(address: str) None [source]¶
Open the provided URL in an overlayw web browser.
Category: General Utility Functions
An overlay web browser is a small dialog that pops up over the top of the main engine window. It can be used for performing simple tasks such as sign-ins.
- bauiv1.pushcall(call: Callable, from_other_thread: bool = False, suppress_other_thread_warning: bool = False, other_thread_use_fg_context: bool = False, raw: bool = False) None [source]¶
Push a call to the logic event-loop. Category: General Utility Functions
This call expects to be used in the logic thread, and will automatically save and restore the babase.Context to behave seamlessly.
If you want to push a call from outside of the logic thread, however, you can pass ‘from_other_thread’ as True. In this case the call will always run in the UI context_ref on the logic thread or whichever context_ref is in the foreground if other_thread_use_fg_context is True. Passing raw=True will disable thread checks and context_ref sets/restores.
- bauiv1.quit(confirm: bool = False, quit_type: babase.QuitType | None = None) None [source]¶
Quit the app.
Category: General Utility Functions
If ‘confirm’ is True, a confirm dialog will be presented if conditions allow; otherwise the quit will still be immediate. See docs for babase.QuitType for explanations of the optional ‘quit_type’ arg.
- bauiv1.request_permission(permission: babase.Permission) None [source]¶
(internal)
- bauiv1.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, claims_tab: bool | None = None, selection_loops_to_parent: bool | None = None) bauiv1.Widget [source]¶
Create or edit a row widget.
Category: User Interface Functions
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.
- bauiv1.safecolor(color: Sequence[float], target_intensity: float = 0.6) tuple[float, ...] [source]¶
Given a color tuple, return a color safe to display as text.
Category: General Utility Functions
Accepts tuples of length 3 or 4. This will slightly brighten very dark colors, etc.
- bauiv1.screenmessage(message: str | babase.Lstr, color: Sequence[float] | None = None, log: bool = False) None [source]¶
Print a message to the local client’s screen, in a given color.
Category: General Utility Functions
Note that this version of the function is purely for local display. To broadcast screen messages in network play, look for methods such as broadcastmessage() provided by the scene-version packages.
- bauiv1.scrollwidget(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 = False, on_select_call: Callable | None = None, center_small_content: 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, claims_tab: bool | None = None, autoselect: bool | None = None) bauiv1.Widget [source]¶
Create or edit a scroll widget.
Category: User Interface Functions
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.
- bauiv1.set_analytics_screen(screen: str) None [source]¶
Used for analytics to see where in the app players spend their time.
Category: General Utility Functions
Generally called when opening a new window or entering some UI. ‘screen’ should be a string description of an app location (‘Main Menu’, etc.)
- bauiv1.set_ui_input_device(input_device_id: int | None) None [source]¶
(internal)
Sets the input-device that currently owns the user interface.
- bauiv1.textwidget(edit: bauiv1.Widget | None = None, parent: bauiv1.Widget | None = None, size: Sequence[float] | None = None, position: Sequence[float] | None = None, text: str | bauiv1.Lstr | None = None, v_align: str | None = None, h_align: str | None = None, editable: bool | None = None, padding: float | None = None, on_return_press_call: Callable[[], 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 | 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) bauiv1.Widget [source]¶
Create or edit a text widget.
Category: User Interface Functions
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.
- bauiv1.timestring(timeval: float | int, centi: bool = True) babase.Lstr ¶
Generate a babase.Lstr for displaying a time value.
Category: General Utility Functions
Given a time value, returns a babase.Lstr with: (hours if > 0 ) : minutes : seconds : (centiseconds if centi=True).
WARNING: the underlying Lstr value is somewhat large so don’t use this to rapidly update Node text values for an onscreen timer or you may consume significant network bandwidth. For that purpose you should use a ‘timedisplay’ Node and attribute connections.
- bauiv1.uibounds() tuple[float, float, float, float] [source]¶
(internal)
Returns a tuple of 4 values: (x-min, x-max, y-min, y-max) representing the range of values that can be plugged into a root level bauiv1.ContainerWidget’s stack_offset value while guaranteeing that its center remains onscreen.
- bauiv1.uicleanupcheck(obj: Any, widget: bauiv1.Widget) None ¶
Add a check to ensure a widget-owning object gets cleaned up properly.
Category: User Interface Functions
This adds a check which will print an error message if the provided object still exists ~5 seconds after the provided bauiv1.Widget dies.
This is a good sanity check for any sort of object that wraps or controls a bauiv1.Widget. For instance, a ‘Window’ class instance has no reason to still exist once its root container bauiv1.Widget has fully transitioned out and been destroyed. Circular references or careless strong referencing can lead to such objects never getting destroyed, however, and this helps detect such cases to avoid memory leaks.
- bauiv1.unlock_all_input() None [source]¶
(internal)
Resumes normal keyboard, mouse, and gamepad event processing.
- bauiv1.widget(edit: bauiv1.Widget | None = None, 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, autoselect: bool | None = None) None [source]¶
Edit common attributes of any widget.
Category: User Interface Functions
Unlike other UI calls, this can only be used to edit, not to create.