Touch

oCanvas is made to be easy to work with. When creating your app, adding support for touch devices should not be difficult. To make it easier, oCanvas has a touch module that handles the events. As a developer, you just bind to both the mouse event and the touch event, separated by a space. In oCanvas, mouse events are not triggered on a touch device. That means you have to bind to both event types, which makes more sense than a mousedown event firing on a touch device. Multi-touch is not yet supported, but will come in a future release.

All predefined display objects support touch events that trigger only inside of the shape, not the bounding rectangle. User-defined objects trigger within the bounding rectangle if the property shapeType is set to rectangular (which is the default). If shapeType is set to radial the event will be triggered within the radius of the shape.

Event Types

touchstart: Gets triggered when a finger is pressed down.
touchend: Gets triggered when a finger is released.
touchmove: Gets triggered when the finger is moving while being pressed down.
touchenter: Gets triggered when the finger first enters the object.
touchleave: Gets triggered when the finger leaves the object.
tap: Gets triggered when the finger is released, and only if the positions where the finger was pressed down and released are both within the object.
dbltap (since version 2.0.0): Gets triggered when two tap events happen shortly after each other.

Event Object

An event object is passed to the handler function as the first argument. This object contains most of the standard properties for a normal event object. Some things are changed though. The timeStamp property is not always correct in the normal object, so that is fixed and should be correct. Also, the properties x and y are added, which refers to the current position.

Touch events are propagated up in the parent chain by default, except for touchenter and touchleave events which do not bubble. You can stop the bubbling by calling the method stopPropagation() on the event object.

If you really need the original event object, it is saved in the property originalEvent.

Touch Module

To bind handlers to touch events, you don't need to interact with the actual touch module of oCanvas — you just use the bind() method of the core instance or a display object. The touch module offers some extras though. These are described under Methods and Properties and exist on the touch module of the core instance. See the example further down.

Methods

Properties

canvasFocused : Boolean: True if the last time the finger was pressed down happened on the canvas, false otherwise.
canvasHovered : Boolean: True if the finger is inside the canvas, false otherwise.
dblTapInterval : Number (since version 2.0.0): The number of milliseconds between two taps that will allow a dbltap event to be triggered. Default: 500
touchState : String: The state of the touch, "up" or "down".
x : Number: Current x position of the finger, relative to the left side of the canvas. Updates only when finger is inside the canvas.
y : Number: Current y position of the finger, relative to the top side of the canvas. Updates only when finger is inside the canvas.

Examples

Example 1

We create a core instance and a text object that will show the mouse position inside the canvas. A loop is set up, which will run 30 times per second and update the text with the current position.

View Example

Code

var canvas = oCanvas.create({
	canvas: "#canvas",
	background: "#ccc",
	disableScrolling: true
});

var text = canvas.display.text({
	x: 177,
	y: 196,
	origin: { x: "center", y: "center" },
	align: "center",
	font: "bold 25px/1.5 sans-serif",
	text: "Touch Position\nX: 0\nY: 0",
	fill: "#000"
});

canvas.addChild(text);

canvas.setLoop(function () {
	text.text = "Touch Position\n" +
			"X: " + canvas.touch.x + "\n" +
			"Y: " + canvas.touch.y;
}).start();

Output