9.9 Popup menus for panes

The CAPI tries to display a popup menu for a pane when the :post-menu gesture is entered by the user (mouse-right-click or Shift+F10 on Microsoft Windows, GTK+ or Motif, control-click on Cocoa). See below for the special case of output-pane .

It first tries to get a menu for the pane. There are two mechanisms by which it can get a menu: which is tried depends on the value of pane-menu .

1. If the pane's initarg pane-menu is not :default in the call to make-instance , then its value is used. If the value is a function or a fbound symbol, it is called with four arguments: the pane, data (this is the selected object if there is a selection), x, y. It should return a menu. If it is not a function or a fbound symbol, it should be a menu, which is used directly. The :pane-menu mechanism is useful when the menu needs to be dependent on the location of the mouse inside the pane, or when each pane requires a unique menu. In other cases, the other mechanism is more useful.
2. If pane-menu is :default (this the default value), CAPI calls the generic function make-pane-popup-menu with two arguments: the pane and its interface. The result should be a menu.

If the chosen mechanism does not produce a menu, the CAPI does not do anything in response to :post-menu .

The system definition of make-pane-popup-menu calls pane-popup-menu-items with the pane and the interface, and if this returns non-nil list, it calls make-menu-for-pane to make the menu. You can define make-pane-popup-menu methods that specialize on your pane or interface classes, but in most cases it is more useful to add methods to pane-popup-menu-items . make-menu-for-pane is used to generate the menu, and it makes the menu such that by default all setup callbacks are done on the pane itself, rather than on the interface. make-pane-popup-menu is useful when the application needs a menu with the same items as the items on the popup menu, typically to add it to the menu bar.

In output-pane , you control the input behavior using the input-model . By default, the system assigns :post-menu and :keyboard-post-menu ( Shift+F10 ) to a callback that raises a menu as described above, but your code can override this in the input-model .

CAPI User Guide (Windows version) - 30 Aug 2011