net.xoetrope.xui
Class XEventHandler

java.lang.Object
  net.xoetrope.xui.XEventHandler

All Implemented Interfaces:

java.awt.event.ActionListener, java.awt.event.FocusListener, java.awt.event.ItemListener, java.awt.event.KeyListener, java.awt.event.MouseListener, java.awt.event.MouseMotionListener, java.awt.event.TextListener, java.util.EventListener, XuiEventHandler

public class XEventHandler
extends java.lang.Object
implements XuiEventHandler, java.awt.event.ActionListener, java.awt.event.FocusListener, java.awt.event.TextListener, java.awt.event.ItemListener, java.awt.event.KeyListener, java.awt.event.MouseListener, java.awt.event.MouseMotionListener

Implements an event handler for XUI. Most of the common events are handled. The class is intended as a mixin for a panel class such as XPage and should not be used directly

Copyright (c) Xoetrope Ltd., 2002-2003

License: see license.txt

$Revision: 2.28 $

Field Summary

protected java.util.Hashtable	classInstances The collection of class instances that provide handlers
protected java.lang.Object	container The page or object whose event is being handled
protected static java.util.EventObject	currentEvt The current event, valid until processed
protected XProject	currentProject The current project, the project that ultimately owns this event handler
protected java.util.Hashtable	handlers The collection of event handlers that are known
protected java.lang.Object	mouseDownComponent The component that owned the mouse pressed event
protected boolean	mouseEventInvoked A flagh indicating if the mouse event has been invoked yet
protected int	suppressFocusEvents A flag to dictate how focus event are processed in the event of a message display
protected XValidationHandler	xValidationHandler The validation handler

Constructor Summary

XEventHandler(XProject project, java.lang.Object c, XValidationHandler vh)
Create an event handler

Method Summary

void	actionPerformed(java.awt.event.ActionEvent e) Adds the specified action listener to receive action events from this button.
void	addActionHandler(java.lang.Object comp, java.lang.String methodName) Adds a handler for action events
void	addFocusHandler(java.lang.Object comp, java.lang.String methodName) Adds a handler for focus events
XMethodReference	addHandler(java.lang.Object comp, long eventType, java.lang.String methodStr) Adds an event handler.
XMethodReference	addHandler(java.lang.Object srcObj, java.lang.String methodName, java.lang.String adderMethod, java.lang.String listenerInterface, long eventMask, java.lang.Object listener) Adds a handler for action events
void	addItemHandler(java.lang.Object comp, java.lang.String methodName) Adds a handler for item events
void	addKeyHandler(java.lang.Object comp, java.lang.String methodName) Adds a handler for key events
void	addListener(java.lang.Object comp, java.lang.String listenerName, java.lang.String argType, java.lang.Object listener) Adds a listener for an event type.
void	addMenuHandler(java.lang.Object menuItem, java.lang.String methodName) Adds a handler for action events
void	addMouseHandler(java.lang.Object comp, java.lang.String methodName) Adds a handler for mouse events
void	addMouseMotionHandler(java.lang.Object comp, java.lang.String methodName) Adds a handler for mouse motion events
void	addTextHandler(java.lang.Object comp, java.lang.String methodName) Adds a handler for text events
java.lang.reflect.Method	findEvent(java.lang.Object src, long eventType) Lookup an event for a component.
void	focusGained(java.awt.event.FocusEvent e) This event indicates that the Component is now the focus owner.
void	focusLost(java.awt.event.FocusEvent e) This event indicates that the Component is no longer the focus owner.
java.util.EventObject	getCurrentEvent() Get the current event
XValidationHandler	getValidationHandler() Get the validation handler reference.
void	invoke(long eventType, java.util.EventObject evt) Invokes an event.
boolean	isFocusChangeSuppressed() Check the focus change status
void	itemStateChanged(java.awt.event.ItemEvent e) This event indicates that an item's state changed.
void	keyPressed(java.awt.event.KeyEvent e) A key has been pressed
void	keyReleased(java.awt.event.KeyEvent e) A key has been released
void	keyTyped(java.awt.event.KeyEvent e) A key was types
void	mouseClicked(java.awt.event.MouseEvent e) The mouse was clicked
void	mouseDragged(java.awt.event.MouseEvent e) The mouse was dragged
void	mouseEntered(java.awt.event.MouseEvent e) The mouse has been moved over the component
void	mouseExited(java.awt.event.MouseEvent e) The mouse has moved beyond the bounds of the component
void	mouseMoved(java.awt.event.MouseEvent e) The mouse has moved
void	mousePressed(java.awt.event.MouseEvent e) The mouse button has been pressed
void	mouseReleased(java.awt.event.MouseEvent e) The mouse button has been released
void	removeHandlers(java.lang.Object comp) Remove all the event handlers for a particular object
void	suppressFocusEvents(boolean suppress) Used by messageboxes and other dialogs to prevent the display of the dialog causing extra focus events from being fired.
void	textValueChanged(java.awt.event.TextEvent e) This event indicates that object's text changed.
boolean	wasMouseClicked() A utility method used to determine if the last event corrseponds to a mouse click.
boolean	wasMouseDoubleClicked() A utility method used to determine if the last event corrseponds to a mouse double click.
boolean	wasMouseRightClicked() A utility method used to determine if the last event corrseponds to a mouse right click.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

