org.deepsymmetry.beatlink.data

Class WaveformDetailComponent

java.lang.Object

java.awt.Component

java.awt.Container

javax.swing.JComponent

org.deepsymmetry.beatlink.data.WaveformDetailComponent

All Implemented Interfaces:

ImageObserver, MenuContainer, Serializable

public class WaveformDetailComponent
extends JComponent

Provides a convenient way to draw waveform detail in a user interface, including annotations like the location at the current time, and cue point markers (if you supply TrackMetadata so their location can be determined), and beat markers (if you also supply a BeatGrid). Can also be configured to automatically update itself to reflect the state of a specified player, showing the current track, playback state, and position, as long as it is able to load appropriate metadata.

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

Fields inherited from class javax.swing.JComponent

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

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

Constructors

Constructor and Description
WaveformDetailComponent(int player) Create a view which updates itself to reflect the track loaded on a particular player, and that player's playback progress.
WaveformDetailComponent(WaveformDetail waveform, CueList cueList, BeatGrid beatGrid) Create a view which draws a specific waveform, even if it is not currently loaded in a player.
WaveformDetailComponent(WaveformDetail waveform, TrackMetadata metadata, BeatGrid beatGrid) Create a view which draws a specific waveform, even if it is not currently loaded in a player.

Method Summary

Modifier and Type	Method and Description
void	clearPlaybackState() Removes all stored playback state.
void	clearPlaybackState(int player) Clear the playback state stored for a player, such as when it has unloaded the track.
static Color	cueColor(CueList.Entry entry) Determine the color to use to draw a cue list entry.
boolean	getAutoScroll() Check whether the component should automatically center itself on the playback position of the player that is furthest into the track.
int	getBeatForX(int x) Determine the beat that corresponds to a particular X coordinate in the component, given the current scale.
long	getFurthestPlaybackPosition() Look up the furthest position, in milliseconds, that has been reached, giving playing players priority over stopped players.
PlaybackState	getFurthestPlaybackState() Look up the playback state that has reached furthest in the track, but give playing players priority over stopped players.
Dimension	getMinimumSize()
int	getMonitoredPlayer() See which player is having its state tracked automatically by the component, if any.
Set<PlaybackState>	getPlaybackState() Look up all recorded playback state information.
PlaybackState	getPlaybackState(int player) Look up the playback state recorded for a particular player.
Dimension	getPreferredSize()
long	getTimeForX(int x) Determine the playback time that corresponds to a particular X coordinate in the component given the current scale.
int	getXForBeat(int beat) Determine the X coordinate within the component at which the specified beat begins.
int	millisecondsToX(long milliseconds) Converts a time in milliseconds to the appropriate x coordinate for drawing something at that time.
protected void	paintComponent(Graphics g)
void	setAutoScroll(boolean auto) Control whether the component should automatically center itself on the playback position of the player that is furthest into the track.
void	setMonitoredPlayer(int player) Configures the player whose current track waveforms and status will automatically be reflected.
void	setOverlayPainter(OverlayPainter painter) Arrange for an overlay to be painted on top of the component.
void	setPlaybackState(int player, long position, boolean playing) Set the current playback state for a player.
void	setScale(int scale) Set the zoom scale of the view.
void	setWaveform(WaveformDetail waveform, CueList cueList, BeatGrid beatGrid) Change the waveform preview being drawn.
void	setWaveform(WaveformDetail waveform, TrackMetadata metadata, BeatGrid beatGrid) Change the waveform preview being drawn.
String	toString()

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, 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, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getUIClassID, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, 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, 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, getAccessibleContext, 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, 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, transferFocus, transferFocusBackward, transferFocusUpCycle

Methods inherited from class java.lang.Object

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

Constructor Detail

WaveformDetailComponent

public WaveformDetailComponent(int player)

Create a view which updates itself to reflect the track loaded on a particular player, and that player's playback progress.

Parameters:

player - the player number to monitor, or zero if it should start out monitoring no player

WaveformDetailComponent

public WaveformDetailComponent(WaveformDetail waveform,
                               TrackMetadata metadata,
                               BeatGrid beatGrid)

Create a view which draws a specific waveform, even if it is not currently loaded in a player.

Parameters:

waveform - the waveform detail to display

metadata - information about the track whose waveform we are drawing, so we can draw cues and memory points

beatGrid - the locations of the beats, so they can be drawn

WaveformDetailComponent

public WaveformDetailComponent(WaveformDetail waveform,
                               CueList cueList,
                               BeatGrid beatGrid)

Create a view which draws a specific waveform, even if it is not currently loaded in a player.

Parameters:

waveform - the waveform detail to display

cueList - used to draw cues and memory points

beatGrid - the locations of the beats, so they can be drawn

Method Detail

setAutoScroll

public void setAutoScroll(boolean auto)

Control whether the component should automatically center itself on the playback position of the player that is furthest into the track. This is the default behavior of the component, and will allow it to be useful at any size, showing a currently-relevant portion of the waveform. If set to false the component must be inside a scroll pane so the user can control what portion of the waveform is visible.

Parameters:

auto - should the waveform be centered on the playback position

getAutoScroll

public boolean getAutoScroll()

Check whether the component should automatically center itself on the playback position of the player that is furthest into the track. This is the default behavior of the component, and will allow it to be useful at any size, showing a currently-relevant portion of the waveform. If set to false the component must be inside a scroll pane so the user can control what portion of the waveform is visible.

Returns:

true if the waveform will be centered on the playback position

setOverlayPainter

public void setOverlayPainter(OverlayPainter painter)

