org.jscience.swing.joggle
Class Joggle

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              org.jscience.swing.joggle.Joggle

All Implemented Interfaces:

java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable

public class Joggle
extends javax.swing.JComponent

A Component drawing a joggle (or wheel) you can drag to move it (scroll) and change a value to the corresponding JoggleModel. The following image shows a joggle UI with HORIZONTAL orientation.

Any joggle has a certain number of grooves. The visible groove count relies on the apex angle. The apex angle must be a value between pi/9 (20 degrees) and pi (180 degrees). For example, if the apex angle is pi then approximately the half of all grooves will be visible. You can set the number of grooves with the method setGrooveCount(int) and the apex angle with setApexAngle(double).

The rotation angle describes the current position of the joggle. You can get it by the method getRotationAngle() but you can also explicitly set it by setRotationAngle(double). Note that the rotation angles of 0 (0 degrees), 2*pi (360 degrees), 4*pi (720 degrees), 6*pi (1080 degrees), etc., corresponds to the same position. You can get these position by the method getPositionAngle().

If you are not using the constructor expecting the arguments for grooveCount, initApexAngle and initRotationAngle, the following default values will be set:

• grooveCount = 30
• apexAngle = Math.PI (180 degrees)
• rotationAngle = 0.0

"Jog the Joggle"

You can "jog" (drag) this Joggle BACKWARD, FORWARD or to both directions. FORWARD means that you can drag this Joggle to the right (HORIZONTAL orientation) or to the bottom (VERTICAL orientation). BACKWARD means that you can drag it to the left (HORIZONTAL orientation) or to the top (VERTICAL orientation). The default jogDirection is BIDIRECTIONAL, that means dragging this Joggle into both directions is possible. You can specify the jogDirection with setJogDirection(int) or with a certain constructor.

If you want the joggle to move constantly and permanently, you only have to "jog" it. This meens, you have to release the mouse button while you are still dragging. The speed of the joggle's rotation depends on the speed you drag it in the moment of mouse releasing.

"Color the Joggle"

There are three colors to set for a joggle.

• First is the light color: visible at the joggle's highlight angle. The default highlight angle is 0 - in this case the light color is the color on the very top of the joggle. The light color can be set by setJoggleLightColor(Color).
• Second color is the shadow color: it defines the destinition color of the color gradient from the highlight angle (light color) to the joggle edges. The shadow color is visible at 90 degrees (or more) from the highlight angle. It can be set by setJoggleShadowColor(Color).
• Third color is the color for the marked groove. The marked groove eases following any rotation of the joggle. The marked groove color changes towards the joggle border like the light color. That's why the marked groove is invisible, if the marked groove color is equal to the light color. The marked groove color can be set by setMarkedGrooveColor(Color).

The default light and shadow colors are the colors of a scrollbar defined by the current LookAndFeel. To get these colors also after the LookAndFeel changed, updateUI() will call UIManager.getColor("ScrollBar.thumbShadow") and UIManager.getColor("ScrollBar.thumbHighlight").
The default marked groove color is red.
The following image shows a joggle with white as the light color and black as the shadow and marked groove color.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class javax.swing.JComponent

javax.swing.JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Container

java.awt.Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

java.awt.Component.AccessibleAWTComponent, java.awt.Component.BaselineResizeBehavior, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy

Field Summary

static int	BACKWARD Direction a Joggle is able to be dragged.
static int	BIDIRECTIONAL Direction a Joggle is able to be dragged.
static int	FORWARD Direction a Joggle is able to be dragged.
static int	HORIZONTAL For horizontal orientation of this Joggle.
static int	TIMER_DELAY
static int	VERTICAL For vertical orientation of this Joggle.

Fields inherited from class javax.swing.JComponent

accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

Joggle()
Creates a new Joggle with a new DefaultJoggleModel.

Joggle(int orientation)
Creates a new Joggle with a new DefaultJoggleModel and the specified orientation.

Joggle(JoggleModel joggleModel)
Creates a new Joggle with the specified JoggleModel.

Joggle(JoggleModel joggleModel, int orientation)
Creates a new Joggle with the specified JoggleModel and orientation.

Joggle(JoggleModel joggleModel, int orientation, int grooveCount, double initApexAngle, int initJogDirection)
Creates a new Joggle with the specified JoggleModel and orientation.

Method Summary

