diff --git a/ChangeLog b/ChangeLog index eaded89a3..a4b1acc95 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,13 @@ +2007-01-24 Richard Frith-Macdoanld + + * Headers/AppKit/NSButtonCell.h: Fix documentation error. + * Headers/AppKit/NSMenu.h: Tidy a litte, fix errors in documentation + markup, fix some documentation cross references. + +2007-01-24 Stefan Bidigaray + + * Headers/AppKit/NSMenu.h: Add documentation (patch #5705). + 2007-01-23 Fred Kiefer * Source/NSTableView.m (-selectAll:, -deselectAll:) Call diff --git a/Headers/AppKit/NSButtonCell.h b/Headers/AppKit/NSButtonCell.h index 1d5dfd24e..1ca8f0236 100644 --- a/Headers/AppKit/NSButtonCell.h +++ b/Headers/AppKit/NSButtonCell.h @@ -67,6 +67,7 @@ * NSMomentaryPushButton * Same as NSMomentaryLightButton. Has been depricated in * Cocoa. + * */ typedef enum _NSButtonType { NSMomentaryLightButton, diff --git a/Headers/AppKit/NSMenu.h b/Headers/AppKit/NSMenu.h index ad9070838..fc24a78c2 100644 --- a/Headers/AppKit/NSMenu.h +++ b/Headers/AppKit/NSMenu.h @@ -45,328 +45,288 @@ @class NSWindow; @class NSMutableArray; - +/* ******************* */ +/* 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. +/** 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. +- (void) setMenu: (NSMenu *)menu; - 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. +/** 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: (int)index; - A value of -1 means that no item will be highlighted. -*/ -- (void)setHighlightedItemIndex:(int)index; -/** - Returns the currently highlighted item. Returns -1 - if no item is highlighted. -*/ -- (int)highlightedItemIndex; +/** Returns the currently highlighted item. Returns -1 + * if no item is highlighted. + */ +- (int) 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. -*/ +/** 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. +/** 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; - It should be called when the menu changes. Changes include - becoming detached, adding or removing submenu items etcetera. +/** Hm, why is this method needed? Shouldn't this be done by + * the update method? + */ +- (void) sizeToFit; //!!! - 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. +/** 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; - It should be called explicitly when other changes occur, such as - becoming detached or changing the title. -*/ -- (void)update; +/** Used by the NSMenu to determine where to position a + * submenu. + */ +- (NSPoint) locationForSubmenu: (NSMenu *)aSubmenu; -/** - Hm, why is this method needed? Shouldn't this be done by - the update method? -*/ -- (void)sizeToFit; //!!! +- (void) performActionWithHighlightingForItemAtIndex: (int)index; //???? -/** - 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:(int)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; +/**

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 - - -/** -

-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. - - -*/ +/**

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; @@ -393,156 +353,252 @@ The displayed menus on the screen have the following structure: int _oldHiglightedIndex; } -/* Controlling Allocation Zones */ -+ (void) setMenuZone: (NSZone*)zone; +/** Returns the memory allocation zone used to create instances of this class. + */ + (NSZone*) menuZone; - -/** - * - * - */ - -- (id) initWithTitle: (NSString*)aTitle; - -/* Setting Up the Menu Commands */ -- (void) addItem: (id )newItem; -- (id ) addItemWithTitle: (NSString *)aString - action: (SEL)aSelector - keyEquivalent: (NSString *)keyEquiv; -- (void) insertItem: (id )newItem - atIndex: (int)index; -- (id ) insertItemWithTitle: (NSString *)aString - action: (SEL)aSelector - keyEquivalent: (NSString *)charCode - atIndex: (unsigned int)index; -- (void) itemChanged: (id )anObject; -- (void) removeItem: (id )anItem; -- (void) removeItemAtIndex: (int)index; - -/* Finding menu items */ -/** - * Returns an array containing all menu items in this menu. - */ -- (NSArray*) itemArray; -- (id ) itemAtIndex: (int)index; -- (id ) itemWithTag: (int)aTag; -- (id ) itemWithTitle: (NSString*)aString; -- (int) numberOfItems; - -/* Finding Indices of Menu Items */ -- (int) indexOfItem: (id )anObject; -- (int) indexOfItemWithTitle: (NSString *)aTitle; -- (int) indexOfItemWithTag: (int)aTag; -- (int) indexOfItemWithTarget: (id)anObject - andAction: (SEL)actionSelector; -- (int) indexOfItemWithRepresentedObject: (id)anObject; -- (int) indexOfItemWithSubmenu: (NSMenu *)anObject; - -/* Managing submenus */ -- (void) setSubmenu: (NSMenu*)aMenu forItem: (id )anItem; -- (void) submenuAction: (id)sender; - -/** - 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 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 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; -/** - Returns the supermenu of this menu. Return nil - if this is the application menu. -*/ -- (NSMenu*) supermenu; -/** - 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; - -/* Enabling and disabling menu items */ -- (BOOL) autoenablesItems; -- (void) setAutoenablesItems: (BOOL)flag; -- (void) update; - -/* Handling keyboard equivalents */ -- (BOOL) performKeyEquivalent: (NSEvent*)theEvent; - -/* Simulating Mouse Clicks */ -- (void) performActionForItemAtIndex: (int)index; - -/** - Change the title of the menu. -*/ -- (void) setTitle: (NSString*)aTitle; -/** - Returns the current title. -*/ -- (NSString*) title; - -/** - 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; -/** - 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; - -/* Updating Menu Layout */ -- (void) setMenuChangedMessagesEnabled: (BOOL)flag; -- (BOOL) menuChangedMessagesEnabled; -- (void) sizeToFit; - -/* Displaying Context-Sensitive Help */ -- (void) helpRequested: (NSEvent*)event; - + (void) popUpContextMenu: (NSMenu*)menu withEvent: (NSEvent*)event forView: (NSView*)view; +/** Specifies the memory allocation zone used to create instances of this class. + */ ++ (void) setMenuZone: (NSZone*)zone; + + +/** 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; + +/* Displaying Context-Sensitive Help */ +- (void) helpRequested: (NSEvent*)event; + +/** Returns the index of item anObject. + */ +- (int) indexOfItem: (id )anObject; + +/** Returns the index of an item with the tag aTag. + */ +- (int) indexOfItemWithTag: (int)aTag; + +/** Returns the index of an item with the target anObject + * and the actionSelector. + */ +- (int) indexOfItemWithTarget: (id)anObject + andAction: (SEL)actionSelector; + +/** Returns the index of an item with the represented object anObject. + */ +- (int) indexOfItemWithRepresentedObject: (id)anObject; + +/** Returns the index of an item with the submenu anObject. + */ +- (int) indexOfItemWithSubmenu: (NSMenu *)anObject; + +/** Returns the index of an item with the title aTitle. + */ +- (int) indexOfItemWithTitle: (NSString *)aTitle; + +/** + */ +- (id) initWithTitle: (NSString*)aTitle; + +/** Insert newItem at position index. + */ +- (void) insertItem: (id )newItem + atIndex: (int)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: (unsigned int)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. + */ +- (id ) itemAtIndex: (int)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: (int)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; + +- (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 + */ +- (int) numberOfItems; + +/** Simulates a mouse click on item located at index. + *

See Also: + *

+ * + * -indexOfItem: + * -indexOfItemWithTitle: + * + */ +- (void) performActionForItemAtIndex: (int)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: (int)index; + +/** Sets if a menu does autoenable. + */ +- (void) setAutoenablesItems: (BOOL)flag; + +- (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; + +/** 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; + +/** Returns the current title. + */ +- (NSString*) title; + +- (void) update; + @end @@ -553,15 +609,12 @@ The displayed menus on the screen have the following structure: */ @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). - *

+/**

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 @@ -571,83 +624,74 @@ The displayed menus on the screen have the following structure: - (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. -*/ +/** 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) -/** - Returns YES if there is a transient version - of this menu displayed on the screen. -*/ -- (BOOL) isTransient; -/** - 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; - -/** -

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

+/** Remove the window from the screen. This method can/should be + * used by the menurepresentation to remove a submenu from the screen. */ -- (void) setMain: (BOOL)isMain; +- (void) close; -/* Shows the menu window on screen */ -/** - Show menu on the screen. This method can/should be used by - the menurepresentation to display a submenu on the screen. - */ +/** 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. -*/ + +/** Display the transient version of the menu. + */ - (void) displayTransient; -/** - 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. +- (BOOL) isPartlyOffScreen; - 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; - - -/** - 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; +/** 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 */ -- (BOOL) isPartlyOffScreen; - (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; - (void) _setOwnedByPopUp: (NSPopUpButtonCell*)popUp;