info.bioinfweb.tic

Class TICComponent

java.lang.Object

info.bioinfweb.tic.TICComponent

Direct Known Subclasses:

ScrollingTICComponent

public abstract class TICComponent
extends java.lang.Object

This is the parent class of all GUI components based in TIC. Inherited classes are toolkit independent GUI components that can be used in both Swing and SWT GUIs. To create toolkit specific instances of inherited classes SwingComponentFactory and SWTComponentFactory from the respective TIC modules can be used.

Creating TIC components

To create a concrete TIC component either the paint(TICPaintEvent) method must be overwritten with code painting the component or toolkit specific classes for Swing and SWT that do not need a toolkit-independent paint method must be provided by overwriting getSwingComponentClassName(Object...) and getSWTComponentClassName(Object...)().

getSize() should be overwritten if a component requires a certain (minimal) size.

Note that depending on your GUI design assignSize() might not have the desired effect if #assignSizeToSWTLayoutData(org.eclipse.swt.graphics.Point, Composite) is not overwritten with an respective implementation.

Mouse and keyboard events

TIC components support adding TIC event listeners for mouse and keyboard events. Due to the implementation of this behavior the toolkit specific components always have mouse and key listeners attached, no matter if a TIC listener was attached to the owning TIC component. In the case of Swing components events will not be forwarded to parent components anymore, even if no listener in this component consumed the event. Therefore TIC components automatically forward events to parent Swing components, if no TIC listener for the according event type consumed that event. TIC listener indicate whether they consumed an event by the return value of their handler methods (e.g. TICMouseWheelListener.mouseWheelMoved(info.bioinfweb.tic.input.TICMouseWheelEvent)).

If more than one listener for the same event type is attached to a TIC component, all listeners will be informed on events, no matter if a previous listener in the list already consumed the event. (Only forwarding to parent events is influenced by the return value of TIC event listeners.)

Author:

Ben Stöver

See Also:

ScrollingTICComponent, ToolkitComponent

Module:

info.bioinfweb.tic.core

Field Summary

Fields

Modifier and Type	Field and Description
protected static java.util.Map<java.lang.Integer,info.bioinfweb.tic.TICComponent.EventDispatcher>	DISPATCHER_MAP
protected boolean	repaintRequested

Constructor Summary

Constructors

Constructor and Description
TICComponent() Creates a new instance of this class.

Method Summary

Modifier and Type	Method and Description
void	addKeyListener(TICKeyListener listener) Adds a key listener to this component (and automatically to the underlying toolkit specific component).
void	addMouseListener(TICMouseListener listener) Adds a mouse listener to this component (and automatically to the underlying toolkit specific component).
void	addMouseWheelListener(TICMouseWheelListener listener) Adds a mouse wheel listener to this component (and automatically to the underlying toolkit specific component).
void	assignSize() Adopts the current component size to the underlying GUI toolkit, if a toolkit specific component has already been created.
boolean	dispatchEvent(TICInputEvent event)
TargetToolkit	getCurrentToolkit() Returns the toolkit the associated toolkit class belongs to.
protected TICListenerSet<TICKeyListener>	getKeyListenersSet()
protected TICListenerSet<TICMouseListener>	getMouseListenersSet()
protected TICListenerSet<TICMouseWheelListener>	getMouseWheelListenersSet()
java.awt.Dimension	getSize() Returns the size this object needs to be painted completely.
protected java.lang.String	getSwingComponentClassName(java.lang.Object... parameters) Method used by SwingComponentFactory in the Swing module to create the concrete GUI object for Swing.
protected java.lang.Object[]	getSwingComponentConstructorParameters(java.lang.Object... parameters) Inherited classes can overwrite this method if their Swing component needs constructor parameters in addition to the owning TICComponent.
protected java.lang.String	getSWTComponentClassName(java.lang.Object... parameters) Method used by SWTComponentFactory in the SWT module to create the concrete GUI object for SWT.
protected java.lang.Object[]	getSWTComponentConstructorParameters(java.lang.Object... parameters) Inherited classes can overwrite this method if their SWT component needs constructor parameters in addition to the owning TICComponent, the parent composite and the SWT style.
ToolkitComponent	getToolkitComponent() Returns a toolkit specific component used to display the contents of this class.
boolean	hasDefinedSize() Determines whether this component specifies a defined size.
boolean	hasToolkitComponent() Checks if an associated toolkit specific component has already been assigned to this instance.
boolean	isUpdateOngoing() Determines whether the contents displayed by this component are currently ongoing.
void	paint(TICPaintEvent event) Painting operations of the implementing class should be performed here, if a toolkit independent painting method is provided.
boolean	removeKeyListener(TICKeyListener listener) Removes the specified key listener from this component (and from the underlying toolkit specific component).
boolean	removeMouseListener(TICMouseListener listener) Removes the specified mouse listener from this component (and from the underlying toolkit specific component).
boolean	removeWheelMouseListener(TICMouseWheelListener listener) Removes the specified mouse wheel listener from this component (and from the underlying toolkit specific component).
void	repaint() Forces the underlying toolkit component to be repainted.
protected void	setToolkitComponent(ToolkitComponent toolkitComponent)
void	setUpdateOngoing(boolean updateOngoing) Allows to specify whether the contents displayed by this component are currently ongoing.

