PopUpMenusDoc.tioga
Created by Christian Jacobi, September 12, 1985 11:20:28 am PDT
Last Edited by: Christian Jacobi, August 26, 1986 10:31:18 am PDT
This df file contains two packages:
PopUpSelection.mesa
PopUpMenus.mesa
Both are implementing pop-up menus, but on different levels
The user is not supposed to know which is lower and which is higher, but he might peek at the implementation.
A) PopUpSelection.mesa
Package which implements a pop-up menu abstraction.
Request:
PROC [
header: Rope.
ROPE ←
NIL, choice:
LIST
OF Rope.
ROPE,
headerDoc: Rope.
ROPE ←
NIL, choiceDoc:
LIST
OF Rope.
ROPE ←
NIL,
default:
NAT ← 0, timeOut:
NAT ← 0, position:
REF ←
NIL
]
RETURNS [
INT];
Shows a pop-up menu and returns the number of the selected entry.
returns: 1 for first choice, 2 for second...
0 if selected outside menu or on header-line
-1 if timed out
header: Header text; can not be selected.
choice: List of possible selections.
headerDoc: Documentation shown if selection is on header or outside menu.
choiceDoc: Documentation for the corresponding choice.
default: Hint for initial selection by implicit mouse movement. 0 if no default.
timeOut: In seconds; 0 for no time out.
position: Hint to override mouse position. See documentation for possible types.
Procedure must not be called from inside a viewers-repaint or a TIP-notify procedure.
There might be a maximum number of choices, see documentation.
When the procedure RequestSelection is called, a pop up menu appears at the position of the mouse. The selection is made by releasing a mouse button. (If necessary, press a mouse button down first).
Press a second mouse button down to move the menu to a different position.
To interactively invoke the help feature: Move the mouse slightly above the header of the pop-up menu.
Position parameter:
NIL: Default, uses the current mouse position. But: If the time since the last call finished is short enough, the menu will appear at exactly the same location as the previous menu. This allows imlementation of nested menus without moving around on the sceen.
$Mouse: Use the current mouse position.
TIPUser.TIPScreenCoords: Use this position. [0,0] is lower left (of device)
REF Interminal.MousePosition: Use this position. [0,0] is upper left (of device).
Limits:
The current implementation limits the number of entries in a pop-up menu to 25. To be safe, do not use more than 20.
User Profile Options
with their default values:
PopUpSelection.FontFamily: "Helvetica"
PopUpSelection.FontSize: 10
PopUpSelection.FontBold: TRUE
PopUpSelection.FontItalic: FALSE
PopUpSelection.LineHeightChange: 0
Rationale
This package returns a number and not the selected rope.
It is easy for a client to get the rope from the number, but it would be hard to get a number from a returned rope.
All the mouse buttons do the same.
There are already more different mouse button conventions in Cedar than I can remember.
An application can invoke a different pop-up menu depending on which mouse button is used; the user should be able to select the menu entry without having to switch mouse button used. [Specially important if the menu is called on a mouse button down event].
Package which supports composition and invocation of popup menus.
Menu: TYPE = ... --handle representing a popup menu
EntryProc:
TYPE =
PROC [menu: Menu←
NIL, entryData:
REF←
NIL, callData:
REF←
NIL]
RETURNS [
REF←
NIL];
Type of procedure called on menu selection
menu: popup menu used
entryData: as defined for the menu entry
callData: as given by call
returned value is passed to caller of menu
The NIL initializations are only of use for clients to call procedure directly
Create:
PROC [header:
ROPE←
NIL, doc:
ROPE←
NIL, clientData:
REF←NIL]
RETURNS [Menu];
Creates a new popup menu (class)
(creates the handle, but does not invoke the created popup menu yet)
header: header line of popup menu
doc: documentation for header line and outside
clientData: stored for the client
Entry:
PROC [menu: Menu, entry:
ROPE←
NIL, proc: EntryProc←
NIL, entryData:
REF←
NIL, doc:
ROPE←
NIL]
RETURNS [sameMenu: Menu];
Makes an entry line for a popup menu
Replaces existing line if entry rope is already used
entry: text for menu line
proc: will be called on selection
entryData: passed to proc on call
a NIL proc and a NIL entryData: removes entry from menu
a NIL proc: on call returns entryData
doc: documentation for this line
sameMenu: for conveniance returns menu again
Timeout:
PROC [menu: Menu, time:
INT𡤀, proc: EntryProc←
NIL, entryData:
REF←
NIL]
RETURNS [sameMenu: Menu];
Defines behaviour of popup menu on timeout
time: in seconds; 0 for no timeout
proc: will be called on timeout when menu is called
entryData: passed to proc on timeout call
a NIL proc and a NIL entryData: no-op on time out (Normal case!)
a NIL proc: on timeout returns entryData
sameMenu: for conveniance returns menu again
Skipped:
PROC [menu: Menu, proc: EntryProc←
NIL, entryData:
REF←
NIL]
RETURNS [sameMenu: Menu];
Defines behaviour of popup menu when called and skipped (no entry selected, no timeout)
proc: will be called on timeout when menu is called
entryData: passed to proc on timeout call, or returned if proc=NIL
sameMenu: for conveniance returns menu again
Most menus do NOT define a skipped behaviour
Call:
PROC [menu: Menu, callData:
REF←
NIL, position:
REF←
NIL, default:
REF←
NIL]
RETURNS [
REF];
Calls a popup menu
(draws the menu, accepts interactive selection and calls the EntryProc)
returns data returned from called EntryProc
or entryData if EntryProc was NIL
menu: popup menu to be used
callData: passed to the EntryProc
position: position of popup menu (see documentation)
defaults to: the current mouse position
default: entry line to select at the beginning; hint only! (see documentation)
defaults to: no line selected at the beginning
ClientData:
PROC [menu: Menu]
RETURNS [
REF]
;
returns clientData as given on Create