# 9

# JCArrowButton

Introduction · Sample Program Code · Specifying JCArrowButton Actions

Sizing the Arrow · Arrow Button Orientation · Button Sensitivity

Property Listing · Example Program

## Introduction

`JCArrowButton` is a component used in other GUI components, like `JCTabManager`, `JCScrollbar` and `JCComboBox`. Much like `JCSeparator`, `JCArrowButton` is more typically added to function within other components (like `JCScrollbar`) rather than function on its own.

`JCArrowButton` displays a simple arrow button that can be clicked by a user. It can be oriented in any one of four different directions. It has no independent function, though it passes an action event to the program when it is clicked by the user.

The following figure shows typical `JCArrowButton`s incorporated within two separate `JCScrollbar`s.

Two JCScrollbars displaying inactive and active JCArrowButtons respectively

This illustration also demonstrates that `JCArrowButton`s are displayed in one of two states: inactive and active.

There is no direct equivalent to `JCArrowButton`s in the Java Development Kit (JDK); while arrow buttons are added to AWT components like `Scrollbar`, they are not directly configurable, and cannot be accessed for use independently of the parent component. `JCArrowButtons` can be added to programs or other components of your own construction.

`JCArrowButton` conforms to standard Windows 95 "look and feel" and behavior. It shares much of the behavior and characteristics of JClass BWT's `JCButton`.

#### Behavior

`JCArrowButton` behaves in the following manner:

- before a button is pressed, it appears raised with respect to the rest of the display. When a button is pressed, it appears depressed
- when the button is pressed, its shadows are reversed to display the "pushed" appearance
- if the button is pressed, and the mouse is dragged outside the button area and subsequently released, no action event is called
- if the mouse is pressed and then released within the button, the button is activated (an event is generated)
- if the ENTER or SPACE BAR key is depressed by the user while it has focus, the button is depressed. It is equivalent to clicking on a button with the mouse.
- unlike a `JCButton`, `JCArrowButton` is typically set so that a continuous stream of action events occur if the `JCArrowButton` remains depressed after a predetermined amount of time, rather than when it is released.

#### Keyboard Traversal

When a `JCArrowButton` has focus (note that focus is not visible), pressing either the ENTER key or the SPACE BAR activates the arrow button (i.e. it is depressed). If the component that contains two `JCArrowButton`s has focus, the cursor keys will shift focus from one `JCArrowButton` to the other. Clicking the ENTER key or the SPACE BAR activates the arrow button.

## Sample Program Code

The following code fragment shows how to insert a `JCArrowButton` navigator window for the scrolledWindow.class example file:

    public class scrolledWindow implements JCActionListener {
    public void actionPerformed(JCActionEvent ev) {
            JCArrowButton btn = (JCArrowButton) ev.getSource();
            ...
    }
            JCArrowButton arrow[] = new JCArrowButton[4];
            int orient[] = { BWTEnum.UP, BWTEnum.LEFT, BWTEnum.RIGHT,
    						BWTEnum.DOWN };
            for (int i=0; i < 4; i++) {
                    arrow[i] = new JCArrowButton(orient[i]);
                    arrow[i].addActionListener(this);
                    arrow[i].setInitialRepeatDelay(50);
            }

This code creates a navigational window with four `JCArrowButton`s, as illustrated in the following image:

Four JCArrowButtons in a separate navigational window

The sample code used in these examples are incorporated into the files arrowButton .class and button.class provided with JClass BWT. For information on how to run these programs, see the " Example Program " section at the end of this chapter.

## Specifying JCArrowButton Actions

`JCArrowButton` enables you to control or read its actions. When a user clicks an `JCArrowButton`, the image on the `JCArrowButton` appears depressed, as depicted in the following illustration:

JCArrowButtons in a regular and a depressed state

The second of the two arrow buttons depicted in the previous illustration shows a button that has been clicked and has not yet been released. This causes a change of state in the arrow button, and causes the image of the button to appear depressed.

To programmatically display the button as pressed, call `armAction`. To display the button in its normal state, call `disarmAction`.

Unlike `JCButton`, the image of the arrow cannot be replaced by a JCString.

## Sizing the Arrow

The `setArrowSize` method is used to set the value for the arrow's size. By default the dimensions of a vertical arrow (either up or down) is 7 x 4 pixels, and 4 x 7 pixels for a horizontal arrow (either left or right).

## Arrow Button Orientation

The orientation of a `JCArrowButton` is set within the initial constructor. By default, a down-pointing arrow is created. The `Orientation` method can also be used to set a `JCArrowButton`'s orientation. `Orientation` can take one of four values: `DOWN` (default), `UP`, `LEFT`, or `RIGHT`.

## Button Sensitivity

Unlike a `JCButton`, in most cases it is desirable for an action event to be sent if a `JCArrowButton` remains depressed after a predetermined amount of time rather than when it is released. Standard Windows 95 behavior dictates that when an arrow button remains depressed after a predetermined time, it is because the user is indicating to the program to repeat the action initiated by the arrow button. For example, if a `JCArrowButton` is part of a navigational bar and the user holds down an up-arrow, the user is telling the program to continue moving a visible display in the desired direction until the button is released. The amount of time the `JCArrowButton` must be depressed before sending an action event is determined by `InitialRepeatDelay`.

`InitialRepeatDelay` sets the time in milliseconds to wait before sending continuous button press events when the button has been pressed and is continually held down. If set to `MAXINT` (default), events are not sent after the button is pressed. When set, it activates `run`, which sends the continual `mouseUp` events.

A reasonable `InitialRepeatDelay value` is 50 milliseconds, which is the default value used in Windows 95 programs.

## Property Listing

The following summarizes the properties of `JCArrowButton`. Complete reference documentation is available online in standard javadoc format in jclass.bwt.JCArrowButton.html.

### jclass.bwt.JCArrowButton

Name | Method | Inherited from
--- | --- | ---
ArrowSize | setArrowSize | `jclass.bwt.JCArrowButton`
`Background` | `setBackground` | `jclass.bwt.JCComponent`
`DoubleBuffer` | `setDoubleBuffer` | `jclass.bwt.JCComponent`
`HighlightThickness` | `setHighlightThickness` | `jclass.bwt.JCComponent`
`InitialRepeatDelay` | `setInitialRepeatDelay` | `jclass.bwt.JCArrowButton`
`Insets` | `setInsets` | `jclass.bwt.JCComponent`
Orientation | setOrientation | `jclass.bwt.JCArrowButton`
`PreferredSize` | `setPreferredSize` | `jclass.bwt.JCComponent`
`ShadowThickness` | `setShadowThickness` | `jclass.bwt.JCComponent`
`Traversable` | `setTraversable` | `jclass.bwt.JCComponent`
UserData | setUserData | `jclass.bwt.JCComponent`

## Example Program

Demonstration programs and example code containing `JCArrowButton` come with JClass BWT. `JCArrowButton` is also incorporated programmatically within other JClass BWT components, including `JCScrollbar` and `JCSpinBox`. The example (part of the `JCScrolledWindow` example) can be viewed in applet form by launching index.html within the /jclass/bwt/examples directory. scrolledWindow.class can also be run as a stand-alone Java application from the command prompt by typing:

    	java jclass.bwt.examples.scrolledWindow