currentEvt

protected static java.util.EventObject currentEvt

The current event, valid until processed

container

protected java.lang.Object container

The page or object whose event is being handled

currentProject

protected XProject currentProject

The current project, the project that ultimately owns this event handler

handlers

protected java.util.Hashtable handlers

The collection of event handlers that are known

classInstances

protected java.util.Hashtable classInstances

The collection of class instances that provide handlers

mouseDownComponent

protected java.lang.Object mouseDownComponent

The component that owned the mouse pressed event

mouseEventInvoked

protected boolean mouseEventInvoked

A flagh indicating if the mouse event has been invoked yet

suppressFocusEvents

protected int suppressFocusEvents

A flag to dictate how focus event are processed in the event of a message display

xValidationHandler

protected XValidationHandler xValidationHandler

The validation handler

Constructor Detail

XEventHandler

public XEventHandler(XProject project,
                     java.lang.Object c,
                     XValidationHandler vh)

Create an event handler

Parameters:

project - the owner project

c - the container/page

vh - the validation handler

Method Detail

removeHandlers

public void removeHandlers(java.lang.Object comp)

Remove all the event handlers for a particular object

Specified by:

removeHandlers in interface XuiEventHandler

Parameters:

comp - the object whose events are being removed

getValidationHandler

public XValidationHandler getValidationHandler()

Get the validation handler reference. Note that you should not hold a reference to this value as it will probably cause a memory leak.

Specified by:

getValidationHandler in interface XuiEventHandler

Returns:

the current validation handler

invoke

public void invoke(long eventType,
                   java.util.EventObject evt)

Invokes an event. Called in response to an event. If a handler has been added for the event it will be invoked.

Specified by:

invoke in interface XuiEventHandler

Parameters:

eventType - the event type

evt - the event object

findEvent

public java.lang.reflect.Method findEvent(java.lang.Object src,
                                          long eventType)

Lookup an event for a component.

Specified by:

findEvent in interface XuiEventHandler

Parameters:

src - the event source component

eventType - the event type

Returns:

the event handler method

isFocusChangeSuppressed

public boolean isFocusChangeSuppressed()

Check the focus change status

Specified by:

isFocusChangeSuppressed in interface XuiEventHandler

Returns:

true if the focus change events are being suppressed.

getCurrentEvent

public java.util.EventObject getCurrentEvent()

Get the current event

Specified by:

getCurrentEvent in interface XuiEventHandler

Returns:

the AWTEvent that was last triggered

addHandler

public XMethodReference addHandler(java.lang.Object comp,
                                   long eventType,
                                   java.lang.String methodStr)
                            throws java.lang.ClassNotFoundException,
                                   java.lang.NoSuchMethodException

Adds an event handler. A specific handler such as the addActionHandler should be used instead of calling this method

The handler can also be defined in classes other than the current page or classes derived from XPage. The syntax for such expressions is as follows:

• mypackage.MyClass[referenceName].myMethod for a named object instance
• mypackage.MyClass[].myMethod to create a new instance of the class on each evaluation
• mypackage.MyClass.myMethod to invoke a static method
• myMethod[referenceName] for a method contained with the invoking page

where mypackage is the name of the Java package containing the class MyClass. The value of referenceName is a user defined value that identifies the instance of the class. The application instantiates an instance of the class when the expression is first encountered and thereafter maintains the instance with each subsequent call retrieving the same instance of the class.

The page may also reference scripts with the expression ${script.XXXXX()} where XXXXX is the name of the script method to be invoked.

Specified by:

addHandler in interface XuiEventHandler

Parameters:

eventType - the event type

