org.malai.interaction
Class Interaction

java.lang.Object
  extended by org.malai.interaction.Interaction
All Implemented Interfaces:
EventHandler, IStateMachine
Direct Known Subclasses:
ButtonPressed, CheckBoxModified, DnD, KeyInteraction, KeysPressure, KeysTyped, ListSelectionModified, MenuItemPressed, MultiClick, PointInteraction, Scrolling, SpinnerModified, TabSelected, TextChanged, WindowClosed

public abstract class Interaction
extends java.lang.Object
implements IStateMachine, EventHandler

Defines an interaction as defined in the Malai model.
An interaction is a state machine and a class.

This file is part of Malai.
Copyright (c) 2009-2012 Arnaud BLOUIN

Malai is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
Malai is distributed without any warranty; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

10/10/2009

Since:
0.1
Author:
Arnaud BLOUIN

Field Summary
protected  boolean activated
          Defines if the interaction is activated or not.
protected  IState currentState
          The current state of the state machine when the state machine is executed.
protected  TimeoutTransition currentTimeout
          The current timeout in progress.
protected  java.util.List<InteractionHandler> handlers
          The handlers that want to be notified when the state machine of the interaction changed.
protected  InitState initState
          The initial state the starts the state machine.
protected  int lastHIDUsed
          Defines the ID of last HID that has been used by the interaction.
protected  java.util.List<IState> states
          The states that compose the finite state machine.
protected  java.util.List<Event> stillProcessingEvents
          The events still in process.
 
Constructor Summary
Interaction()
          Creates the interaction with a init state.
Interaction(InitState initState)
          Creates the state machine.
 
Method Summary
protected  void addEvent(Event event)
          Adds the given event to the events 'still in process' list.
 void addHandler(InteractionHandler handler)
          Adds an interaction handler.
 void addState(IState state)
          Adds a state to the state machine.
protected  void checkTimeoutTransition()
          Checks if the current state has a timeout transition.
private  boolean checkTransition(ITransition transition)
          Checks if the transition can be executed and executes it if possible.
 void clearEventsStillInProcess()
          Clears the events of the interaction still in process.
private  void executeTransition(ITransition transition)
          Executes the given transition.
 java.util.List<InteractionHandler> getHandlers()
           
 int getLastHIDUsed()
           
static Pickable getPickableAt(double x, double y, java.lang.Object source)
          Try to find a Pickable object at the given coordinate in the given source object.
protected abstract  void initStateMachine()
          Initialises the interaction: creates the states and the transitions.
 boolean isRunning()
           
 void linkToEventable(Eventable eventable)
          Links the interaction to an eventable object (e.g. a MPanel or a MButton).
protected  void notifyHandlersOnAborting()
          Notifies handlers that the interaction stops.
protected  void notifyHandlersOnStart()
          Notifies handlers that the interaction starts.
protected  void notifyHandlersOnStop()
          Notifies handlers that the interaction stops.
protected  void notifyHandlersOnUpdate()
          Notifies handlers that the interaction updates.
 void onAborting()
          Aborts the state machine.
 void onButtonPressed(javax.swing.AbstractButton button)
          Defines actions to do when a button is activated.
 void onCheckBoxModified(javax.swing.JCheckBox checkbox)
          Defines actions to do when the given check box is selected/unselected.
 void onItemSelected(java.awt.ItemSelectable itemSelectable)
          Defines actions to do when the selected items of the given list changed.
 void onKeyPressure(int key, int idHID, java.lang.Object object)
          Defines actions to do when a key of a keyboard is pressed.
 void onKeyRelease(int key, int idHID, java.lang.Object object)
          Defines actions to do when a key of a keyboard is released.
 void onMenuItemPressed(javax.swing.JMenuItem menuItem)
          Defines actions to do when the given menu item is pressed.
 void onMove(int button, int x, int y, boolean pressed, int idHID, java.lang.Object source)
          Defines action to do when a mouse or something equivalent is moved.
 void onPressure(int button, int x, int y, int idHID, java.lang.Object source)
          Defines action to do when the button of a mouse or something equivalent is pressed.
 void onRelease(int button, int x, int y, int idHID, java.lang.Object source)
          Defines action to do when the button of a mouse or something equivalent is released.
 void onScroll(int posX, int posY, int direction, int amount, int type, int idHID, java.lang.Object src)
          Defines actions to do when a scrolling device (e.g. a mouse wheel) is used.
 void onSpinnerChanged(javax.swing.JSpinner spinner)
          Defines actions to do when the value of the given spinner change.
 void onStarting()
          Starts the state machine.
 void onTabChanged(javax.swing.JTabbedPane tabbedPanel)
          Defines actions to do when the selected tab of a tabbed panel has changed.
 void onTerminating()
          Terminates the state machine.
 void onTextChanged(javax.swing.text.JTextComponent textComp)
          Defines actions to do when the text of a text field or something equivalent is modified.
 void onTimeout(TimeoutTransition timeoutTransition)
          Defines action to do when a timeout is elapsed.
 void onUpdating()
          Updates the state machine.
 void onWindowClosed(MFrame frame)
          Defines actions to do when the decorative close button of a frame is pressed.
