com.swfm.mica.events
Class MiEventHandler

java.lang.Object
  com.swfm.mica.events.MiEventHandler

All Implemented Interfaces:

MiiCommandNames, MiiEventHandler, MiiEventTypes

Direct Known Subclasses:

MiAdjusterEventHandler, MiBrowsableGridEventHandler, MiComboBoxPopperKeyEventHandler, MiDelegateEvents, MiEventMonitor, MiGrabObjectEventHandlers, MiIClickAndDrop, MiICreateConnection, MiICreateMultiPointObject, MiICreateObject, MiICreateSelectDeleteManagedPoints, MiICreateText, MiIDeleteObjectUnderMouse, MiIDeleteObjectUnderMouse2, MiIDeleteSelectedObjects, MiIDeselectAll, MiIDisplayContextMenu, MiIDisplayHelpDialog, MiIDragAndCopyWithMouse, MiIDragBackgroundPan, MiIDragConnection, MiIDragConnectionSegment, MiIDragger, MiIDragObjectUnderMouse, MiIDuplicateSelectedParts, MiIEditorSearchEventHandler, MiIExecuteActionHandler, MiIExecuteCommand, MiIFlowEditorEventHandler, MiIJumpPan, MiIMouseWheelScroller, MiINormalizedPan, MiInterceptEvent, MiIOnePtPan, MiIPan, MiIPartInspector, MiIPrint, MiIReCalcLayouts, MiIRubberbandBounds, MiIRubberbandPoint, MiISelectArea, MiISelectObjectUnderMouse, MiISingleKeyCreateObject, MiIZoomArea, MiIZoomAroundMouse, MiIZoomAroundMouseUsingWheel, MiManipulatorTargetEventHandler, MiNotifyWhenDirectoryContentsChanges, MiNotifyWhenFileChanges, MiPlaySoundEventHandler, MiSetStatusBarStateToNameOfObjectUnderMouse, MiShortCutHandler, MiTableHeaderAndFooterManager, MiTreeListDragAndDropEditingEventHandler, MiTwoStateWidgetEventHandler

public abstract class MiEventHandler

extends java.lang.Object

implements MiiEventHandler, MiiCommandNames, MiiEventTypes

This class implements the MiiEventHandler. It also serves as the base class of the MiEventMonitor and MiShortCutHandler classes.

A sub-class of this abstract class implements one of two methods:

 processCommand()	This method uses isCommand(String) to ascertain 
			what the current command is and then processCommands
			functionality accordingly. It also may use
			getEvent() to get the event that triggered the
			command. Use translations to specify what events
			trigger what commands.
 or

 processEvent(MiEvent)This method overrides any an all translations
			this event handler may have and receives all
			the events sent to the event handler.
 

Translations

Each event handler has it's own set of (optional) 'translations'. A translation converts an event into a command. Typically an event handler will have a set of functionality which is invoked by a set of commands.

The general event handler will also have a number of pre-defined translations that are it's 'default' translations. These default translations. map a set of suitable events to it's command functionality. These events are 'suitable' in that, in all of the event handlers supplied with Mica, the event handlers can all work simultaneously. For example, cannot be mapped to both MiIZoomAroundMouse.ZoomOut and MiIDisplayContextMenu.popup because these are often used together in a graphics editor.

Position Dependency

Event handlers can be either position dependent or independent. If they are dependent, then they only respond to events that occur within the bounds of the MiPart they are assinged to. If they are independent, then the respond to events that occur anywhere within the window containing the MiPart they are assigned to. These position independent event handlers are also called 'global' event handlers (see MiWindow).

Version:

%I% %G%

Author:

Michael L. Davis

Field Summary

Constructor Summary

MiEventHandler()
Constructs a new MiEventHandler.

Method Summary

