src/menubar.c

   1 /* Implements an elisp-programmable menubar.
   2    Copyright (C) 1993, 1994 Free Software Foundation, Inc.
   3    Copyright (C) 1995 Tinker Systems and INS Engineering Corp.
   4
   5 This file is part of XEmacs.
   6
   7 XEmacs is free software; you can redistribute it and/or modify it
   8 under the terms of the GNU General Public License as published by the
   9 Free Software Foundation; either version 2, or (at your option) any
  10 later version.
  11
  12 XEmacs is distributed in the hope that it will be useful, but WITHOUT
  13 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  14 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15 for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with XEmacs; see the file COPYING.  If not, write to
  19 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20 Boston, MA 02111-1307, USA.  */
  21
  22 /* Synched up with: Not in FSF. */
  23
  24 /* Authorship:
  25
  26    Created by Ben Wing as part of device-abstraction work for 19.12.
  27    Menu filters and many other keywords added by Stig for 19.12.
  28    Menu accelerators c. 1997? by ??.  Moved here from event-stream.c.
  29    Much other work post-1996 by ??.
  30 */
  31
  32 #include <config.h>
  33 #include "lisp.h"
  34
  35 #include "buffer.h"
  36 #include "device.h"
  37 #include "frame.h"
  38 #include "gui.h"
  39 #include "keymap.h"
  40 #include "menubar.h"
  41 #include "redisplay.h"
  42 #include "window.h"
  43
  44 int menubar_show_keybindings;
  45 Lisp_Object Vmenubar_configuration;
  46
  47 Lisp_Object Qcurrent_menubar;
  48
  49 Lisp_Object Qactivate_menubar_hook, Vactivate_menubar_hook;
  50
  51 Lisp_Object Vmenubar_visible_p;
  52
  53 static Lisp_Object Vcurrent_menubar; /* DO NOT ever reference this.
  54                                         Always go through Qcurrent_menubar.
  55                                         See below. */
  56
  57 Lisp_Object Vblank_menubar;
  58
  59 int popup_menu_titles;
  60
  61 Lisp_Object Vmenubar_pointer_glyph;
  62
  63 /* prefix key(s) that must match in order to activate menu.
  64    This is ugly.  fix me.
  65    */
  66 Lisp_Object Vmenu_accelerator_prefix;
  67
  68 /* list of modifier keys to match accelerator for top level menus */
  69 Lisp_Object Vmenu_accelerator_modifiers;
  70
  71 /* whether menu accelerators are enabled */
  72 Lisp_Object Vmenu_accelerator_enabled;
  73
  74 /* keymap for auxiliary menu accelerator functions */
  75 Lisp_Object Vmenu_accelerator_map;
  76
  77 Lisp_Object Qmenu_force;
  78 Lisp_Object Qmenu_fallback;
  79 Lisp_Object Qmenu_quit;
  80 Lisp_Object Qmenu_up;
  81 Lisp_Object Qmenu_down;
  82 Lisp_Object Qmenu_left;
  83 Lisp_Object Qmenu_right;
  84 Lisp_Object Qmenu_select;
  85 Lisp_Object Qmenu_escape;
  86
  87 static int
  88 menubar_variable_changed (Lisp_Object sym, Lisp_Object *val,
  89                           Lisp_Object in_object, int flags)
  90 {
  91   MARK_MENUBAR_CHANGED;
  92   return 0;
  93 }
  94
  95 void
  96 update_frame_menubars (struct frame *f)
  97 {
  98   if (f->menubar_changed || f->windows_changed)
  99     MAYBE_FRAMEMETH (f, update_frame_menubars, (f));
 100
 101   f->menubar_changed = 0;
 102 }
 103
 104 void
 105 free_frame_menubars (struct frame *f)
 106 {
 107   /* If we had directly allocated any memory for the menubars instead
 108      of using all Lisp_Objects this is where we would now free it. */
 109
 110   MAYBE_FRAMEMETH (f, free_frame_menubars, (f));
 111 }
 112
 113 static void
 114 menubar_visible_p_changed (Lisp_Object specifier, struct window *w,
 115                            Lisp_Object oldval)
 116 {
 117   MARK_MENUBAR_CHANGED;
 118 }
 119
 120 static void
 121 menubar_visible_p_changed_in_frame (Lisp_Object specifier, struct frame *f,
 122                                     Lisp_Object oldval)
 123 {
 124   update_frame_menubars (f);
 125 }
 126
 127 Lisp_Object
 128 current_frame_menubar (const struct frame* f)
 129 {
 130   struct window *w = XWINDOW (FRAME_LAST_NONMINIBUF_WINDOW (f));
 131   return symbol_value_in_buffer (Qcurrent_menubar, w->buffer);
 132 }
 133
 134 Lisp_Object
 135 menu_parse_submenu_keywords (Lisp_Object desc, Lisp_Object gui_item)
 136 {
 137   Lisp_Gui_Item *pgui_item = XGUI_ITEM (gui_item);
 138
 139   /* Menu descriptor should be a list */
 140   CHECK_CONS (desc);
 141
 142   /* First element may be menu name, although can be omitted.
 143      Let's think that if stuff begins with anything than a keyword
 144      or a list (submenu), this is a menu name, expected to be a string */
 145   if (!KEYWORDP (XCAR (desc)) && !CONSP (XCAR (desc)))
 146     {
 147       CHECK_STRING (XCAR (desc));
 148       pgui_item->name = XCAR (desc);
 149       desc = XCDR (desc);
 150       if (!NILP (desc))
 151         CHECK_CONS (desc);
 152     }
 153
 154   /* Walk along all key-value pairs */
 155   while (!NILP(desc) && KEYWORDP (XCAR (desc)))
 156     {
 157       Lisp_Object key, val;
 158       key = XCAR (desc);
 159       desc = XCDR (desc);
 160       CHECK_CONS (desc);
 161       val = XCAR (desc);
 162       desc = XCDR (desc);
 163       if (!NILP (desc))
 164         CHECK_CONS (desc);
 165       gui_item_add_keyval_pair (gui_item, key, val, ERROR_ME);
 166     }
 167
 168   /* Return the rest - supposed to be a list of items */
 169   return desc;
 170 }
 171
 172 DEFUN ("menu-find-real-submenu", Fmenu_find_real_submenu, 2, 2, 0, /*
 173 Find a submenu descriptor within DESC by following PATH.
 174 This function finds a submenu descriptor, either from the description
 175 DESC or generated by a filter within DESC. The function regards :config
 176 and :included keywords in the DESC, and expands submenus along the
 177 PATH using :filter functions. Return value is a descriptor for the
 178 submenu, NOT expanded and NOT checked against :config and :included.
 179 Also, individual menu items are not looked for, only submenus.
 180
 181 See also 'find-menu-item'.
 182 */
 183        (desc, path))
 184 {
 185   Lisp_Object path_entry, submenu_desc, submenu;
 186   struct gcpro gcpro1, gcpro2;
 187   Lisp_Object gui_item = allocate_gui_item ();
 188   Lisp_Gui_Item* pgui_item = XGUI_ITEM (gui_item);
 189
 190   GCPRO2 (gui_item, desc);
 191
 192   EXTERNAL_LIST_LOOP (path_entry, path)
 193     {
 194       /* Verify that DESC describes a menu, not single item */
 195       if (!CONSP (desc))
 196         RETURN_UNGCPRO (Qnil);
 197
 198       /* Parse this menu */
 199       desc = menu_parse_submenu_keywords (desc, gui_item);
 200
 201       /* Check that this (sub)menu is active */
 202       if (!gui_item_active_p (gui_item))
 203         RETURN_UNGCPRO (Qnil);
 204
 205       /* Apply :filter */
 206       if (!NILP (pgui_item->filter))
 207         desc = call1 (pgui_item->filter, desc);
 208
 209       /* Find the next menu on the path inside this one */
 210       EXTERNAL_LIST_LOOP (submenu_desc, desc)
 211         {
 212           submenu = XCAR (submenu_desc);
 213           if (CONSP (submenu)
 214               && STRINGP (XCAR (submenu))
 215               && !NILP (Fstring_equal (XCAR (submenu), XCAR (path_entry))))
 216             {
 217               desc = submenu;
 218               goto descend;
 219             }
 220         }
 221       /* Submenu not found */
 222       RETURN_UNGCPRO (Qnil);
 223
 224     descend:
 225       /* Prepare for the next iteration */
 226       gui_item_init (gui_item);
 227     }
 228
 229   /* We have successfully descended down the end of the path */
 230   UNGCPRO;
 231   return desc;
 232 }
 233
 234 DEFUN ("popup-menu", Fpopup_menu, 1, 2, 0, /*
 235 Pop up the menu described by MENU-DESCRIPTION.
 236 A menu description is a list of menu items, strings, and submenus.
 237
 238 The first element of a menu must be a string, which is the name of the menu.
 239 This is the string that will be displayed in the parent menu, if any.  For
 240 toplevel menus, it is ignored.  This string is not displayed in the menu
 241 itself.
 242
 243 If an element of a menu is a string, then that string will be presented in
 244 the menu as unselectable text.
 245
 246 If an element of a menu is a string consisting solely of hyphens, then that
 247 item will be presented as a solid horizontal line.
 248
 249 If an element of a menu is a list, it is treated as a submenu.  The name of
 250 that submenu (the first element in the list) will be used as the name of the
 251 item representing this menu on the parent.
 252
 253 Otherwise, the element must be a vector, which describes a menu item.
 254 A menu item can have any of the following forms:
 255
 256  [ "name" callback <active-p> ]
 257  [ "name" callback <active-p> <suffix> ]
 258  [ "name" callback :<keyword> <value>  :<keyword> <value> ... ]
 259
 260 The name is the string to display on the menu; it is filtered through the
 261 resource database, so it is possible for resources to override what string
 262 is actually displayed.
 263
 264 If the `callback' of a menu item is a symbol, then it must name a command.
 265 It will be invoked with `call-interactively'.  If it is a list, then it is
 266 evaluated with `eval'.
 267
 268 The possible keywords are this:
 269
 270  :active   <form>    Same as <active-p> in the first two forms: the
 271                      expression is evaluated just before the menu is
 272                      displayed, and the menu will be selectable only if
 273                      the result is non-nil.
 274
 275  :suffix   <form>    Same as <suffix> in the second form: the expression
 276                      is evaluated just before the menu is displayed and
 277                      resulting string is appended to the displayed name,
 278                      providing a convenient way of adding the name of a
 279                      command's ``argument'' to the menu, like
 280                      ``Kill Buffer NAME''.
 281
 282  :keys     "string"  Normally, the keyboard equivalents of commands in
 283                      menus are displayed when the `callback' is a symbol.
 284                      This can be used to specify keys for more complex menu
 285                      items.  It is passed through `substitute-command-keys'
 286                      first.
 287
 288  :style    <style>   Specifies what kind of object this menu item is:
 289
 290                         nil     A normal menu item.
 291                         toggle  A toggle button.
 292                         radio   A radio button.
 293
 294                      The only difference between toggle and radio buttons is
 295                      how they are displayed.  But for consistency, a toggle
 296                      button should be used when there is one option whose
 297                      value can be turned on or off, and radio buttons should
 298                      be used when there is a set of mutually exclusive
 299                      options.  When using a group of radio buttons, you
 300                      should arrange for no more than one to be marked as
 301                      selected at a time.
 302
 303  :selected <form>    Meaningful only when STYLE is `toggle' or `radio'.
 304                      This specifies whether the button will be in the
 305                      selected or unselected state.
 306
 307 For example:
 308
 309  [ "Save As..."    write-file  t ]
 310  [ "Revert Buffer" revert-buffer (buffer-modified-p) ]
 311  [ "Read Only"     toggle-read-only :style toggle :selected buffer-read-only ]
 312
 313 See menubar.el for many more examples.
 314 */
 315        (menu_description, event))
 316 {
 317   struct frame *f = decode_frame (Qnil);
 318   MAYBE_FRAMEMETH (f, popup_menu, (menu_description, event));
 319   return Qnil;
 320 }
 321
 322 DEFUN ("normalize-menu-item-name", Fnormalize_menu_item_name, 1, 2, 0, /*
 323 Convert a menu item name string into normal form, and return the new string.
 324 Menu item names should be converted to normal form before being compared.
 325 This removes %_'s (accelerator indications) and converts %% to %.
 326 */
 327        (name, buffer))
 328 {
 329   struct buffer *buf = decode_buffer (buffer, 0);
 330   Lisp_String *n;
 331   Charcount end;
 332   int i;
 333   Bufbyte *name_data;
 334   Bufbyte *string_result;
 335   Bufbyte *string_result_ptr;
 336   Emchar elt;
 337   int expecting_underscore = 0;
 338
 339   CHECK_STRING (name);
 340
 341   n = XSTRING (name);
 342   end = string_char_length (n);
 343   name_data = string_data (n);
 344
 345   string_result = (Bufbyte *) alloca (end * MAX_EMCHAR_LEN);
 346   string_result_ptr = string_result;
 347   for (i = 0; i < end; i++)
 348     {
 349       elt = charptr_emchar (name_data);
 350       elt = DOWNCASE (buf, elt);
 351       if (expecting_underscore)
 352         {
 353           expecting_underscore = 0;
 354           switch (elt)
 355             {
 356             case '%':
 357               /* Allow `%%' to mean `%'.  */
 358               string_result_ptr += set_charptr_emchar (string_result_ptr, '%');
 359               break;
 360             case '_':
 361               break;
 362             default:
 363               string_result_ptr += set_charptr_emchar (string_result_ptr, '%');
 364               string_result_ptr += set_charptr_emchar (string_result_ptr, elt);
 365             }
 366         }
 367       else if (elt == '%')
 368         expecting_underscore = 1;
 369       else
 370         string_result_ptr += set_charptr_emchar (string_result_ptr, elt);
 371       INC_CHARPTR (name_data);
 372     }
 373
 374   if (string_result_ptr - string_result == XSTRING_LENGTH (name)
 375       && !memcmp (string_result, XSTRING_DATA (name), XSTRING_LENGTH (name)))
 376     return name;
 377
 378   return make_string (string_result, string_result_ptr - string_result);
 379 }
 380
 381 void
 382 syms_of_menubar (void)
 383 {
 384   defsymbol (&Qcurrent_menubar, "current-menubar");
 385
 386   defsymbol (&Qmenu_force, "menu-force");
 387   defsymbol (&Qmenu_fallback, "menu-fallback");
 388
 389   defsymbol (&Qmenu_quit, "menu-quit");
 390   defsymbol (&Qmenu_up, "menu-up");
 391   defsymbol (&Qmenu_down, "menu-down");
 392   defsymbol (&Qmenu_left, "menu-left");
 393   defsymbol (&Qmenu_right, "menu-right");
 394   defsymbol (&Qmenu_select, "menu-select");
 395   defsymbol (&Qmenu_escape, "menu-escape");
 396
 397   DEFSUBR (Fpopup_menu);
 398   DEFSUBR (Fnormalize_menu_item_name);
 399   DEFSUBR (Fmenu_find_real_submenu);
 400 }
 401
 402 void
 403 vars_of_menubar (void)
 404 {
 405   /* put in Vblank_menubar a menubar value which has no visible
 406    * items.  This is a bit tricky due to various quirks.  We
 407    * could use '(["" nil nil]), but this is apparently equivalent
 408    * to '(nil), and a new frame created with this menubar will
 409    * get a vertically-squished menubar.  If we use " " as the
 410    * button title instead of "", we get an etched button border.
 411    * So we use
 412    *  '(("No active menubar" ["" nil nil]))
 413    * which creates a menu whose title is "No active menubar",
 414    * and this works fine.
 415    */
 416
 417   Vblank_menubar = list1 (list2 (build_string ("No active menubar"),
 418                                  vector3 (build_string (""), Qnil, Qnil)));
 419   staticpro (&Vblank_menubar);
 420
 421   DEFVAR_BOOL ("popup-menu-titles", &popup_menu_titles /*
 422 If true, popup menus will have title bars at the top.
 423 */ );
 424   popup_menu_titles = 1;
 425
 426   /* #### Replace current menubar with a specifier. */
 427
 428   /* All C code must access the menubar via Qcurrent_menubar
 429      because it can be buffer-local.  Note that Vcurrent_menubar
 430      doesn't need to exist at all, except for the magic function. */
 431
 432   DEFVAR_LISP_MAGIC ("current-menubar", &Vcurrent_menubar /*
 433 The current menubar.  This may be buffer-local.
 434
 435 When the menubar is changed, the function `set-menubar-dirty-flag' has to
 436 be called for the menubar to be updated on the frame.  See `set-menubar'
 437 and `set-buffer-menubar'.
 438
 439 A menubar is a list of menus and menu-items.
 440 A menu is a list of menu items, keyword-value pairs, strings, and submenus.
 441
 442 The first element of a menu must be a string, which is the name of the menu.
 443 This is the string that will be displayed in the parent menu, if any.  For
 444 toplevel menus, it is ignored.  This string is not displayed in the menu
 445 itself.
 446
 447 Menu accelerators can be indicated in the string by putting the
 448 sequence "%_" before the character corresponding to the key that will
 449 invoke the menu or menu item.  Uppercase and lowercase accelerators
 450 are equivalent.  The sequence "%%" is also special, and is translated
 451 into a single %.
 452
 453 If no menu accelerator is present in the string, XEmacs will act as if
 454 the first character has been tagged as an accelerator.
 455
 456 Immediately following the name string of the menu, various optional
 457 keyword-value pairs are permitted: currently, :filter, :active, :included,
 458 and :config. (See below.)
 459
 460 If an element of a menu (or menubar) is a string, then that string will be
 461 presented as unselectable text.
 462
 463 If an element of a menu is a string consisting solely of hyphens, then that
 464 item will be presented as a solid horizontal line.
 465
 466 If an element of a menu is a string beginning with "--:", it will be
 467 presented as a line whose appearance is controlled by the rest of the
 468 text in the string.  The allowed line specs are system-dependent, and
 469 currently work only under X Windows (with Lucid and Motif menubars);
 470 otherwise, a solid horizontal line is presented, as if the string were
 471 all hyphens.
 472
 473 The possibilities are:
 474
 475   "--:singleLine"
 476   "--:doubleLine"
 477   "--:singleDashedLine"
 478   "--:doubleDashedLine"
 479   "--:noLine"
 480   "--:shadowEtchedIn"
 481   "--:shadowEtchedOut"
 482   "--:shadowEtchedInDash"
 483   "--:shadowEtchedOutDash"
 484   "--:shadowDoubleEtchedIn" (Lucid menubars only)
 485   "--:shadowDoubleEtchedOut" (Lucid menubars only)
 486   "--:shadowDoubleEtchedInDash" (Lucid menubars only)
 487   "--:shadowDoubleEtchedOutDash" (Lucid menubars only)
 488
 489 If an element of a menu is a list, it is treated as a submenu.  The name of
 490 that submenu (the first element in the list) will be used as the name of the
 491 item representing this menu on the parent.
 492
 493 If an element of a menubar is `nil', then it is used to represent the
 494 division between the set of menubar-items which are flushleft and those
 495 which are flushright.
 496
 497 Otherwise, the element must be a vector, which describes a menu item.
 498 A menu item is of the following form:
 499
 500  [ "name" callback :<keyword> <value> :<keyword> <value> ... ]
 501
 502 The following forms are also accepted for compatibility, but deprecated:
 503
 504  [ "name" callback <active-p> ]
 505  [ "name" callback <active-p> <suffix> ]
 506
 507 The name is the string to display on the menu; it is filtered through the
 508 resource database, so it is possible for resources to override what string
 509 is actually displayed.  Menu accelerator indicators (the sequence `%_') are
 510 also processed; see above.  If the name is not a string, it will be
 511 evaluated with `eval', and the result should be a string.
 512
 513 If the `callback' of a menu item is a symbol, then it must name a command.
 514 It will be invoked with `call-interactively'.  If it is a list, then it is
 515 evaluated with `eval'.
 516
 517 In the deprecated forms, <active-p> is equivalent to using the :active
 518 keyword, and <suffix> is equivalent to using the :suffix keyword.
 519
 520 The possible keywords are:
 521
 522  :active   <form>    The expression is evaluated just before the menu is
 523                      displayed, and the menu will be selectable only if
 524                      the result is non-nil.
 525
 526  :suffix   <form>    The expression is evaluated just before the menu is
 527                      displayed and the resulting string is appended to
 528                      the displayed name, providing a convenient way of
 529                      adding the name of a command's ``argument'' to the
 530                      menu, like ``Kill Buffer NAME''.
 531
 532  :keys     "string"  Normally, the keyboard equivalents of commands in
 533                      menus are displayed when the `callback' is a symbol.
 534                      This can be used to specify keys for more complex menu
 535                      items.  It is passed through `substitute-command-keys'
 536                      first.
 537
 538  :style    <style>   Specifies what kind of object this menu item is:
 539
 540                         nil     A normal menu item.
 541                         toggle  A toggle button.
 542                         radio   A radio button.
 543                         button  A menubar button.
 544
 545                      The only difference between toggle and radio buttons is
 546                      how they are displayed.  But for consistency, a toggle
 547                      button should be used when there is one option whose
 548                      value can be turned on or off, and radio buttons should
 549                      be used when there is a set of mutually exclusive
 550                      options.  When using a group of radio buttons, you
 551                      should arrange for no more than one to be marked as
 552                      selected at a time.
 553
 554  :selected <form>    Meaningful only when STYLE is `toggle', `radio' or
 555                      `button'.  This specifies whether the button will be in
 556                      the selected or unselected state.
 557
 558  :included <form>    This can be used to control the visibility of a menu or
 559                      menu item.  The form is evaluated and the menu or menu
 560                      item is only displayed if the result is non-nil.
 561
 562  :config  <symbol>   This is an efficient shorthand for
 563                          :included (memq symbol menubar-configuration)
 564                      See the variable `menubar-configuration'.
 565
 566  :filter <function>  A menu filter can only be used at the beginning of a
 567                      submenu description (i.e. not in a menu item itself).
 568                      (Remember that most of the keywords can take evaluated
 569                      expressions as well as constants.)  The filter is used to
 570                      incrementally create a submenu only when it is selected
 571                      by the user and not every time the menubar is activated.
 572                      The filter function is passed the list of menu items in
 573                      the submenu and must return the modified list to be
 574                      actually used.  The filter MUST NOT destructively modify
 575                      the list of menu items passed to it.  It is called only
 576                      when the menu is about to be displayed, so other menus
 577                      may already be displayed.  Vile and terrible things will
 578                      happen if a menu filter function changes the current
 579                      buffer, window, or frame.  It also should not raise,
 580                      lower, or iconify any frames.  Basically, the filter
 581                      function should have no side-effects.
 582
 583  :key-sequence keys  Used in FSF Emacs as an hint to an equivalent keybinding.
 584                      Ignored by XEmacs for easymenu.el compatibility.
 585                      (XEmacs computes this information automatically.)
 586
 587 For example:
 588
 589  ("%_File"
 590   :filter file-menu-filter      ; file-menu-filter is a function that takes
 591                                 ; one argument (a list of menu items) and
 592                                 ; returns a list of menu items
 593   [ "Save %_As..."    write-file  t ]
 594   [ "%_Revert Buffer" revert-buffer (buffer-modified-p) ]
 595   [ "R%_ead Only"     toggle-read-only :style toggle
 596                       :selected buffer-read-only ]
 597   )
 598
 599 See menubar-items.el for many more examples.
 600
 601 After the menubar is clicked upon, but before any menus are popped up,
 602 the functions on the `activate-menubar-hook' are invoked to make top-level
 603 changes to the menus and menubar.  Note, however, that the use of menu
 604 filters (using the :filter keyword) is usually a more efficient way to
 605 dynamically alter or sensitize menus.  */, menubar_variable_changed);
 606
 607   Vcurrent_menubar = Qnil;
 608
 609   DEFVAR_LISP ("activate-menubar-hook", &Vactivate_menubar_hook /*
 610 Function or functions called before a menubar menu is pulled down.
 611 These functions are called with no arguments, and should interrogate and
 612 modify the value of `current-menubar' as desired.
 613
 614 The functions on this hook are invoked after the mouse goes down, but before
 615 the menu is mapped, and may be used to activate, deactivate, add, or delete
 616 items from the menus.  However, it is probably the case that using a :filter
 617 keyword in a submenu would be a more efficient way of updating menus.  See
 618 the documentation of `current-menubar'.
 619
 620 These functions may return the symbol `t' to assert that they have made
 621 no changes to the menubar.  If any other value is returned, the menubar is
 622 recomputed.  If `t' is returned but the menubar has been changed, then the
 623 changes may not show up right away.  Returning `nil' when the menubar has
 624 not changed is not so bad; more computation will be done, but redisplay of
 625 the menubar will still be performed optimally.
 626 */ );
 627   Vactivate_menubar_hook = Qnil;
 628   defsymbol (&Qactivate_menubar_hook, "activate-menubar-hook");
 629
 630   DEFVAR_BOOL ("menubar-show-keybindings", &menubar_show_keybindings /*
 631 If true, the menubar will display keyboard equivalents.
 632 If false, only the command names will be displayed.
 633 */ );
 634   menubar_show_keybindings = 1;
 635
 636   DEFVAR_LISP_MAGIC ("menubar-configuration", &Vmenubar_configuration /*
 637 A list of symbols, against which the value of the :config tag for each
 638 menubar item will be compared.  If a menubar item has a :config tag, then
 639 it is omitted from the menubar if that tag is not a member of the
 640 `menubar-configuration' list.
 641 */ , menubar_variable_changed);
 642   Vmenubar_configuration = Qnil;
 643
 644   DEFVAR_LISP ("menubar-pointer-glyph", &Vmenubar_pointer_glyph /*
 645 *The shape of the mouse-pointer when over the menubar.
 646 This is a glyph; use `set-glyph-image' to change it.
 647 If unspecified in a particular domain, the window-system-provided
 648 default pointer is used.
 649 */ );
 650
 651   DEFVAR_LISP ("menu-accelerator-prefix", &Vmenu_accelerator_prefix /*
 652 Prefix key(s) that must be typed before menu accelerators will be activated.
 653 Set this to a value acceptable by define-key.
 654
 655 NOTE: This currently only has any effect under X Windows.
 656 */ );
 657   Vmenu_accelerator_prefix = Qnil;
 658
 659   DEFVAR_LISP ("menu-accelerator-modifiers", &Vmenu_accelerator_modifiers /*
 660 Modifier keys which must be pressed to get to the top level menu accelerators.
 661 This is a list of modifier key symbols.  All modifier keys must be held down
 662 while a valid menu accelerator key is pressed in order for the top level
 663 menu to become active.
 664
 665 NOTE: This currently only has any effect under X Windows.
 666
 667 See also menu-accelerator-enabled and menu-accelerator-prefix.
 668 */ );
 669   Vmenu_accelerator_modifiers = list1 (Qmeta);
 670
 671   DEFVAR_LISP ("menu-accelerator-enabled", &Vmenu_accelerator_enabled /*
 672 Whether menu accelerator keys can cause the menubar to become active.
 673 If 'menu-force or 'menu-fallback, then menu accelerator keys can
 674 be used to activate the top level menu.  Once the menubar becomes active, the
 675 accelerator keys can be used regardless of the value of this variable.
 676
 677 menu-force is used to indicate that the menu accelerator key takes
 678 precedence over bindings in the current keymap(s).  menu-fallback means
 679 that bindings in the current keymap take precedence over menu accelerator keys.
 680 Thus a top level menu with an accelerator of "T" would be activated on a
 681 keypress of Meta-t if menu-accelerator-enabled is menu-force.
 682 However, if menu-accelerator-enabled is menu-fallback, then
 683 Meta-t will not activate the menubar and will instead run the function
 684 transpose-words, to which it is normally bound.
 685
 686 See also menu-accelerator-modifiers and menu-accelerator-prefix.
 687 */ );
 688   Vmenu_accelerator_enabled = Qnil;
 689
 690   DEFVAR_LISP ("menu-accelerator-map", &Vmenu_accelerator_map /*
 691 Keymap for use when the menubar is active.
 692 The actions menu-quit, menu-up, menu-down, menu-left, menu-right,
 693 menu-select and menu-escape can be mapped to keys in this map.
 694 NOTE: This currently only has any effect under X Windows.
 695
 696 menu-quit    Immediately deactivate the menubar and any open submenus without
 697              selecting an item.
 698 menu-up      Move the menu cursor up one row in the current menu.  If the
 699              move extends past the top of the menu, wrap around to the bottom.
 700 menu-down    Move the menu cursor down one row in the current menu.  If the
 701              move extends past the bottom of the menu, wrap around to the top.
 702              If executed while the cursor is in the top level menu, move down
 703              into the selected menu.
 704 menu-left    Move the cursor from a submenu into the parent menu.  If executed
 705              while the cursor is in the top level menu, move the cursor to the
 706              left.  If the move extends past the left edge of the menu, wrap
 707              around to the right edge.
 708 menu-right   Move the cursor into a submenu.  If the cursor is located in the
 709              top level menu or is not currently on a submenu heading, then move
 710              the cursor to the next top level menu entry.  If the move extends
 711              past the right edge of the menu, wrap around to the left edge.
 712 menu-select  Activate the item under the cursor.  If the cursor is located on
 713              a submenu heading, then move the cursor into the submenu.
 714 menu-escape  Pop up to the next level of menus.  Moves from a submenu into its
 715              parent menu.  From the top level menu, this deactivates the
 716              menubar.
 717
 718 This keymap can also contain normal key-command bindings, in which case the
 719 menubar is deactivated and the corresponding command is executed.
 720
 721 The action bindings used by the menu accelerator code are designed to mimic
 722 the actions of menu traversal keys in a commonly used PC operating system.
 723 */ );
 724
 725   Fprovide (intern ("menubar"));
 726   Fprovide (intern ("menu-accelerator-support"));
 727 }
 728
 729 void
 730 specifier_vars_of_menubar (void)
 731 {
 732   DEFVAR_SPECIFIER ("menubar-visible-p", &Vmenubar_visible_p /*
 733 *Whether the menubar is visible.
 734 This is a specifier; use `set-specifier' to change it.
 735 */ );
 736   Vmenubar_visible_p = Fmake_specifier (Qboolean);
 737
 738   set_specifier_fallback (Vmenubar_visible_p, list1 (Fcons (Qnil, Qt)));
 739   set_specifier_caching (Vmenubar_visible_p,
 740                          offsetof (struct window, menubar_visible_p),
 741                          menubar_visible_p_changed,
 742                          offsetof (struct frame, menubar_visible_p),
 743                          menubar_visible_p_changed_in_frame, 0);
 744 }
 745
 746 void
 747 complex_vars_of_menubar (void)
 748 {
 749   Vmenubar_pointer_glyph = Fmake_glyph_internal (Qpointer);
 750
 751   Vmenu_accelerator_map = Fmake_keymap (Qnil);
 752 }