iAdded some documentation and a protocol

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/gui/trunk@14867 72102866-910b-0410-8b05-ffd578937521

ChangeLog

@@ -4,6 +4,8 @@
 	* Headers/gnustep/gui/PSOperators.h:
 	Add const qualifier to PSPrintf and PSWriteData argument types to
 	match all other declatrations.
+	* Headers/gnustep/gui/NSMenu.h: Add and document validation protocol.
+	* Headers/gnustep/gui/NSMenuItem.h: Add some documentation and tidy.
 
 2002-10-28  Adam Fedor  <fedor@gnu.org>
 

Headers/gnustep/gui/NSMenu.h

@@ -149,36 +149,54 @@
 @end
 
 
-@interface NSObject (NSMenuActionResponder)
-
-- (BOOL)validateMenuItem:(NSMenuItem*)aMenuItem;
+/**
+ * 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
+/**
+ * <p>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.
+ * </p>
+ * <p>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).
+ * </p>
+ */
+- (BOOL) validateMenuItem: (id<NSMenuItem>)menuItem;
 @end
 
 #ifndef	NO_GNUSTEP
+@interface NSObject (NSMenuActionResponder)
+- (BOOL) validateMenuItem: (NSMenuItem*)aMenuItem;
+@end
+
 @interface NSMenu (GNUstepExtra)
-- (BOOL)isFollowTransient;
-- (NSWindow *)window;
+- (BOOL) isFollowTransient;
+- (NSWindow*) window;
 
 /* Shows the menu window on screen */
-- (void)display;
-- (void)displayTransient;
+- (void) display;
+- (void) displayTransient;
 
 /* Close the associated window menu */
-- (void)close;
-- (void)closeTransient;
+- (void) close;
+- (void) closeTransient;
 
 /* Moving menus */
-- (void)nestedSetFrameOrigin:(NSPoint)aPoint;
+- (void) nestedSetFrameOrigin: (NSPoint)aPoint;
 
 /* Shift partly off-screen menus */
-- (BOOL)isPartlyOffScreen;
-- (void)nestedCheckOffScreen;
-- (void)shiftOnScreen;
+- (BOOL) isPartlyOffScreen;
+- (void) nestedCheckOffScreen;
+- (void) shiftOnScreen;
 
 /* Popup behaviour */
-- (BOOL)_ownedByPopUp;
-- (void)_setOwnedByPopUp: (NSPopUpButtonCell*)popUp;
+- (BOOL) _ownedByPopUp;
+- (void) _setOwnedByPopUp: (NSPopUpButtonCell*)popUp;
 
 /* Show menu on right mouse down */
 - (void) _rightMouseDisplay: (NSEvent*)theEvent;

Headers/gnustep/gui/NSMenuItem.h

@@ -37,66 +37,58 @@
 @class NSMenu;
 @class NSImage;
 
+/**
+ * Specifies the methods that an object must implement if it is to be
+ * placed in a menu as a menu item.  The [NSMenuItem] class provides
+ * a reference implementation suitable for most uses.
+ */
 @protocol NSMenuItem <NSCopying, NSCoding>
 
-+ (void)setUsesUserKeyEquivalents:(BOOL)flag;
-+ (BOOL)usesUserKeyEquivalents;
++ (id<NSMenuItem>) separatorItem;
++ (void) setUsesUserKeyEquivalents: (BOOL)flag;
++ (BOOL) usesUserKeyEquivalents;
 
