Introduction

BIAS, (B)ogus-(I)nput (A)ction-(S)elector package. A package defining an interface between application event input data (including but not limited to hardware input) and user-defined actions. The idea being that various sorts of input data, mainly that gathered from an user-interaction (e.g., a mouse button being pressed and dragged), may be modeled and reduced into high-level events. Those “bogus” events are then taken as input to implement user-defined actions on application objects (e.g., push that button or select that geometry on the screen and move it close to me).

Targeted applications

Depending on whether or not the user defines her own set of actions, targeted applications are:

Action-less applications

Action-less applications simple require to reduce input data into a raw BogusEvent.

Action-driven applications

In this case, the targeted applications for the package are those able to:

  1. Itemize the application functionality into a list of actions (see Action).
  2. Reduce input data into a BogusEvent and characterize it with a Shortcut (which are used to bind the user-defined Actions).
  3. Implement each action item taking as input those (reduced) BogusEvents (see Grabber and BogusEvent).

Observation: Third parties may not always need to implement their own BogusEvents but simply use (depart from) those already conveniently provided here:

  1. KeyboardEvent, representing any keyboard.
  2. ClickEvent which stands for a button clicked.
  3. MotionEvent which represents data gathered from user motion, e.g., the user moves her hand in front of a kinect, or a finger is being dragged on a touch screen surface. MotionEvents were modeled according to their “degrees-of-freedom (DOFs)” (see DOF1Event, DOF2Event, DOF3Event and DOF6Event), not only because they (DOF’s) represent a nice property to classify input devices, but mainly because manipulating stuff on 3D may be performed differently given events carrying different DOF’s. Intuitively, the greater the DOF’s the richer the user experience may be.

These default bogus-event set should serve as a common ground to all sorts of tangible interfaces manipulating geometry on a 2D/3D space.

Usage

Usage is simple:

  1. Instantiate an InputHandler.
  2. Define your bogus events.
  3. Define/implement some Agents capable of dealing with your events and register them at the handler (see registerAgent(Agent)).
  4. Action-driven applications should additionally implement user-defined actions (see performInteraction(BogusEvent)). In this case, to customize the user experience simply bind bogus event Shortcuts (see shortcut()) to user-defined actions using the Agent Profiles.
  5. Attach a call to handle() at the end of your main event (drawing) loop.

Hacking

The package is developed as a git subtree (see also “here”). It should thus be made part of a bigger (container) project (see Figure 1). The package only dependency is util, package based on Daniel Bell gwt-hashcode-equals which provides hashCode(), equals() and clone() Java implementations compatible with gwt. Note that UTIL is distributed as another git subtree.

Initial setup

First (and only) time setup. Here <my_repo> is the project repo where you plan to include the BIAS and UTIL trees.

1
2
3
4
5
6
git clone <my_repo>
cd <my_repo>
git remote add -f bias https://github.com/remixlab/bias_tree.git
git subtree add --prefix src/remixlab/bias bias master --squash
git remote add -f util https://github.com/remixlab/util_tree.git
git subtree add --prefix src/remixlab/util util master --squash

Now git push will push the trees into your remote repo. From now on you will be able to use your repo as any other basic git repo:

1
2
3
4
5
#clone it:
git clone <my_repo>
cd <my_repo>
#If you want to submit changes to some the trees please
#refer to: https://help.github.com/articles/using-pull-requests

Read-write access setup (only for developers who have been granted read-write access to the trees)

(do the initial setup above first)

Clone the repo and add the remotes:

1
2
3
4
git clone <my_repo>
cd <my_repo>
git remote add -f bias https://github.com/remixlab/bias_tree.git
git remote add -f util https://github.com/remixlab/util_tree.git

To update your BIAS subtree:

1
2
3
#fetching command:
git fetch bias master
git subtree pull --prefix src/remixlab/bias bias master --squash

To update your UTIL subtree:

1
2
3
#fetching command:
git fetch util master
git subtree pull --prefix src/remixlab/util util master --squash

To contribute to the main project:

1
git push

To contribute to the BIAS subtree:

1
git subtree push --prefix=src/remixlab/bias bias master

To contribute to the UTIL subtree:

1
git subtree push --prefix=src/remixlab/util util master