Package com.valhalla.sdk.api.widgets

Class WidgetSnapshot

java.lang.Object

com.valhalla.sdk.api.widgets.WidgetSnapshot

All Implemented Interfaces:

Identifiable

public final class WidgetSnapshot
extends Object
implements Identifiable

One complete, coherent live-widget observation.

This is the full contract behind the revision-pinned native live-widget bridge. The older Widget model carried geometry but dropped the ordered action slots and the dynamic child index the adapter publishes, while its parser defaulted absent geometry to (0, 0, 0, 0) and absent visibility to true. Both defaults turned "the adapter did not say" into a confident-looking answer.

A snapshot therefore states what is known and nothing more:

• getBounds() is empty when the adapter published no safe geometry, never a zero rectangle.
• isVisibilityKnown() separates "reported hidden" from "not reported", and isVisible() is false in both cases.
• getActions() preserves slot order, including empty slots, because an action's position is part of its identity.
• getCapturedTick() and getSnapshotGeneration() let a caller reject a stale observation before acting on it.

Snapshots are observational. Performing an action requires the capability-backed facade, which revalidates identity on the client thread immediately before dispatch.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	MAX_ACTIONS	Upper bound on retained action slots; a longer list is malformed.
static final int	MAX_TEXT_LENGTH	Upper bound on retained text; a longer value is malformed.
static final int	NO_CHILD_INDEX	Sentinel for a widget that is not a dynamic child.
static final int	NO_SPRITE_ID	Sentinel for a widget whose revision-pinned sprite metadata is absent.

Constructor Summary

Constructors

Constructor	Description
WidgetSnapshot(int packedId, int childIndex, String text, List<String> actions, boolean visible, boolean visibilityKnown, WidgetBounds bounds, int spriteId, long capturedTick, long snapshotGeneration)	Creates a validated snapshot with optional revision-pinned sprite metadata.
WidgetSnapshot(int packedId, int childIndex, String text, List<String> actions, boolean visible, boolean visibilityKnown, WidgetBounds bounds, long capturedTick, long snapshotGeneration)	Creates a validated snapshot.

Method Summary

Modifier and Type	Method	Description
boolean	equals(Object other)
Optional<Integer>	findExactAction(String action)	Finds the single slot whose action equals a label, ignoring case.
List<String>	getActions()	Returns the ordered action slots.
Optional<WidgetBounds>	getBounds()	Returns published geometry.
long	getCapturedTick()	Returns the native tick this observation belongs to.
int	getChildId()	Returns the child identifier within the group.
int	getChildIndex()	Returns the dynamic child index.
int	getGroupId()	Returns the widget group.
int	getId()	Returns the packed groupId << 16 | childId identifier.
long	getSnapshotGeneration()	Returns the monotonic snapshot/session generation.
OptionalInt	getSpriteId()	Returns revision-pinned sprite metadata when the live widget exposes it.
String	getText()	Returns captured text, possibly blank.
int	hashCode()
boolean	hasText(String expected)	Tests full-text equality, ignoring case and surrounding whitespace.
boolean	hasUniqueExactAction(String exactAction)	Tests direct, case-sensitive equality and requires one live action slot.
boolean	isCurrent(long generation)	Tests whether this observation still belongs to a generation.
boolean	isDynamicChild()	Returns whether this observation is a dynamic child.
boolean	isVisibilityKnown()	Returns whether visibility was reported at all.
boolean	isVisible()	Returns whether the adapter reported this widget visible.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

MAX_ACTIONS

public static final int MAX_ACTIONS

Upper bound on retained action slots; a longer list is malformed.

See Also:

• Constant Field Values

MAX_TEXT_LENGTH

public static final int MAX_TEXT_LENGTH

Upper bound on retained text; a longer value is malformed.

See Also:

• Constant Field Values

NO_CHILD_INDEX

public static final int NO_CHILD_INDEX

Sentinel for a widget that is not a dynamic child.

See Also:

• Constant Field Values

NO_SPRITE_ID

public static final int NO_SPRITE_ID

Sentinel for a widget whose revision-pinned sprite metadata is absent.

See Also:

• Constant Field Values

Constructor Details

