Kazari is a touch gesture input library.
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")These functions are available in Kazari 1.0.0.
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
BaseConstrainttype
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))The BaseGesture class. All gesture object inherit this class.
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?
Send touch moved event to the gesture. In LÖVE environment, this function should be called in
love.touchmoved with their arguments passed accordingly.
Send touch released event to the gesture. In LÖVE environment, this function should be called in
love.touchreleased with their arguments passed accordingly.
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.
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.
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.
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.
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.
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:
minfingersmust be at least 1.maxfingersmust be at leastminfingers(default).clipclips the position of each finger instead of the average.
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.
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.
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.
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).
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)
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.
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.