type: utility

release: 0.0

status: in development

documentation: N/A

demo: http://view.jqueryui.com/interactions/demos/interaction/default.html

TODOs

• Figure out how to organize functional spec since isValidTarget is not an abstract method 
• Create a demo that is a simple interaction for putting paint on a canvas, could even apply more paint (or perhaps a deeper color) depending on the pressure (for devices that support such event data) 

iOS Developer Library - Handling Events

1 - Description:

This utility is a base for building interactions. Interactions all have in common a 3-part event model: start -> move(s) -> stop. This interaction base serves as an abstraction layer for events from any input device that allows for movement with such an event model, or anything that could be mapped to such a model. Examples are drag-and-drop (mouse), swipe/slide (touch), etc.

There is built-in support for mouse and touch events on both desktop and mobile browsers. There is also an extension mechanism (called interaction hooks) such that the base can be extended to support input from any device that can trigger the start, multiple moves, and a stop. This would bring that same support to any interaction that builds on top of the interaction base, meaning each of those interactions does not need specific knowledge of each device and its API.

2 - Visual Design:

N/A

3 - Functional Specification:

The interaction utility is not designed to be used standalone, but as an extension base for interactions. Such an extension must provide implementations for at least _start, _move, and _stop. For example:

$.widget( "demo.simple", $.ui.interaction, {

     _start: function( event, position ) {

          //

     },

     _move: function( event, position ) {

          //

     },

     _stop: function( event, position ) {

          //

     }

});

In addition to being able to create an interaction by extending interaction as a base, the interaction base can also be extended to support input devices other than mouse and touch (for which support is built-in). This is accomplished by the interaction hooks (see below in this section).

Note: The interaction hooks supports arbitrary event models. As such, plugins that build on top of interaction should not attempt to read any properties from the events that are passed to _start(), _move(), and _stop(). All logic should be implemented based on the pointer position.

Options:

• none

Methods:

• none (no public methods - see below for Abstract Methods to be provided by widget that extends ui.interaction)

Events:

• none

Abstract Methods (to be provided by widget that extends ui.interaction):

• _isValidTarget( targetElement )
• Called before _start(), giving an opportunity for a start to not occur based on the target element
• default implementation: return true
• Arguments
• targetElement - jQuery object that contains the target DOMElement 
• _start( event, pointerPosition )
• Called by whatever event triggers the interaction movement to start.
• default implementation: none (must be provided by widget that extends ui.interaction) 
• Arguments:
• event - native event that triggered start
• pointerPosition - { x, y }
• x: pageX
• y: pageY 
• _move( event, pointerPosition )
• Called by whatever event triggers the interaction movements between start and stop.
• default implementation: none (must be provided by widget that extends ui.interaction) 
• Arguments 
• event - native event that triggered move
• pointerPosition - { x, y }
• x: pageX
• y: pageY 
• _stop( event, pointerPosition )
• Called by whatever event triggers the interaction movement to stop.
• default implementation: none (must be provided by widget that extends ui.interaction) 
• Arguments
• event - native event that triggered stop
• pointerPosition - { x, y }
• x: pageX
• y: pageY 

Interaction Hooks:

• setup ( widget, start )
• Arguments
• widget - widget instance, will have $.ui.interaction in the prototype chain
• start( event, targetElement, pointerPosition ) - callback that the hook should call when it detects the start of an interaction.
• Arguments
• event
• targetElement
• pointerPosition - { x, y }
• Return: boolean whether a start resulted from the call to start. Should be used to prevent doing things that should only be done if a start occurred.
• handle ( widget, move, stop )
• Called if start was called 
• Arguments
• widget - widget instance
• move( event, pointerPosition ) - callback that the hook should call when it detects a move
• Arguments
• event
• pointerPosition - { x, y } 
• stop( event, pointerPosition ) - callback that the hook should call when it detects the end of an interaction
• Arguments
• event
• pointerPosition - { x, y } 

4 - Markup & Style:

N/A

5 - Latest version of plugin:

http://view.jqueryui.com/interactions/demos/interaction/default.html

6 - Open issues being discussed

(Use this area to place things that we're hashing out like features and options we're not sure we should include, questions about how this fits into UI and relates to other widgets and utilities, known problems, whether features should be broken across multiple releases, etc.)