UiWidget
Extends: BGE.GameEntity
Base Abstract class for all UI Elements
Properties
customPosition(boolean) — If position = "custom", then m.customX is horizontal position of this element from the parent position ' and m.customY is the vertical position of this element from the parent position (positive is down)customX(float)customY(float)horizAlign(string) — If customPosition is false, this dictates where horizontally in the container this element should go. Can be: "left", "center" or "right"vertAlign(string) — If customPosition is false, this dictates where vertically in the container this element should go. Can be: "top", "center" or "bottom"width(integer) — Width of the elementheight(integer) — Height of the elementfocusable(boolean) — Can this widget receive focus/hover from its owning UiContainer's cursor?focused(boolean) — Does this widget currently have focus? Set by the owning UiContainer - do not set directly.hovered(boolean) — Is the owning UiContainer's cursor currently over this widget? Set by the owning UiContainer.parentContainer(UiWidget) — The UiContainer this widget was added to via addChild() - set by ' UiContainer.addChild(). Used by BGE.UI.FocusManager to reposition a ' focusable widget correctly when seeding initial focus before the first ' draw() has ever positioned it (see FocusManager.update()).canvas(BGE.Canvas)padding(OffsetSize)margin(OffsetSize)hasAppliedThemeFont(boolean) — Latches true the first time this widget applies a resolved theme's ' custom font to its own DrawableText (see applyThemeFont()) - a theme's ' font is only ever applied once per widget, which sidesteps having to ' compare two roFont instances with=(a runtime crash on native ' components in BrightScript) to detect a later theme/font change.
Constructor
new UiWidget(game: BGE.Game): UiWidgetParameters
game(BGE.Game)
Instance Methods
getValue(): dynamic
Function to get the value of the UI element
Returns
dynamic
draw(parent?: UiWidget): void
Method called each frame to draw any images of this entity
Parameters
parent(UiWidget, optional, default: "invalid") — the parent of this Ui Element - will be an object with {x, y, width, height}
Returns
void
onFocus(): void
Called when this widget gains focus (via the owning UiContainer's cursor or focus-order seeding). Override to show a focus-ring, etc.
Returns
void
onBlur(): void
Called when this widget loses focus.
Returns
void
drawOverlay(canvas: BGE.Canvas, theme: BGE.UI.Theme): void
Called once per frame, for whichever widget currently has focus, by BGE.UI.FocusManager.draw() - AFTER the whole gameUi tree has drawn, so this always renders above every other widget regardless of container z-order/nesting. Override to draw content that must float above everything else, e.g. Select's popup option list (see BGE.UI.Select). Empty by default - most widgets don't need this.
Parameters
canvas(BGE.Canvas)theme(BGE.UI.Theme)
Returns
void
onMouseOver(): void
Called when the owning UiContainer's cursor moves onto this widget.
Returns
void
onMouseOut(): void
Called when the owning UiContainer's cursor moves off this widget.
Returns
void
onMouseDown(): void
Called when OK is pressed while the cursor is over this widget (or this widget is focused via cursor-primary hover).
Returns
void
onMouseUp(): void
Called when OK is released while the cursor is over this widget.
Returns
void
onClick(): void
Called when OK is pressed and released while the cursor is over this widget (or this widget is focused). The common "activate" hook - most widgets (Button, Checkbox, Select) only need to override this one.
Returns
void
handleInput(input: BGE.GameInput): boolean
Called only on the widget currently focused in its owning UiContainer (when that container's focusEnabled is true), Roku onKeyEvent-style - see https://developer.roku.com/dev/docs/onkeyevent. Return true to mark the input handled: the container won't move its cursor this frame. Override to react to directional input while focused (e.g. Slider/Select adjusting on Left/Right) - call input.consume() too if the input shouldn't also reach GameEntity.onInput(). This is separate from onInput(), which every widget still receives unconditionally each frame regardless of focus - see UiContainer.onInput().
Parameters
input(BGE.GameInput)
Returns
boolean
setCanvas(canvas?: BGE.Canvas): void
Set the canvas this UIWidgetDraws to
Parameters
canvas(BGE.Canvas, optional, default: "invalid") — The canvas this should draw to - if invalid, then will draw to the game canvas
Returns
void
repositionBasedOnParent(parent?: UiWidget): void
Method called each frame to reposition
Parameters
parent(UiWidget, optional, default: "invalid") — the parent of this Ui Element - will be an object with {x, y, width, height}
Returns
void
getWorldPosition(parent?: UiWidget): BGE.Math.Vector
Method called each frame to draw any images of this entity
Parameters
parent(UiWidget, optional, default: "invalid") — the parent of this Ui Element
Returns
BGE.Math.Vector
containsPoint(point: BGE.Math.Vector): boolean
Is the given point (in the same coordinate space as m.position - UI canvas space) within this widget's current bounds? Bounds are half-open: the top-left corner counts, the bottom-right edge doesn't.
Parameters
point(BGE.Math.Vector)
Returns
boolean
isContainer(): boolean
Is this widget a UiContainer? Overridden to true in UiContainer.
Returns
boolean
resolveTheme(parent?: UiWidget): BGE.UI.Theme
Resolves the theme a draw() override should use: the parent's effectiveTheme() when parent is a UiContainer, else the game's defaultTheme. Shared by every widget's draw() instead of each duplicating this fallback.
Parameters
parent(UiWidget, optional, default: "invalid") — the parent passed into draw()
Returns
BGE.UI.Theme
drawThemedBackground(
theme: BGE.UI.Theme,
x: float,
y: float,
width: float,
height: float,
color: integer,
): void
Draws a widget's themed background fill: theme.backgroundImage (a 9-patch or plain image) when set, else a flat color rectangle. Shared by every widget with a themed background (Button, Checkbox, Slider, TextInput, Select) instead of each duplicating this dispatch.
Parameters
theme(BGE.UI.Theme)x(float)y(float)width(float)height(float)color(integer) — flat fill color, used only when theme.backgroundImage is invalid
Returns
void
applyThemeFont(
theme: BGE.UI.Theme,
drawableText: BGE.DrawableText,
): void
Applies theme.font to drawableText, once, the first time this widget draws with a theme whose font is set. A theme with no custom font (invalid) leaves drawableText untouched - today's default-font behavior. Applying more than once would mean detecting a later theme/font change, which can't be done by comparing two roFont instances with = (a runtime crash on native components) - so this is deliberately a one-time application, not dynamic font-swapping.
Parameters
theme(BGE.UI.Theme) — the theme resolved via resolveTheme()drawableText(BGE.DrawableText) — this widget's own text drawable
Returns
void
isValid(): boolean
Inherited from BGE.GameEntity#isValid
Overrides: BGE.GameEntity#isValid
Is this still a valid entity?
Returns
boolean
isOnScreen(): boolean
Inherited from BGE.GameEntity#isOnScreen
Overrides: BGE.GameEntity#isOnScreen
Whether this entity had at least one drawable actually drawn (not culled by the camera frustum) as of the last frame. True for an entity with no drawables at all, since there's no geometry to say it's off-screen - a purely logical entity (a spawner, a game-state controller) shouldn't get silently treated as "off-screen" by code using this to skip work.
This is a signal only - nothing in the engine uses it to skip an entity's own onUpdate()/collision checks automatically, since a culled entity can still be relevant to gameplay (e.g. approaching from off-screen). It's meant for game code that wants to opt in to skipping its own expensive, purely-visual per-frame work for an entity that isn't currently visible. See issue #75.
Returns
boolean
invalidate(): void
Inherited from BGE.GameEntity#invalidate
Overrides: BGE.GameEntity#invalidate
Marks this entity as invalid, so it will be cleared/destroyed at the end of the frame
Returns
void
invalidateAfter(delayMs: integer): void
Inherited from BGE.GameEntity#invalidateAfter
Overrides: BGE.GameEntity#invalidateAfter
Marks this entity as dying: it stays fully alive, valid, and processed normally (still updates, still draws, still collides) for delayMs milliseconds, then invalidate() is called automatically. Use this instead of calling invalidate() directly when an entity needs to trigger a one-shot effect (e.g. a particle burst) that should have a chance to actually render before the entity disappears - invalidate() removes all of this entity's drawables from the scene immediately, which would cut off that effect on its very first frame.
Sets isDying = true immediately, so other game code (e.g. a collision handler) can check it to avoid re-triggering logic on an entity that's already in its death sequence. Colliders are NOT removed during the grace period - a dying entity can still register collisions until it's actually invalidated, so guard on isDying at the very top of onCollision() (before any score/sound/effect side effect) to avoid double-firing.
Parameters
delayMs(integer) — how long to wait, in milliseconds, before this entity is actually invalidated
Returns
void
checkDyingTimeout(): void
Inherited from BGE.GameEntity#checkDyingTimeout
Overrides: BGE.GameEntity#checkDyingTimeout
Called once per frame (from Game's entity-processing loop) for every valid entity, regardless of whether it overrides onUpdate() - checks whether an invalidateAfter() grace period has elapsed and, if so, calls the real invalidate(). A no-op for an entity that isn't dying.
Returns
void
onCreate(args: roAssociativeArray): void
Inherited from BGE.GameEntity#onCreate
Overrides: BGE.GameEntity#onCreate
Method to be called when this entity is added to a Game. Override in subclass
Parameters
args(roAssociativeArray)
Returns
void
onUpdate(deltaTime: float): void
Inherited from BGE.GameEntity#onUpdate
Overrides: BGE.GameEntity#onUpdate
Method for handling any updates based on time since previous frame
Parameters
deltaTime(float) — milliseconds since last frame
Returns
void
onCollision(
myCollider: Collider,
otherCollider: Collider,
otherEntity: GameEntity,
): void
Inherited from BGE.GameEntity#onCollision
Overrides: BGE.GameEntity#onCollision
Method for processing all collisions
Parameters
myCollider(Collider) — the collider of this entity that collidedotherCollider(Collider) — the collider of the other entity in the collisionotherEntity(GameEntity) — the entity that owns the other collider
Returns
void
onDrawBegin(
Renderer: renderer,
gameRenderer: Renderer,
uiRenderer: Renderer,
): void
Inherited from BGE.GameEntity#onDrawBegin
Overrides: BGE.GameEntity#onDrawBegin
Method called each frame before drawing any images of this entity
Parameters
Renderer(renderer) — the Renderer images will be drawn togameRenderer(Renderer)uiRenderer(Renderer)
Returns
void
onDrawEnd(
canvas: Renderer,
gameRenderer: Renderer,
uiRenderer: Renderer,
): void
Inherited from BGE.GameEntity#onDrawEnd
Overrides: BGE.GameEntity#onDrawEnd
Method called each frame after drawing all images of this entity
Parameters
Returns
void
onInput(input: GameInput): void
Inherited from BGE.GameEntity#onInput
Overrides: BGE.GameEntity#onInput
Method to process input per frame
Parameters
input(GameInput) — GameInput object for the last frame
Returns
void
onControls(controls: BGE.Controller.ControlMap): void
Inherited from BGE.GameEntity#onControls
Overrides: BGE.GameEntity#onControls
Called once per frame, before onUpdate(), with the game's ControlMap - the same object as m.game.controls, just without the boilerplate of reaching through m.game each frame.
IMPORTANT: only called when the game has bound at least one action/axis via ControlMap.bindAction()/bindAxis() (ControlMap.hasBindings()). A game that never binds anything never gets this callback at all - not with an empty ControlMap, not with an error, just silently never called. This preserves ControlMap's zero-cost guarantee: binding nothing costs nothing, including this dispatch. If your entity overrides onControls() but never sees it fire, check that something in the game calls bindAction/bindAxis.
Parameters
controls(BGE.Controller.ControlMap)
Returns
void
onECPKeyboard(char: integer): void
Inherited from BGE.GameEntity#onECPKeyboard
Overrides: BGE.GameEntity#onECPKeyboard
Method to process an ECP keyboard event
Parameters
char(integer)
Returns
void
onECPInput(data: roInputEvent): void
Inherited from BGE.GameEntity#onECPInput
Overrides: BGE.GameEntity#onECPInput
Method to process an External Control Protocol event
Parameters
data(roInputEvent)
Returns
void
onAudioEvent(msg: roAudioPlayerEvent): void
Inherited from BGE.GameEntity#onAudioEvent
Overrides: BGE.GameEntity#onAudioEvent
Method to handle audio events
Parameters
msg(roAudioPlayerEvent) — roAudioPlayerEvent
Returns
void
onPause(): void
Inherited from BGE.GameEntity#onPause
Overrides: BGE.GameEntity#onPause
Called when the game pauses
Returns
void
onResume(pauseTimeMs: integer): void
Inherited from BGE.GameEntity#onResume
Overrides: BGE.GameEntity#onResume
Called when the game unpauses
Parameters
pauseTimeMs(integer) — The number of milliseconds the game was paused
Returns
void
onUrlEvent(msg: roUrlEvent): void
Inherited from BGE.GameEntity#onUrlEvent
Overrides: BGE.GameEntity#onUrlEvent
Called on url event
Parameters
msg(roUrlEvent) — roUrlEvent
Returns
void
onGameEvent(eventName: string, data: roAssociativeArray): void
Inherited from BGE.GameEntity#onGameEvent
Overrides: BGE.GameEntity#onGameEvent
General purpose event handler for in-game events.
Parameters
eventName(string) — Event name that describes the event typedata(roAssociativeArray) — Any extra data to go along with the event
Returns
void
onChangeRoom(newRoom: Room): void
Inherited from BGE.GameEntity#onChangeRoom
Overrides: BGE.GameEntity#onChangeRoom
Method called when the current room changes. This method is only called when the entity is marked as persistant, otherwise entities are destroyed on room changes.
Parameters
newRoom(Room) — The next room
Returns
void
onDestroy(): void
Inherited from BGE.GameEntity#onDestroy
Overrides: BGE.GameEntity#onDestroy
Method called when this entity is destroyed
Returns
void
addCircleCollider(
colliderName: string,
radius: float,
offset_x?: float,
offset_y?: float,
enabled?: boolean,
): CircleCollider
Inherited from BGE.GameEntity#addCircleCollider
Overrides: BGE.GameEntity#addCircleCollider
Adds a circle collider to this entity
Parameters
colliderName(string) — Name of the collider (only one collider with the same name can be added)radius(float) — radius of the circleoffset_x(float, optional, default: 0) — horizontal offset from entity position of centre of the circleoffset_y(float, optional, default: 0) — vertical offset from entity position of centre of the circleenabled(boolean, optional, default: true) — is this collider enabled?
Returns
addRectangleCollider(
colliderName: string,
width: float,
height: float,
offset_x?: float,
offset_y?: float,
enabled?: boolean,
): RectangleCollider
Inherited from BGE.GameEntity#addRectangleCollider
Overrides: BGE.GameEntity#addRectangleCollider
Adds a rectangle collider to this entity
Parameters
colliderName(string) — Name of the collider (only one collider with the same name can be added)width(float) — Width of rectangleheight(float) — Height of rectangleoffset_x(float, optional, default: 0) — horizontal offset from entity position of left edge of rectangleoffset_y(float, optional, default: 0) — vertical offset from entity position of bottom edge of rectangle (top edge is at offset_y - height)enabled(boolean, optional, default: true) — is this collider enabled?
Returns
addCollider(colliderToAdd: Collider): Collider
Inherited from BGE.GameEntity#addCollider
Overrides: BGE.GameEntity#addCollider
Adds a collider that has already been constructed
Parameters
colliderToAdd(Collider) — the collider to add (only one collider with the same name can be added)
Returns
getCollider(colliderName: string): Collider
Inherited from BGE.GameEntity#getCollider
Overrides: BGE.GameEntity#getCollider
Gets a collider based on its name
Parameters
colliderName(string) — The name of the collider to find
Returns
removeCollider(colliderName: string): void
Inherited from BGE.GameEntity#removeCollider
Overrides: BGE.GameEntity#removeCollider
Removes a collider by its name
Parameters
colliderName(string) — the name of the collider to remove
Returns
void
clearAllColliders(): void
Inherited from BGE.GameEntity#clearAllColliders
Overrides: BGE.GameEntity#clearAllColliders
Remove all colliders from this entity
Returns
void
addImage(
regionName?: string,
imageName: string,
region: roRegion,
args?: roAssociativeArray,
insertPosition?: integer,
): Image
Inherited from BGE.GameEntity#addImage
Overrides: BGE.GameEntity#addImage
Adds a basic image (non-animated) to be drawn for this entity
Parameters
regionName(string, optional, default: "\"\"") — an optional unique name for the region, used for caching image dataimageName(string) — Name of the imageregion(roRegion) — anroRegionof a bitmap to drawargs(roAssociativeArray, optional, default: "{}") — any extra properties to set (e.g. offset_x, offset_y, rotation, scale_x, scale_y, etc.)insertPosition(integer, optional, default: -1) — the position/order in the images array where the image should be added (defaults to being added at the end)
Returns
addAnimatedImage(
imageName: string,
regions: Array.<roRegion>,
args?: roAssociativeArray,
insertPosition?: integer,
): AnimatedImage
Inherited from BGE.GameEntity#addAnimatedImage
Overrides: BGE.GameEntity#addAnimatedImage
Adds a animated image to be drawn for this entity. Animated images cycle through regions of a bitmap (e.g. spritesheet)
Parameters
imageName(string) — Name of the imageregions(Array.<roRegion>) — an array ofroRegionof a bitmap to drawargs(roAssociativeArray, optional, default: "{}") — any extra properties to set (e.g. offset_x, offset_y, rotation, scale_x, scale_y, etc.)insertPosition(integer, optional, default: -1) — the position/order in the images array where the image should be added (defaults to being added at the end)
Returns
addSprite(
bitmap: roBitmap,
imageName: string,
spriteSheet: roBitmap,
cellWidth: integer,
cellHeight: integer,
args?: roAssociativeArray,
insertPosition?: integer,
): Sprite
Inherited from BGE.GameEntity#addSprite
Overrides: BGE.GameEntity#addSprite
Adds a Sprite to be drawn for this entity. Sprites can have specific animations configured buy choosing series of cells from a sprite sheet
Parameters
bitmap(roBitmap) — the bitmap object to use for teh SpriteSheet (e.g response from game.getBitmap("bitmap_name"))imageName(string) — Name of the imagespriteSheet(roBitmap)cellWidth(integer) — the height in pixels of a dingle cell in the spritecellHeight(integer) — the height in pixels of a dingle cell in the spriteargs(roAssociativeArray, optional, default: "{}") — any extra properties to set (e.g. offset_x, offset_y, rotation, scale_x, scale_y, etc.)insertPosition(integer, optional, default: -1) — the position/order in the images array where the image should be added (defaults to being added at the end)
Returns
addRectangle(
rectangleName: string,
width: float,
height: float,
args?: roAssociativeArray,
insertPosition?: integer,
): DrawableRectangle
Inherited from BGE.GameEntity#addRectangle
Overrides: BGE.GameEntity#addRectangle
Adds a rectangle to be drawn for this entity. The rectangle's top left corner sits at the entity's position (plus the drawable's own offset), and it extends width to the right and height downwards in world space.
Parameters
rectangleName(string) — Name of the rectanglewidth(float) — width of the rectangle in world unitsheight(float) — height of the rectangle in world unitsargs(roAssociativeArray, optional, default: "{}") — any extra properties to set (e.g. color, outlineRGBA, outlineWidth, filled, offset, rotation, scale, drawMode)insertPosition(integer, optional, default: -1) — the position/order in the drawables array where the rectangle should be added (defaults to being added at the end)
Returns
addCircle(
circleName: string,
radius: float,
args?: roAssociativeArray,
insertPosition?: integer,
): DrawableCircle
Inherited from BGE.GameEntity#addCircle
Overrides: BGE.GameEntity#addCircle
Adds a filled circle to be drawn for this entity, via the renderer's shared circle texture. The circle's top left (of its bounding square) sits at the entity's position (plus the drawable's own offset), extending radius * 2 right and down in world space - like DrawableRectangle, it foreshortens into an ellipse in the oriented 3D draw modes. Use addSphere() instead for a circle that never does this.
Parameters
circleName(string) — Name of the circleradius(float) — radius of the circle in world unitsargs(roAssociativeArray, optional, default: "{}") — any extra properties to set (e.g. color, outlineRGBA, outlineWidth, outlineSegments, offset, rotation, scale, drawMode)insertPosition(integer, optional, default: -1) — the position/order in the drawables array where the circle should be added (defaults to being added at the end)
Returns
addSphere(
sphereName: string,
radius: float,
args?: roAssociativeArray,
insertPosition?: integer,
): DrawableSphere
Inherited from BGE.GameEntity#addSphere
Overrides: BGE.GameEntity#addSphere
Adds a filled circle that always renders as an undistorted circle regardless of camera angle - because a sphere looks the same from every direction. See DrawableSphere.
Parameters
sphereName(string) — Name of the sphereradius(float) — radius of the sphere in world unitsargs(roAssociativeArray, optional, default: "{}") — any extra properties to set (e.g. color, outlineRGBA, outlineWidth, outlineSegments, offset, scale)insertPosition(integer, optional, default: -1) — the position/order in the drawables array where the sphere should be added (defaults to being added at the end)
Returns
addParticles(
particlesName: string,
shape: BGE.ParticleShape,
args?: roAssociativeArray,
insertPosition?: integer,
): DrawableParticles
Inherited from BGE.GameEntity#addParticles
Overrides: BGE.GameEntity#addParticles
Adds a particle emitter to be drawn for this entity. See DrawableParticles for the full set of configurable behavior (spawnRate, lifetime, velocity/spread, acceleration, color/alpha/size-over-lifetime, maxParticles) and its start()/stop()/ burst() control API.
Parameters
particlesName(string) — Name of the particle emitter drawableshape(BGE.ParticleShape) — see DrawableParticles.shapeargs(roAssociativeArray, optional, default: "{}") — any extra properties to set (e.g. spawnRate, lifetime, velocity, acceleration, startColor, endColor, startAlpha, endAlpha, startSize, endSize, maxParticles)insertPosition(integer, optional, default: -1) — the position/order in the drawables array where the emitter should be added (defaults to being added at the end)
Returns
addDrawable(
imageName: string,
drawableObject: Drawable,
insertPosition?: integer,
): Drawable
Inherited from BGE.GameEntity#addDrawable
Overrides: BGE.GameEntity#addDrawable
Adds any Drawable/Image object to this entity
Parameters
imageName(string) — Name of the imagedrawableObject(Drawable) — The image to be addedinsertPosition(integer, optional, default: -1) — the position/order in the images array where the image should be added (defaults to being added at the end)
Returns
getDrawable(imageName: string, drawableName: string): Drawable
Inherited from BGE.GameEntity#getDrawable
Overrides: BGE.GameEntity#getDrawable
Gets a drawable by its name from the lookup table
Parameters
imageName(string) — Name of drawable to getdrawableName(string)
Returns
removeDrawable(drawableName: string): void
Inherited from BGE.GameEntity#removeDrawable
Overrides: BGE.GameEntity#removeDrawable
Removes a drawable from the entity
Parameters
drawableName(string) — Name of drawable to remove
Returns
void
updateTransformationMatrix(): void
Inherited from BGE.GameEntity#updateTransformationMatrix
Overrides: BGE.GameEntity#updateTransformationMatrix
Returns
void
movedLastFrame(): boolean
Inherited from BGE.GameEntity#movedLastFrame
Overrides: BGE.GameEntity#movedLastFrame
Returns
boolean
getStaticVariable(staticVariableName: string): dynamic
Inherited from BGE.GameEntity#getStaticVariable
Overrides: BGE.GameEntity#getStaticVariable
TODO: work on statics
Parameters
staticVariableName(string)
Returns
dynamic
setStaticVariable(
staticVariableName: string,
staticVariableValue: dynamic,
): void
Inherited from BGE.GameEntity#setStaticVariable
Overrides: BGE.GameEntity#setStaticVariable
TODO: work on statics
Parameters
staticVariableName(string)staticVariableValue(dynamic)
Returns
void
addInterface(interfaceName: string): void
Inherited from BGE.GameEntity#addInterface
Overrides: BGE.GameEntity#addInterface
TODO: work on Interfaces
Parameters
interfaceName(string)
Returns
void
hasInterface(interfaceName: string): boolean
Inherited from BGE.GameEntity#hasInterface
Overrides: BGE.GameEntity#hasInterface
TODO: work on Interfaces
Parameters
interfaceName(string)
Returns
boolean
debugDraw(
renderObj: Renderer,
drawAxes?: boolean,
drawName?: boolean,
): void
Inherited from BGE.GameEntity#debugDraw
Overrides: BGE.GameEntity#debugDraw
Draws the entity's axes and/or its name
Parameters
renderObj(Renderer)drawAxes(boolean, optional, default: false)drawName(boolean, optional, default: false)
Returns
void