Input API

Note

This document is archived as it refers to a design process.

The high level API for Fyne aims to be device agnostic. This is an important part of offering a truly cross-platform framework. We want to support apps that could work on desktop with mouse and keyboard, touch screens on mobile devices and more.

The APIs are split into multiple levels, the input abstractions, widget callbacks and driver specific APIs.

Input abstraction

The input device abstraction focuses on the user intent of an action. On a desktop clicking a mouse button is the same as a touch screen tapping. A scrollwheel motion for a desktop interaction is the same as a tap and drag on a smart phone.

Pointer input

A PointerEvent is passed to each of these functions. It has a Position parameter so that calculations can be made based on the location of a tap/click.

Function	Desktop	Mobile example	Fields
Tapped	left mouse click	single finger tap	n/a
TappedSecondary	right mouse click	single finger long tap	n/a
Scrolled	scroll wheel	finger tap and drag	X/Y delta
Zoomed	CTRL + scroll wheel	two finger "pinch"	zoom delta

Key input

Key input is split into three types - text (visible), key (control keys) and shortcut (combination). A visible input is presented as a rune that can be printed or appended. An invisible one has a Name property that can be compared to a list of key names like KeyReturn. Shortcut is called when Fyne recognised a particular combination of actions that result in a shortcut.

Function	Example	Desktop	Mobile example
TypedRune	c	c key	c virtual key
	D	Shift + d	D virtual upper
	%	Shift + 5	% symbol picker
TypedKey	Escape	Esc key	n/a
	Up	Up key	up virtual key / keyboard swipe up
	Delete	Del key	del virtual key
Shortcut	Copy	Ctrl + c	Double tap and selecting from popup
	Undo	Ctrl + z	Shake

Widget callbacks

Callbacks that the API user can set should begin with "On" and then the verb - derived from the list above.

Widget	Callback	Notes
Button	OnTapped	When a button has been tapped in any manner (mouse, keyboard, test)
Check	OnChanged	The widget handles interactions, mouse or keyboard, and this event shows a state change
Entry	OnTyped	When text has been written to an entry widget causing the content to be altered
Form	OnCancelled	Called when a form is cancelled - this could be due to cancel being clicked, Escape key pressed etc

Driver specifics (Future)

Each (class of) driver may choose to provide specific access to lower level device event information. Using these APIs will mean that the drivers must be available at compile time. Also be careful to check that the current driver is of the type you expect - callbacks may not fire in the way you expect if a different driver is loaded. For example relying on a MouseDown callback may not work when a mobile driver is loaded.

Drivers are also able to extend the information passed to the higher level events. The PointerEvent passed to Tapped() could be enhanced to include a KeyModifier field by the desktop driver.

Desktop

MouseDown, MouseUp, MouseScroll will provide hardware triggered events before being interpreted for the higher level APIs.

KeyDown, KeyUp will be triggered for the hardware down/up signals which are focussed on key presses rather than the symbol created by such actions.