sos.marker
Class JMarkerBar

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              sos.marker.JMarkerBar

All Implemented Interfaces:

java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, javax.accessibility.Accessible

public class JMarkerBar
extends javax.swing.JComponent
implements javax.accessibility.Accessible

A Swing component that draws a stripe of markers, often used next to a scroll bar to mark locations of errors, bookmarks, or search results.

A JMarkerBar can be laid out vertically or horizontally. The orientation and (possibly) component orientation control the direction the marker bar is laid out. See setOrientation(int) for more information.

The marker bar gets its markers from a javax.swing.ListModel that returns objects that implement the Marker interface. The marker bar uses a MarkerRenderer to draw its markers. If one is not set with setMarkerRenderer, then the pluggable look-and-feel delegate installs an instance of DefaultMarkerRenderer, which renders each marker as a rectangle.

When a marker is clicked, a java.awt.event.ActionEvent is sent to all registered action listeners. A listener can determine the clicked marker by invoking getClickedIndex() and then perform the desired action. A common action is to scroll an accompanying scroll pane to the location represented by the clicked index. See Utility.scrollToMarker(javax.swing.JComponent, sos.marker.JMarkerBar, int) for a helper method.

For more information on how to use and customize a JMarkerBar, see Side of Software's online tutorial.

Since:

1.0

Nested Class Summary

protected class

JMarkerBar.AccessibleJMarkerBar Accessibility support for a JMarkerBar.

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.BltBufferStrategy, java.awt.Component.FlipBufferStrategy

Field Summary

static int	LINE_AXIS An orientation value that means the markers are laid out in the direction that text flows across lines, according to the component's ComponentOrientation property.
static int	PAGE_AXIS An orientation value that means the markers are laid out in the direction that lines flow across a page, according to the component's ComponentOrientation property.
static int	X_AXIS An orientation value that means the markers are laid out horizontally.
static int	Y_AXIS An orientation value that means the markers are laid out vertically.

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

JMarkerBar()
Creates a JMarkerBar with no markers.

JMarkerBar(java.util.List<?> markers)
Creates a JMarkerBar with a list of markers.

JMarkerBar(javax.swing.ListModel markerModel)
Creates a JMarkerBar with the specified marker model.

JMarkerBar(Marker[] markers)
Creates a JMarkerBar with an array of markers.

Method Summary

void	addActionListener(java.awt.event.ActionListener actionListener) Registers an action listener with this marker bar.
void	fireActionEvent() Creates an ActionEvent and notifies registered action listeners.
javax.accessibility.AccessibleContext	getAccessibleContext() Gets the AccessibleContext associated with this JMarkerBar.
java.awt.event.ActionListener[]	getActionListeners() Returns an array of ActionListeners that were registered with this marker bar via addActionListener.
int	getClickedIndex() Returns the index of the last marker clicked.
java.awt.Rectangle	getMarkerBounds(int markerIndex) Returns the bounds of the drawn marker at the specified index.
MarkerRenderer	getMarkerRenderer() Returns the object that renders this bar's markers.
javax.swing.ListModel	getModel() Returns the model that supplies the markers to this marker bar.
int	getOrientation() Returns this marker bar's orientation.
java.lang.String	getToolTipText(java.awt.event.MouseEvent e) Returns the string to be used as the tooltip for the specified event.
MarkerBarUI	getUI() Returns the look and feel delegate that renders this object.
java.lang.String	getUIClassID() Returns the UIDefaults key used to look up the name of the swing.plaf.ComponentUI class that defines the look and feel for this component.
int[]	locationToIndices(java.awt.Point point) Returns an array of marker indices that are rendered at the specified point.
void	removeActionListener(java.awt.event.ActionListener actionListener) Unregisters the specified action listener, so that it no longer is notified when markers are clicked.
void	setClickedIndex(int markerIndex) Sets the index of the last marker clicked and fires an action event.
void	setMarkerRenderer(MarkerRenderer markerRenderer) Sets the object responsible for painting the markers in this marker bar.
void	setModel(javax.swing.ListModel markerModel) Sets the underlying model from which this marker bar gets its markers.
void	setOrientation(int orientation) Sets the orientation of this marker bar.
void	setUI(MarkerBarUI newUI) Sets the look and feel delegate for this marker bar.
void	updateUI() Resets the UI property with the value from the current look and feel.

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, 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, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, 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, 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

