XTkPopUps.mesa
Copyright Ó 1991, 1992 by Xerox Corporation. All rights reserved.
Created by Christian Jacobi, October 14, 1991 9:31:44 pm PDT
Christian Jacobi, May 7, 1992 11:01 am PDT
A simple pop up buttons interface for XTk.
This is my 9th try; it might or might not be the last one.
A pop up button is a button which when activated makes a pop up menu (shell) appear.
Terminology:
Activation = Poping up pop up shell
Selection = Choosing an entry in pop up shell
Pop up button, base = Button which when activated pops up a pop up shell
Pop up shell = Shell which is popped up on activation.
When a pop up button is activated, it creates a pop-up shell widget and calls a WidgetCreateClosure to create the contents. (with shell for the parent, registerData for registerData, closureData for closureData). There are no restrictions for the children of the shell, except acceptance that there is a button grab ongoing (ownerEvents=TRUE).
It is perfectly ok for a pop up shell widget to contain other pop up buttons.
There is no guarantee that only one entry is selected, or, that only one instance of any pop up menu is shown. (E.g. this interface does not really specify whether an openwindow pin feature is implemented or not).
Basic features
CreateWidgetProc:
TYPE =
PROC [parent: XTk.Widget ¬
NIL, closureData:
REF ¬
NIL, registerData:
REF ¬
NIL, image:
REF ¬
NIL, event: XTk.Event ¬
NIL]
RETURNS [XTk.Widget];
Called to create the inside (or a part of the inside) of a pop up menu.
Widget should not be included into parent (because caller will do so).
WidgetCreateClosure: TYPE = REF WidgetCreateClosureRec;
WidgetCreateClosureRec: TYPE = RECORD [creator: CreateWidgetProc, closureData: REF];
ChoiceList: TYPE = LIST OF Choice;
Choice:
TYPE =
RECORD [
image:
REF ¬
NIL,
This specifies what is displayed in the pop-up menu. It is passed to the actual creator of the widget. Standard buttons understand Rope.ROPE, REF TEXT, ATOM.
key <<callData>>:
REF
ANY ¬
NIL,
This is passed to notify to specify the identify of the choice taken.
For NIL, a default dependent on impl and context is used (typically image).
(context: for base button no base selection is made)
impl:
REF
ANY ¬
NIL,
This specifies implementor for displaying image.
For NIL, a standard button is used.
help:
REF ¬
NIL,
This describes this choice for the user. This doc should be sufficiently short.
notify: XTk.WidgetNotifyProc ¬
NIL
For NIL, use default provided externally. (e.g. defaultNotify from WidgetCreateClosureFromChoiceList.)
];
CreateSimplePopUpButton:
PROC [text: Rope.
ROPE ¬
NIL, list: ChoiceList, defaultNotify: XTk.WidgetNotifyProc, notifyTQ: XTk.
TQ ¬
NIL, registerData:
REF ¬
NIL, help: Rope.
ROPE ¬
NIL]
RETURNS [button: XTk.Widget];
Conveniance procedure calling all the primitives to make a pop up button.
CreatePopUpButton:
PROC [text: Rope.
ROPE ¬
NIL, createMenu: WidgetCreateClosure, registerData:
REF ¬
NIL, image:
REF ¬
NIL, help: Rope.
ROPE ¬
NIL]
RETURNS [button: XTk.Widget];
Creates a pop up button widget.
WidgetCreateClosureFromChoiceList:
PROC [list: ChoiceList, defaultNotify: XTk.WidgetNotifyProc, notifyTQ: XTk.
TQ ¬
NIL]
RETURNS [closure: WidgetCreateClosure];
Make up a createMenu closure useful for CreatePopUpButton.
defaultNotify is used for any list.notify with NIL value.
Notifys forked if notifyTQ=NIL.
RegisterBaseSelection:
PROC [base: XTk.Widget, notify: XTk.WidgetNotifyProc, registerData, callData:
REF ¬
NIL, notifyTQ: XTk.
TQ ¬
NIL];
Registers (or changes) procedure to be called when base is selected.
Useful for selection of a pop up base button itself (instead of a menu entry).
Useful for non standard-button-class widgets (Registers notify used when calling "Select").
Forked if notifyTQ=NIL.
SimplePopUpWithRegularShell:
PROC [list: ChoiceList, defaultNotify: XTk.WidgetNotifyProc, notifyTQ: XTk.
TQ ¬
NIL, screen: Xl.Screen ¬
NIL, pos: Xl.Point ¬ [-1, -1], registerData:
REF ¬
NIL, event: Xl.Event ¬
NIL, header: Rope.
ROPE ¬
NIL, helpHandle:
REF ¬
NIL];
Conveniance procedure.
PopUpWithRegularShell:
PROC [createMenu: WidgetCreateClosure, screen: Xl.Screen ¬
NIL, pos: Xl.Point ¬ [-1, -1], registerData:
REF ¬
NIL, image:
REF ¬
NIL, event: Xl.Event ¬
NIL, header: Rope.
ROPE ¬
NIL, helpHandle:
REF ¬
NIL];
Builds a regular shell displaying contents generated by pop up menu procedures.
NullNotify: XTk.WidgetNotifyProc;
A handy no-op proc.
Features for more elaborate clients
PseudoBase:
TYPE = <<PRIVATE>>
REF;
Ref to latent instance of a pop up menu. (Represents pop up menu whether it is currently active or not).
PopCarrier:
TYPE =
REF;
Carrier of a pop up menu. Either a PseudoBase, or, a base (an XTk.Widget).
CreatePseudoBase:
PROC [registerData:
REF ¬
NIL]
RETURNS [PseudoBase];
Useful for pop up menus in absence of base button.
registerData is passed to CreateWidgetProc (which might pass it on to a WidgetNotifyProc)
MakeItBase:
PROC [base: XTk.Widget, registerData:
REF ¬
NIL, createMenu: WidgetCreateClosure ¬
NIL, image:
REF ¬
NIL, help: Rope.
ROPE ¬
NIL];
Builds pop up button behavior on top of an existing widget to be used as base.
registerData is passed to CreateWidgetProc (which might pass it on to a WidgetNotifyProc).
image passed to CreateWidgetProc.
SetMenuCreator:
PROC [carrier: PopCarrier, createMenu: WidgetCreateClosure ¬
NIL];
Defines or changes callback used for creating pop-up shell.
SetHelp:
PROC [carrier: PopCarrier, help: Rope.
ROPE ¬
NIL];
Defines or changes help information.
Select:
PROC [choice: XTk.Widget, event: XTk.Event];
If choice is an entry of a pop up menu, simulates selection.
Tears down menu if it is not of a permanent kind.
TearDown:
PROC [carrier: PopCarrier];
Removes the pop up part, if it is not of a permanent kind.
Useful to deactivate a pop up menu without a button release event.
carrier might be a base widget, a pop up shell widget, a child of a pop up shell widget, or, a PseudoBase.
PopUp:
PROC [pseudoBase: PseudoBase, event: XTk.Event, parentCarrier: PopCarrier ¬
NIL, image:
REF ¬
NIL, pos: Xl.Point ¬ [-1, -1]];
Explicitely activates a pop up menu. (Make it visible).
This is useful for implementing more elaborate kinds of base buttons.
Might or might not succed, according to timestamp carried by event. If an other instance of this PseudoBase is visible, might fail or tear other instance down first.
Event one of ButtonPressEvent or EnterNotifyEvent.