Kazari

Kazari is a touch gesture input library.

Setup

To start, clone the repository. Say you're in your current project directory (directory where main.lua reside), run:

git clone https://github.com/MikuAuahDark/Kazari libs/kazari

You can change libs/kazari to libs/hanachirusato or anywhere else as long as you remember what name to use in require later.

To load the library, use require:

local kazari = require("libs.kazari")

Documentation

---

These functions are available in Kazari 1.0.0.

Constraint

This is pseudo-type that can be used to limit where the touch gesture operates on.

This pseudo-type accept one of these:

• nil, which means touch is unbounded.
• Array of numbers in order: {x position, y position, width, height}
• Key-value pairs with these structure: {x = x position, y = y position, w = width, h = height}
• NLay's BaseConstraint type

boolean kazari.is(any object, Class<? extends BaseGesture> class)

Check if object is an instance of class where class inherits BaseGesture.

Returns: is object an instance of class?

Example:

-- Check if object is an instance of BaseGesture
print(kazari.is(object, kazari.BaseGesture))

kazari.BaseGesture

The BaseGesture class. All gesture object inherit this class.

boolean BaseGesture:touchpressed(any id, number x, number y, number pressure)

Send touch pressed event to the gesture. In LÖVE environment, this function should be called in love.touchpressed with their arguments passed accordingly.

Class that derive BaseGesture may contain constraint as their constructor parameter. It's responsible to ensure that only touches at those areas defined by constraint are consumed.

Returns: Is the event consumed?

boolean BaseGesture:touchmoved(any id, number x, number y, number dx, number dy, number pressure)

Send touch moved event to the gesture. In LÖVE environment, this function should be called in love.touchmoved with their arguments passed accordingly.

boolean BaseGesture:touchreleased(any id, number x, number y)

Send touch released event to the gesture. In LÖVE environment, this function should be called in love.touchreleased with their arguments passed accordingly.

kazari.ZoomGesture(boolean clip = false, Constraint constraint = nil)

The ZoomGesture class. This gesture class is responsible of performing pinch zoom using 2 fingers. Calling this function creates ZoomGesture instance which is derived from BaseGesture.

Setting clip to true restrict each finger movement to the area bounded by constraint.

void ZoomGesture:onZoom(any context, function func)

Register function func to be called everytime the zoom ratio is updated, additionally passing context as the 1st parameter.

The function signature for func must follow this convention:

void func(any context, number scale, number midX, number midY)

Where scale always starts at 1 first then increase or decrease based on the finger movement. midX and midY are middle point of the touch position.

void ZoomGesture:onZoomComplete(any context, function func)

Same as above but called when pinch zoom gesture is completed (user lifting their finger).

The function signature for func must follow this convention:

void func(any context, number scale)

Where scale is the final scale ratio relative to the first time this gesture is performed.

kazari.RotateGesture(Constraint constraint = nil)

The RotateGesture class. This gesture class is responsible of performing 2-finger rotate gesture. Calling this function creates RotateGesture instance which is derived from BaseGesture.

void RotateGesture:onRotate(any context, function func)

Register function func to be called everytime the angle is updated, additionally passing context as the 1st parameter.

The function signature for func must follow this convention:

void func(any context, number angle, number da)

Where angle always starts at 0 first then increase or decrease based on the finger movement. angle range can go above 2 * math.pi (1 turn clockwise) or below -2 * math.pi (1 turn counter-clockwise). da is angle difference between last angle update. Positive value means clockwise rotation, negative value means counter-clockwise rotation.

void RotateGesture:onRotateComplete(any context, function func)

Same as above but called when rotate gesture is completed (user lifting their finger) and passes the final value (with the da parameter being nil).

kazari.PanGesture(number minfingers, number maxfingers = minfingers boolean clip = false, Constraint constraint = nil)

The PanGesture class. This gesture class is responsible of reporting x and y movement from minfingers finger(s) (1 included) to mzxfingers finger(s) (1 included). Calling this function creates PanGesture instance which is derived from BaseGesture.

Notes:

• minfingers must be at least 1.
• maxfingers must be at least minfingers (default).
• clip clips the position of each finger instead of the average.

void PanGesture:onMove(any context, function func)

Register function func to be called everytime the average position is updated, additionally passing context as the 1st parameter.

The function signature for func must follow this convention:

void func(any context, number x, number y, number dx, number dy, number pressure)

Where x, y are the relative position of the movement and pressure are the average pressure across fingers. Note that on pressure-insensitive touchscreens, pressure will be always 1. dx and dy are position differences from previous call of this function.

void PanGesture:onMoveComplete(any context, function func)

Register function func to be called when user lifting their finger and the amount of fingers registered are less than minfingers.

The function signature for func must follow this convention:

void func(any context, number x, number y, number pressure)

Where x, y are the final relative position of the movement and pressure are the average pressure across fingers. Note that on pressure-insensitive touchscreens, pressure will be always 1.

void PanGesture:getTouchCount()

Returns amount of fingers currently the user has in their screen (depends on the :touch* method calls). Returns value from 0 inclusive to maxfingers inclusive.

kazari.TapGesture(number nfingers, number moveThreshold = 32, number altDuration = 0, Constraint constraint = nil)

The TapGesture class. This gesture class is responsible of sending "tap" event with at least nfingers finger(s) (1 included), additionally with option to have "alternative" tap (usually mapped to "right click") when user holds their finger(s) for at least altDuration time units. altDuration of 0 means the "alternative" tap is disabled. moveThreshold is the maximum distance unit the user finger can move before the tap is cancelled. Calling this function creates TapGesture instance which is derived from BaseGesture.

The definition of time unit depends entirely on the units of delta time passed in :update function. If user treat the delta time as milliseconds, then the time unit is in milliseconds.

The definition of distance unit depends entirely on the user. Distance units may be in virtual resolution or in pixels, as long as it is a unit that define distance on screen.

void TapGesture:update(number dt)

Update the tap gesture for alternate tap. In LÖVE environment, this function should be called in love.update with their arguments passed accordingly.

Note that it's okay not to call this function if altDuration is set to 0 (where alternate tap events is disabled).

void TapGesture:onStart(any context, function func)

Register function func to be called when a tap is initiated, additionally passing context as the 1st parameter.

"Tap" is initiated when at least nfingers finger(s) are in the bound defined by constraint, not moving at all.

The function signature for func must follow this convention:

void func(any context)

void TapGesture:onCancel(any context, function func)

Register function func to be called when a tap is cancelled, additionally passing context as the 1st parameter.

"Tap" is cancelled when the average position of the fingers moves more than moveThreshold distance units.

The function signature for func must follow this convention:

void func(any context, number duration)

Where duration is how long user fingers was on the screen before it was cancelled, in time units.

void TapGesture:onTap(any context, function func)

Register function func to be called when a tap is successfully initiated, additionally passing context as the 1st parameter.

"Tap" is considered success when the average position of the finger moves less than moveThreshold distance units and then user release one or more of their finger(s).

The function signature for func must follow this convention:

void func(any context, boolean alternate, number duration)

Where alternate is true if duration is longer than or equal to altDuration (except where altDuration is 0, alternate will always be false) and duration is how long user fingers was on the screen before the user releases one or more of their finger(s) on the screen, in time units.