methodStr - the method to be invoked in response to the object

comp - the component that fires the event

Throws:

java.lang.ClassNotFoundException - The class cannot be found

java.lang.NoSuchMethodException - The specified method does not exist in the class

addListener

public void addListener(java.lang.Object comp,
                        java.lang.String listenerName,
                        java.lang.String argType,
                        java.lang.Object listener)

Adds a listener for an event type. This method should not normally be called by an application

Specified by:

addListener in interface XuiEventHandler

Parameters:

comp - the component that fires events

listenerName - the name of the listener interface

argType - the listener arguments

listener - the listener implementation, usually the page's this pointer

addHandler

public XMethodReference addHandler(java.lang.Object srcObj,
                                   java.lang.String methodName,
                                   java.lang.String adderMethod,
                                   java.lang.String listenerInterface,
                                   long eventMask,
                                   java.lang.Object listener)

Adds a handler for action events

Specified by:

addHandler in interface XuiEventHandler

Parameters:

srcObj - the menu item that fires the events

methodName - the method to be invoked in response to the action event

adderMethod - the adder method name e.g. addActionListener

listenerInterface - the listener interface e.g. java.awt.event.ActionListener

eventMask - the event mask e.g. AWTEvent.ACTION_EVENT_MASK

listener - the listener implementation, usually the page's this pointer

See Also:

ActionListener, ActionEvent

addMenuHandler

public void addMenuHandler(java.lang.Object menuItem,
                           java.lang.String methodName)

Adds a handler for action events

Specified by:

addMenuHandler in interface XuiEventHandler

Parameters:

menuItem - the menu item that fires the events

methodName - the method to be invoked in response to the action event

See Also:

ActionListener, ActionEvent

addActionHandler

public void addActionHandler(java.lang.Object comp,
                             java.lang.String methodName)

Adds a handler for action events

Specified by:

addActionHandler in interface XuiEventHandler

Parameters:

comp - the component that fires the events

methodName - the method to be invoked in response to the action event

See Also:

ActionListener, ActionEvent

addFocusHandler

public void addFocusHandler(java.lang.Object comp,
                            java.lang.String methodName)

Adds a handler for focus events

Specified by:

addFocusHandler in interface XuiEventHandler

Parameters:

comp - the component that fires the events

methodName - the method to be invoked in response to the focus event

See Also:

FocusListener, FocusEvent

addTextHandler

public void addTextHandler(java.lang.Object comp,
                           java.lang.String methodName)

Adds a handler for text events

Specified by:

addTextHandler in interface XuiEventHandler

Parameters:

comp - the component that fires the events

methodName - the method to be invoked in response to the text event

See Also:

TextListener, TextEvent

addItemHandler

public void addItemHandler(java.lang.Object comp,
                           java.lang.String methodName)

Adds a handler for item events

Specified by:

addItemHandler in interface XuiEventHandler

Parameters:

comp - the component that fires the events

methodName - the method to be invoked in response to the item event

See Also:

ItemListener, ItemEvent

addKeyHandler

public void addKeyHandler(java.lang.Object comp,
                          java.lang.String methodName)

Adds a handler for key events

Specified by:

addKeyHandler in interface XuiEventHandler

Parameters:

comp - the component that fires the events

methodName - the method to be invoked in response to the key event

See Also:

KeyListener, KeyEvent

addMouseHandler

public void addMouseHandler(java.lang.Object comp,
                            java.lang.String methodName)

Adds a handler for mouse events

Specified by:

addMouseHandler in interface XuiEventHandler

Parameters:

comp - the component that fires the events

methodName - the method to be invoked in response to the mouse event

See Also:

MouseMotionListener, MouseEvent

addMouseMotionHandler

public void addMouseMotionHandler(java.lang.Object comp,
                                  java.lang.String methodName)

Adds a handler for mouse motion events

Specified by:

addMouseMotionHandler in interface XuiEventHandler

Parameters:

comp - the component that fires the events

methodName - the method to be invoked in response to the mouse event

See Also:

MouseMotionListener, MouseEvent

wasMouseClicked

public boolean wasMouseClicked()

A utility method used to determine if the last event corrseponds to a mouse click. The notion of a click is extended by assuming the a mouse press and release within a single component constitutes a click even if not at the same coordinate. A MouseEvent.MOUSE_CLICKED is only triggered when the press and release are at the same location and this is often inadequate for end-user interaction.

Specified by:

wasMouseClicked in interface XuiEventHandler

Returns:

