This file is indexed.

/usr/include/GNUstep/AppKit/NSMenu.h is in libgnustep-gui-dev 0.25.0-4+b1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
/* 
   NSMenu.h

   Copyright (C) 1996 Free Software Foundation, Inc.

   Author:  Ovidiu Predescu <ovidiu@net-community.com>
   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 <http://www.gnu.org/licenses/> 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 <GNUstepBase/GSVersionMacros.h>

#import <Foundation/NSObject.h>
#import <Foundation/NSGeometry.h>

#import <AppKit/NSMenuItem.h>
#import <AppKit/AppKitDefines.h>

@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; //????

/** <p>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.
 *  </p>
 *  <p>The method returns when the interaction from the user with the
 *  menu system is over.
 *  </p>
 *  <p>The method returns NO when the user releases the mouse button
 *  above a submenu item and  YES in all other cases.
 *  </p>
 *  <p>This return value can be used to determine if submenus should
 *  be removed from the screen or that they are supposed to stay.
 *  </p>
 *  <p>The implementation should roughly follow the following logic:
 *  </p>
 *  <code>
 *  {
 *    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;
 *  }
 *  </code>
 *
 *  Note that actual implementations tend to be more complicated because
 *  because of all kind of useability issues.   Useabilities issues to
 *  look out for are:
 *  <list>
 *   <item>Menus that are only partly on the screen.  Those need to be 
 *         moved while navigation the menu.</item>
 *   <item>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.</item>
 *   <item>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.</item>
 *  </list>
 */
- (BOOL) trackWithEvent: (NSEvent *)event;

@end

/**
 * The NSMenuDelegate protocol defines optional methods implemented
 * by delegates of NSMenu objects.
 */
@protocol NSMenuDelegate <NSObject>

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

/** <p>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.</p>
 *  <p>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, <em>info</em>, 
 *  <em>services</em>, <em>print</em>, <em>hide</em> and <em>quit</em>.</p>
 *  <p>After the <em>info</em> item normally some submenus follow containing
 *  the application specific actions.</p>
 *  <p>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.</p>
 *  <p>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.</p>
 *  <p>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.</p>
 *  <deflist>
 *   <term>Application menu</term>
 *    <desc>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.</desc>
 *   <term>Attached menu</term>
 *    <desc>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 <em>attached</em> menu.   It is 
 *          attached to the menu that was clicked in.</desc>
 *   <term>Detached menu</term>
 *    <desc>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.</desc>
 *   <term>Transient menu</term>
 *    <desc>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.
 *          <p>It is important to note that it is impossible to click 
 *          in transient menus.</p></desc>
 *   <term>Attached transient menu</term>
 *    <desc>This is a menu that is attached and transient at the same 
 *          time.</desc>
 *  </deflist>
 *
 *  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.
 *  <br/>
 *  To understand how the diffent kind of menus are created lets look 
 *  at some user actions:
 *
 *  <list>
 *   <item>The user clicks on an item which is not a submenu.<br/>
 *         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.</item>
 *   <item>The user clicks on a submenu item which is not highlighted 
 *         already<br/> 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.
 *         <p>If the submenu is a detached menu, the transient version
 *         of the submenu will be shown</p></item>
 *   <item>The user clicks on a submenu item which is highlighted<br/>
 *         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.</item>
 *   <item>The user drags over a menu item<br/>
 *         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.</item>
 *  </list>
 *
 *  <br/>
 *  <strong>Customizing the look of Menus</strong>
 *  <br/>
 *
 *  There are basically three ways of customizing the look of NSMenu
 *  <enum>
 *   <item>Using custom NSMenuItemCell's.  This you should do when you 
 *         want to influence the look of the items displayed in the 
 *         menu.</item>
 *   <item>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.</item>
 *   <item>Reimplement NSMenu.  This you should not do. But, if you 
 *         implement everything yourself you can achieve anything.</item>
 *  </enum>
 *
 *  <br/>
 *  <strong>Information for implementing custom NSMenuView class</strong>
 *  <br/>
 *  When implementing a custom NSMenuView class it is important
 *  to keep the following information in mind.
 *
 *  <list>
 *   <item>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.</item>
 *   <item>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.</item>
 *  </list>
 *
 *  The displayed menus on the screen have the following structure:
 *  <enum>
 *   <item>The ordered graph of displayed menus (note, NOT the set of 
 *         NSMenus) form a collection of line graphs.</item>
 *   <item>The attached menus are precisely the non root vertices in 
 *         this graph.</item>
 *   <item>An attached menu of a transient menu is itself a transient 
 *         menu.</item>
 *   <item>The collection of transient menus form connect subgraph of 
 *         the menu graph.</item>
 *  </enum>
 *
 */
