Class UIButton

public abstract class UIButton extends UISingleContainer
{
  // Fields
  public static final int TOGGLE;
  public static final int TRITOGGLE;

  // Constructors
  public UIButton();
  public UIButton(IUIComponent comp);
  public UIButton(IUIComponent comp, int style);

  // Methods
  public void doDefaultAction();
  public String getDefaultAction();
  public int getStyle();
  public boolean keyDown(Event e, int key);
  public boolean keyUp(Event e, int key);
  public boolean mouseClicked(Event e, int x, int y);
  public void setHot(boolean on);
  public void setStyle(int style);
}

This class implements an abstract button control. The following diagram shows the classes that extend UIButton.

UIButton
|
+--UICheckButton
|  |
|  +--UIRadioButton
|
+--UIPushButton
   |
   +--UIExpandButton
   |
   +--UIRepeatButton

When constructing a button, you typically specify the button's content and style. The UIText, UIGraphic, and UIItem classes provide several options for adding text and graphical images to your button. The following example demonstrates different ways to construct a button.

// Construct a push button that displays the String
// "Push Button". By default, this text is centered.
// Make the button raised and toggled.
UIPushButton p1 = 
   new UIPushButton("Push Button", 
                    UIPushButton.RAISED | UIButton.TOGGLE);

// Construct a check box button that displays the text
// stored in a UIText object. Left-align the text and
// make the button tritoggled. 
UICheckButton c1 = 
   new UICheckButton(new UIText("Checkbox", UIStatic.LEFT), 
                     UIButton.TRITOGGLE); 

// Construct a repeating push button that displays the graphical
// image stored in the variable myImage. Left-align the image.
UIRepeatButton r1 = 
      new UIRepeatButton(new UIGraphic(myImage, UIStatic.LEFT));

// Construct a radio button that displays both the graphical 
// image stored in the variable myImage and the text 
// "Radio Button." Put the image above the text.
UIRadioButton r2 = 
   new UIRadioButton(new UIItem(myImage, "Radio Button", 
                                0, UIItem.ABOVE));

// Add each button to the container.
add(p1);
add(c1);
add(r1);
add(r2);

UIButton inherits the setName method to change the text displayed on a button after it is created. The getName method allows you to retrieve the current text. The following example shows how to use these two methods.

// Define two UIPushButton variables.
UIPushButton p1, p2;


// Construct p1 and p2. p1 displays only text, while
// p2 displays a graphical image and text.
p1 = new UIPushButton("p1 text");
p2 = new UIPushButton(new UIItem(myImage, "p2 text")); 
add(p1);
add(p2);

// Now replace the text displayed from p2 with the text from p1. 
String s = p1.getName();  
p2.setName(s);  // p2 now displays a graphical image and
                // the text from p1.

Note When you construct a button with a String, the button is automatically hot-tracked. To override this default, use a UIText object instead of a String, as shown in the following example.

UIPushButton p1, p2, p3;

// Construct a button with a String. 
// By default, the button is hot-tracked.
p1 = new UIPushButton("Hot-tracked text");

// Construct a button with a UIText object. 
// By default, the button is not hot-tracked.
p2 = new UIPushButton(new UIText("Text not hot-tracked"));

// To create a hot-tracked button using UIText, 
// specify the UIStatic.HOTTRACK flag.
p3 = new UIPushButton(new UIText("Hot-tracked UIText", 
                                 UIStatic.HOTTRACK));
add(p1);
add(p2);
add(p3); 

For more information about hot-tracking, see the UIText overview.

Note The hot-track color is the same color as the button text color. As a result, hot-tracking does not appear to be functional.

Typically, when a UIButton object is pressed and released, an action event is generated. (With UIRepeatButton objects, action events are continually generated while the button remains pressed.) The following example shows how to use the action method to trap these events.

public boolean action(Event e, Object o)
{
  if (e.target == c)  // c is a UICheckButton object.
  {
     // isChecked returns true if c is checked, 
     // false if c is unchecked.
     boolean enabled = c.isChecked();

     // p1 and p2 are UIPushButton objects that 
     // will be enabled if c is checked; otherwise, 
     // they will be disabled.
     p1.setEnabled(enabled);
     p2.setEnabled(enabled);
     return true;
  }
  return false;
}

In both UIRadioButton and UICheckButton objects, the behavior of the action method is inconsistent with that of AWT components in certain cases. The inconsistency is in the way the states of the button object are retrieved.

For example, if you create a menu with a UIMenuButton, add a UIRadioButton to it as a UIMenuItem, the action method returns different values under AFC and AWT.

//Add a radio button as a menu item.
UIMenuItem uimi = new UIMenuItem(new UIRadioButton("button as menu item"));

The action method returns the following values when AFC is used.