void	addChangeListener(javax.swing.event.ChangeListener l) Adds a listener to the list that is notified each time a change to the model occurs.
void	doLayout()
protected void	fireStateChanged() Sends a ChangeEvent, whose source is this Joggle, to each listener which was added to this Joggle.
boolean	getAntialiasing() Returns true if the Java2D rendering mode is set to antialias this Joggle, false otherwise.
double	getApexAngle() Returns the current apex angle describing the visible part of this Joggle.
int	getGrooveCount() Returns the current count of grooves of this Joggle.
double	getHighlightAngle() Returns the angle (in radian) to the lightpoint shining on this Joggle.
int	getJogDirection() Returns the currently set direction this Joggle is able to be dragged.
java.awt.Color	getJoggleLightColor() Returns the current light color of this Joggle.
java.awt.Color	getJoggleShadowColor() Returns the current shadow color of this Joggle.
java.awt.Color	getMarkedGrooveColor() Returns the color of the marked groove.
JoggleModel	getModel() Returns this Joggle's data model.
double	getPositionAngle() Returns the angle (in radian) in relation to the current rotation angle but ignoring the count of rotations.
double	getRotationAngle() Returns the current rotation angle (in radian).
SharableTimer	getTimer() Returns the SharableTimer this Joggle is using.
double	getValue() Returns the value this Joggle is currently representing.
void	paintComponent(java.awt.Graphics g)
void	removeChangeListener(javax.swing.event.ChangeListener l) Removes a ChangeListener from this Joggle.
void	setAntialiasing(boolean b) Specifies the Java2D rendering mode.
void	setApexAngle(double d) Sets a new apex angle (in radian) for this Joggle.
void	setGrooveCount(int i) Sets the total (visible and invisible) count of grooves of this Joggle.
void	setHighlightAngle(double d) Sets the angle (in radian) to the lightpoint shining on this Joggle.
void	setJogDirection(int direction) Sets the direction this Joggle should be able to be dragged.
void	setJoggleLightColor(java.awt.Color c) Sets this Joggle's color at the highlight angle.
void	setJoggleShadowColor(java.awt.Color c) Sets this Joggle's shadow color.
void	setMarkedGrooveColor(java.awt.Color c) Sets the color of this Joggle's marked groove.
void	setModel(JoggleModel model) Sets a new data model for this Joggle.
void	setRotationAngle(double d) Sets the current rotation angle (in radian) of this Joggle.
void	setTimer(SharableTimer timer) Sets a new SharableTimer for this Joggle.
void	setValue(double value) Sets a new (transmissioned) value to the model.
void	updateUI() Sets shadow and light color to new LookAndFeel colors of a scrollbar only if they were not set manually by the user.

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getAccessibleContext, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getUIClassID, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintImmediately, paintImmediately, paramString, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle

Methods inherited from class java.lang.Object

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

Field Detail

HORIZONTAL

public static final int HORIZONTAL

For horizontal orientation of this Joggle.

See Also:

Constant Field Values

VERTICAL

public static final int VERTICAL

For vertical orientation of this Joggle.

See Also:

Constant Field Values

BIDIRECTIONAL

public static final int BIDIRECTIONAL

Direction a Joggle is able to be dragged.

See Also:

Constant Field Values

FORWARD

public static final int FORWARD

Direction a Joggle is able to be dragged.

See Also:

Constant Field Values

BACKWARD

public static final int BACKWARD

Direction a Joggle is able to be dragged.

See Also:

Constant Field Values

TIMER_DELAY

public static final int TIMER_DELAY

See Also:

Constant Field Values

Constructor Detail

Joggle

public Joggle()

Creates a new Joggle with a new DefaultJoggleModel. Other initial values are:

• orientation = HORIZONTAL
• grooveCount = 30
• apexAngle = Math.PI
• rotationAngle = 0.0
• jogDirection = BIDIRECTIONAL

Joggle

public Joggle(int orientation)

Creates a new Joggle with a new DefaultJoggleModel and the specified orientation. The orientation can be HORIZONTAL or VERTICAL. Other initial values are:

• grooveCount = 30
• apexAngle = Math.PI
• rotationAngle = 0.0
• jogDirection = BIDIRECTIONAL

Parameters:

orientation - HORIZONTAL or VERTICAL.

Joggle

public Joggle(JoggleModel joggleModel)

Creates a new Joggle with the specified JoggleModel. Other initial values are:

• orientation = HORIZONTAL
• grooveCount = 30
• apexAngle = Math.PI
• rotationAngle = joggleModel.getValue() / joggleModel.getTransmissionRatio()
• jogDirection = BIDIRECTIONAL

