Class UIMenuButton

public class UIMenuButton extends UIMenuLauncher
{
  // Constructors
  public UIMenuButton(String string, UIMenuList menu);
  public UIMenuButton(String string, int style, UIMenuList menu);
  public UIMenuButton(IUIComponent comp, UIMenuList menu);
  public UIMenuButton(IUIComponent comp, int style,
        UIMenuList menu);

  // Methods
  public boolean action(Event e, Object o);
  public void ended(Event event);
  public Rectangle getPlacement(Dimension size);
  public int getRoleCode();
  public boolean keyDown(Event e, int key);
  public boolean launch();
  public boolean mouseDown(Event e, int x, int y);
  public void requestFocus();
}

This class implements a menu button control. UIMenuButton uses UIPushButton to create the content of the menu button control. Each UIMenuButton object is then associated with a pop-up menu, which uses UIMenuList for the content of the menu. Typically, you'll add a collection of UIMenuButton objects to a UIBand control to create a menu bar, as shown in the following example.

UIBand menuBar;
UIMenuButton fileButton, editButton, helpButton;

// Create the menu bar and add it to the container.
menuBar = new UIBand();
add(menuBar); 

// Create the menus.
UIMenuList fileMenu = new UIMenuList();
UIMenuList editMenu = new UIMenuList();
UIMenuList helpMenu = new UIMenuList();
...  // Add items to each menu.

// Create each menu button.
fileButton = new UIMenuButton("File", fileMenu);
editButton = new UIMenuButton("Edit", editMenu);
helpButton = new UIMenuButton("Help", helpMenu);

// Add each menu button to the menu bar.
menuBar.add(fileButton);
menuBar.add(editButton);
menuBar.add(helpButton);

For more information about using UIMenuButton objects, see the UIMenuLauncher 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.

UIComponent
  |
  +--UIContainer
    |
    +--UIStateContainer
      |
      +--UISingleContainer
        |
        +--UIMenuLauncher
          |
          +--UIMenuButton

Constructors

UIMenuButton

public UIMenuButton(String string, UIMenuList menu);

Creates a menu button control with the specified text and menu.

Parameter	Description
string	The text to be displayed by the control.
menu	The UIMenuList object containing the content of the associated pop-up menu.

Remarks:

By default, the button is hot-tracked and its style is RAISED. To create a button that is not hot-tracked, pass a UIText object instead of a String. For more information about hot-tracking, see the UIButton overview.

UIMenuButton

public UIMenuButton(String string, int style, UIMenuList menu);

Creates a menu button control with the specified text, style, and menu.

Parameter	Description
string	The text to be displayed by the control.
style	The style of the button. Possible values include UIPushButton.RAISED or 0 for a flat style. Be aware that specifying UIButton.TOGGLE or UIButton.TRITOGGLE has no effect. You must manually set and clear the button's checked state.
menu	The UIMenuList object containing the content of the associated pop-up menu.

Remarks:

By default, the button is hot-tracked. To create a button that is not hot-tracked, pass a UIText object instead of a String. For more information about hot-tracking, see the UIButton overview.

Exceptions:

IllegalArgumentException if an undefined style was specified.

UIMenuButton

public UIMenuButton(IUIComponent comp, UIMenuList menu);

Creates a menu button control with the specified component and menu.

Parameter	Description
comp	The component to be displayed by the control.
menu	The UIMenuList object containing the content of the associated pop-up menu.

Remarks:

By default, the button's style is RAISED. Typically, you'll pass a UIText, UIGraphic, or UIItem object for the component. For examples of how to construct buttons, see the UIButton overview.

UIMenuButton

public UIMenuButton(IUIComponent comp, int style, UIMenuList menu);

Creates a menu button control with the specified component, style, and menu.

Parameter	Description
comp	The component to be displayed by the control.
style	The style of the button. Possible values include UIPushButton.RAISED or 0 for a flat style. Be aware that specifying UIButton.TOGGLE or UIButton.TRITOGGLE has no effect. You must manually set and clear the button's checked state.
menu	The UIMenuList object containing the content of the associated pop-up menu.

Remarks:

Typically, you'll pass a UIText, UIGraphic, or 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

action

public boolean action(Event e, Object o);

Launches or cancels the menu button's associated pop-up menu.

Return Value:

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

Parameter	Description
e	The event posted to the button.
o	The object that posted the event.

Remarks:

By default, an action event is generated when an item in the pop-up menu is selected. This method responds by cancelling the menu. For information about trapping action events, see the UIMenuLauncher overview.

ended

public void ended(Event event);

Called by the button control's associated pop-up menu when the menu is closed.

Return Value:

No return value.

Parameter	Description
event	The event that will be fired after ended is complete; null if no event will be fired.

Remarks:

This method is invoked by cancel (inherited through UIMenuLauncher). ended clears the launched state of the pop-up menu and clears the checked state of the control's UIPushButton content component.

Overrides:

ended(Event) in UIMenuLauncher.

getPlacement

public Rectangle getPlacement(Dimension size);

Called by the button's associated pop-up menu when the menu is to be displayed.

Return Value:

Returns the bounding rectangle (in screen coordinates) of the pop-up menu.

Parameter	Description
size	Specifies the preferred size (in pixels) of the pop-up menu.

Remarks:

This method calls fitToScreen (inherited through UIMenuLauncher) to determine where the pop-up menu will be displayed. By default, the pop-up menu is positioned below the button when it is launched.

Overrides:

getPlacement(Dimension) in UIMenuLauncher.

See Also: launch

getRoleCode

public int getRoleCode();

Retrieves the role of the object.

Return Value:

Returns the ROLE_SYSTEM_BUTTONMENU role code for the menu button object.

keyDown

public boolean keyDown(Event e, int key);

Determines whether the DOWN ARROW key is being pressed, and if so, launches the associated menu.

Return Value:

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

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

See Also: launch

launch

public boolean launch();

Launches the button control's associated pop-up menu.

Return Value:

Returns true if the pop-up menu was launched; otherwise, returns false.

Remarks:

This method sets the launched state of the pop-up menu and sets the checked state of the control's UIPushButton content component. The getPlacement method is invoked to display the menu. Any previously launched menu is cancelled.

Overrides:

launch() in UIMenuLauncher.

mouseDown

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

Launches or cancels the button control's associated pop-up menu.

Return Value:

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

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

Remarks:

If the pop-up menu is already in the launched state when the control is clicked, the menu is cancelled; otherwise, it is launched.

requestFocus

public void requestFocus();

Requests that the button control's UIPushButton content component receives focus.

Return Value:

No return value.