6.2 The JScrollBar Class

JScrollBar is the Swing implementation of a scrollbar. The JScrollBar class is shown in various L&Fs in Figure 6-3.

Figure 6-3. Scrollbars in several L&Fs

To program with a scrollbar, it is important to understand its anatomy. Scrollbars are composed of a rectangular tab, called a slider or thumb, located between two arrow buttons. The arrow buttons on either end increment or decrement the slider's position by an adjustable number of units, generally one. In addition, clicking in the area between the thumb and the end buttons (often called the paging area) moves the slider one block, or 10 units by default. The user can modify the value of the scrollbar in one of three ways: by dragging the thumb in either direction, by pushing on either of the arrow buttons, or by clicking in the paging area.

Scrollbars can have one of two orientations: horizontal or vertical. Figure 6-4 provides an illustration of a horizontal scrollbar. JScrollBar uses the bounded-range model to represent the scrollbar's data. The assignment of each bounded-range property is also shown in Figure 6-5. The minimum and maximum of the scrollbar fall on the interior edges of the arrow buttons. The scrollbar's value is defined as the left (or top) edge of the slider. Finally, the extent of the scrollbar defines the width of the thumb in relation to the total range. (The older Adjustable interface from the java.awt package referred to the extent as the "visible amount.") Note that horizontal scrollbars increment to the right and vertical scrollbars increment downward.

Figure 6-4. Anatomy of a horizontal scrollbar

Figure 6-5. JScrollBar class diagram

6.2.1 Properties

Table 6-3 shows the properties of the JScrollBar component. Most of these properties come from the java.awt.Adjustable interface. The orientation property gives the direction of the scrollbar, either JScrollBar.HORIZONTAL or JScrollBar.VERTICAL. The unitIncrement property represents the integer amount by which the bounded-range value changes when the user clicks on either of the arrow buttons. The blockIncrement property represents the integer amount by which the scrollbar value changes when the user clicks in either of the paging areas. The enabled property indicates whether the scrollbar can generate or respond to events. The minimum , maximum, value, and valueIsAdjusting properties match the equivalent properties in the BoundedRangeModel of the scrollbar. The visibleAmount property matches the extent property in the model; it indicates the thickness of the thumb. The minimumSize and maximumSize properties allow the scrollbar to behave appropriately when it is resized.

Table 6-3. JScrollBar properties
Property	Data type	get	set	Default value
accessibleContext^o	AccessibleContext	·		`JScrollBarAccessibleJ-ScrollBar( )`
adjustment-Listeners^1.4	Adjustment-Listener[]	·		Empty array
blockIncrement^{b, o, *}	int	·	·	`10`
enabled^o	boolean		·	`true`
maximum^o	int	·	·	`100`
maximumSize^o	Dimension	·
minimum^o	int	·	·	`0`
minimumSize^o	Dimension	·
model^b	BoundedRangeModel	·	·	`DefaultBoundedRangeModel( )`
orientation^{b, o}	int	·	·	`JScrollBar.VERTICAL`
UI^{b, o}	ScrollBarUI	·	·	From L&F
UIClassID^o	String	·		`"ScrollBarUI"`
unitIncrement^{b, o, *}	int	·	·	`1`
value^o	int	·	·	`0`
valueIsAdjusting	boolean	·	·	`false`
visibleAmount^o	int	·	·	`10`
^1.4since 1.4, ^bbound, ^ooverridden, *indexed version (on direction) also available See also the properties of the `JComponent` class (Table 3-6).

6.2.2 Events

JScrollBar objects trigger java.awt.event.AdjustmentEvents whenever the component undergoes a change. Recall, however, that the bounded-range model generates a ChangeEvent when one of its properties changes. It becomes the responsibility of the JScrollBar class to convert change events to adjustment events and pass them on to registered listeners. Figure 6-6 shows the sequence of events between the component, model, and delegate when the user drags the scrollbar. JScrollBar also generates a PropertyChangeEvent when any of its bound properties change.

Figure 6-6. Chain of events after the user drags the scrollbar

Because JScrollBar was meant as a drop-in replacement for the AWT scrollbar, the older event system has been preserved to maintain consistency with the AWT 1.1 Adjustable interface. However, with Swing, the majority of cases in which you would have used a scrollbar have been taken care of with the JScrollPane class. You rarely need a standalone JScrollBar. (See Chapter 11 for more information on JScrollPane.)

The following methods are defined in the JScrollBar class:

public void addAdjustmentListener(AdjustmentListener l)
public void removeAdjustmentListener(AdjustmentListener l): Add or remove a specific listener for AdjustmentEvents from the scrollbar.

6.2.3 Constructors

public JScrollBar( )
public JScrollBar(int orientation)
public JScrollBar(int orientation, int value, int extent, int minimum, int maximum): Set the initial values of the scrollbar. If either of the first two constructors is invoked, the scrollbar initializes itself using the default values shown in Table 6-3. The orientation must be either JScrollBar.HORIZONTAL or JScrollBar.VERTICAL, or else the constructor throws a runtime IllegalArgumentException. If desired, the last four parameters in the third constructor can be used to initialize the scrollbar's bounded-range model to new values.

6.2.4 Miscellaneous

public int getUnitIncrement(int direction)
public int getBlockIncrement(int direction): Convenience methods that return the scrollbar unit and block increments for a particular direction. The direction is -1 for down and left, and 1 for up and right. These methods are typically invoked by the UI delegate to determine how far to increment in a particular direction. Subclasses can override these methods to specify the units to increment in either direction, based on the content represented. For example, if a scrollbar was attached to a word-processing document, the variable-sized text in the document could result in different unit increments at any particular time for a vertical scrollbar.
public void setValues(int newValue, int newExtent, int newMinimum, int newMaximum): This method maps to the setRangeValues( ) method in the BoundedRangeModel interface.

6.2.5 Handling Events from a Scrollbar

The following program demonstrates how to monitor events generated by a pair of scrollbars:

// ScrollBarExample.java // import java.awt.*; import java.awt.event.*; import javax.swing.*; public class ScrollBarExample extends JPanel {     JLabel label;     public ScrollBarExample( ) {         super(true);         label=new JLabel( );         setLayout(new BorderLayout( ));         JScrollBar hbar=new JScrollBar(JScrollBar.HORIZONTAL, 30, 20, 0, 300);         JScrollBar vbar=new JScrollBar(JScrollBar.VERTICAL, 30, 40, 0, 300);         hbar.setUnitIncrement(2);         hbar.setBlockIncrement(1);         hbar.addAdjustmentListener(new MyAdjustmentListener( ));         vbar.addAdjustmentListener(new MyAdjustmentListener( ));         add(hbar, BorderLayout.SOUTH);         add(vbar, BorderLayout.EAST);         add(label, BorderLayout.CENTER);     }     class MyAdjustmentListener implements AdjustmentListener {         public void adjustmentValueChanged(AdjustmentEvent e) {            label.setText("    New Value is " + e.getValue( ) + "      ");            repaint( );         }     }     public static void main(String s[]) {          JFrame frame = new JFrame("Scroll Bar Example");          frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);          frame.setContentPane(new ScrollBarExample( ));          frame.setSize(200,200);          frame.setVisible(true);     } }

The code is relatively easy to follow. The application creates a single panel and adds two scrollbars, one on the right side and one on the bottom. It then listens for any adjustments in either scrollbar and paints the scrollbar's new value in the middle of the panel. Figure 6-7 shows the result.

Figure 6-7. A simple scrollbar example