@interface NSMenu : NSObject <NSCoding, NSCopying>
{
  NSString *_title;
  NSMutableArray *_items;
  NSView<NSMenuView>* _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 <NSMenuItem>)newItem;

/** Prefered method for inserting a menu item.  This method calls 
 *  [NSMenu-insertItemWithTitle:-action:-keyEquivalent:-atIndex:]
 *  <deflist>
 *   <term>aString</term>
 *    <desc>The title of the specific menu item.</desc>
 *   <term>aSelector</term>
 *    <desc>The action taken by selecting this menu item, or NULL.</desc>
 *   <term>keyEquiv</term>
 *    <desc>The shortcut key for this menu item.  If none is needed, 
 *          specify and empty NSString, ie: @"".</desc>
 *  </deflist>
 *  <p>See Also: -insertItemWithTitle:-action:-keyEquivalent:-atIndex</p>
 */
- (id <NSMenuItem>) addItemWithTitle: (NSString *)aString
                              action: (SEL)aSelector
                       keyEquivalent: (NSString *)keyEquiv;

/** Returns the menu that is attached to this menu.  
 *  <p>
 *  If two instances of this menu are visible,
 *  return the attached window of the transient version
 *  of this menu.</p>
 *  <p>
 *  If no menu is attached return nil.</p>
 */
- (NSMenu*) attachedMenu;

/** Returns YES if item does autoenable (default value) and NO otherwise.
 *  <p>See Also:
 *  </p>
 *  <list>
 *   <item>-setAutoenablesItems:</item>
 *  </list>
 */
- (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 <NSMenuItem>)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;

/** <init/>
 */
- (id) initWithTitle: (NSString*)aTitle;

/** Insert newItem at position index.
 */
- (void) insertItem: (id <NSMenuItem>)newItem
            atIndex: (NSInteger)index;

/** Inserts a new menu item at position index.
 *  <p>See Also: 
 *  </p>
 *  <list>
 *   <item>-addItemWithTitle:-action:-keyEquivalent-atIndex:</item>
 *  </list>
 */
- (id <NSMenuItem>) 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.
 *  <p>
 *  If two instances of this menu are visible, return
 *  the outcome of the check for the transient version
 *  of the menu.</p>
 */
- (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 <NSMenuItem>)anObject;

/** Retuns an item referenced by aTag.
 *  <p>See Also:
 *  </p>
 *  <list>
 *   <item>-indexOfItemWithTag:</item>
 *   <item>[(NSMenuItem)-tag]</item>
 *  </list>
 */
- (id <NSMenuItem>) itemWithTag: (NSInteger)aTag;

/** Returns an item with aString as its title.
 */
- (id <NSMenuItem>) 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.
 *  <p>See Also:
 *  </p>
 *  <list>
 *   <item>-indexOfItem:</item>
 *   <item>-indexOfItemWithTitle:</item>
 *  </list>
 */
- (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 <NSMenuItem>)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.
 *  <p>
 *  The default is NSMenuView, but a user can supply its
 *  own NSView object as long as it
 *  </p>
 *  <list>
 *   <item>Inherits from NSView</item>
 *   <item>Implements NSMenuView protocol</item>
 *  </list>
 */
- (void) setMenuRepresentation: (id) menuRep;

/** Set a submenu of a menu.
 *  <deflist>
 *   <term>aMenu</term>
 *    <desc>The submenu to be inserted.</desc>
 *   <term>anItem</term>
 *    <desc>Item to be turned into a submenu.</desc>
 *  </deflist>
 *  <p>See Also:
 *  </p>
 *  <list>
 *   <item>[(NSMenuItem)-setSubmenu:]</item>
 *  </list>
 */
- (void) setSubmenu: (NSMenu*)aMenu forItem: (id <NSMenuItem>)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
/** <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

#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<NSMenuItem>)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.
 *  <p>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.</p>
 */
- (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.
 *  <p>
 *  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.</p>
 */
- (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