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
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.
|
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.
|
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.
|
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
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.
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.
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.
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
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
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.
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
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.
|
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.
|
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.
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.
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
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.