true if the mouse was clicked

wasMouseDoubleClicked

public boolean wasMouseDoubleClicked()

A utility method used to determine if the last event corrseponds to a mouse double click. The notion of a click is extended by assuming the a mouse press and release within a single component constitutes a click even if not at the same coordinate. A MouseEvent.MOUSE_CLICKED is only triggered when the press and release are at the same location and this is often inadequate for end-user interaction.

Specified by:

wasMouseDoubleClicked in interface XuiEventHandler

Returns:

true if the mouse was double clicked

wasMouseRightClicked

public boolean wasMouseRightClicked()

A utility method used to determine if the last event corrseponds to a mouse right click. The notion of a click is extended by assuming the a mouse press and release within a single component constitutes a click even if not at the same coordinate. A MouseEvent.MOUSE_CLICKED is only triggered when the press and release are at the same location and this is often inadequate for end-user interaction.

Specified by:

wasMouseRightClicked in interface XuiEventHandler

Returns:

true if the mouse was right clicked

actionPerformed

public void actionPerformed(java.awt.event.ActionEvent e)

Adds the specified action listener to receive action events from this button. Action events occur when a user presses or releases the mouse over this button. If l is null, no exception is thrown and no action is performed.

Specified by:

actionPerformed in interface java.awt.event.ActionListener

Parameters:

e - the event

focusGained

public void focusGained(java.awt.event.FocusEvent e)

This event indicates that the Component is now the focus owner.

Specified by:

focusGained in interface java.awt.event.FocusListener

Parameters:

e - the event

focusLost

public void focusLost(java.awt.event.FocusEvent e)

This event indicates that the Component is no longer the focus owner.

Specified by:

focusLost in interface java.awt.event.FocusListener

Parameters:

e - the event

textValueChanged

public void textValueChanged(java.awt.event.TextEvent e)

This event indicates that object's text changed.

Specified by:

textValueChanged in interface java.awt.event.TextListener

Parameters:

e - the event

itemStateChanged

public void itemStateChanged(java.awt.event.ItemEvent e)

This event indicates that an item's state changed.

Specified by:

itemStateChanged in interface java.awt.event.ItemListener

Parameters:

e - the event

keyPressed

public void keyPressed(java.awt.event.KeyEvent e)

A key has been pressed

Specified by:

keyPressed in interface java.awt.event.KeyListener

Parameters:

e - the event

keyReleased

public void keyReleased(java.awt.event.KeyEvent e)

A key has been released

Specified by:

keyReleased in interface java.awt.event.KeyListener

Parameters:

e - the event

keyTyped

public void keyTyped(java.awt.event.KeyEvent e)

A key was types

Specified by:

keyTyped in interface java.awt.event.KeyListener

Parameters:

e - the event

mouseClicked

public void mouseClicked(java.awt.event.MouseEvent e)

The mouse was clicked

Specified by:

mouseClicked in interface java.awt.event.MouseListener

Parameters:

e - the event

mouseEntered

public void mouseEntered(java.awt.event.MouseEvent e)

The mouse has been moved over the component

Specified by:

mouseEntered in interface java.awt.event.MouseListener

Parameters:

e - the event

mouseExited

public void mouseExited(java.awt.event.MouseEvent e)

The mouse has moved beyond the bounds of the component

Specified by:

mouseExited in interface java.awt.event.MouseListener

Parameters:

e - the event

mousePressed

public void mousePressed(java.awt.event.MouseEvent e)

The mouse button has been pressed

Specified by:

mousePressed in interface java.awt.event.MouseListener

Parameters:

e - the event

mouseReleased

public void mouseReleased(java.awt.event.MouseEvent e)

The mouse button has been released

Specified by:

mouseReleased in interface java.awt.event.MouseListener

Parameters:

e - the event

mouseMoved

public void mouseMoved(java.awt.event.MouseEvent e)

The mouse has moved

Specified by:

mouseMoved in interface java.awt.event.MouseMotionListener

Parameters:

e - the event

mouseDragged

public void mouseDragged(java.awt.event.MouseEvent e)

The mouse was dragged

Specified by:

mouseDragged in interface java.awt.event.MouseMotionListener

Parameters:

e - the event

suppressFocusEvents

public void suppressFocusEvents(boolean suppress)

Used by messageboxes and other dialogs to prevent the display of the dialog causing extra focus events from being fired.

Specified by:

suppressFocusEvents in interface XuiEventHandler

Parameters:

suppress - true to suppress focus events