-+ (id <NSMenuItem>)separatorItem;
-
-- (id)initWithTitle:(NSString *)aString
-	     action:(SEL)aSelector
-      keyEquivalent:(NSString *)charCode;
-
-- (void)setMenu:(NSMenu *)menu;
-- (NSMenu *)menu;
-
-- (BOOL)hasSubmenu;
-- (void)setSubmenu:(NSMenu *)submenu;
-- (NSMenu *)submenu;
-
-- (void)setTitle:(NSString*)aString;
-- (NSString*)title;
-- (BOOL)isSeparatorItem;
-
-- (void)setKeyEquivalent:(NSString*)aKeyEquivalent;
-- (NSString*)keyEquivalent;
-- (void)setKeyEquivalentModifierMask:(unsigned int)mask;
-- (unsigned int)keyEquivalentModifierMask;
-
-- (NSString*)userKeyEquivalent;
-- (unsigned int)userKeyEquivalentModifierMask;
-
-- (void)setMnemonicLocation:(unsigned) location;
-- (unsigned)mnemonicLocation;
-- (NSString *)mnemonic;
-- (void)setTitleWithMnemonic:(NSString *)stringWithAmpersand;
-
-- (void)setImage:(NSImage *)menuImage;
-- (NSImage *)image;
-
-- (void)setState:(int)state;
-- (int)state;
-- (void)setOnStateImage:(NSImage *)image;
-- (NSImage *)onStateImage;
-- (void)setOffStateImage:(NSImage *)image;
-- (NSImage *)offStateImage;
-- (void)setMixedStateImage:(NSImage *)image;
-- (NSImage *)mixedStateImage;
-
-- (void)setEnabled:(BOOL)flag;
-- (BOOL)isEnabled;
-
-- (void)setTarget:(id)anObject;
-- (id)target;
-- (void)setAction:(SEL)aSelector;
-- (SEL)action;
-
-- (void)setTag:(int)anInt;
-- (int)tag;
-
-- (void)setRepresentedObject:(id)anObject;
-- (id)representedObject;
+- (SEL) action;
+- (BOOL) hasSubmenu;
+- (NSImage*) image;
+- (id) initWithTitle: (NSString*)aString
+	      action: (SEL)aSelector
+       keyEquivalent: (NSString*)charCode;
+- (BOOL) isEnabled;
+- (BOOL) isSeparatorItem;
+- (NSString*) keyEquivalent;
+- (unsigned int) keyEquivalentModifierMask;
+- (NSMenu*) menu;
+- (NSImage*) mixedStateImage;
+- (NSString*) mnemonic;
+- (unsigned) mnemonicLocation;
+- (NSImage*) offStateImage;
+- (NSImage*) onStateImage;
+- (id) representedObject;
+- (void) setAction: (SEL)aSelector;
+- (void) setEnabled: (BOOL)flag;
+- (void) setImage: (NSImage*)menuImage;
+- (void) setKeyEquivalent: (NSString*)aKeyEquivalent;
+- (void) setKeyEquivalentModifierMask: (unsigned int)mask;
+- (void) setMenu: (NSMenu*)menu;
+- (void) setMixedStateImage: (NSImage*)image;
+- (void) setMnemonicLocation: (unsigned) location;
+- (void) setOffStateImage: (NSImage*)image;
+- (void) setOnStateImage: (NSImage*)image;
+- (void) setRepresentedObject: (id)anObject;
+- (void) setState: (int)state;
+- (void) setSubmenu: (NSMenu*)submenu;
+- (void) setTag: (int)anInt;
+- (void) setTarget: (id)anObject;
+- (void) setTitle: (NSString*)aString;
+- (void) setTitleWithMnemonic: (NSString*)stringWithAmpersand;
+- (int) state;
+- (NSMenu*) submenu;
+- (int) tag;
+- (id) target;
+- (NSString*) title;
+- (unsigned int) userKeyEquivalentModifierMask;
+- (NSString*) userKeyEquivalent;
 
 @end
 
@@ -123,12 +115,12 @@
 
 @end
 
+#ifndef	NO_GNUSTEP
 @interface NSMenuItem (GNUstepExtra)
-
-- (void)setChangesState:(BOOL)flag;
-- (BOOL)changesState;
-
+- (void) setChangesState: (BOOL)flag;
+- (BOOL) changesState;
 @end
+#endif
 
 #endif // _GNUstep_H_NSMenuItem