XTkSlider.mesa
Copyright Ó 1990, 1991, 1992 by Xerox Corporation. All rights reserved.
Created by Christian Jacobi, June 25, 1990 4:28:29 pm PDT
Christian Jacobi, April 20, 1992 5:23 pm PDT
DIRECTORY
Xl USING [GContext],
XTk USING [Event, Widget, WidgetSpec];
XTkSlider: CEDAR DEFINITIONS
~ BEGIN OPEN Xl;
Widget: TYPE = XTk.Widget;
Slider: TYPE = Widget;
WidgetSpec: TYPE = XTk.WidgetSpec;
Direction: TYPE = {right, up, left, down}; --order may change
Reason: TYPE = {temporary, client, set, abort};
NormalizedSliderValue: TYPE = REAL; -- in range [0.0, 1.0]
Slider and Filter procedures are called on button down; periodically while the button mouse button is held down provided the mouse coordinates have changed, and upon release of the button. The procedures are also called on an abort, which occurs when the button is released while the cursor is outside its active region. (Of course the procedures are also called when clients call SetContents).
In spite of the choice of names, the FilterProc is the real thing. The SliderProc could be considered a shortcut for the notification mechanism.
"reason" is the reason the client procedure is being called.
temporary - new temporary slider value.
set - button up, new real slider value.
client - a client called SetContents; generates new real slider value.
abort - slider value reset because button up was invalid.
"contents" displayed or new contents of slider.
"event" X event causing action (NIL if not available); useful for time stamp...
"clientData" from widget creation.
Do not make assumption about thread. In case of concurrent calls to SetContents, the procedures are called concurrently, but always the latest contents at call time is passed.
SliderProc:
TYPE =
PROC [slider: Slider, clientData:
REF, contents: NormalizedSliderValue, event: XTk.Event, reason: Reason];
Type of the client supplied procedure which is called when the slider value is changed.
Warning: calling SetContents (or InternalSetContents) would cause recursion.
FilterProc:
TYPE =
PROC [slider: Slider, clientData:
REF, contents:
REAL, event: XTk.Event, reason: Reason]
RETURNS [filteredValue:
REAL];
Type of an optional client supplied procedure which is called whenever a new slider value is proposed. This procedure is used to filter the slider value before feedback is provided, or, the SliderProc (or notification) is called. It can be used to make the slider move in discrete jumps, for example. The FilterProc must not call SetContents as this would recurse (However, calling InternalSetContents is ok as the FilterProc belongs to the logical parent of the slider). The FilterProc may return a negative filteredValue to prevent usage of it.
IsSlider:
PROC [widget: XTk.Widget]
RETURNS [
BOOL];
Predicate whether SetContents and GetContents make sense
CreateSlider:
PROC [widgetSpec: WidgetSpec ¬ [], direction: Direction ¬ right, contents: NormalizedSliderValue, clientData:
REF ¬
NIL, filterProc: FilterProc ¬
NIL, sliderProc: SliderProc ¬
NIL, gc: Xl.GContext ¬
NIL]
RETURNS [Slider];
Creates a slider widget.
clientData: passed to client procedures.
contents: initial contents of slider.
filterProc: called to validate or modify slider values.
sliderProc: called to notify changes.
SetFilter:
PROC [slider: XTk.Widget, filterProc: FilterProc ¬
NIL, sliderProc: SliderProc ¬
NIL, clientData:
REF ¬
NIL];
Replaces filter and sliderProc.
SetGC:
PROC [slider: Slider, gc: Xl.GContext ¬
NIL];
Set gc used to paint slider. Callers responsibility to be valid. NIL ok.
GetContents:
PROC [slider: Slider]
RETURNS [contents: NormalizedSliderValue];
Returns the current contents of the slider.
Not necessarily equal to displayed state, as temporary contents is not reported.
SetContents:
PROC [slider: Slider, contents: NormalizedSliderValue, event: XTk.Event ¬
NIL];
Tries to set the contents of the slider; can be called by anybody. (E.g. interactively).
The proposed state will be filtered and if the filter suggests so, the InternalSetContents procedure is called.
event is optional, it is forwarded to registered notifiers
InternalSetContents:
PROC [slider: Slider, contents: NormalizedSliderValue, event: XTk.Event ¬
NIL, reason: Reason ¬ client];
Sets the contents of the slider; must be called by the logical parent of the slider only (no filtering will be done).
event is optional, it is forwarded to registered notifiers
sliderSetKey:
READONLY
ATOM;
-- ¬ $sliderSet
Key for notifier. Notifier is called when slider is changed (even temporaryly).
Reason is passed to callData as ATOM [$temporary, $client, $set, $abort].
END.