Packages
 In this topic

*Constructors

*Methods

 

Packages   PreviousThis PackageNext
Package com.ms.ui   Previous This
Package
Next

 


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.

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

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

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

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

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

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

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

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

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

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

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

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

upnrm.gif © 1998 Microsoft Corporation. All rights reserved. Terms of use.