Methods inherited from class java.lang.Object

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

Field Detail

DISPATCHER_MAP

protected static final java.util.Map<java.lang.Integer,info.bioinfweb.tic.TICComponent.EventDispatcher> DISPATCHER_MAP

repaintRequested

protected boolean repaintRequested

Constructor Detail

TICComponent

public TICComponent()

Creates a new instance of this class.

Method Detail

getCurrentToolkit

public TargetToolkit getCurrentToolkit()

Returns the toolkit the associated toolkit class belongs to.

Returns:

the toolkit type or TargetToolkit.UNDEFINED if no toolkit specific implementation has yet been assigned

paint

public void paint(TICPaintEvent event)

Painting operations of the implementing class should be performed here, if a toolkit independent painting method is provided. The coordinates in the provided context are relative to this component, (0, 0) represents the top left corner of this area.

If implementing classes provide custom toolkit specific components by overwriting getSwingComponentClassName(Object...) and getSwingComponentClassName(Object...) the implementation of this method may remain empty.

This default implementation is empty. Inherited classes must either overwrite it or overwrite getSwingComponentClassName(Object...) and getSWTComponentClassName(Object...) to provide toolkit components that do not need an implementation of this method.

Parameters:

event - the paint event providing the graphics context and information on which part of the component should be repainted

getSize

public java.awt.Dimension getSize()

Returns the size this object needs to be painted completely.

Components may specify their minimal size or the only acceptable fixed size here. The respective toolkit components should be implemented respectively. Returning null if the component does not prefer any size is also valid.

Note that this size may differ from the actual size of the toolkit component, e.g. if it specifies a preferred size.

This default implementation always returns null.

Returns:

the dimension in pixels needed to completely paint this component or null

See Also:

ToolkitComponent.getToolkitSize()

hasDefinedSize

public boolean hasDefinedSize()

Determines whether this component specifies a defined size. See getSize() for details.

Returns:

true if this component returns a defined size in getSize() or false if this component does not have any preferred size and getSize() returns null

isUpdateOngoing

public boolean isUpdateOngoing()

Determines whether the contents displayed by this component are currently ongoing.

repaint() makes use of this property to avoid unnecessary repaint operations.

Returns:

true if an update is currently ongoing, false otherwise

Since:

0.5.0

setUpdateOngoing

public void setUpdateOngoing(boolean updateOngoing)

Allows to specify whether the contents displayed by this component are currently ongoing.

repaint() makes use of this property to avoid unnecessary repaint operations. If this property is changed from true to false, the component will be repainted directly, if that was previously requested.

Parameters:

updateOngoing - true if an update is currently ongoing, false otherwise

repaint

public void repaint()

Forces the underlying toolkit component to be repainted. This method will only have an effect if a toolkit specific component has already been assigned (hasToolkitComponent() return true).

If isUpdateOngoing() is set to true, calls of this method will not cause a direct repaint. The request for repainting is stored internally by this instance and it will be repainted when setUpdateOngoing(boolean) is set to false the next time. (If this method was called multiple times before that, still only one repaint operation will be performed.)

assignSize

public void assignSize()

Adopts the current component size to the underlying GUI toolkit, if a toolkit specific component has already been created.

This methods delegates to ToolkitComponent.assignSize(), if an underlying toolkit-specific component was already created.

getToolkitComponent

public ToolkitComponent getToolkitComponent()

Returns a toolkit specific component used to display the contents of this class.

Returns:

the toolkit specific component or null if neither a Swing nor a SWT component has yet been created

setToolkitComponent

protected void setToolkitComponent(ToolkitComponent toolkitComponent)