protected  void processEvents()
          At the end of the interaction, the events still in process must be recycled to be reused in the interaction.
 void reinit()
          Reinits the state machine.
protected  void removeKeyEvent(int idHID, int key)
          Removes the given KeyPress event from the events 'still in process' list.
protected  void removePressEvent(int idHID)
          Removes the given Press event from the events 'still in process' list.
 void setActivated(boolean activated)
          Defines if the state machine is activated.
 void setLastHIDUsed(int hid)
           
protected  void stopCurrentTimeout()
          Stops the current timeout transition.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

states

protected java.util.List<IState> states
The states that compose the finite state machine.


initState

protected InitState initState
The initial state the starts the state machine.


currentState

protected IState currentState
The current state of the state machine when the state machine is executed.


activated

protected boolean activated
Defines if the interaction is activated or not. If not, the interaction will not change on events.


handlers

protected java.util.List<InteractionHandler> handlers
The handlers that want to be notified when the state machine of the interaction changed.


stillProcessingEvents

protected java.util.List<Event> stillProcessingEvents
The events still in process. For example when the user press key ctrl and scroll one time using the wheel of the mouse, the interaction scrolling is finished but the event keyPressed 'ctrl' is still in process. At the end of the interaction, these events are re-introduced into the state machine of the interaction for processing.


currentTimeout

protected TimeoutTransition currentTimeout
The current timeout in progress.


lastHIDUsed

protected int lastHIDUsed
Defines the ID of last HID that has been used by the interaction. If the interaction has stopped or is aborted, the value of the attribute is -1.

Constructor Detail

Interaction

public Interaction()
Creates the interaction with a init state.


Interaction

public Interaction(InitState initState)
Creates the state machine.

Parameters:
initState - The initial state of the state machine.
Throws:
java.lang.IllegalArgumentException - If the given state is null.
Since:
0.1
Method Detail

initStateMachine

protected abstract void initStateMachine()
Initialises the interaction: creates the states and the transitions.

Since:
0.1

setActivated

public void setActivated(boolean activated)
Description copied from interface: IStateMachine
Defines if the state machine is activated.

Specified by:
setActivated in interface IStateMachine
Parameters:
activated - True: the state machine will be activated.

reinit

public void reinit()
Description copied from interface: IStateMachine
Reinits the state machine.

Specified by:
reinit in interface IStateMachine

getHandlers

public java.util.List<InteractionHandler> getHandlers()
Returns:
The handlers that listens to the interaction.

addHandler

public void addHandler(InteractionHandler handler)
Adds an interaction handler.

Parameters:
handler - The handler to add.
Since:
0.1

notifyHandlersOnStart

protected void notifyHandlersOnStart()
                              throws MustAbortStateMachineException
Notifies handlers that the interaction starts.

Throws:
MustAbortStateMachineException
Since:
0.1

notifyHandlersOnUpdate

protected void notifyHandlersOnUpdate()
                               throws MustAbortStateMachineException
Notifies handlers that the interaction updates.

Throws:
MustAbortStateMachineException
Since:
0.1

notifyHandlersOnStop

protected void notifyHandlersOnStop()
                             throws MustAbortStateMachineException
Notifies handlers that the interaction stops.

Throws:
MustAbortStateMachineException
Since:
0.1

notifyHandlersOnAborting

protected void notifyHandlersOnAborting()
Notifies handlers that the interaction stops.

Since:
0.1

getPickableAt

public static Pickable getPickableAt(double x,
                                     double y,
                                     java.lang.Object source)
Try to find a Pickable object at the given coordinate in the given source object.

Parameters:
x - The X-coordinate of the location to check.
y - The Y-coordinate of the location to check.
source - The source object in which the function will search.
Returns:
null if nothing is found. Otherwise a pickable object.
Since:
0.2

addState