Arrange for an overlay to be painted on top of the component.

Parameters:

painter - if not null, its OverlayPainter.paintOverlay(Component, Graphics) method will be called once this component has done its own painting

setPlaybackState

public void setPlaybackState(int player,
                             long position,
                             boolean playing)

Set the current playback state for a player. Will cause part of the component to be redrawn if the player state has changed (and we have the TrackMetadata we need to translate the time into a position in the component). This will be quickly overruled if a player is being monitored, but can be used in other contexts.

Parameters:

player - the player number whose playback state is being recorded

position - the current playback position of that player in milliseconds

playing - whether the player is actively playing the track

Throws:

IllegalStateException - if the component is configured to monitor a player, and this is called with state for a different player

IllegalArgumentException - if player is less than one

Since:

0.5.0

clearPlaybackState

public void clearPlaybackState(int player)

Clear the playback state stored for a player, such as when it has unloaded the track.

Parameters:

player - the player number whose playback state is no longer valid

Since:

0.5.0

clearPlaybackState

public void clearPlaybackState()

Removes all stored playback state.

Since:

0.5.0

getPlaybackState

public PlaybackState getPlaybackState(int player)

Look up the playback state recorded for a particular player.

Parameters:

player - the player number whose playback state information is desired

Returns:

the corresponding playback state, if any has been stored

Since:

0.5.0

getPlaybackState

public Set<PlaybackState> getPlaybackState()

Look up all recorded playback state information.

Returns:

the playback state recorded for any player

Since:

0.5.0

setScale

public void setScale(int scale)

Set the zoom scale of the view. a value of 1 (the smallest allowed) draws the waveform at full scale. Larger values combine more and more segments into a single column of pixels, zooming out to see more at once.

Parameters:

scale - the number of waveform segments that should be averaged into a single column of pixels

Throws:

IllegalArgumentException - if scale is less than 1 or greater than 256

setWaveform

public void setWaveform(WaveformDetail waveform,
                        TrackMetadata metadata,
                        BeatGrid beatGrid)

Change the waveform preview being drawn. This will be quickly overruled if a player is being monitored, but can be used in other contexts.

Parameters:

waveform - the waveform detail to display

metadata - information about the track whose waveform we are drawing, so we can draw cue and memory points

beatGrid - the locations of the beats, so they can be drawn

setWaveform

public void setWaveform(WaveformDetail waveform,
                        CueList cueList,
                        BeatGrid beatGrid)

Change the waveform preview being drawn. This will be quickly overruled if a player is being monitored, but can be used in other contexts.

Parameters:

waveform - the waveform detail to display

cueList - used to draw cue and memory points

beatGrid - the locations of the beats, so they can be drawn

setMonitoredPlayer

public void setMonitoredPlayer(int player)

Configures the player whose current track waveforms and status will automatically be reflected. Whenever a new track is loaded on that player, the waveform and metadata will be updated, and the current playback position and state of the player will be reflected by the component.

Parameters:

player - the player number to monitor, or zero if monitoring should stop

getMonitoredPlayer

public int getMonitoredPlayer()

See which player is having its state tracked automatically by the component, if any.

Returns:

the player number being monitored, or zero if none

getMinimumSize

public Dimension getMinimumSize()

Overrides:

getMinimumSize in class JComponent

getPreferredSize

public Dimension getPreferredSize()

Overrides:

getPreferredSize in class JComponent

getFurthestPlaybackState

public PlaybackState getFurthestPlaybackState()

Look up the playback state that has reached furthest in the track, but give playing players priority over stopped players. This is used to choose the scroll center when auto-scrolling is active.

Returns:

the playback state, if any, with the highest playing PlaybackState.position value

getFurthestPlaybackPosition

public long getFurthestPlaybackPosition()

Look up the furthest position, in milliseconds, that has been reached, giving playing players priority over stopped players. If there are no playback positions, returns 0.

Returns:

The position in milliseconds of the furthest playback state reached, or 0 if there are no playback states

getTimeForX

public long getTimeForX(int x)

Determine the playback time that corresponds to a particular X coordinate in the component given the current scale.

Parameters:

x - the horizontal position within the component coordinate space

Returns:

the number of milliseconds into the track this would correspond to (may fall outside the actual track)

getBeatForX

public int getBeatForX(int x)

Determine the beat that corresponds to a particular X coordinate in the component, given the current scale. Clicks past the end of the track will return the final beat, clicks before the first beat (or if there is no beat grid) will return -1.

Parameters:

x - the horizontal position within the component coordinate space

Returns:

the beat number being played at that point, or -1 if the point is before the first beat

getXForBeat

public int getXForBeat(int beat)

Determine the X coordinate within the component at which the specified beat begins.

Parameters:

beat - the beat number whose position is desired

Returns:

the horizontal position within the component coordinate space where that beat begins

Throws:

IllegalArgumentException - if the beat number exceeds the number of beats in the track.

millisecondsToX

public int millisecondsToX(long milliseconds)

Converts a time in milliseconds to the appropriate x coordinate for drawing something at that time.

Parameters:

milliseconds - the time at which something should be drawn

Returns:

the component x coordinate at which it should be drawn

cueColor

public static Color cueColor(CueList.Entry entry)

Determine the color to use to draw a cue list entry. Hot cues are green, ordinary memory points are red, and loops are orange.

Parameters:

entry - the entry being drawn

Returns:

the color with which it should be represented.

paintComponent

protected void paintComponent(Graphics g)

Overrides:

paintComponent in class JComponent

toString

public String toString()

Overrides:

toString in class Component