Parameters:

joggleModel - A data model for this Joggle .

Joggle

public Joggle(JoggleModel joggleModel,
              int orientation)

Creates a new Joggle with the specified JoggleModel and orientation. The orientation can be HORIZONTAL or VERTICAL. Other initial values are:

• grooveCount = 30
• apexAngle = Math.PI
• rotationAngle = joggleModel.getValue() / joggleModel.getTransmissionRatio()
• jogDirection = BIDIRECTIONAL

Parameters:

joggleModel - A data model for this Joggle .

orientation - HORIZONTAL or VERTICAL.

Joggle

public Joggle(JoggleModel joggleModel,
              int orientation,
              int grooveCount,
              double initApexAngle,
              int initJogDirection)

Creates a new Joggle with the specified JoggleModel and orientation. The orientation can be HORIZONTAL or VERTICAL. Further more, init values for grooveCount, apexAngle and jogDirection have to be specified. See class documentation for details.

The current position of this Joggle - its rotationAngle - will be calculated by

joggleModel.getValue() / joggleModel.getTransmissionRatio().

Parameters:

joggleModel - A data model for this Joggle .

orientation - HORIZONTAL or VERTICAL.

grooveCount - total number of grooves this Joggle has.

initApexAngle - the angle describing the visible part of this Joggle.

initJogDirection - FORWARD, BACKWARD or BIDIRECTIONAL.

Throws:

java.lang.IllegalArgumentException - if the initApexAngle is no value between pi and pi/9.

java.lang.IllegalArgumentException - if the orientation is not HORIZONTAL or VERTICAL.

java.lang.IllegalArgumentException - if the jogDirection is not FORWARD, BACKWARD or BIDIRECTIONAL.

Method Detail

paintComponent

public void paintComponent(java.awt.Graphics g)

Overrides:

paintComponent in class javax.swing.JComponent

getApexAngle

public double getApexAngle()

Returns the current apex angle describing the visible part of this Joggle.

Returns:

the current apex angle describing the visible part of this Joggle.

See Also:

setApexAngle(double)

setApexAngle

public void setApexAngle(double d)

Sets a new apex angle (in radian) for this Joggle. The angle describes the visible part of this Joggle.

Parameters:

d - the new apex angle.

Throws:

java.lang.IllegalArgumentException - if d>pi or d<pi/9

getGrooveCount

public int getGrooveCount()

Returns the current count of grooves of this Joggle. Note that the really visible groove count depends on the apex angle and is the half of the set groove count at the maximum apex angle of pi (180 degrees).

Returns:

the currently set groove count.

See Also:

getApexAngle()

setGrooveCount

public void setGrooveCount(int i)

Sets the total (visible and invisible) count of grooves of this Joggle. Note that the really visible number of grooves depends on the currently set apex angle.

Parameters:

i - the new count of grooves.

See Also:

setApexAngle(double)

getRotationAngle

public double getRotationAngle()

Returns the current rotation angle (in radian). This angle describes the absolut position of this Joggle depending on the count of rotations. If you want the angle in relation to one rotation, you have to call getPositionAngle().

Returns:

the current rotation angle.

See Also:

getPositionAngle()

setRotationAngle

public void setRotationAngle(double d)

Sets the current rotation angle (in radian) of this Joggle. The rotation angle describes its absolut position depending on the count of rotations the Joggle has already complete.

Parameters:

d - the new rotation angle.

getPositionAngle

public double getPositionAngle()

Returns the angle (in radian) in relation to the current rotation angle but ignoring the count of rotations. That's why the postion angle is a value between 0 (inclusively) and 2*pi (exclusively). For example: If the rotationAngle is 2*pi (4*pi, 6*pi, 8*pi, ...), the position angle is 0.

Returns:

the relativ position angle in relation to one rotation.

getHighlightAngle

public double getHighlightAngle()

Returns the angle (in radian) to the lightpoint shining on this Joggle.

Returns:

the angle (in radian) to the lightpoint shining on this Joggle.

setHighlightAngle

public void setHighlightAngle(double d)

Sets the angle (in radian) to the lightpoint shining on this Joggle. If d=0 then the lightpoint stands in the zenith to this Joggle. Other values around zero move the lightpoint to the left and right (HORIZONTAL orientation) or top and bottom (VERTICAL orientation). d should be a radian value between -pi and pi.