public void addState(IState state)
Description copied from interface: IStateMachine
Adds a state to the state machine.

Specified by:
addState in interface IStateMachine
Parameters:
state - The state to add. Must not be null.

linkToEventable

public void linkToEventable(Eventable eventable)
Links the interaction to an eventable object (e.g. a MPanel or a MButton).

Parameters:
eventable - The Eventable object.
Since:
0.2

isRunning

public boolean isRunning()
Specified by:
isRunning in interface IStateMachine
Returns:
True: the state machine is running.

executeTransition

private void executeTransition(ITransition transition)
Executes the given transition. Only if the state machine is activated.

Parameters:
transition - The transition to execute.
Since:
0.1

stopCurrentTimeout

protected void stopCurrentTimeout()
Stops the current timeout transition.

Since:
0.2

checkTransition

private boolean checkTransition(ITransition transition)
Checks if the transition can be executed and executes it if possible.

Parameters:
transition - The transition to check.
Returns:
True: the transition has been executed.
Since:
0.2

onTextChanged

public void onTextChanged(javax.swing.text.JTextComponent textComp)
Description copied from interface: EventHandler
Defines actions to do when the text of a text field or something equivalent is modified.

Specified by:
onTextChanged in interface EventHandler
Parameters:
textComp - The text field.

onScroll

public void onScroll(int posX,
                     int posY,
                     int direction,
                     int amount,
                     int type,
                     int idHID,
                     java.lang.Object src)
Description copied from interface: EventHandler
Defines actions to do when a scrolling device (e.g. a mouse wheel) is used.

Specified by:
onScroll in interface EventHandler
Parameters:
posX - The X-coordinate of the position where the event occurred.
posY - The Y-coordinate of the position where the event occurred.
direction - Defines if the scrolling is up (positive value) or down (negative value).
amount - The number of units to scroll by scroll.
type - The type of scrolling that should take place in response to this event (block or unit increment).
idHID - The identifier of the used HID.
src - The object that threw the event.

onButtonPressed

public void onButtonPressed(javax.swing.AbstractButton button)
Description copied from interface: EventHandler
Defines actions to do when a button is activated.

Specified by:
onButtonPressed in interface EventHandler
Parameters:
button - The pressed button.

onItemSelected

public void onItemSelected(java.awt.ItemSelectable itemSelectable)
Description copied from interface: EventHandler
Defines actions to do when the selected items of the given list changed.

Specified by:
onItemSelected in interface EventHandler
Parameters:
itemSelectable - The list that changed.

onSpinnerChanged

public void onSpinnerChanged(javax.swing.JSpinner spinner)
Description copied from interface: EventHandler
Defines actions to do when the value of the given spinner change.

Specified by:
onSpinnerChanged in interface EventHandler
Parameters:
spinner - The spinner that changed.

onCheckBoxModified

public void onCheckBoxModified(javax.swing.JCheckBox checkbox)
Description copied from interface: EventHandler
Defines actions to do when the given check box is selected/unselected.

Specified by:
onCheckBoxModified in interface EventHandler
Parameters:
checkbox - The modified check box;

onMenuItemPressed

public void onMenuItemPressed(javax.swing.JMenuItem menuItem)
Description copied from interface: EventHandler
Defines actions to do when the given menu item is pressed.

Specified by:
onMenuItemPressed in interface EventHandler
Parameters:
menuItem - The pressed menu item.

onKeyPressure

public void onKeyPressure(int key,
                          int idHID,
                          java.lang.Object object)
Description copied from interface: EventHandler
Defines actions to do when a key of a keyboard is pressed.

Specified by:
onKeyPressure in interface EventHandler
Parameters:
key - The pressed key code.
idHID - The identifier of the HID that produced the event.
object - The object that produces the event.

onKeyRelease

public void onKeyRelease(int key,
                         int idHID,
                         java.lang.Object object)
Description copied from interface: EventHandler
Defines actions to do when a key of a keyboard is released.

Specified by:
onKeyRelease in interface EventHandler
Parameters:
key - The released key code.
idHID - The identifier of the HID that produced the event.
object - The object that produces the event.

onMove

public void onMove(int button,
                   int x,
                   int y,
                   boolean pressed,
                   int idHID,
                   java.lang.Object source)
Description copied from interface: EventHandler
Defines action to do when a mouse or something equivalent is moved.

Specified by:
onMove in interface EventHandler
Parameters:
button - The identifier of the pressed button, if a button is pressed (else -1).
x - The X-coordinate of the pressure location.
y - The Y-coordinate of the pressure location.
pressed - True: a button of the mouse is pressed.
idHID - The identifier of the used HID.
source - The object that produces the event.

