27 Menus

A menu is set by setting the value of the variable current-menubar (which may be buffer-local) and then calling set-menubar-dirty-flag to signal a change. This will cause the menu to be redrawn at the next redisplay. The format of the data in current-menubar is described in menubar.c.

Internally the data in current-menubar is parsed into a tree of widget_value's (defined in lwlib.h); this is accomplished by the recursive function menu_item_descriptor_to_widget_value(), called by compute_menubar_data(). Such a tree is deallocated using free_widget_value().

update_screen_menubars() is one of the external entry points. This checks to see, for each screen, if that screen’s menubar needs to be updated. This is the case if

1. set-menubar-dirty-flag was called since the last redisplay. (This function sets the C variable menubar_has_changed.)
2. The buffer displayed in the screen has changed.
3. The screen has no menubar currently displayed.

set_screen_menubar() is called for each such screen. This function calls compute_menubar_data() to create the tree of widget_value’s, then calls lw_create_widget(), lw_modify_all_widgets(), and/or lw_destroy_all_widgets() to create the X-Toolkit widget associated with the menu.

update_psheets(), the other external entry point, actually changes the menus being displayed. It uses the widgets fixed by update_screen_menubars() and calls various X functions to ensure that the menus are displayed properly.

The menubar widget is set up so that pre_activate_callback() is called when the menu is first selected (i.e. mouse button goes down), and menubar_selection_callback() is called when an item is selected. pre_activate_callback() calls the function in activate-menubar-hook, which can change the menubar (this is described in menubar.c). If the menubar is changed, set_screen_menubars() is called. menubar_selection_callback() enqueues a menu event, putting in it a function to call (either eval or call-interactively) and its argument, which is the callback function or form given in the menu’s description.