Field Detail

X_AXIS

public static final int X_AXIS

An orientation value that means the markers are laid out horizontally.

See Also:

Y_AXIS, getOrientation(), setOrientation(int), Constant Field Values

Y_AXIS

public static final int Y_AXIS

An orientation value that means the markers are laid out vertically.

See Also:

X_AXIS, getOrientation(), setOrientation(int), Constant Field Values

LINE_AXIS

public static final int LINE_AXIS

An orientation value that means the markers are laid out in the direction that text flows across lines, according to the component's ComponentOrientation property.

See Also:

PAGE_AXIS, getOrientation(), setOrientation(int), Constant Field Values

PAGE_AXIS

public static final int PAGE_AXIS

An orientation value that means the markers are laid out in the direction that lines flow across a page, according to the component's ComponentOrientation property.

See Also:

LINE_AXIS, getOrientation(), setOrientation(int), Constant Field Values

Constructor Detail

JMarkerBar

public JMarkerBar()

Creates a JMarkerBar with no markers. The JMarkerBar's orientation is set to PAGE_AXIS.

JMarkerBar

public JMarkerBar(Marker[] markers)

Creates a JMarkerBar with an array of markers. Each element of the array should be non-null. Subsequent changes to the array may result in undefined marker bar behavior. The JMarkerBar's orientation is set to PAGE_AXIS.

Parameters:

markers - array of markers to use as the underlying marker model

JMarkerBar

public JMarkerBar(java.util.List<?> markers)

Creates a JMarkerBar with a list of markers. Each element of the list should implement the Marker interface. Subsequent changes to the array may result in undefined marker bar behavior. The JMarkerBar's orientation is set to PAGE_AXIS.

Parameters:

markers - list of markers to use as the underlying marker model

JMarkerBar

public JMarkerBar(javax.swing.ListModel markerModel)

Creates a JMarkerBar with the specified marker model. The supplied ListModel must return from its getElementAt method objects that implement Marker. The JMarkerBar's orientation is set to PAGE_AXIS.

Parameters:

markerModel - the underlying marker model

Throws:

java.lang.IllegalArgumentException - if markerModel is null

Method Detail

addActionListener

public void addActionListener(java.awt.event.ActionListener actionListener)

Registers an action listener with this marker bar. Registered action listeners get notified when a marker is acted upon, or clicked.

Parameters:

actionListener - listener to be registered

See Also:

getActionListeners(), removeActionListener(java.awt.event.ActionListener)

fireActionEvent

public void fireActionEvent()

Creates an ActionEvent and notifies registered action listeners. The event will have the command "markerClicked".

getAccessibleContext

public javax.accessibility.AccessibleContext getAccessibleContext()

Gets the AccessibleContext associated with this JMarkerBar.

Specified by:

getAccessibleContext in interface javax.accessibility.Accessible

Overrides:

getAccessibleContext in class javax.swing.JComponent

Returns:

the AccessibleContext associated with this JMarkerBar

getActionListeners

public java.awt.event.ActionListener[] getActionListeners()

Returns an array of ActionListeners that were registered with this marker bar via addActionListener.

Returns:

an array of registered action listeners

See Also:

addActionListener(java.awt.event.ActionListener)

getClickedIndex

public int getClickedIndex()

Returns the index of the last marker clicked. Action listeners often fetch this value to determine the source of the event.

Returns:

the index of the last marker clicked

getOrientation

public int getOrientation()

Returns this marker bar's orientation.

Returns:

one of PAGE_AXIS, LINE_AXIS, X_AXIS, and Y_AXIS

See Also:

setOrientation(int), PAGE_AXIS, LINE_AXIS, Y_AXIS, X_AXIS

getMarkerBounds

public java.awt.Rectangle getMarkerBounds(int markerIndex)