WidgetSnapshot

public WidgetSnapshot(int packedId,
 int childIndex,
 String text,
 List<String> actions,
 boolean visible,
 boolean visibilityKnown,
 WidgetBounds bounds,
 long capturedTick,
 long snapshotGeneration)

Creates a validated snapshot.

Parameters:

packedId - non-negative groupId << 16 | childId

childIndex - dynamic child index, or NO_CHILD_INDEX

text - captured text, possibly blank; never null

actions - ordered action slots; blank entries preserve position

visible - whether the adapter reported the widget visible

visibilityKnown - whether the adapter reported visibility at all

bounds - published geometry, or null when unknown

capturedTick - native tick the observation belongs to

snapshotGeneration - monotonic snapshot/session generation

Throws:

IllegalArgumentException - for malformed identity, text, or actions

WidgetSnapshot

public WidgetSnapshot(int packedId,
 int childIndex,
 String text,
 List<String> actions,
 boolean visible,
 boolean visibilityKnown,
 WidgetBounds bounds,
 int spriteId,
 long capturedTick,
 long snapshotGeneration)

Creates a validated snapshot with optional revision-pinned sprite metadata. A sprite is discovery information only; it is never an action identity.

Parameters:

spriteId - native sprite id, or NO_SPRITE_ID when absent

Method Details

getId

public int getId()

Returns the packed groupId << 16 | childId identifier.

Specified by:

getId in interface Identifiable

Returns:

the packed groupId << 16 | childId identifier

getGroupId

public int getGroupId()

Returns the widget group.

Returns:

the widget group

getChildId

public int getChildId()

Returns the child identifier within the group.

Returns:

the child identifier within the group

getChildIndex

public int getChildIndex()

Returns the dynamic child index.

Returns:

the dynamic child index, or NO_CHILD_INDEX when this is a top-level component rather than a dynamic child

isDynamicChild

public boolean isDynamicChild()

Returns whether this observation is a dynamic child.

Returns:

whether this observation is a dynamic child

getText

public String getText()

Returns captured text, possibly blank.

Returns:

captured text, possibly blank

getActions

public List<String> getActions()

Returns the ordered action slots.

Empty strings mark slots the widget publishes without an action. Position is preserved because a slot's index is part of the contract the client uses to dispatch.

Returns:

immutable ordered action slots

getSpriteId

public OptionalInt getSpriteId()

Returns revision-pinned sprite metadata when the live widget exposes it. This value cannot authorize interaction by itself.

hasUniqueExactAction

public boolean hasUniqueExactAction(String exactAction)

Tests direct, case-sensitive equality and requires one live action slot. The generic action bridge deliberately does not trim, normalize, or choose among repeated labels.

findExactAction

public Optional<Integer> findExactAction(String action)

Finds the single slot whose action equals a label, ignoring case.

Parameters:

action - exact action label

Returns:

the matching slot index, or empty when absent or ambiguous

isVisible

public boolean isVisible()

Returns whether the adapter reported this widget visible.

Returns:

whether the adapter reported this widget visible

isVisibilityKnown

public boolean isVisibilityKnown()

Returns whether visibility was reported at all.

isVisible() is false both for a widget reported hidden and for one whose visibility the adapter never published. Use this to tell the two apart before treating absence as evidence.

Returns:

true when the adapter published a visibility flag

getBounds

public Optional<WidgetBounds> getBounds()

Returns published geometry.

Returns:

validated native-surface bounds, or empty when the adapter published none

getCapturedTick

public long getCapturedTick()

Returns the native tick this observation belongs to.

Returns:

the native tick this observation belongs to

getSnapshotGeneration

public long getSnapshotGeneration()

Returns the monotonic snapshot/session generation.

Returns:

the monotonic snapshot/session generation

isCurrent

public boolean isCurrent(long generation)

Tests whether this observation still belongs to a generation.

Parameters:

generation - the caller's current snapshot generation

Returns:

true when the snapshot is from that same generation

hasText

public boolean hasText(String expected)

Tests full-text equality, ignoring case and surrounding whitespace.

Parameters:

expected - expected text

Returns:

true when the captured text matches

equals

public boolean equals(Object other)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object