/* NSMenu.h Copyright (C) 1996 Free Software Foundation, Inc. Author: Ovidiu Predescu Date: May 1997 A completely rewritten version of the original source by Scott Christley. This file is part of the GNUstep GUI Library. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; see the file COPYING.LIB. If not, see or write to the Free Software Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ #ifndef _GNUstep_H_NSMenu #define _GNUstep_H_NSMenu #import #import #import #import #import @class NSString; @class NSEvent; @class NSFont; @class NSMatrix; @class NSPopUpButton; @class NSPopUpButtonCell; @class NSView; @class NSWindow; @class NSMutableArray; @class NSScreen; /* ******************* */ /* NSMenuView Protocol */ /* ******************* */ @protocol NSMenuView /** Set the menu that this view object will be drawing. * This method will NOT retain the menu. * In normal usage an instance of NSMenu will * use this method to supply the NSMenuView with reference * to itself. The NSMenu will retain the NSMenuView. */ - (void) setMenu: (NSMenu *)menu; /** Set the currently highlighted item. * This is used by the NSMenu class to restore * the selected item when it is temporary set to * another item. This happens when both the regular * version and the transient version are on the screen. * A value of -1 means that no item will be highlighted. */ - (void) setHighlightedItemIndex: (NSInteger)index; /** Returns the currently highlighted item. Returns -1 * if no item is highlighted. */ - (NSInteger) highlightedItemIndex; /** This should ensure that if there is an attached * submenu this submenu will be detached. * Detaching means that this particular menu representation * should be removed from the screen. * It should implement a deep detach, that is, all * attached submenus of this menu should also be detached. */ - (void) detachSubmenu; /** This will relayout the NSMenuView. * It should be called when the menu changes. Changes include * becoming detached, adding or removing submenu items etcetera. * However, normally it does not need to be called directly because * Because the NSMenuView is supposed to listen to the NSMenu notifications * for the item added, removed and change notifications. * It should be called explicitly when other changes occur, such as * becoming detached or changing the title. */ - (void) update; /** Hm, why is this method needed? Shouldn't this be done by * the update method? */ - (void) sizeToFit; //!!! /** Method used by NSMenuItemCell to draw itself correctly and nicely * lined up with the other menu items. */ - (float) stateImageWidth; /** Method used by NSMenuItemCell to draw itself correctly and nicely * lined up with the other menu items */ - (float) imageAndTitleOffset; /** Methos used by NSMenuItemCell to draw itself correctly and nicely * lined up with the other menu items. */ - (float) imageAndTitleWidth; /** Methos used by NSMenuItemCell to draw itself correctly and nicely * lined up with the other menu items. */ - (float) keyEquivalentOffset; /** Used by NSItemCell to ... */ - (float) keyEquivalentWidth; /** Used by the NSMenu to determine where to position a * submenu. */ - (NSPoint) locationForSubmenu: (NSMenu *)aSubmenu; - (void) performActionWithHighlightingForItemAtIndex: (NSInteger)index; //???? /**

This is method is responsible for handling all events while * the user is interacting with this menu. It should pass on this * call to another menurepresentation when the user moves the * mouse cursor over either a submenu or over the supermenu. *

*

The method returns when the interaction from the user with the * menu system is over. *

*

The method returns NO when the user releases the mouse button * above a submenu item and YES in all other cases. *

*

This return value can be used to determine if submenus should * be removed from the screen or that they are supposed to stay. *

*

The implementation should roughly follow the following logic: *

