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.26 $

Field Summary

protected static int	changeCounter A counter for changes to the registry.
protected static java.util.Hashtable	configFiles The config files used to build the set of component adapters.
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 static int	localChangeCounter Used for tracking changes to the registry spec.
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 static java.util.Hashtable	registrations The collection of registered event handlers that are known
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.
static void	addConfigFile(java.lang.String key, java.lang.Object resource, boolean overwrite) Add a configuration file.
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	addHandler(PageSupport xpage, java.lang.Object targetComp, java.lang.String typeStr, java.lang.String methodName) Adds an event handler.
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	checkRegistration() Check that all the registered components are loaded
protected void	doRead(java.lang.String key, java.lang.Object configFile) Read the component registry.
protected void	doRead(java.lang.String key, java.lang.String configFile) Read the component registry.
protected void	doRead(java.lang.String key, java.net.URL configFileURL) Read the component registry.
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
protected void	read() Read the component registry.
void	read(java.lang.String key, java.io.Reader reader) Read the component registry.
protected void	read(java.lang.String key, java.lang.String configFile) Read the component registry.
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.
void	updateConfig() Signal that the configuration has been updated.
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

configFiles

protected static java.util.Hashtable configFiles

The config files used to build the set of component adapters. Stores the file names

changeCounter

protected static int changeCounter

A counter for changes to the registry. Used to indicate if the registry needs to be rebuilt

localChangeCounter

protected static int localChangeCounter

Used for tracking changes to the registry spec.

registrations

protected static java.util.Hashtable registrations

The collection of registered event handlers that are known

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

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

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

addHandler

public void addHandler(PageSupport xpage,
                       java.lang.Object targetComp,
                       java.lang.String typeStr,
                       java.lang.String methodName)

Adds an event handler.

Specified by:

addHandler in interface XuiEventHandler

Parameters:

xpage - The page that contains the response methods

targetComp - the component to which the event handler is added

typeStr - the type of handler

methodName - the name of the response method

addConfigFile

public static void addConfigFile(java.lang.String key,
                                 java.lang.Object resource,
                                 boolean overwrite)

Add a configuration file. If the files have already been loaded then the new file will be loaded

Parameters:

key - the name by which the configuration file is referenced

resource - the name/path of the configuration file or the URL for the file

overwrite - true to overwrite and existing entry matching the specified key

updateConfig

public void updateConfig()

Signal that the configuration has been updated.

read

protected void read()

Read the component registry. The format is described in the components.xsd schema.

read

protected void read(java.lang.String key,
                    java.lang.String configFile)

Read the component registry. The format is described in the components.xsd schema. The config file is also registered.

Parameters:

configFile - the name of the configuration file

key - the name by which the configuration file is referenced

doRead

protected void doRead(java.lang.String key,
                      java.lang.Object configFile)

Read the component registry. The format is described in the components.xsd schema.

Parameters:

configFile - the name of the configuration file

key - the name by which the configuration file is referenced

doRead

protected void doRead(java.lang.String key,
                      java.lang.String configFile)

Read the component registry. The format is described in the components.xsd schema.

Parameters:

configFile - the name of the configuration file

key - the name by which the configuration file is referenced

doRead

protected void doRead(java.lang.String key,
                      java.net.URL configFileURL)

Read the component registry. The format is described in the components.xsd schema.

Parameters:

configFileURL - the URL of the configuration file

key - the name by which the configuration file is referenced

read

public void read(java.lang.String key,
                 java.io.Reader reader)

Read the component registry. The format is described in the components.xsd schema.

Parameters:

key - the name by which the configuration file is referenced

reader - the reader from which to read the file

checkRegistration

public void checkRegistration()

Check that all the registered components are loaded