Event.target

The name of the menu button.

Event.arg

The UIMenuItem (in this case, the name of the UIRadioButton).

Object parameter

The next state of the UIRadioButton.

In comparison, the action method returns the following under AWT.

Event.target

The name of the menu button.

Event.arg

The next state of the UIRadioButton.

Object parameter

The next state of the UIRadioButton.

You must query the button to retrieve states when using AFC, if you are currently using the action method to retrieve the states of buttons in your Java code.

UIComponent
  |
  +--UIContainer
    |
    +--UIStateContainer
      |
      +--UISingleContainer
        |
        +--UIButton

Constructors

UIButton

public UIButton();

Creates a button control with no content.

UIButton

public UIButton(IUIComponent comp);

Creates a button control with the specified component.

Parameter	Description
comp	The component to be displayed within the button.

Remarks:

Typically, you'll pass a UIText, a UIGraphic, or a UIItem object for the component. For examples of how to construct buttons, see the UIButton overview.

UIButton

public UIButton(IUIComponent comp, int style);

Creates a button control with the specified component and style.

Parameter	Description
comp	The component to be displayed within the button.
style	The style of the button. You can pass TOGGLE or TRITOGGLE, or you can set any bit in the mask 0xFF000000.

Remarks:

Typically, you'll pass a UIText, a UIGraphic, or a UIItem object for the component. For examples of how to construct buttons, see the UIButton overview.

Exceptions:

IllegalArgumentException if an undefined style was specified.

Methods

doDefaultAction

public void doDefaultAction();

Performs the default action for the button.

Return Value:

No return value.

Remarks:

The default action for a button is "Press." This method executes a button press by generating an action event. If the button's style is TOGGLE or TRITOGGLE, the appropriate checked state (unchecked, checked, or indeterminate) is also set.

See Also: getDefaultAction

getDefaultAction

public String getDefaultAction();

Retrieves the default action for the button.

Return Value:

Returns the string "Press".

See Also: doDefaultAction

getStyle

public int getStyle();

Retrieves the button's current style settings.

Return Value:

Returns an integer containing the current style settings. For a list of possible styles, see setStyle.

keyDown

public boolean keyDown(Event e, int key);

Determines whether the SPACEBAR or the ENTER key is being pressed, and if so, sets the pressed state.

Return Value:

Returns true if the event was handled; otherwise, returns false.

Parameter	Description
e	The event posted to the button control.
key	The key that has been pressed.

Remarks:

This method is called when the button has focus and a key is pressed. If the key being pressed is the SPACEBAR or the ENTER key, the button's pressed state is set. If the ESC key is being pressed, the button's pressed state is cleared.

For more information about states, see the UIStateContainer overview.

See Also: keyUp

keyUp

public boolean keyUp(Event e, int key);

Determines whether the SPACEBAR or the ENTER key is being released, and if so, generates an action event.

Return Value:

Returns true if the event was handled; otherwise, returns false.

Parameter	Description
e	The event posted to the button control.
key	The key that has been released.

Remarks:

This method is called when the button has focus and a key is released. If the key being released is the SPACEBAR or the ENTER key, an action event is generated, and, if the button's style is TOGGLE or TRITOGGLE, the appropriate checked state (unchecked, checked, or indeterminate) is set. keyUp also clears the button's pressed state, which was previously set by keyDown.

For more information about states, see the UIStateContainer overview.

See Also: keyDown

mouseClicked

public boolean mouseClicked(Event e, int x, int y);

Generates an action event for the button.

Return Value:

Returns true if the event was handled; otherwise, returns false.

Parameter	Description
e	The event posted to the button control.
x	The x coordinate of the event.
y	The y coordinate of the event.

Remarks:

This method is called when the button control is clicked. If the control's style is TOGGLE or TRITOGGLE, mouseClicked also sets the appropriate checked state (unchecked, checked, or indeterminate).

setHot

public void setHot(boolean on);

Sets or clears the hot-tracked state of the button.

Return Value:

No return value.

Parameter	Description
on	If true, the hot-tracked state is set; otherwise, it is cleared.

Remarks:

For more information about states, see the UIStateContainer overview.

setStyle

public void setStyle(int style);

Sets the button's current style.

Return Value:

No return value.

Parameter	Description
style	The style of the button. You can pass TOGGLE or TRITOGGLE, or you can set any bit in the mask 0xFF000000.

Exceptions:

IllegalArgumentException if an undefined style was specified.

See Also: getStyle

Fields

TOGGLE

Specifies that the button will automatically alternate between the unchecked and checked states whenever the button is pressed.

TRITOGGLE

Specifies that the button will automatically alternate between the unchecked, checked, and indeterminate states (in that order) whenever the button is pressed.