Previous
Contents
Index
Next
| Package com.ms.ui |
Previous |
Contents |
Index |
Next |
public abstract class UIButton extends UIPanel
{
// Fields
public static final int TOGGLE;
public static final int TRITOGGLE;
// Constructors
public UIButton();
public UIButton(Component comp);
public UIButton(Component comp, int style);
// Methods
public int getStyle();
public void setStyle(int style);
public void setHot(boolean on);
public void reshape(int x, int y, int width, int height);
public boolean keyDown(Event e, int key);
public boolean keyUp(Event e, int key);
public boolean mouseUp(Event e, int x, int y);
public void doDefaultAction();
public String getDefaultAction();
}
An abstract class that manages a 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 examples demonstrate different ways to construct a button.
// Construct a push button that displays the text
// "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));
Like other components, you must add each button you create to the container, as follows.
UIPushButton p = new UIPushButton("My Button");
add(p);
Note that 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 two push buttons: p1 displays only text.
// 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's text will be hot-tracked (hot-tracking and other button states are discussed below). To override this default, construct the button with 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 text is hot-tracked.
p1 = new UIPushButton("Hot-tracked text");
// Construct a button with a UIText object. By default,
// the text is not hot-tracked.
p2 = new UIPushButton(new UIText("Text not hot-tracked"));
// Construct a button with a UIText object. Specify the
// UIStatic.HOTTRACK flag to make the text hot-tracked.
p3 = new UIPushButton(new UIText("Hot-tracked UIText",
UIStatic.HOTTRACK));
add(p1);
add(p2);
add(p3);
Each button class defines and/or inherits the get and set methods to determine and change the current button state. The following table describes the different states.
| focus | When a button has focus, it can receive keyboard input. |
| hot-tracked | When the user moves the mouse over a button, hot-tracking indicates that this button will receive focus if the user clicks it. |
| pressed | A button is pressed when the user holds the mouse button inside the button area. |
| checked | If the button's style is set to TOGGLE, the button's state will automatically alternate between unchecked and checked. If the style is TRITOGGLE, the state will alternate between unchecked, checked, and indeterminate. |
| indeterminate | If the button's style is TRITOGGLE, the button's state will alternate between unchecked, checked, and indeterminate. |
Typically, when a button is pressed and released, an action event is sent to the button. (Note that with UIRepeatButton objects, action events are continually generated while the button remains pressed.) The following example shows how two push buttons can be enabled or disabled, depending on whether a check box button has been selected.
public boolean action(Event evt, Object arg)
{
if (arg == c) // c is a UICheckButton object.
{
// getChecked returns true if c is checked,
// false if c is unchecked.
boolean enabled = c.getChecked();
// p1 and p2 are UIPushButton objects that
// will be enabled if c is checked; otherwise,
// they will be disabled.
p1.enable(enabled);
p2.enable(enabled);
return true;
}
return false;
}
public UIButton();Creates a button control with no content.
public UIButton(Component comp);Creates a button control using the specified component for content.
Parameter Description comp The component to be displayed within the button. Remarks:
Typically, the comp parameter will specify a UIText, UIGraphic, or UIItem object. See the UIButton overview for examples of how to construct buttons.
public UIButton(Component comp, int style);Creates a button control using the specified component for content and the specified style.
Parameter Description comp The component to be displayed within the button. style The style of the button. You can specify one of the predefined styles, which are TOGGLE or TRITOGGLE, or you can set any bit in the mask 0xFF000000. Remarks:
If any undefined style bits are specified, an IllegalArgumentException is thrown. Typically, the comp parameter will specify a UIText, UIGraphic, or UIItem object. See the UIButton overview for examples of how to construct buttons.
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 setting the appropriate state and generating an action event.
public String getDefaultAction();Retrieves the default action for the button.
Return Value:
Returns a String specifying the default action.
Remarks:
The default action for a button is "Press."
public int getStyle();Retrieves the button's current style settings.
Return Value:
Returns an integer containing the current style bits.
Remarks:
To change the button's style, call setStyle.
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 button states, see the UIButton overview.
public boolean keyUp(Event e, int key);Determines whether the SPACEBAR or the ENTER key is being released and, if so, clears 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 released. Remarks:
This method is called when the button has focus and a key is released. If the key being pressed is the SPACEBAR or the ENTER key, the button's pressed state is cleared and the appropriate state (unchecked, checked, or indeterminate) is set. For more information about button states, see the UIButton overview.
public boolean mouseUp(Event e, int x, int y);Reacts to the mouse button being released inside the button area.
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 mouse button is released inside the button area. If the button is pressed, the appropriate state (unchecked, checked, or indeterminate) is set. For more information about button states, see the UIButton overview.
public void reshape(int x, int y, int width, int height);Reshapes the button to the specified bounding box in its parent's coordinate space.
Return Value:
No return value.
Parameter Description x The x coordinate of the button's upper left corner. y The y coordinate of the button's upper left corner. width The width of the button. height The height of the button. Remarks:
After reshaping the button, this method then validates the button to update the layout of its content.
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 button states, see the UIButton overview.
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 specify one of the predefined styles, which are TOGGLE or TRITOGGLE, or you can set any bit in the mask 0xFF000000. Remarks:
This method throws an IllegalArgumentException if any undefined style bits are specified. To determine the current style, call getStyle.
© 1997 Microsoft Corporation. All rights reserved. Legal Notices.