com.jidesoft.gauge
Class Dial

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              com.jidesoft.gauge.AbstractGauge<DialAxis>
                  com.jidesoft.gauge.Dial

All Implemented Interfaces:

ResizableComponent, GaugeModelListener, ImageObserver, MenuContainer, Serializable, EventListener

Direct Known Subclasses:

Clock

public class Dial
extends AbstractGauge<DialAxis>

The main class for displaying circular gauges - or gauges that form part of a circle. The gauge class supports multiple needles, and you can configure the appearance of needles with a NeedleStyle.

The dimensions of dial-related properties and needles are generally specified in terms of the radius of the dial so that the proportions of the dial objects remain unchanged under resizing. In other words, the same dial object will look good whether large or small.

See Also:

Serialized Form

Nested Class Summary

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

JComponent.AccessibleJComponent

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

Container.AccessibleAWTContainer

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

Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

static String

PROPERTY_DIAL_BACKGROUND

Fields inherited from class com.jidesoft.gauge.AbstractGauge

DEFAULT_NEEDLE_NAME, PROPERTY_BACKGROUND_PAINT, PROPERTY_RESIZE_FONTS

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

Dial()
Create a new Dial instance.

Method Summary

void	addAxis(DialAxis axis)
void	addDrawable(Drawable drawable) Adds a Drawable object to the dial
void	addNeedle(String needleName, NeedleStyle style) Adds a needle and associates it with the specified needle name
protected Point2D	calculatePixelPoint2D(DialAxis axis, double axisValue)
GeneralPath	createSegment(double fromAngle, double toAngle, double innerRadius, double outerRadius)
protected Paint	deriveFacePaint(Color faceColor, float x, float y, float radius)
Double	getAngle(DialAxis axis, Double value) Returns the angle (in degrees) of the value on the supplied axis, or null if the supplied value is null.
Double	getAngle(Double value) Returns the angle of the value on the primary axis
GaugeModel	getAnimatedModel()
DialAxis	getAxis() Returns the primary axis for the dial
Paint	getDialBackground() Deprecated. in favour of getGaugeBackground()
double	getEndAngle()
Color	getFaceColor() Returns the base color of the face of the display
Paint	getFacePaint() The current Paint used for the face of the Dial.
DialFrame	getFrame()
int	getNeedleAnimationPeriod()
double	getNeedleAnimationSpeed()
List<String>	getNeedleNames()
NeedleRenderer	getNeedleRenderer(String name) Returns the needle renderer for the specified needle
NeedleStyle	getNeedleStyle(String needleName) Returns the display style associated with the specified needle
int	getPivotX()
int	getPivotY()
float	getRadius() Returns a radius in pixels
double	getStartAngle()
Color	getTickColor()
boolean	isAnimateOnChange() Returns a boolean to indicate whether animation is being used to show needle changes
NeedleDescriptor	needleAt(Point2D p) Determines whether there is a needle at the specified pixel position.
Collection<NeedleDescriptor>	needlesAt(Point2D p) Determines which needles, if any, are at the specified pixel position, returning a collection of descriptor objects that describe the needles.
static double	normalizeAngle(double angle) Reduces an angle value (given in degrees) to a value in the range [0, 360)
void	paintComponent(Graphics g) The main method for painting the display
void	removeAxis(DialAxis axis)
void	removeDrawable(Drawable drawable) Removes the specified Drawable from the dial
void	removeDrawables() Removes all Drawables from the dial
void	removeNeedle(String name) Removes the named needle from the dial
void	removeNeedleRenderer(String name) Remove the renderer associated with the specified needle
void	removeNeedles() Removes all needles from the dial
NeedleDescriptor	rendered(String needleName) Returns a NeedleDescriptor object for the named needle
void	setAnimatedModel(GaugeModel animatedModel)
void	setAnimateOnChange(boolean animateOnChange) Specify whether animation should be used to move needles when the value changes.
void	setAxis(DialAxis axis) Specify the axis to use for the dial.
void	setDialBackground(Paint background) Deprecated. in favour of setBackgroundPaint()
void	setEndAngle(double endAngle) Sets the end angle for the gauge as a value in degrees
void	setFaceColor(Color faceColor) Sets the base color of the face of the display
void	setFacePaint(Paint facePaint) Sets the paint to use for filling the face of a Dial.
void	setFrame(DialFrame frame)
void	setNeedleAnimationPeriod(int needleAnimationPeriod)
void	setNeedleAnimationSpeed(double needleAnimationSpeed)
void	setNeedleRenderer(String name, NeedleRenderer renderer) Specify the needle renderer to use with the specified needle
void	setNeedleStyle(String needleName, NeedleStyle style) Specify the style to use with the specified needle
void	setStartAngle(double startAngle) Sets the start angle for the gauge as a value in degrees
void	setTickColor(Color tickColor) Sets the color of the ticks (value markers) in the display
void	setValue(String needleName, Positionable pos, boolean fireUpdate) Set the value of the specified needle on the primary axis
void	update() Update by forcing a re-drawing of the dial face