hasToolkitComponent

public boolean hasToolkitComponent()

Checks if an associated toolkit specific component has already been assigned to this instance.

Returns:

true if a component has been assigned, false otherwise

getSwingComponentClassName

protected java.lang.String getSwingComponentClassName(java.lang.Object... parameters)

Method used by SwingComponentFactory in the Swing module to create the concrete GUI object for Swing. Inherited classes providing custom Swing specific implementations should overwrite this method.

Note that custom implementations need to provide constructors as defined in the documentation of ToolkitComponent.

Parameters:

parameters - an optional list of parameters that were passed to the getSwingComponent() method of SwingComponentFactory

Returns:

a fully qualified class name for a class used to create the concrete Swing GUI instance associated with this instance

getSwingComponentConstructorParameters

protected java.lang.Object[] getSwingComponentConstructorParameters(java.lang.Object... parameters)

Inherited classes can overwrite this method if their Swing component needs constructor parameters in addition to the owning TICComponent.

The default implementation of this method returns an empty array an can be left unchanged for all Swing components that do not need additional constructor parameters.

Parameters:

parameters - an optional list of parameters that were passed to the getSwingComponent() method of SwingComponentFactory

Returns:

the list of additional parameters to be passed to the constructor of the Swing component defined by the return value of getSwingComponentClassName(Object...)

Since:

3.0.0

getSWTComponentClassName

protected java.lang.String getSWTComponentClassName(java.lang.Object... parameters)

Method used by SWTComponentFactory in the SWT module to create the concrete GUI object for SWT. Inherited classes providing custom SWT specific implementations should overwrite this method.

Note that custom implementations need to provide constructors as defined in the documentation of ToolkitComponent.

Parameters:

parameters - an optional list of parameters that were passed to the getSWTComponent() method of SWTComponentFactory

Returns:

a fully qualified class name for a class used to create the concrete SWT GUI instance associated with this instance

getSWTComponentConstructorParameters

protected java.lang.Object[] getSWTComponentConstructorParameters(java.lang.Object... parameters)

Inherited classes can overwrite this method if their SWT component needs constructor parameters in addition to the owning TICComponent, the parent composite and the SWT style.

The default implementation of this method returns an empty array an can be left unchanged for all SWT components that do not need additional constructor parameters.

Parameters:

parameters - an optional list of parameters that were passed to the getSWTComponent() method of SWTComponentFactory

Returns:

the list of additional parameters to be passed to the constructor of the Swing component defined by the return value of getSwingComponentClassName(Object...)

Since:

3.0.0

getKeyListenersSet

protected TICListenerSet<TICKeyListener> getKeyListenersSet()

getMouseListenersSet

protected TICListenerSet<TICMouseListener> getMouseListenersSet()

getMouseWheelListenersSet

protected TICListenerSet<TICMouseWheelListener> getMouseWheelListenersSet()

addKeyListener

public void addKeyListener(TICKeyListener listener)

Adds a key listener to this component (and automatically to the underlying toolkit specific component).

Parameters:

listener - the object to listen to key events

removeKeyListener

public boolean removeKeyListener(TICKeyListener listener)

Removes the specified key listener from this component (and from the underlying toolkit specific component).

Parameters:

listener - the listener to be removed

Returns:

true if the specified lister was contained in the list, false otherwise

addMouseListener

public void addMouseListener(TICMouseListener listener)

Adds a mouse listener to this component (and automatically to the underlying toolkit specific component).

Parameters:

listener - the object to listen to mouse events

See Also:

addMouseWheelListener(TICMouseWheelListener)

removeMouseListener

public boolean removeMouseListener(TICMouseListener listener)

Removes the specified mouse listener from this component (and from the underlying toolkit specific component).

Parameters:

listener - the listener to be removed

Returns:

true if the specified lister was contained in the list, false otherwise

addMouseWheelListener

public void addMouseWheelListener(TICMouseWheelListener listener)

Adds a mouse wheel listener to this component (and automatically to the underlying toolkit specific component).

Parameters:

listener - the object to listen to mouse wheel events

See Also:

addMouseListener(TICMouseListener)

removeWheelMouseListener

public boolean removeWheelMouseListener(TICMouseWheelListener listener)

Removes the specified mouse wheel listener from this component (and from the underlying toolkit specific component).

Parameters:

listener - the listener to be removed

Returns:

true if the specified lister was contained in the list, false otherwise

dispatchEvent

public boolean dispatchEvent(TICInputEvent event)