InputAPI reference
Class VirtualControls
Namespace: MicroEngine.Input
Assembly: MicroEngine.Input.Touch.dll
Guide: Input
On-screen controls at run time: hit testing, finger tracking, d-pad and joystick values, tap latching, haptics and drawing. It is an IActionSource (read by InputMap with the keyboard and gamepad), an ITouchOverlay (drawn by the backend over the game) and an input layer (IInputLayer, at TouchControls): a finger that lands on a control is the control’s, every other finger goes on to gameplay as a pointer. Each finger belongs to the control it started on until it lifts, so two thumbs work independently and a thumb that slides a little stays on its control.
public sealed class VirtualControls : IActionSource, ITouchOverlay, IInputLayerInheritance
Implements
IActionSource, ITouchOverlay, IInputLayer
Constructors
VirtualControls(TouchLayout?)
Creates the controls for layout (null: CreateDefault). Games use the instance in Game.Touch.
public VirtualControls(TouchLayout? layout = null)Parameters
layout TouchLayout?
Exceptions
Two controls share an id.
Properties
Actions
Every action a control of the layout can press.
public IEnumerable<string> Actions { get; }Property Value
Device
Always Touch.
public InputDevice Device { get; }Property Value
FingerCount
Fingers currently on the screen (on a control or not).
public int FingerCount { get; }Property Value
IsActive
Whether the controls take part in the game: the game drawing them over the frame, reading them as an action source and giving them the touches over them. A game’s controls start inactive and cost nothing; they become active when the game sets a Layout or the platform’s touch screen is touch-first (TouchFirst), and stay active. Controls created and driven directly (Update) work whatever this says.
public bool IsActive { get; }Property Value
KeepFrameClear
Whether the game frame is fitted around the controls while they are shown (default true): on screens close to 16:9, where the letterbox bars cannot hold them, the frame is made as large as it can be without any control covering it (see Frame).
public bool KeepFrameClear { get; set; }Property Value
LastFrame
The frame chosen by the last Frame call, in screen pixels (tests and diagnostics).
public RectF LastFrame { get; }Property Value
Layout
The layout in use. Setting it (a scene with other controls) releases every finger and activates the controls (IsActive).
public TouchLayout Layout { get; set; }Property Value
MinimumFrameFraction
The smallest frame, as a fraction of the largest, that KeepFrameClear may choose; below it controls overlap the edge of the frame instead.
public float MinimumFrameFraction { get; set; }Property Value
PixelsPerDp
Pixels per dp used by the current layout, after shrinking to fit the screen.
public float PixelsPerDp { get; }Property Value
Shown
Whether the controls are drawn this frame.
public bool Shown { get; }Property Value
TouchFirst
Whether the screen they were last laid out for is touch-first.
public bool TouchFirst { get; }Property Value
Vibrations
Vibrations requested since start (tests and diagnostics).
public int Vibrations { get; }Property Value
Methods
Activate()
Activates the controls (IsActive); the game wires them in at its next frame. Does nothing when they already are.
public void Activate()BeginFrame(ITouchScreen?)
Starts a frame: taps an update has read stop counting, and the controls are laid out again when the screen’s size, safe area or density changed (releasing every finger). Called by the loop before the frame’s touches.
public void BeginFrame(ITouchScreen? screen)Parameters
screen ITouchScreen?
CancelAll()
Releases every finger, as when the game loses focus or is suspended. Toggled buttons stay as they are.
public void CancelAll()Draw(IOverlayCanvas)
Draws the shown controls with the layout’s skin (Skin, by default DefaultTouchSkin shaped by the layout’s styles), each with its state this frame.
public void Draw(IOverlayCanvas canvas)Parameters
canvas IOverlayCanvas
EndFrame(float, InputDevice)
Ends a frame’s touches: works out the actions the controls press, whether they are shown and their press
animations. otherDevice is the device that last pressed an action (a keyboard or gamepad hides
Auto controls).
public void EndFrame(float dt, InputDevice otherDevice = InputDevice.None)Parameters
dt float
otherDevice InputDevice
EndUpdate()
Ends a fixed update: the taps it read stop counting, so a tap shorter than a frame is down in exactly one update, the first that reads it, as a key’s or a gamepad button’s is, also when a slow frame catches up with several updates. The engine’s loop calls it after every update; code that samples the controls itself calls it after each of its updates (without it, read taps expire at the next BeginFrame).
public void EndUpdate()Frame(Vector2, RectF, int, int, Presentation?)
Where the backend draws the game frame. Without shown controls it is Fit. With shown
controls that would cover the largest frame, the frame moves to the top of the safe area, or just below a control
anchored at the top (horizontally centred), and takes the largest size at which no control of the layout overlaps it, never below
MinimumFrameFraction; a whole-number scale is kept when it is within 90 % of that size, so pixels
stay even when it costs little (unless the presentation’s rounding is fractional, as in HighResolution2D; null presentation is PixelArt). Controls hidden by context still count, so a dialogue does not resize the game.
public RectF Frame(Vector2 window, RectF safeArea, int virtualWidth, int virtualHeight, Presentation? presentation = null)Parameters
window Vector2
safeArea RectF
virtualWidth int
virtualHeight int
presentation Presentation?
Returns
Geometry(string)
The control’s centre and drawn radius in screen pixels, as last laid out.
public (Vector2 Center, float Radius) Geometry(string id)Parameters
id string
Returns
(Vector2 Center, float Radius)
Handle(in InputEvent)
The input layer: takes the touch-screen pointers (Touch of TouchScreen) that land on a control (HandleTouch, with ScreenPosition); everything else goes on.
public bool Handle(in InputEvent e)Parameters
Returns
HandleTouch(TouchEvent)
Applies one touch (screen pixels). Returns whether the finger is a control’s: a finger that lands on a visible control is, until it lifts; any other finger is not, and its events are left for gameplay.
public bool HandleTouch(TouchEvent e)Parameters
Returns
IsDown(string)
Whether a control holds action down; a tap shorter than an update still counts once.
public bool IsDown(string action)Parameters
action string
Returns
IsPressed(string)
Whether the control is pressed (a button held or toggled on, a d-pad or stick pushed).
public bool IsPressed(string id)Parameters
id string
Returns
IsVisible(string)
Whether the control id is shown and touchable, after SetVisible and the scene’s context.
public bool IsVisible(string id)Parameters
id string
Returns
Exceptions
No control has that id.
ScriptLift(int)
Lifts a scripted finger.
public void ScriptLift(int finger)Parameters
finger int
ScriptTouch(int, string, Vector2)
A scripted touch, as an input script’s touch command: finger finger goes down (or moves)
on control target, displaced by offset radii from its centre, at the next
update. The touch goes through the same hit testing as a real finger.
public void ScriptTouch(int finger, string target, Vector2 offset)Parameters
finger int
target string
offset Vector2
ScriptTouchAt(int, Vector2)
A scripted touch at a point given as fractions (0..1) of the screen.
public void ScriptTouchAt(int finger, Vector2 normalized)Parameters
finger int
normalized Vector2
SetContext(IEnumerable<string>?)
The actions the current context needs (the top scene’s Scene.TouchActions, set by the game
every frame): only controls that press at least one of them are shown and touchable; null shows them all. A
dialogue that only advances with “confirm” hides the d-pad over its text, keeps the button that confirms, and
the hidden controls release their fingers. The game frame does not change size with the context.
public void SetContext(IEnumerable<string>? actions)Parameters
actions IEnumerable<string>?
SetVisible(string, bool)
Shows or hides one control (hidden ones ignore touches and release their finger).
public void SetVisible(string id, bool visible)Parameters
id string
visible bool
TakeScripted(List<TouchEvent>)
Moves the scripted touches queued since the previous frame (ScriptTouch, ScriptTouchAt,
ScriptLift) into events as touch events in screen pixels, after the events
already in it. Call after BeginFrame, which lays the controls out; without a screen they stay queued.
public void TakeScripted(List<TouchEvent> events)Parameters
events List<TouchEvent>
Update(ITouchScreen?, float, InputDevice)
Called once per frame by the loop, before the steps: lays the controls out for the screen, applies its touch
events and scripted touches, and advances visibility and press animations. otherDevice is the
device that last pressed an action (a keyboard or gamepad hides Auto controls).
Equivalent to BeginFrame, then every touch of the screen and every scripted touch through
HandleTouch, then EndFrame; the engine’s loop routes the touches through the input
layers instead, so fingers no control takes reach gameplay.
public void Update(ITouchScreen? screen, float dt, InputDevice otherDevice = InputDevice.None)Parameters
screen ITouchScreen?
dt float
otherDevice InputDevice
Value(string)
The action’s strength, 0..1: a joystick’s deflection, 1 for a pressed button or d-pad direction.
public float Value(string action)Parameters
action string
Returns
ValueOf(string)
A stick’s value after its dead zone, or a d-pad’s direction, each axis -1..1.
public Vector2 ValueOf(string id)Parameters
id string