void	addEventToCommandTranslation(java.lang.String commandToGenerate, int type, int key, int modifiers) Adds a translation from the given event to the given command.
void	addEventToCommandTranslation(java.lang.String commandToGenerate, MiEvent event) Adds a translation from the given event to the given command.
void	addEventToCommandTranslation(java.lang.String commandToGenerate, MiEvent event1, MiEvent event2) Adds a translation from the given event to the given command.
MiiEventHandler	copy() Returns a copy of this MiEventHandler.
boolean	getAlwaysConsumeTriggerEvents() Gets whether this event handler will always return Mi_CONSUME_EVENT whenever it receives an event that is a trigger event (i.e.
java.lang.String	getCommand() Gets the command to use.
MiEvent	getEvent()
MiEvent	getEventToCommandTranslation(java.lang.String commandToGenerate, MiEvent event)
java.lang.String	getName() Gets the name of this event handler.
static java.lang.String	getNameForType(int type) Gets the name for the given event handler type.
MiPart	getObject() Gets the MiPart that events sent to this event handler should transform their positions relative to.
java.lang.String[]	getRequestedCommands() Gets an array of command names that can be processed by this event handler.
MiEvent[]	getRequestedEvents() Gets an array of events that can be processed by this event handler.
MiPart	getTarget() Gets the MiPart that this is assigned to.
int	getType() Gets the type of this event handler.
boolean	isCommand(java.lang.String cmd) Gets whether the given command is equal to the current command.
boolean	isEnabled() Gets whether this event handler is enabled.
boolean	isPositionDependent() Gets whether this event handler only want events that occur within the bounds of any MiPart is assigned to.
boolean	isSingleton() Gets whether this event handler is copied and assigned along with the part that it assigned to when the part is copied.
boolean	isType(int type) Gets whether this event handler is of the given type.
int	processCommand(MiEvent event, java.lang.String command) Processes the given command as if generated from the given event.
int	processCommand(java.lang.String command) Processes the given command.
int	processEvent(MiEvent event) Processes the given event.
void	removeAllEventToCommandTranslations()
void	removeEventToCommandTranslation(MiEvent event) Removes the translation that involves the given event.
void	removeEventToCommandTranslation(java.lang.String commandToGenerate) Removes the translation that generates the given command.
void	removeEventToCommandTranslation(java.lang.String commandToGenerate, int type, int key, int modifiers) Removes the translation that generates the given command.
void	removeEventToCommandTranslation(java.lang.String commandToGenerate, MiEvent event) Removes the translation that generates the given command.
void	setAlwaysConsumeTriggerEvents(boolean flag) Sets whether this event handler will always return Mi_CONSUME_EVENT whenever it receives an event that is a trigger event (i.e.
void	setCommand(java.lang.String command) Sets the command to use.
void	setEnabled(boolean flag) Sets whether this event handler is enabled.
boolean	setEventToCommandTranslation(java.lang.String commandToGenerate, int type, int key, int modifiers) Sets (replaces) the translation for the given command to now be generated from the given event.
boolean	setEventToCommandTranslation(java.lang.String commandToGenerate, MiEvent event) Sets (replaces) the translation for the given command to now be generated from the given event.
boolean	setEventToCommandTranslation(java.lang.String commandToGenerate, MiEvent event1, MiEvent event2) Modifies an existing or adds if none a translation from the given event sequence to the given command.
void	setIsSingleton(boolean flag) Sets whether this event handler is copied and assigned along with the part that it assigned to when the part is copied.
void	setName(java.lang.String name) Sets the name of this event handler.
void	setObject(MiPart part) Sets the MiPart that events sent to this event handler should transform their positions relative to.
void	setPositionDependent(boolean flag) Sets whether this event handler only want events that occur within the bounds of any MiPart is assigned to.
void	setPropertyValue(java.lang.String name, java.lang.String value) Sets the property with the given name to the given value.
void	setTarget(MiPart part) Sets the MiPart that this is assigned to.
java.lang.String	toString() Returns information about this MiEventHandler.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MiEventHandler

public MiEventHandler()

Constructs a new MiEventHandler.

Method Detail

setName

public void setName(java.lang.String name)

Sets the name of this event handler.

Parameters:

name - the name of this event handler

getName

public java.lang.String getName()

Gets the name of this event handler.

Specified by:

getName in interface MiiEventHandler

Returns:

the name of this event handler

setTarget

public void setTarget(MiPart part)

Sets the MiPart that this is assigned to. This is set when this is assigned to a part.

Specified by:

setTarget in interface MiiEventHandler

Parameters:

part - the target part

getTarget

public MiPart getTarget()

Gets the MiPart that this is assigned to. This should be used instead of any local references to the target. Or better yet, access the event.getTarget if possible. This is in order that copying of MiParts, which also copies their eventhandlers, works as expected.

Specified by:

getTarget in interface MiiEventHandler

Returns:

the assigned to part

setObject

public void setObject(MiPart part)

Sets the MiPart that events sent to this event handler should transform their positions relative to.

Specified by:

setObject in interface MiiEventHandler

Parameters:

part - the local part

getObject

public MiPart getObject()

Gets the MiPart that events sent to this event handler should transform their positions relative to.

Specified by:

getObject in interface MiiEventHandler

Returns:

the local part

getType

public int getType()

Gets the type of this event handler. Valid types are: Mi_ORDINARY_EVENT_HANDLER_TYPE Mi_SHORT_CUT_EVENT_HANDLER_TYPE Mi_MONITOR_EVENT_HANDLER_TYPE Mi_GRAB_EVENT_HANDLER_TYPE

Specified by:

getType in interface MiiEventHandler

Returns:

the type of this event handler

See Also:

#setType

isType

public boolean isType(int type)

Gets whether this event handler is of the given type.

Returns:

true if of the given type

See Also:

getType()

setEnabled

public void setEnabled(boolean flag)

Sets whether this event handler is enabled.

Specified by:

setEnabled in interface MiiEventHandler

Parameters:

flag - true if enabled

isEnabled

public boolean isEnabled()

Gets whether this event handler is enabled.

Specified by:

isEnabled in interface MiiEventHandler

Returns:

true if enabled

setAlwaysConsumeTriggerEvents

public void setAlwaysConsumeTriggerEvents(boolean flag)

Sets whether this event handler will always return Mi_CONSUME_EVENT whenever it receives an event that is a trigger event (i.e. one that is found in the translation table). This is useful in situations where there are MiParts on top of each other and it is desired that the desensitizing of the top part should not cause the user's actions to apply to the underneath part.

Parameters:

flag - true if consuming trigger events

See Also:

getAlwaysConsumeTriggerEvents()

getAlwaysConsumeTriggerEvents

public boolean getAlwaysConsumeTriggerEvents()

Gets whether this event handler will always return Mi_CONSUME_EVENT whenever it receives an event that is a trigger event (i.e. one that is found in the translation table).

Returns:

true if consuming trigger events

See Also:

setAlwaysConsumeTriggerEvents(boolean)

setPositionDependent

public void setPositionDependent(boolean flag)

Sets whether this event handler only want events that occur within the bounds of any MiPart is assigned to. Otherwise this would be a 'global' or 'window-wide' event handler.

Parameters:

flag - true if only want events that occur within the bounds of the MiPart it is assigned to.

isPositionDependent

public boolean isPositionDependent()

Gets whether this event handler only want events that occur within the bounds of any MiPart is assigned to. Otherwise this would be a 'global' or 'window-wide' event handler.

Specified by:

isPositionDependent in interface MiiEventHandler

Returns:

true if only want events that occur within the bounds of the MiPart it is assigned to.

setIsSingleton

public void setIsSingleton(boolean flag)

Sets whether this event handler is copied and assigned along with the part that it assigned to when the part is copied.

Parameters:

flag - true only if want this eventhandler not to be copied. Default is false.

isSingleton

public boolean isSingleton()

Gets whether this event handler is copied and assigned along with the part that it assigned to when the part is copied.

Specified by:

isSingleton in interface MiiEventHandler

Returns:

true only if this eventhandler is not to be copied. Default is false.

addEventToCommandTranslation

public void addEventToCommandTranslation(java.lang.String commandToGenerate,
                                         int type,
                                         int key,
                                         int modifiers)

Adds a translation from the given event to the given command. When the event is received by this event handler it will generate the given command and send it to the processCommand method.

Parameters:

type - the type of the event to translate

key - the key of the event to translate

modifiers - the modifiers of the event to translate

See Also:

setEventToCommandTranslation(java.lang.String, com.swfm.mica.events.MiEvent, com.swfm.mica.events.MiEvent), removeEventToCommandTranslation(java.lang.String, int, int, int)

addEventToCommandTranslation

public void addEventToCommandTranslation(java.lang.String commandToGenerate,
                                         MiEvent event)

Adds a translation from the given event to the given command. When the event is received by this event handler it will generate the given command and send it to the processCommand method.

Specified by:

addEventToCommandTranslation in interface MiiEventHandler

Parameters:

event - the event to translate

commandToGenerate - the command to translate the event to

See Also:

setEventToCommandTranslation(java.lang.String, com.swfm.mica.events.MiEvent, com.swfm.mica.events.MiEvent), removeEventToCommandTranslation(java.lang.String, int, int, int)

addEventToCommandTranslation

public void addEventToCommandTranslation(java.lang.String commandToGenerate,
                                         MiEvent event1,
                                         MiEvent event2)

Adds a translation from the given event to the given command. When the event is received by this event handler it will generate the given command and send it to the processCommand method.

Parameters:

event1 - the part1 of the two part event to translate

event2 - the part2 of the two part event to translate

See Also:

setEventToCommandTranslation(java.lang.String, com.swfm.mica.events.MiEvent, com.swfm.mica.events.MiEvent), removeEventToCommandTranslation(java.lang.String, int, int, int)

setEventToCommandTranslation

public boolean setEventToCommandTranslation(java.lang.String commandToGenerate,
                                            MiEvent event1,
                                            MiEvent event2)

Modifies an existing or adds if none a translation from the given event sequence to the given command. When the event is received by this event handler it will generate the given command and send it to the processCommand method.

Parameters:

event1 - the part1 of the two part event to translate

event2 - the part2 of the two part event to translate

Returns:

true if modified an existing translation

See Also:

setEventToCommandTranslation(java.lang.String, com.swfm.mica.events.MiEvent, com.swfm.mica.events.MiEvent), removeEventToCommandTranslation(java.lang.String, int, int, int)

setEventToCommandTranslation

public boolean setEventToCommandTranslation(java.lang.String commandToGenerate,
                                            int type,
                                            int key,
                                            int modifiers)

Sets (replaces) the translation for the given command to now be generated from the given event. When the event is received by this event handler it will generate the given command and send it to the processCommand method. Only the first translation found is modified.

Parameters:

type - the type of the event to translate

key - the key of the event to translate

modifiers - the modifiers of the event to translate

Returns:

true if a translation was modified

See Also:

addEventToCommandTranslation(java.lang.String, int, int, int), removeEventToCommandTranslation(java.lang.String, int, int, int)

setEventToCommandTranslation

public boolean setEventToCommandTranslation(java.lang.String commandToGenerate,
                                            MiEvent event)

Sets (replaces) the translation for the given command to now be generated from the given event. When the event is received by this event handler it will generate the given command and send it to the processCommand method. Only the first translation found is modified.

Specified by:

setEventToCommandTranslation in interface MiiEventHandler

Parameters:

event - the event to translate

commandToGenerate - the command to translate the event to

Returns:

true if a translation was modified

See Also:

addEventToCommandTranslation(java.lang.String, int, int, int), removeEventToCommandTranslation(java.lang.String, int, int, int)

getEventToCommandTranslation

public MiEvent getEventToCommandTranslation(java.lang.String commandToGenerate,
                                            MiEvent event)

removeEventToCommandTranslation

public void removeEventToCommandTranslation(java.lang.String commandToGenerate,
                                            int type,
                                            int key,
                                            int modifiers)

Removes the translation that generates the given command. Only the first translation found is removed.

Parameters:

type - the type of the event of the translation to remove

key - the key of the event of the translation to remove

modifiers - the modifiers of the event of the translation to remove

Returns:

true if a translation was removed

See Also:

addEventToCommandTranslation(java.lang.String, int, int, int), setEventToCommandTranslation(java.lang.String, com.swfm.mica.events.MiEvent, com.swfm.mica.events.MiEvent)

removeEventToCommandTranslation

public void removeEventToCommandTranslation(java.lang.String commandToGenerate,
                                            MiEvent event)

Removes the translation that generates the given command. Only the first translation found is removed.

Parameters:

event - the event part of the translation to remove

Returns:

true if a translation was removed

See Also:

addEventToCommandTranslation(java.lang.String, int, int, int), setEventToCommandTranslation(java.lang.String, com.swfm.mica.events.MiEvent, com.swfm.mica.events.MiEvent)

removeEventToCommandTranslation

public void removeEventToCommandTranslation(java.lang.String commandToGenerate)

Removes the translation that generates the given command. Only the first translation found is removed.

Specified by:

removeEventToCommandTranslation in interface MiiEventHandler

Parameters:

commandToGenerate - the command whose translation to remove.

Returns:

true if a translation was removed

See Also:

addEventToCommandTranslation(java.lang.String, int, int, int), setEventToCommandTranslation(java.lang.String, com.swfm.mica.events.MiEvent, com.swfm.mica.events.MiEvent)

removeEventToCommandTranslation

public void removeEventToCommandTranslation(MiEvent event)

Removes the translation that involves the given event. Only the first translation found is removed.

Specified by:

removeEventToCommandTranslation in interface MiiEventHandler

Parameters:

event - the event whose translation to remove.

Returns:

true if a translation was removed

See Also:

addEventToCommandTranslation(java.lang.String, int, int, int), setEventToCommandTranslation(java.lang.String, com.swfm.mica.events.MiEvent, com.swfm.mica.events.MiEvent)

removeAllEventToCommandTranslations

public void removeAllEventToCommandTranslations()

processEvent

public int processEvent(MiEvent event)

Processes the given event.

Specified by:

processEvent in interface MiiEventHandler

Parameters:

event - The event to process

Returns:

Mi_CONSUME_EVENT if no other event handlers should see this event Mi_PROPOGATE_EVENT if other event handlers can also see this event

getNameForType

public static java.lang.String getNameForType(int type)

Gets the name for the given event handler type. Possible return values are: Mi_UNKNOWN_EVENT_HANDLER_TYPE_NAME Mi_ORDINARY_EVENT_HANDLER_TYPE_NAME Mi_SHORT_CUT_EVENT_HANDLER_TYPE_NAME Mi_MONITOR_EVENT_HANDLER_TYPE_NAME Mi_GRAB_EVENT_HANDLER_TYPE_NAME

Parameters:

type - the event handler type

Returns:

the name of the event handler type

getEvent

public MiEvent getEvent()

processCommand

public int processCommand(java.lang.String command)

Processes the given command.

Returns:

Mi_CONSUME_EVENT if no other event handlers should see the event that generated the command Mi_PROPOGATE_EVENT if other event handlers can also see the event that generated the command

processCommand

public int processCommand(MiEvent event,
                          java.lang.String command)

Processes the given command as if generated from the given event.

Parameters:

event - The event that the event handler will get any needed positional information

Returns:

Mi_CONSUME_EVENT if no other event handlers should see the event that generated the command Mi_PROPOGATE_EVENT if other event handlers can also see the event that generated the command

setCommand

public void setCommand(java.lang.String command)

Sets the command to use.

Parameters:

command - The command use

getCommand

public java.lang.String getCommand()

Gets the command to use.

Returns:

The command use

isCommand

public boolean isCommand(java.lang.String cmd)

Gets whether the given command is equal to the current command.

Parameters:

cmd - The given command

Returns:

true if the given command is the current command

getRequestedEvents

public MiEvent[] getRequestedEvents()

Gets an array of events that can be processed by this event handler.

Specified by:

getRequestedEvents in interface MiiEventHandler

Returns:

an array of events that this event handler is interested in.

getRequestedCommands

public java.lang.String[] getRequestedCommands()

Gets an array of command names that can be processed by this event handler. Command names can be generated from translations of input events, default translations of which are specified by the event handler. Many event handlers use this methodology to support a mapping from specific events to commands. In this way, the event handlers process the commands, not events. However the event handler will often look at the current event stored in the event handler to get additional (i.e. positional) information.

Specified by:

getRequestedCommands in interface MiiEventHandler

Returns:

an array of comands that this event handler is capable of processing

See Also:

addEventToCommandTranslation(java.lang.String, int, int, int), setEventToCommandTranslation(java.lang.String, com.swfm.mica.events.MiEvent, com.swfm.mica.events.MiEvent), removeEventToCommandTranslation(java.lang.String, int, int, int)

setPropertyValue

public void setPropertyValue(java.lang.String name,
                             java.lang.String value)

Sets the property with the given name to the given value. This is useful for changing the events that triggers a command.

Specified by:

setPropertyValue in interface MiiEventHandler

Parameters:

name - the name of an property

value - the value of the property

copy

public MiiEventHandler copy()

Returns a copy of this MiEventHandler.

Specified by:

copy in interface MiiEventHandler

Returns:

the copy

toString

public java.lang.String toString()

Returns information about this MiEventHandler.

Returns:

textual information (class name + unique numerical id + [disabled])