Parameters:

d - a radian value describing the highlight angle.

getAntialiasing

public boolean getAntialiasing()

Returns true if the Java2D rendering mode is set to antialias this Joggle, false otherwise.

Returns:

true if the Java2D rendering mode is set to antialias this Joggle, false otherwise.

setAntialiasing

public void setAntialiasing(boolean b)

Specifies the Java2D rendering mode. If this property is set to true, this Joggle will be drawn antialiased, otherwise not. The default is true.

Parameters:

b -

getJoggleLightColor

public java.awt.Color getJoggleLightColor()

Returns the current light color of this Joggle. The light color is the color at the joggle's highlight angle.

Returns:

the light color of this Joggle.

See Also:

getHighlightAngle()

setJoggleLightColor

public void setJoggleLightColor(java.awt.Color c)

Sets this Joggle's color at the highlight angle.

Parameters:

c - the new light color.

See Also:

getHighlightAngle()

getJoggleShadowColor

public java.awt.Color getJoggleShadowColor()

Returns the current shadow color of this Joggle. The shadow color is visible at 90 degrees or more from the highlight angle.

Returns:

the shadow color of this Joggle.

See Also:

getJoggleLightColor(), getHighlightAngle()

setJoggleShadowColor

public void setJoggleShadowColor(java.awt.Color c)

Sets this Joggle's shadow color.

Parameters:

c - the new shadow color.

getMarkedGrooveColor

public java.awt.Color getMarkedGrooveColor()

Returns the color of the marked groove. The marked groove makes it easier to follow any single rotation of this Joggle.

Returns:

the color of the marked groove.

setMarkedGrooveColor

public void setMarkedGrooveColor(java.awt.Color c)

Sets the color of this Joggle's marked groove.

Parameters:

c - the new color for the marked groove.

getJogDirection

public int getJogDirection()

Returns the currently set direction this Joggle is able to be dragged.

Returns:

FORWARD, BACKWARD or BIDIRECTIONAL

setJogDirection

public void setJogDirection(int direction)

Sets the direction this Joggle should be able to be dragged.

Parameters:

direction - FORWARD, BACKWARD or BIDIRECTIONAL

getModel

public JoggleModel getModel()

Returns this Joggle's data model.

Returns:

this Joggle's data model.

See Also:

JoggleModel

setModel

public void setModel(JoggleModel model)

Sets a new data model for this Joggle.

Parameters:

model - the new data model.

See Also:

JoggleModel

getValue

public double getValue()

Returns the value this Joggle is currently representing.

Note: The returned value comes from the model and is almost never equal to the rotationAngle. It rather depends on the rotationAngle by multiplying it with a transmissionRatio. This ratio is defined in the model, too.

Returns:

the value this Joggle is currently representing.

See Also:

JoggleModel.getValue(), JoggleModel.getTransmissionRatio()

setValue

public void setValue(double value)

Sets a new (transmissioned) value to the model.

Parameters:

value - the new value this Joggle has to represent.

See Also:

getValue(), JoggleModel.setValue(double), JoggleModel.getTransmissionRatio()

getTimer

public SharableTimer getTimer()

Returns the SharableTimer this Joggle is using.

Returns:

the SharableTimer this Joggle is using.

setTimer

public void setTimer(SharableTimer timer)

Sets a new SharableTimer for this Joggle.

Parameters:

timer - the new timer.

doLayout

public void doLayout()

Overrides:

doLayout in class java.awt.Container

updateUI

public void updateUI()

Sets shadow and light color to new LookAndFeel colors of a scrollbar only if they were not set manually by the user. The method will be called in constructor and if a new LookAndFeel was set and SwingUtilities.updateComponentTreeUI(Component) was called.

Overrides:

updateUI in class javax.swing.JComponent

addChangeListener

public void addChangeListener(javax.swing.event.ChangeListener l)

Adds a listener to the list that is notified each time a change to the model occurs.

Parameters:

l - the ChangeListener to add

See Also:

#setValue(doublevalue)

removeChangeListener

public void removeChangeListener(javax.swing.event.ChangeListener l)

Removes a ChangeListener from this Joggle.

Parameters:

l - the listener to remove.

fireStateChanged

protected void fireStateChanged()

Sends a ChangeEvent, whose source is this Joggle, to each listener which was added to this Joggle. This method is called each time a ChangeEvent is received from the model.

See Also:

#addChangeListener(ChangeListenerl)