Button Trait

API Service: ButtonApi

The state and events from a momentary push-button input. This trait facilitates reactions to basic user input. Both the basic button state (pressed or not) as well as higher-level input events like "double click" are supported.

Method	Request Type	Response Type	Description
GetButtonState	GetButtonStateRequest	ButtonState	Gets the current state of the button. Contain the most recent gesture, so clients using polling can still detect and respond to gestures. However, to reduce latency, PullButtonState is recommended for this use case.
PullButtonState	PullButtonStateRequest	PullButtonStateResponse stream	Fetches changes to button Press state and gestures, and optionally the initial state.
UpdateButtonState	UpdateButtonStateRequest	ButtonState	Updates the stored button state according to the write mask. Real (physical) buttons are not expected to implement this method - it is intended for virtual or mock buttons

ButtonState

Field Name	Type	Description
state	ButtonState.Press
state_change_time	google.protobuf.Timestamp	The time that state changed to its present value.
most_recent_gesture	ButtonState.Gesture	The gesture that is currently in progress, or finished most recently. May be absent, if there is no gesture recorded for this button.

ButtonState.Gesture

A representation of user intent, deduced from a pattern of button presses. The way that the device converts button presses into gestures is implementation-defined. There may be a delay between the button presses and the registration of a gesture.

Field Name	Type	Description
id	string	Opaque identifier changes each time a new gesture begins. The gesture will remain in the ButtonState even when the client has already seen it; the client can use the id to detect when a new gesture has begun.
kind	ButtonState.Gesture.Kind
count	int32	A counter for sub-events that occur within a single gesture. See the Kind for details of meaning.
start_time	google.protobuf.Timestamp	The time when the gesture was first recognised.
end_time	google.protobuf.Timestamp	The time when the gesture was recognised as completed. For HOLD gestures, this remains unset until the button is released.

ButtonState.Gesture.Kind

Name	Number	Description
KIND_UNSPECIFIED	0
CLICK	1	One or more short press-and-release actions. Clicks in short succession may be fused into double-clicks, triple-clicks etc. - in this case, the number of fused clicks is stored in the count field. When clicks are fused in this way, the gesture will not appear at all until the final click has finished - it's not possible for a single gesture to be first reported as a single click, and then modified to a double click.
HOLD	2	Button is kept in the pressed state for an extended period. Buttons may support repeat events, in which case the count will increment for each repeat event, keeping id the same because it's part of the same gesture. For HOLD gestures, the end_time is not set until the button has been released, allowing the client to determine when the gesture has ended.

ButtonState.Press

Instantaneous button state.

Name	Number	Description
PRESS_UNSPECIFIED	0
UNPRESSED	1	Button is in its neutral position.
PRESSED	2	Button is being pushed in.

GetButtonStateRequest

Field Name	Type	Description
name	string
read_mask	google.protobuf.FieldMask

PullButtonStateRequest

Field Name	Type	Description
name	string
read_mask	google.protobuf.FieldMask
updates_only	bool	By default, PullButtonState sends the initial ButtonState when the stream opens, followed by changes. Setting updates_only true will disable this behaviour, sending only when the ButtonState changes.

PullButtonStateResponse

Field Name	Type	Description
changes	repeated PullButtonStateResponse.Change

PullButtonStateResponse.Change

Field Name	Type	Description
name	string
change_time	google.protobuf.Timestamp
button_state	ButtonState

UpdateButtonStateRequest

Field Name	Type	Description
name	string
update_mask	google.protobuf.FieldMask
button_state	ButtonState