onPressure

public void onPressure(int button,
                       int x,
                       int y,
                       int idHID,
                       java.lang.Object source)
Description copied from interface: EventHandler
Defines action to do when the button of a mouse or something equivalent is pressed.

Specified by:
onPressure in interface EventHandler
Parameters:
button - The identifier of the pressed button.
x - The X-coordinate of the pressure location.
y - The Y-coordinate of the pressure location.
idHID - The identifier of the used HID.
source - The object that produces the event.

onRelease

public void onRelease(int button,
                      int x,
                      int y,
                      int idHID,
                      java.lang.Object source)
Description copied from interface: EventHandler
Defines action to do when the button of a mouse or something equivalent is released.

Specified by:
onRelease in interface EventHandler
Parameters:
button - The identifier of the released button.
x - The X-coordinate of the release location.
y - The Y-coordinate of the release location.
idHID - The identifier of the used HID.
source - The object that produces the event.

onWindowClosed

public void onWindowClosed(MFrame frame)
Description copied from interface: EventHandler
Defines actions to do when the decorative close button of a frame is pressed.

Specified by:
onWindowClosed in interface EventHandler
Parameters:
frame - The frame closed.

onTabChanged

public void onTabChanged(javax.swing.JTabbedPane tabbedPanel)
Description copied from interface: EventHandler
Defines actions to do when the selected tab of a tabbed panel has changed.

Specified by:
onTabChanged in interface EventHandler
Parameters:
tabbedPanel - The tabbed panel that produces the event.

onTimeout

public void onTimeout(TimeoutTransition timeoutTransition)
Description copied from interface: EventHandler
Defines action to do when a timeout is elapsed.

Specified by:
onTimeout in interface EventHandler
Parameters:
timeoutTransition - The transition which produced the timeout event.

addEvent

protected void addEvent(Event event)
Adds the given event to the events 'still in process' list.

Parameters:
event - The event to add.
Since:
0.2

removeKeyEvent

protected void removeKeyEvent(int idHID,
                              int key)
Removes the given KeyPress event from the events 'still in process' list.

Parameters:
idHID - The identifier of the HID which produced the event.
key - The key code of the event to remove.
Since:
0.2

removePressEvent

protected void removePressEvent(int idHID)
Removes the given Press event from the events 'still in process' list.

Parameters:
idHID - The identifier of the HID which produced the event.
Since:
0.2

processEvents

protected void processEvents()
At the end of the interaction, the events still in process must be recycled to be reused in the interaction. For instance will the KeysScrolling interaction, if key 'ctrl' is pressed and the user scrolls the key event 'ctrl' is re-introduced into the state machine of the interaction to be processed.

Since:
0.2

onTerminating

public void onTerminating()
                   throws MustAbortStateMachineException
Description copied from interface: IStateMachine
Terminates the state machine.

Specified by:
onTerminating in interface IStateMachine
Throws:
MustAbortStateMachineException - If something happens requiring the interaction to abort.

onAborting

public void onAborting()
Description copied from interface: IStateMachine
Aborts the state machine.

Specified by:
onAborting in interface IStateMachine

onStarting

public void onStarting()
                throws MustAbortStateMachineException
Description copied from interface: IStateMachine
Starts the state machine.

Specified by:
onStarting in interface IStateMachine
Throws:
MustAbortStateMachineException - If something happens requiring the interaction to abort.

onUpdating

public void onUpdating()
                throws MustAbortStateMachineException
Description copied from interface: IStateMachine
Updates the state machine.

Specified by:
onUpdating in interface IStateMachine
Throws:
MustAbortStateMachineException - If something happens requiring the interaction to abort.

checkTimeoutTransition

protected void checkTimeoutTransition()
Checks if the current state has a timeout transition. If it is the case, the timeout transition is launched.

Since:
0.2

getLastHIDUsed

public int getLastHIDUsed()
Returns:
The ID of last HID that has been used by the interaction. If the interaction has stopped or is aborted, the value of the attribute is -1.
Since:
0.2

setLastHIDUsed

public void setLastHIDUsed(int hid)
Parameters:
hid - The ID of last HID that has been used by the interaction. If the interaction has stopped or is aborted, the value of the attribute is -1.
Since:
0.2

clearEventsStillInProcess

public void clearEventsStillInProcess()
Clears the events of the interaction still in process.

Since:
0.2