* * { * while (have not released mouse button) * { * if (mouse hovers over submenu, or supermenu) * { * if ([(menurepresentation under mouse) * trackWithEvent: the event]) * { * [self detachSubmenu]; * return YES; * } * return NO; * } * //highlight item under mouse * * if (highlighting submenu item) * { * [self attachSubmenuAtIndex:..]; * } * else * { * [self detachSubmenu]; * } * get next event. * } * * execute the menu action if applicable; * * return YES | NO depending on the situation; * } * * * Note that actual implementations tend to be more complicated because * because of all kind of useability issues. Useabilities issues to * look out for are: * * Menus that are only partly on the screen. Those need to be * moved while navigation the menu. * Submenus that are hard to reach. If the natural route to * the content of a submenu travels through other menu items * you do not want to remove the submenu immediately. * Transient menus require slightly different behaviour from * the normal menus. For example, when selecting a action from * a transient menu that brings up a modal panel you would * expect the transient menu to dissappear. However in the * normal menu system you want it to stay, so you still have * feedback on which menu action triggered the modal panel. * */ - (BOOL) trackWithEvent: (NSEvent *)event; @end /** * The NSMenuDelegate protocol defines optional methods implemented * by delegates of NSMenu objects. */ @protocol NSMenuDelegate /** * Allows the delegate to return the target and action for a key-down event. */ - (BOOL) menuHasKeyEquivalent: (NSMenu *)menu forEvent: (NSEvent *)event target: (id *)target action: (SEL *)action; /** * Invoked on the delegate to allow changes before the menu opens. */ - (void) menuWillOpen: (NSMenu *)menu; /** * Invoked when the menu is about to be displayed. */ - (NSInteger) numberOfItemsInMenu: (NSMenu *)menu; /** * Invoked to indicate that the menu is about to be updated. */ - (void) menuNeedsUpdate: (NSMenu *)menu; /** * Invoked to inform the delegate that the menu did close. */ - (void) menuDidClose: (NSMenu *)menu; /** * Invoked too notify the delegate that the item will be highlighted. */ - (void) menu: (NSMenu *)menu willHighlightItem: (NSMenuItem *)item; /** * Invoked to allow the delegate to update an item before * it is displayed. */ - (BOOL) menu: (NSMenu *)menu updateItem: (NSMenuItem *)item atIndex: (NSInteger)index shouldCancel: (BOOL)shouldCancel; /** * Specify a display location for the menu */ - (NSRect)confinementRectForMenu: (NSMenu *)menu onScreen: (NSScreen *)screen; @end /**

Menus provide the user with a list of actions and/or submenus. * Submenus themselves are full fledged menus and so a heirarchical * structure of appears.

*

Every application has one special menu, the so called Application * menu. This menu is always visible on the screen when the application * is active. This menu normally contains items like, info, * services, print, hide and quit.

*

After the info item normally some submenus follow containing * the application specific actions.

*

On GNUstep the content of the menu is stacked vertically as * oppossed to the Windows and Mac world, where they are stacked * horizontally. Also because the menus are not part of any normal * window they can be dragged around opened and closed independend of * the application windows.

*

This can lead to a few menus being open simultanuously. * The collection of open menus is remembered, * when the program is started again, all the torn off menus aka * detached menus, are displayed at their last known position.

*

The menu behaviour is richer than in most other environments and * bear some explanation. This explanation is aimed at users of Menus * but more so at the developer of custom menus.

* * Application menu * There alwasy at least one menu present and visible while the * application is active. This is the application menu. This * window can never be closed. * Attached menu * Normally when you click in a menu on a submenu item, the * submenu is shown directly next to the menu you click in. * The submenu is now called an attached menu. It is * attached to the menu that was clicked in. * Detached menu * A menu is detached when it is not attached to its parent * menu. A menu can become detached when the user drags a * submenu away from its parents. A detached window contains in * its title a close button. * Transient menu * A transient menu is a menu that dissappears as * soon as the user stops interacting with the menus. * Typically a transient menu is created when a right mouse * click appears in an application window. The right mouse * click will bring up the Application menu at the place the * user clicks. While keeping the mouse button down the * user can select items by moving around. When releasing the * button, all transient menus will be removed from the screen * and the action will be executed. *

It is important to note that it is impossible to click * in transient menus.

 * Attached transient menu * This is a menu that is attached and transient at the same * time. * * * A single NSMenu instance can be displayed zero or one times when the * user is not interaction with the menus. * When the user is interaction with the menus it can occur that the * same NSMenu is displayed in two locations at the same time. This is * only possible when one of the displayed instances is a transient * menu. *
* To understand how the diffent kind of menus are created lets look * at some user actions: * * * The user clicks on an item which is not a submenu.
* The item is highlighted until the action corresponding with * the item is completed. More precisely, the application * highlights the menu item, performs the action, and * unhighlights the item. * The user clicks on a submenu item which is not highlighted * already
If the submenu is not a detached menu, the * submenu will become an attached menu to the menu that is * clicked in. The item that is clicked in will * become highlighted and stays highlighted. *

If the submenu is a detached menu, the transient version * of the submenu will be shown

 * The user clicks on a submenu item which is highlighted
* This means that the submenu is an attached submenu for this * menu. After clicking the submenu item will no be no longer * highlighted and the submenu will be removed from the screen. * The user drags over a menu item
* The item will be highlighted, if the item is a submenu item, * the submenu will be shown as an attached submenu. This can * be transient, or non transient. * * *
* Customizing the look of Menus *
* * There are basically three ways of customizing the look of NSMenu * * Using custom NSMenuItemCell's. This you should do when you * want to influence the look of the items displayed in the * menu. * Using custom NSMenuView. This is the class to modify if * you want to change the way the menu is layout on the screen. * So if you want to stack the menu items horizontally, you * should change this class. This should be rarely needed. * Reimplement NSMenu. This you should not do. But, if you * implement everything yourself you can achieve anything. * * *
* Information for implementing custom NSMenuView class *
* When implementing a custom NSMenuView class it is important * to keep the following information in mind. * * * The menus (or the menu items) form a tree. Navigating * through this tree is done with the methods * [NSMenu-supermenu], which returns the parent menu * of the receiver, and with [NSMenu-itemAtIndex:] which returns * a NSMenuItem on which we can call [(NSMenuItem)-submenu] for * a child menu. * The menus as displayed on the screen do NOT form a tree. * This because detached and transient menus lead to duplicate * menus on the screen. * * * The displayed menus on the screen have the following structure: * * The ordered graph of displayed menus (note, NOT the set of * NSMenus) form a collection of line graphs. * The attached menus are precisely the non root vertices in * this graph. * An attached menu of a transient menu is itself a transient * menu. * The collection of transient menus form connect subgraph of * the menu graph. * * */ @interface NSMenu : NSObject { NSString *_title; NSMutableArray *_items; NSView* _view; NSMenu *_superMenu; NSMenu *_attachedMenu; NSMutableArray *_notifications; id _delegate; // GNUstepExtra category NSPopUpButtonCell *_popUpButtonCell; struct GSMenuFlags { unsigned int changedMessagesEnabled: 1; unsigned int autoenable: 1; unsigned int needsSizing: 1; unsigned int is_tornoff: 1; unsigned int transient: 1; unsigned int horizontal: 1; unsigned int mainMenuChanged: 1; unsigned int unused: 25; } _menu; @private NSWindow *_aWindow; NSWindow *_bWindow; NSMenu *_oldAttachedMenu; int _oldHiglightedIndex; NSString *_name; } /** Returns the memory allocation zone used to create instances of this class. */ + (NSZone*) menuZone; /** Specifies the memory allocation zone used to create instances of this class. */ + (void) setMenuZone: (NSZone*)zone; + (void) popUpContextMenu: (NSMenu*)menu withEvent: (NSEvent*)event forView: (NSView*)view; #if OS_API_VERSION(MAC_OS_X_VERSION_10_3, GS_API_LATEST) + (void) popUpContextMenu: (NSMenu *)menu withEvent: (NSEvent *)event forView: (NSView *)view withFont: (NSFont *)font; #endif #if OS_API_VERSION(MAC_OS_X_VERSION_10_2, GS_API_LATEST) + (BOOL) menuBarVisible; + (void) setMenuBarVisible: (BOOL)flag; #endif /** Add newItem to the menu. */ - (void) addItem: (id )newItem; /** Prefered method for inserting a menu item. This method calls * [NSMenu-insertItemWithTitle:-action:-keyEquivalent:-atIndex:] * * aString * The title of the specific menu item. * aSelector * The action taken by selecting this menu item, or NULL. * keyEquiv * The shortcut key for this menu item. If none is needed, * specify and empty NSString, ie: @"". * *

See Also: -insertItemWithTitle:-action:-keyEquivalent:-atIndex

*/ - (id ) addItemWithTitle: (NSString *)aString action: (SEL)aSelector keyEquivalent: (NSString *)keyEquiv; /** Returns the menu that is attached to this menu. *

* If two instances of this menu are visible, * return the attached window of the transient version * of this menu.

*

* If no menu is attached return nil.

*/ - (NSMenu*) attachedMenu; /** Returns YES if item does autoenable (default value) and NO otherwise. *

See Also: *

* * -setAutoenablesItems: * */ - (BOOL) autoenablesItems; #if OS_API_VERSION(MAC_OS_X_VERSION_10_0, MAC_OS_X_VERSION_10_1) - (id) contextMenuRepresentation; #endif #if OS_API_VERSION(MAC_OS_X_VERSION_10_3, GS_API_LATEST) - (id) delegate; #endif /* Displaying Context-Sensitive Help */ - (void) helpRequested: (NSEvent*)event; /** Returns the index of item anObject. */ - (NSInteger) indexOfItem: (id )anObject; /** Returns the index of an item with the tag aTag. */ - (NSInteger) indexOfItemWithTag: (NSInteger)aTag; /** Returns the index of an item with the target anObject * and the actionSelector. */ - (NSInteger) indexOfItemWithTarget: (id)anObject andAction: (SEL)actionSelector; /** Returns the index of an item with the represented object anObject. */ - (NSInteger) indexOfItemWithRepresentedObject: (id)anObject; /** Returns the index of an item with the submenu anObject. */ - (NSInteger) indexOfItemWithSubmenu: (NSMenu *)anObject; /** Returns the index of an item with the title aTitle. */ - (NSInteger) indexOfItemWithTitle: (NSString *)aTitle; /** */ - (id) initWithTitle: (NSString*)aTitle; /** Insert newItem at position index. */ - (void) insertItem: (id )newItem atIndex: (NSInteger)index; /** Inserts a new menu item at position index. *

See Also: *

* * -addItemWithTitle:-action:-keyEquivalent-atIndex: * */ - (id ) insertItemWithTitle: (NSString *)aString action: (SEL)aSelector keyEquivalent: (NSString *)charCode atIndex: (NSInteger)index; /** Returns if this menu is attached to its supermenu, * return nil if it does not have a parent menu. *

* If two instances of this menu are visible, return * the outcome of the check for the transient version * of the menu.

*/ - (BOOL) isAttached; /** If there are two instances of this menu visible, return NO. * Otherwise, return YES if we are a detached menu and visible. */ - (BOOL) isTornOff; /** * Returns an array containing all menu items in this menu. */ - (NSArray*) itemArray; /** Returns an item located at index. */ - (NSMenuItem *) itemAtIndex: (NSInteger)index; /** Informs the menu that the specified item has changed. */ - (void) itemChanged: (id )anObject; /** Retuns an item referenced by aTag. *

See Also: *

* * -indexOfItemWithTag: * [(NSMenuItem)-tag] * */ - (id ) itemWithTag: (NSInteger)aTag; /** Returns an item with aString as its title. */ - (id ) itemWithTitle: (NSString*)aString; /** Returns the position where submenu will be displayed * when it will be displayed as an attached menu of this menu. * The result is undefined when aSubmenu is not actually a submenu * of this menu. */ - (NSPoint) locationForSubmenu: (NSMenu*)aSubmenu; #if OS_API_VERSION(MAC_OS_X_VERSION_10_4, GS_API_LATEST) - (float)menuBarHeight; #endif - (BOOL) menuChangedMessagesEnabled; /** Return the NSView that is used for drawing * the menu. * It is the view set with [NSMenu-setMenuRepresentation:] and * therefore it should be safe to assume it is an NSView * implementing the NSMenuView protocol. */ - (id) menuRepresentation; /** Returns the numbers of items on the menu */ - (NSInteger) numberOfItems; /** Simulates a mouse click on item located at index. *

See Also: *

* * -indexOfItem: * -indexOfItemWithTitle: * */ - (void) performActionForItemAtIndex: (NSInteger)index; /** Looks for a menu item that responds to theEvent on the receiver. If * the receiver is a submenu, the method is performed on it. */ - (BOOL) performKeyEquivalent: (NSEvent*)theEvent; /** Calls -removeItemAtIndex: for anItem. */ - (void) removeItem: (id )anItem; /** Removes item at position index. */ - (void) removeItemAtIndex: (NSInteger)index; /** Sets if a menu does autoenable. */ - (void) setAutoenablesItems: (BOOL)flag; #if OS_API_VERSION(MAC_OS_X_VERSION_10_0, MAC_OS_X_VERSION_10_1) - (void) setContextMenuRepresentation: (id)representation; #endif #if OS_API_VERSION(MAC_OS_X_VERSION_10_3, GS_API_LATEST) - (void) setDelegate:(id) delegate; #endif - (void) setMenuChangedMessagesEnabled: (BOOL)flag; /** Set the View that should be used to display the menu. *

* The default is NSMenuView, but a user can supply its * own NSView object as long as it *

* * Inherits from NSView * Implements NSMenuView protocol * */ - (void) setMenuRepresentation: (id) menuRep; /** Set a submenu of a menu. * * aMenu * The submenu to be inserted. * anItem * Item to be turned into a submenu. * *

See Also: *

* * [(NSMenuItem)-setSubmenu:] * */ - (void) setSubmenu: (NSMenu*)aMenu forItem: (id )anItem; /** Set the supermenu of this menu. * TODO: add explanation if this will change remove this menu * from the old supermenu or if it does not. */ - (void) setSupermenu: (NSMenu *)supermenu; #if OS_API_VERSION(MAC_OS_X_VERSION_10_0, MAC_OS_X_VERSION_10_1) - (void) setTearOffMenuRepresentation: (id)representation; #endif /** Change the title of the menu. */ - (void) setTitle: (NSString*)aTitle; - (void) sizeToFit; - (void) submenuAction: (id)sender; /** Returns the supermenu of this menu. Return nil * if this is the application menu. */ - (NSMenu*) supermenu; #if OS_API_VERSION(MAC_OS_X_VERSION_10_0, MAC_OS_X_VERSION_10_1) - (id) tearOffMenuRepresentation; #endif /** Returns the current title. */ - (NSString*) title; - (void) update; @end /** * Specifies the protocol to which an object must confirm if it is to be * used to validate menu items (in order to implement automatic enabling * and disabling of menu items). */ @protocol NSMenuValidation /**

The receiver should return YES if the menuItem is valid ... and should * be enabled in the menu, NO if it is invalid and the user should not be * able to select it.

*

This method is invoked automatically to determine whether menu items * should be enabled or disabled automatically whenever [NSMenu-update] is * invoked (usually by the applications event loop).

*/ - (BOOL) validateMenuItem: (id)menuItem; @end #if OS_API_VERSION(MAC_OS_X_VERSION_10_3, GS_API_LATEST) @interface NSObject (NSMenuDelegate) - (void) menuNeedsUpdate: (NSMenu *)menu; - (NSInteger) numberOfItemsInMenu: (NSMenu *)menu; - (BOOL) menu: (NSMenu *)menu updateItem: (NSMenuItem *)item atIndex: (NSInteger)index shouldCancel: (BOOL)shouldCancel; - (BOOL) menuHasKeyEquivalent: (NSMenu *)menu forEvent: (NSEvent *)event target: (id *)target action: (SEL *)action; @end #endif #if OS_API_VERSION(GS_API_NONE, GS_API_NONE) @interface NSObject (NSMenuActionResponder) - (BOOL) validateMenuItem: (id)aMenuItem; @end /** This interface exist contains methods that are meant * for the NSMenuView. If you write your own implementation * of the NSMenuView interface you can use these methods * to popup other menus or close them. */ @interface NSMenu (GNUstepExtra) /** Remove the window from the screen. This method can/should be * used by the menurepresentation to remove a submenu from the screen. */ - (void) close; /** Remove the transient version of the window from the screen. * This method is used by NSMenuView implementations that need * to open/close transient menus. */ - (void) closeTransient; /** Show menu on the screen. This method can/should be used by * the menurepresentation to display a submenu on the screen. */ - (void) display; /** Display the transient version of the menu. */ - (void) displayTransient; - (BOOL) isPartlyOffScreen; /** Returns YES if there is a transient version * of this menu displayed on the screen. */ - (BOOL) isTransient; /* Moving menus */ - (void) nestedSetFrameOrigin: (NSPoint)aPoint; /** Flag this menu to be the main menu of the application, * when isMain is YES. Flag it as no longer being the main * menu when NO is handed in. *

This method also checks the user defaults to determine how * the menu is to be displayed (eg vertical or horizontal) and can * therefore be used to change window geometry.

*/ - (void) setMain: (BOOL)isMain; /** When the flag is YES * this method will detach the receiver from its parent and * update the menurepresentation so it will display a close * button if appropriate. *

* If the flag is NO this method will update the menurepresentation * so it will be able to remove the close button if needed. * Note that it will not reattach to its parent menu.

*/ - (void) setTornOff: (BOOL) flag; /* Shift partly off-screen menus */ - (void) shiftOnScreen; /** Returns the window in which this menu is displayed. * If there is a transient version it will return the * window in which the transient version is displayed. * If the Menu is not displayed at all the result * is meaningless. */ - (NSWindow*) window; /* Popup behaviour */ - (BOOL) _ownedByPopUp; - (NSPopUpButtonCell *)_owningPopUp; - (void) _setOwnedByPopUp: (NSPopUpButtonCell*)popUp; @end #endif APPKIT_EXPORT NSString* const NSMenuDidSendActionNotification; APPKIT_EXPORT NSString* const NSMenuWillSendActionNotification; APPKIT_EXPORT NSString* const NSMenuDidAddItemNotification; APPKIT_EXPORT NSString* const NSMenuDidRemoveItemNotification; APPKIT_EXPORT NSString* const NSMenuDidChangeItemNotification; APPKIT_EXPORT NSString* const NSMenuDidBeginTrackingNotification; APPKIT_EXPORT NSString* const NSMenuDidEndTrackingNotification; #endif // _GNUstep_H_NSMenu