io7m | single-page | multi-page | JSycamore User Manual
3.2. Text
Previous
3. Standard Components
Up
Front Matter
Next

# 3.3. Buttons

- 3.3.1. Description
- 3.3.2. Semantics

## 3.3.1. Description

1
A button is a simple component that triggers a listener when the user clicks on it.

### 3.3.1.2. Button

3
Buttons always have exactly one assigned listener. A listener is simply a parameterless function that is evaluated by the button implementation and is expected to perform some kind of side effect. By default, buttons have a listener that does nothing. A listener can be assigned to or removed from the button at any time, and "removing" the listener simply re-assigns a default listener that does nothing when evaluated.

## 3.3.2. Semantics

1
Button components implement the given state machine [1]:

### 3.3.2.2. Button State

3
Buttons begin in the BUTTON_IDLE state. If the button is inactive, it will stay in the BUTTON_IDLE state regardless of mouse or keyboard events.
4
Otherwise, assuming that the button is active, if the user moves the mouse cursor over the button, the button transitions to the BUTTON_OVER state. If the user then moves the cursor such that it is no longer over the button, the button transitions back to the BUTTON_IDLE state.
5
When in the BUTTON_OVER state, if the user presses the primary mouse button, the button transitions to the BUTTON_PRESSED state. If the user moves the mouse cursor such that it is no longer over the button (without releasing the primary mouse button), the button transitions to the BUTTON_PRESSED_NOT_OVER state. Otherwise, if the user leaves the mouse cursor over the button and then releases the primary mouse button, the button transitions to the BUTTON_CLICKED state. The button evaluates the associated listener and then either transitions to the BUTTON_OVER state if the mouse cursor is still over the button, or transitions to the BUTTON_IDLE state if the mouse cursor is no longer over the button.
6
In the BUTTON_PRESSED_NOT_OVER state, the user can either release the primary mouse button, which returns the button to the BUTTON_IDLE state, or the user can move the cursor such that it is back over the button again, resulting in the button transitioning back to the BUTTON_PRESSED state.
7
The BUTTON_CLICKED state is the only state in which the listener will be evaluated, and the listener will be evaluated exactly once upon each transition to the BUTTON_CLICKED state.

## Footnotes

1 | Buttons are not necessarily implemented in terms of an explicit state machine; this is merely a method of specifying how buttons should behave. References to this footnote: 1

3.2. Text
Previous
3. Standard Components
Up
Front Matter
Next
io7m | single-page | multi-page | JSycamore User Manual