org.jscience.swing.joggle
Class Joggle

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Container
          extended by javax.swing.JComponent
              extended by 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.

joggle screenshot

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:

"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.

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.

joggle black and white screenshot

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:


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:

Parameters:
orientation - HORIZONTAL or VERTICAL.

Joggle

public Joggle(JoggleModel joggleModel)
Creates a new Joggle with the specified JoggleModel. Other initial values are:

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:

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)