Methods inherited from class com.jidesoft.gauge.AbstractGauge

createPositionable, drawRotatedStringIfWithinBounds, drawStringIfWithinBounds, gaugeChanged, getAncestorBackground, getBackgroundPaint, getFontComparisonSize, getFontSizeRatio, getModel, getValue, getValue, isAllowTickLabelOverlap, isResizeFonts, isShadowVisible, longestTickLabel, setAllowTickLabelOverlap, setBackgroundPaint, setFontComparisonSize, setFontSizeRatio, setModel, setResizeFonts, setShadowVisible, setValue, setValue, setValue, setValue, setValue, setValue, tickLabelFontForAxis

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, updateUI

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, 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

Methods inherited from interface com.jidesoft.chart.ResizableComponent

addComponentListener

Field Detail

PROPERTY_DIAL_BACKGROUND

public static final String PROPERTY_DIAL_BACKGROUND

See Also:

Constant Field Values

Constructor Detail

Dial

public Dial()

Create a new Dial instance.

Method Detail

getNeedleNames

public List<String> getNeedleNames()

getAnimatedModel

public GaugeModel getAnimatedModel()

setAnimatedModel

public void setAnimatedModel(GaugeModel animatedModel)

getAxis

public DialAxis getAxis()

Returns the primary axis for the dial

Returns:

the primary axis for the dial

setAxis

public void setAxis(DialAxis axis)

Specify the axis to use for the dial. The axis is used to specify properties such as inner and outer radius, fill color and tick style

Parameters:

axis - the DialAxis instance

addAxis

public void addAxis(DialAxis axis)

removeAxis

public void removeAxis(DialAxis axis)

addNeedle

public void addNeedle(String needleName,
                      NeedleStyle style)

Adds a needle and associates it with the specified needle name

Parameters:

needleName - the name of the needle

style - the style to use when displaying the needle

setNeedleStyle

public void setNeedleStyle(String needleName,
                           NeedleStyle style)

Specify the style to use with the specified needle

Parameters:

needleName - the name of the needle

style - the display style associated with the needle

getNeedleStyle

public NeedleStyle getNeedleStyle(String needleName)

Returns the display style associated with the specified needle

Parameters:

needleName - the name of the needle

Returns:

the style associated with the named needle

removeNeedle

public void removeNeedle(String name)

Removes the named needle from the dial

Parameters:

name - the name of the needle to remove

removeNeedles

public void removeNeedles()

Removes all needles from the dial

setNeedleRenderer

public void setNeedleRenderer(String name,
                              NeedleRenderer renderer)

Specify the needle renderer to use with the specified needle

Parameters:

name - the needle whose renderer is being specified

renderer - the renderer

removeNeedleRenderer

public void removeNeedleRenderer(String name)

Remove the renderer associated with the specified needle

Parameters:

name - the name of the needle whose renderer is to be removed

getNeedleRenderer

public NeedleRenderer getNeedleRenderer(String name)

Returns the needle renderer for the specified needle

Parameters:

name - the name of the needle

Returns:

the associated needle renderer

addDrawable

public void addDrawable(Drawable drawable)

Adds a Drawable object to the dial

Parameters:

drawable - the Drawable to add

See Also:

DialIntervalMarker, DialLabel

removeDrawable

public void removeDrawable(Drawable drawable)

Removes the specified Drawable from the dial

Parameters:

drawable - the drawable to remove

removeDrawables

public void removeDrawables()

Removes all Drawables from the dial

isAnimateOnChange

public boolean isAnimateOnChange()

Returns a boolean to indicate whether animation is being used to show needle changes

Returns:

a boolean to indicate whether animation is being used to show needle changes

setAnimateOnChange

public void setAnimateOnChange(boolean animateOnChange)

Specify whether animation should be used to move needles when the value changes. When animation is being used, the needle turns to the new value instead of changing instantly.

Parameters:

animateOnChange - whether to use animation to move needles

getNeedleAnimationSpeed

public double getNeedleAnimationSpeed()

setNeedleAnimationSpeed

public void setNeedleAnimationSpeed(double needleAnimationSpeed)

getNeedleAnimationPeriod

public int getNeedleAnimationPeriod()

setNeedleAnimationPeriod

public void setNeedleAnimationPeriod(int needleAnimationPeriod)

setValue

public void setValue(String needleName,
                     Positionable pos,
                     boolean fireUpdate)

Set the value of the specified needle on the primary axis

