Class UIMenuLauncher

public abstract class UIMenuLauncher extends UISingleContainer
             implements IUIMenuLauncher
{
  // Constructors
  public UIMenuLauncher(UIMenuList menu);
  public UIMenuLauncher(IUIComponent comp);
  public UIMenuLauncher(IUIComponent comp, UIMenuList menu);

  // Methods
  public void cancel();
  public void ended(Event event);
  public Rectangle fitToScreen(Rectangle exclude, Dimension size,
        boolean right);
  public IUIContainer getDisplayer();
  public UIMenuList getMenu();
  public Rectangle getPlacement(Dimension size);
  public boolean isLaunched();
  public boolean launch();
  public boolean postEvent(Event e);
  public void raiseEvent(Event e);
  public void setFocused(boolean on);
  public void setHot(boolean on);
  public void setMenu(UIMenuList menu);
  public void setSelected(boolean on);
}

This class implements an abstract menu launcher control. By implementing the IUIMenuLauncher interface, UIMenuLauncher provides methods for launching and cancelling a pop-up menu. Typically, a UIMenuLauncher object is associated with a specific UIMenuList control, which is used for the content of the pop-up menu. This is a one-to-one relationship — you can't assign a UIMenuList to more than one menu launcher at a time.

Classes that extend UIMenuLauncher include UIMenuButton, and UIMenuItem, and UIContextMenu. The following example shows how to create a UIMenuButton object with an associated pop-up menu. It contains a UIMenuItem object, which launches a second pop-up menu.

UIBand myMenuBar;
UIMenuButton myButton;
UIMenuList myMenu;
UIMenuItem myItem;
UIComponent c1, c2, c3;

// Construct the pop-up menu for the menu button.
UIMenuList myMenu = new UIMenuList();

// Add two text items to myMenu.
c1 = myMenu.add("Item 1");
c2 = myMenu.add("Item 2");

// Add a UIMenuItem object to myMenu.
{
  // Construct the pop-up menu for the UIMenuItem 
  // object and add a text item to the menu.
  UIMenuList mySubMenu = new UIMenuList();
  c3 = mySubMenu.add("Sub Item 1");

  // Construct the UIMenuItem object, using mySubMenu.
  UIMenuItem myItem = new UIMenuItem("Item 3", mySubMenu);

  // Add myItem to myMenu.
  myMenu.add(myItem);
}

// Now construct the menu button, using myMenu.	
UIMenuButton myButton = new UIMenuButton("Menu 1", myMenu);

// Construct the menu bar and add the menu button.
myMenuBar = new UIBand();
myMenuBar.add(myButton);
add(myMenuBar);  // Add the menu bar to the container.

When an item in the pop-up menu is selected, an action event is generated. The following example shows how to use the action method to trap this event.

public boolean action(Event e, Object arg)
{
   if (e.target == myButton)
   {
      if (arg == c1)
      {
         // Do something.
         return true;
      }
      else if (arg == c2)
      {
         // Do something.
         return true;
      }
      else if (arg == c3)
      {
         // Do something.
         return true;
      }
   }
   return false;
}

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

Constructors

UIMenuLauncher

public UIMenuLauncher(UIMenuList menu);

Creates a menu launcher control with the specified menu. The control itself has no content.

Parameter	Description
menu	The UIMenuList object containing the content of the associated pop-up menu.

UIMenuLauncher

public UIMenuLauncher(IUIComponent comp);

Creates a menu launcher control with the specified component. The control has no associated menu.

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

UIMenuLauncher

public UIMenuLauncher(IUIComponent comp, UIMenuList menu);

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

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

Methods

cancel

public void cancel();

Cancels the control's associated pop-up menu.

Return Value:

No return value.

Remarks:

This method implements cancel in the IUIMenuLauncher interface. If the pop-up menu is currently launched, this method terminates the launch and closes the pop-up menu.

See Also: launch

ended

public void ended(Event event);

Called by the control's associated pop-up menu once the menu is closed (either by selecting an item or cancelling menu mode).

Return Value:

No return value.

Parameter	Description
event	The event that will be fired by the caller after end is complete; null if no event will be fired.

Remarks:

This method implements selected in the IUIMenuLauncher interface by resetting its state.

fitToScreen

public Rectangle fitToScreen(Rectangle exclude, Dimension size,
        boolean right);

Determines where the pop-up menu will be displayed on the screen.

Return Value:

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

Parameter	Description
exclude	The rectangle identifying where the pop-up menu will be displayed when it is launched. The menu will not obscure this rectangle.
size	The preferred size (in pixels) of the pop-up menu.
right	If true, the pop-up menu will be displayed to the right of the exclude rectangle; otherwise, the pop-up menu will be displayed below this rectangle.

Remarks:

This method is called by getPlacement.

getDisplayer

public IUIContainer getDisplayer();

Retrieves the displayer for the pop-up menu associated with the menu launcher control. By default, this is null.

Note Any displayer must have a UIMenuLauncher menu as a child.

Return Value:

Returns the displayer object for the pop-up menu.

getMenu

public UIMenuList getMenu();

Retrieves the pop-up menu associated with the menu launcher control.

Return Value:

Returns the UIMenuList object containing the menu's content.

Remarks:

This method implements getMenu in the IUIMenuLauncher interface.

See Also: setMenu

getPlacement

public Rectangle getPlacement(Dimension size);

Called by the control's 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	The preferred size (in pixels) of the pop-up menu.

Remarks:

This method implements getPlacement in the IUIMenuLauncher interface, and calls fitToScreen to determine where the pop-up menu will be displayed. By default, the menu is positioned to the right of the menu launcher control.

See Also: launch

isLaunched

public boolean isLaunched();

Determines the launched state of the control's associated pop-up menu.

Return Value:

Returns true if the launched state is set; otherwise, returns false. .

Remarks:

This method implements isLaunched in the IUIMenuLauncher interface. The launch method sets the pop-up menu's launched state The ended method clears it.

launch

public boolean launch();

Launches the control's associated pop-up menu.

Return Value:

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

Remarks:

This method implements launch in the IUIMenuLauncher interface. launch sets the pop-up menu's launched state and invokes getPlacement to display the menu. Any previously launched menu is cancelled.

See Also: cancel, isLaunched

postEvent

public boolean postEvent(Event e);

Posts the specified event.

Return Value:

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

Parameter	Description
e	The event.

raiseEvent

public void raiseEvent(Event e);

Called by the object's pop-up menu when an event occurs.

Return Value:

No return value.

Parameter	Description
e	The event that occurred.

setFocused

public void setFocused(boolean on);

Sets or clears the focus state of the menu launcher control.

Return Value:

No return value.

Parameter	Description
on	If true, the focus state is set; otherwise, it is cleared.

Remarks:

This method also sets or clears the focus state of the control's content component.

Overrides:

setFocused(boolean) in UISingleContainer.

setHot

public void setHot(boolean on);

Sets or clears the hot-tracked state of the menu launcher control.

Return Value:

No return value.

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

Remarks:

This method also sets or clears the hot-tracked state of the control's content component.

setMenu

public void setMenu(UIMenuList menu);

Sets the pop-up menu to be associated with the menu launcher control.

Return Value:

No return value.

Parameter	Description
menu	The UIMenuList object containing the menu's content.

Remarks:

This method implements setMenu in the IUIMenuLauncher interface.

See Also: getMenu

setSelected

public void setSelected(boolean on);

Sets or clears the selected state of the menu launcher control.

Return Value:

No return value.

Parameter	Description
on	If true, the selected state is set; otherwise, it is cleared.

Remarks:

This method also sets or clears the selected state of the control's content component.