org.eclipse.actf.model
Interface IGuiModel

All Superinterfaces:
IModel
All Known Implementing Classes:
AbstractGuiModel, AwtGuiModel, IA2GuiModel, MsaaGuiModel, SwingGuiModel, SwtGuiModel

public interface IGuiModel
extends IModel

The IGuiModel interface is implemented in order to allow the IBM Reflexive GUI Builder to support a variety of GUI models. The application is packaged with implementations of the IGuiModel interface in order to accommodate GUIs designed according to the Swing, AWT, and Eclipse SWT frameworks (although the AWT models is discouraged since it does not fully support accessibility features provided in other models such as Swing).

A better name for this interface is actually GUIHierarchicalStructure since an model is a hierarchical structure that embodies the hierarchical nature of Java GUI components. Although ACTF can be used to construct and render implementations of this interface, not all hierarchical structures can be built using ACTF. However, the validation mechanism does support the validation of any hierarchical structure once the appropriate validator implementation and validation document(s) are written.

Author:
Mike Squillace

Method Summary
 void asyncInvokeOnUIThread(Runnable runnable)
          asyncronously executes the given Runnable from within the UI thread.
 Rectangle getBoundingRectangle(Object element)
          gets the rectangle bounding the given element
 ModelEventType getModelEventType(Object eventId)
          get the ModelEventType instances associated with the given event id.
 ModelEventType[] getModelEventTypes(Class sourceType)
          get the model event types for the given source type.
 void highlight(Object element)
          highlight or visually indicate the element that is being examined.
 void invokeOnUIThread(Runnable runnable)
          executes the given Runnable from within the UI thread.
 boolean isUIThread()
          returns whether or not the currently executing thread is the UI thread.
 boolean isValid(Object component)
          returns whether or not the specified component is valid for access.
 boolean isVisible(Object component)
          returns whether or not the specified component is currently visible
 void registerModelEventListener(IModelEventListener listener, ModelEventType[] eventTypes)
          register a listener to receive notification when events with the given eventTypes are fired within this model.
 boolean requestFocusFor(Object comp)
          request the focus for the specified component.
 void unregisterModelEventListener(IModelEventListener listener, ModelEventType[] eventTypes)
          unregister a previously registered listener.
 
Methods inherited from interface org.eclipse.actf.model.IModel
addModelChangeListener, getBaseType, getDefaultAliasPrefix, getName, getNodeId, getNodeLocator, getNodeName, getOrder, getPackageNames, getTreeWalker, removeModelChangeListener, setNodeID
 

Method Detail

getModelEventTypes

ModelEventType[] getModelEventTypes(Class sourceType)
get the model event types for the given source type. A ModelEventType object describes the types of events that can be fired within the context of this runtime model. If the sourceType is null, then all of the event types of which this model is aware will be returned else only events that can be fired by the given sourceType will be returned.

Parameters:
sourceType - type to be queried for events
Returns:
all events that can be fired by instances of the given type or all events of which this model is aware
See Also:
org.eclipse.actf.core.model.event.ModelEventType

getModelEventType

ModelEventType getModelEventType(Object eventId)
get the ModelEventType instances associated with the given event id. The event id is model-specific and will usually be presented in the model's API. What constitutes an event id and how they are determined should be specified in clients that implement this model.

Parameters:
eventId - model-specific event id
Returns:
ModelEventType instances associated with this event id or null if no event types are associated with this id

registerModelEventListener

void registerModelEventListener(IModelEventListener listener,
                                ModelEventType[] eventTypes)
register a listener to receive notification when events with the given eventTypes are fired within this model. The eventTypes should be obtained from one of the getModelEventTypes methods.

Parameters:
listener - listener to be notified when specified events occur
eventTypes - event types for which listener is being registered
See Also:
getModelEventType(Object), getModelEventTypes(Class)

unregisterModelEventListener

void unregisterModelEventListener(IModelEventListener listener,
                                  ModelEventType[] eventTypes)
unregister a previously registered listener. The eventTypes should be obtained from either of the getModelEventTypes methods.

Parameters:
listener - listener to be unregistered
eventTypes - event types for which listener is to be unregistered
See Also:
registerModelEventListener(IModelEventListener, ModelEventType[]), org.eclipse.actf.core.model.event.ModelEventType#getId()

isUIThread

boolean isUIThread()
returns whether or not the currently executing thread is the UI thread. The UI thread is the thread upon which actions effecting the state or drawing of a component or the event handlers associated with a component are to be executed. If this method returns false, the client will typically need to invoke the invokeOnUIThread method in order to effect the GUI.

Returns:
true if the current thread is the UI thread, false otherwise
See Also:
invokeOnUIThread(Runnable)

invokeOnUIThread

void invokeOnUIThread(Runnable runnable)
executes the given Runnable from within the UI thread. This method will typically be called if isUIThread returns false.

Parameters:
runnable - - Runnable to be invoked in UI thread
See Also:
isUIThread()

asyncInvokeOnUIThread

void asyncInvokeOnUIThread(Runnable runnable)
asyncronously executes the given Runnable from within the UI thread. That is, the Runnable is placed in a queue and control is returned immediately to the calling thread.

Parameters:
runnable - - Runnable to be invoked in UI thread
See Also:
invokeOnUIThread(Runnable)

isVisible

boolean isVisible(Object component)
returns whether or not the specified component is currently visible

Parameters:
component - - component to be tested
Returns:
whether or not the component is currently visible or showing on the screen

isValid

boolean isValid(Object component)
returns whether or not the specified component is valid for access. Components may be invalid because their underlying resources have been disposed, because the device that displays or renders them is destroyed, or for many other reasons.

Parameters:
component - - component to be tested
Returns:
true if this component is valid, false otherwise
See Also:
org.eclipse.actf.core.model.InvalidComponentException

requestFocusFor

boolean requestFocusFor(Object comp)
request the focus for the specified component. This method should be invoked, for example, just prior to validation for a report that reflects the state of the component while visible.

Parameters:
comp - - component for which focus is desired
Returns:
true if focus is successful, false otherwise

getBoundingRectangle

Rectangle getBoundingRectangle(Object element)
gets the rectangle bounding the given element

Parameters:
element - - element for which bounds are desired
Returns:
bounding rectangle of component

highlight

void highlight(Object element)
highlight or visually indicate the element that is being examined. Highlighting may take place by placing a border around the element, flashing the element, or changing its background color.

Parameters:
element - - the element to be highlited