Specified by:

setValue in class AbstractGauge<DialAxis>

Parameters:

needleName - the needle whose value we are setting

pos - a Positionable object that carries the value of the needle (and possibly other information too)

fireUpdate - specify whether an update event should be fired on the model

getFaceColor

public Color getFaceColor()

Returns the base color of the face of the display

Returns:

the base color of the face of the display

setFaceColor

public void setFaceColor(Color faceColor)

Sets the base color of the face of the display

Parameters:

faceColor - the new color of the display

getFacePaint

public Paint getFacePaint()

The current Paint used for the face of the Dial.

Returns:

the Paint used for the face of the Dial.

See Also:

setFacePaint(java.awt.Paint)

setFacePaint

public void setFacePaint(Paint facePaint)

Sets the paint to use for filling the face of a Dial.

Note that if you call setFacePaint with an instance of Color, the method derives a Paint based on the Color. If you just want a plain Color, use setFaceColor instead.

Parameters:

facePaint - the paint to use for the fill of the dial face

setDialBackground

public void setDialBackground(Paint background)

Deprecated. in favour of setBackgroundPaint()

Specify the background to use for this dial. This is like the setBackground() method of JComponent, except that you can supply a Paint instance rather than just a Color. This opens up the possibilities with gradient effects.

Parameters:

background - the background Paint

getDialBackground

public Paint getDialBackground()

Deprecated. in favour of getGaugeBackground()

Returns the dial background. If no paint instance has been set by calling setDialBackground() this method returns the value of the inherited method getBackground() instead.

Returns:

the background Paint for the instance.

getTickColor

public Color getTickColor()

Returns:

the color of the ticks

setTickColor

public void setTickColor(Color tickColor)

Sets the color of the ticks (value markers) in the display

Parameters:

tickColor - the new color of the ticks in the display

getStartAngle

public double getStartAngle()

setStartAngle

public void setStartAngle(double startAngle)

Sets the start angle for the gauge as a value in degrees

Parameters:

startAngle - an angle in degrees

getEndAngle

public double getEndAngle()

setEndAngle

public void setEndAngle(double endAngle)

Sets the end angle for the gauge as a value in degrees

Parameters:

endAngle - an angle in degrees

needleAt

public NeedleDescriptor needleAt(Point2D p)

Determines whether there is a needle at the specified pixel position. If there is, the name of the needle is returned

Parameters:

p - the pixel point of enquiry

Returns:

null if no needle is at the pixel point; otherwise a NeedleDescriptor that provides information about the name and shape of the needle.

needlesAt

public Collection<NeedleDescriptor> needlesAt(Point2D p)

Determines which needles, if any, are at the specified pixel position, returning a collection of descriptor objects that describe the needles.

Parameters:

p - the pixel point of interest

Returns:

a collection of NeedleDescriptor objects that specify which needles are at the supplied pixel location

rendered

public NeedleDescriptor rendered(String needleName)

Returns a NeedleDescriptor object for the named needle

Parameters:

needleName - the name of the needle of interest

Returns:

a NeedleDescriptor object for the named needle

getAngle

public Double getAngle(Double value)

Returns the angle of the value on the primary axis

Parameters:

value - the value for which we compute the appropriate angle for drawing

Returns:

an angle in degrees

getAngle

public Double getAngle(DialAxis axis,
                       Double value)

Returns the angle (in degrees) of the value on the supplied axis, or null if the supplied value is null.

Parameters:

axis - the axis context for the supplied value

value - the value for which we compute the appropriate angle for drawing

Returns:

an angle in degrees, or null if the supplied value is null

normalizeAngle

public static double normalizeAngle(double angle)

Reduces an angle value (given in degrees) to a value in the range [0, 360)

Parameters:

angle - an angle in degrees

Returns:

an equivalent angle in degrees but in the range [0, 360)

deriveFacePaint

protected Paint deriveFacePaint(Color faceColor,
                                float x,
                                float y,
                                float radius)

calculatePixelPoint2D

protected Point2D calculatePixelPoint2D(DialAxis axis,
                                        double axisValue)

Specified by:

calculatePixelPoint2D in class AbstractGauge<DialAxis>

getFrame

public DialFrame getFrame()

setFrame

public void setFrame(DialFrame frame)

getRadius

public float getRadius()

Returns a radius in pixels

Returns:

the radius in pixels

getPivotX

public int getPivotX()

getPivotY

public int getPivotY()

update

public void update()

Update by forcing a re-drawing of the dial face

paintComponent

public void paintComponent(Graphics g)

The main method for painting the display

Overrides:

paintComponent in class JComponent

createSegment

public GeneralPath createSegment(double fromAngle,
                                 double toAngle,
                                 double innerRadius,
                                 double outerRadius)