Returns the bounds of the drawn marker at the specified index. The bounds are in this marker bar's coordinate system.

Parameters:

markerIndex - the index of the marker in question

Returns:

the bounds of the drawn marker at markerIndex, or null if the index is out of bounds or if there is no installed MarkerBarUI

getMarkerRenderer

public MarkerRenderer getMarkerRenderer()

Returns the object that renders this bar's markers.

Returns:

the object responsible for rendering the markers

See Also:

setMarkerRenderer(sos.marker.MarkerRenderer)

getModel

public javax.swing.ListModel getModel()

Returns the model that supplies the markers to this marker bar.

Returns:

the underlying list of markers

See Also:

setModel(javax.swing.ListModel)

getToolTipText

public java.lang.String getToolTipText(java.awt.event.MouseEvent e)

Returns the string to be used as the tooltip for the specified event. This implementation will attempt to fetch the tooltip text from the Component that renders the topmost marker at the location of the event.

Overrides:

getToolTipText in class javax.swing.JComponent

Parameters:

e - event for which the tooltip is requested (may be null)

Returns:

the tooltip text (may be null)

getUI

public MarkerBarUI getUI()

Returns the look and feel delegate that renders this object.

Returns:

the UI for this marker bar

getUIClassID

public java.lang.String getUIClassID()

Returns the UIDefaults key used to look up the name of the swing.plaf.ComponentUI class that defines the look and feel for this component.

Overrides:

getUIClassID in class javax.swing.JComponent

Returns:

the UIDefaults key for a ComponentUI subclass

locationToIndices

public int[] locationToIndices(java.awt.Point point)

Returns an array of marker indices that are rendered at the specified point. The markers are rendered in the order given by the returned array.

Parameters:

point - x,y location in the marker bar's coordinate system

Returns:

the marker indices rendered at point, or null if there is no MarkerBarUI installed

removeActionListener

public void removeActionListener(java.awt.event.ActionListener actionListener)

Unregisters the specified action listener, so that it no longer is notified when markers are clicked.

Parameters:

actionListener - listener to unregister

setClickedIndex

public void setClickedIndex(int markerIndex)

Sets the index of the last marker clicked and fires an action event. Typically the pluggable look-and-feel UI delegate invokes this method in response to a mouse click on a marker, but clients may programmatically simulate a clicked marker by invoking this method.

Parameters:

markerIndex - index of the marker that was clicked

See Also:

getClickedIndex()

setOrientation

public void setOrientation(int orientation)

Sets the orientation of this marker bar. The marker bar will be laid out vertically if its layout orientation is Y_AXIS, if its orientation is PAGE_AXIS and its component orientation is horizontal, or if its orientation is LINE_AXIS and its component orientation is not horizontal.

This is a bound property; a property change event for "orientation" is sent.

Parameters:

orientation - PAGE_AXIS, LINE_AXIS, Y_AXIS, or X_AXIS

Throws:

java.lang.IllegalArgumentException - if orientation is not one of PAGE_AXIS, LINE_AXIS, X_AXIS, or Y_AXIS

See Also:

getOrientation(), PAGE_AXIS, LINE_AXIS, Y_AXIS, X_AXIS

setMarkerRenderer

public void setMarkerRenderer(MarkerRenderer markerRenderer)

Sets the object responsible for painting the markers in this marker bar.

Parameters:

markerRenderer - object to render the markers

See Also:

getMarkerRenderer()

setModel

public void setModel(javax.swing.ListModel markerModel)

Sets the underlying model from which this marker bar gets its markers. The supplied ListModel must return from its getElementAt method objects that implement Marker.

This is a bound property; a property change event for "model" is sent.

Parameters:

markerModel - the list of markers

Throws:

java.lang.IllegalArgumentException - if markerModel is null

See Also:

getModel(), Marker

setUI

public void setUI(MarkerBarUI newUI)

Sets the look and feel delegate for this marker bar.

Parameters:

newUI - the new UI delegate

updateUI

public void updateUI()

Resets the UI property with the value from the current look and feel.

Overrides:

updateUI in class javax.swing.JComponent