8
JCArrowButton

Introduction · Sample Program Code · Specifying JCArrowButton Actions

Sizing the Arrow · Arrow Button Orientation · Button Sensitivity

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 JCArrowButtons incorporated within two separate JCScrollbars.

Two JCScrollbars displaying inactive and active JCArrowButtons respectively

This illustration also displays that JCArrowButtons are displayed in one of two states: inactive and active.

There is no direct equivalent to JCArrowButtons 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 then the mouse is dragged outside the button 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 RETURN or space 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 JCArrowButtons, 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 program, 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 in 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 ArrowSize 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 an 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 good, typical InitialRepeatDelay value is 50 milliseconds, which is the default values 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

8 JCArrowButton