10.1 MenuComponent

MenuComponent is an abstract class that is the parent of all menu-related objects. You will never create an instance of the object. Nor are you likely to subclass it yourself--to make the subclass work, you'd have to provide your own peer on every platform where you want the application to run.

Names

The name serves as an alternative, nonlocalized reference identifier for menu components. If your event handlers compare menu label strings to an expected value and labels are localized for a new environment, the approach fails.

public String getName ()

The getName() method retrieves the name of the menu component. Every instance of a subclass of MenuComponent is named when it is created.

public void setName (String name)

The setName() method changes the current name of the component to name.

Peers

public MenuComponentPeer getPeer ()

The getPeer() method returns a reference to the MenuComponent peer as a MenuComponentPeer.

public synchronized void removeNotify ()

The removeNotify() method destroys the peer of the MenuComponent and removes it from the screen. addNotify() will be specific to the subclass.

Events

Event handling is slightly different between versions. If using the 1.0 event model, use postEvent(). Otherwise, use dispatchEvent() to post an event to this MenuComponent or processEvent() to receive and handle an event. Remember not to mix versions within your programs.

public boolean postEvent (Event e)

The postEvent() method posts Event e to the MenuComponent. The event is delivered to the Frame at the top of the object hierarchy that contains the selected MenuComponent. The only way to capture this event before it gets handed to the Frame is to override this method. There are no helper functions as there are for Components. Find out which MenuComponent triggered the event by checking e.arg, which contains its label, or ((MenuItem)e.target).getName() for the nonlocalized name of the target.

public boolean postEvent (Event e) {
    // Use getName() vs. e.arg for localization possibility
    if ("About".equals (((MenuItem)e.target).getName()))
        playLaughingSound(); // Help request
    return super.postEvent (e);
}

If you override this method, in order for this Event to propagate to the Frame that contains the MenuComponent, you must call the original postEvent() method (super.postEvent(e)).

The actual value returned by postEvent() is irrelevant.

public final void dispatchEvent(AWTEvent e)

The dispatchEvent() method allows you to post new AWT events to this menu component's listeners. dispatchEvent() tells the MenuComponent to deal with the AWTEvent e by calling its processEvent() method. This method is similar to Java 1.0's postEvent() method. Events delivered in this way bypass the system's event queue. It's not clear why you would want to bypass the event queue, except possibly to deliver some kind of high priority event.

protected void processEvent(AWTEvent e)

The processEvent() method receives all AWTEvents with a subclass of MenuComponent as its target. processEvent() then passes them along for processing. When you subclass a child class, overriding processEvent() allows you to process all events without having to provide listeners. However, remember to call super.processEvent(e) last to ensure regular functionality is still executed. This is like overriding postEvent() using the 1.0 event model.

Miscellaneous methods

public MenuContainer getParent ()

The getParent() method returns the parent MenuContainer for the MenuComponent. MenuContainer is an interface that is implemented by Component (in 1.1 only), Frame, Menu, and MenuBar. This means that getParent() could return any one of the four.

protected String paramString ()

The paramString() method of MenuComponent helps build up the string to display when toString() is called for a subclass. At the MenuComponent level, the current name of the object is appended to the output.

public String toString ()--can be called by user for subclass

The toString() method at the MenuComponent level cannot be called directly. This toString() method is called when you call a subclass's toString() and the specifics of the subclass is added between the brackets ([ and ]). At this level, the results would be:

java.awt.MenuComponent[aname1]