vbtkit/src/lego/NumericVBT.i3


 Copyright (C) 1992, Digital Equipment Corporation                         
 All rights reserved.                                                      
 See the file COPYRIGHT for a full description.                            
                                                                           
 Last modified on Fri Jun 11 21:34:28 PDT 1993 by meehan                   
      modified on Mon Feb  1 00:25:39 PST 1993 by mhb                      
      modified on Tue Jun 16 13:08:32 PDT 1992 by muller                   
      modified on Fri Mar 20 22:35:51 1992 by steveg                       
<* PRAGMA LL *>
A NumericVBT is a VBT class for displaying and changing an integer within some range. A NumericVBT has three parts (from left to right): a minus button, a type-in field, and a plus button. The type-in field is restricted to contain an integer within a specified range; it can be changed by editing (it uses the default editing model), or by typing Return, or by clicking on the plus or minus buttons. The plus/minus buttons are trill buttons, so clicking and holding will cause the value of the NumericVBT to continuously increment/decrement.

The NumericVBT has a callback method that is called each time the user types Return or click the plus or minus button. The default callback method is a no-op.

INTERFACE NumericVBT;

IMPORT AnyEvent, Filter, Font, Shadow, TypeinVBT,  VBT;

TYPE
  T <: Public;
  Public = Filter.T OBJECT
             typein: Typein := NIL; (* READONLY after init *)
           METHODS
             <* LL.sup <= VBT.mu *>
             init (min       : INTEGER  := FIRST (INTEGER);
                   max       : INTEGER  := LAST (INTEGER);
                   allowEmpty: BOOLEAN  := FALSE;
                   naked     : BOOLEAN  := FALSE;
                   font      : Font.T   := Font.BuiltIn;
                   shadow    : Shadow.T := NIL              ):
               T;
             callback (event: AnyEvent.T);
           END;
  Typein <: TypeinVBT.T;
The call to v.init(...) initializes v as a NumericVBT and returns v. The integer stored with v, referred to as ``the value in'' v, is constrained to be in the range
      [min .. MAX (min, max)]
   
The initial value in v is equal to min.

If allowEmpty is TRUE, then ``empty'' (no text in the type-in area) is a distinct and valid state, and can be tested by the procedure IsEmpty. The call Get(v) in the empty state will return FIRST(INTEGER), regardless of whether this is in the valid range. Clicking the plus/minus buttons has no effect when v is in the empty state.

If naked is TRUE, then the numeric interactor appears as just a type-in field, without plus or minus buttons.

IF v.typein is NIL when v.init(...) is called, then a new Typein will be allocated and assigned to v.typein. Whether or not it was NIL at the time of the call, it will be initialized via

      v.typein(FALSE, 1.5, 1.5, font, shadow)
   
That is, it will not be expandable, its margins will be 1.5 mm, and font and shadow will determine its appearance.

The implementation calls

      v.callback(event)
   
when the user clicks the plus/minus buttons, or types Return in the type-in area. The event parameter reports the details of the event as either an AnyEvent.Mouse (clicking on the plus/minus buttons) or an AnyEvent.Key (typing Return in the type-in area). The value in v is changed before v.callback is invoked.

The value in v is range-checked before the callback is called, and in every call to Get. If the number is out of range, the nearest number in range will be written into the type-in area, and that value will be returned to the caller of Get.

PROCEDURE Put (v: T; n: INTEGER);
<* LL.sup = VBT.mu *>
Change the value in v to be
       MIN(GetMax(v), MAX(GetMin(v), n))
   
and display this value in the type-in area. Note that v.callback is not invoked.

PROCEDURE PutBounds (v: T; min, max: INTEGER);
<* LL.sup = VBT.mu *>
Change v.min to be min and v.max to be MAX(min, max), and then call Put(v, Get(v)). The call to Put has the effect of projecting the value of v into the new bounds.

PROCEDURE Get (v: T)   : INTEGER; <* LL.sup = VBT.mu *>
Return the current value in v. This value is range-checked, in case the user typed an out-of-range value without typing Return.

PROCEDURE GetMin (v: T): INTEGER; <* LL.sup = VBT.mu *>
PROCEDURE GetMax (v: T): INTEGER; <* LL.sup = VBT.mu *>
Return the indicated value associated with v.

PROCEDURE SetEmpty (v: T);
<* LL.sup = VBT.mu *>
Set v to the empty state. This is a no-op unless allowEmpty was TRUE when v was initialized.

PROCEDURE IsEmpty (v: T): BOOLEAN;
<* LL.sup = VBT.mu *>
Test whether v is in the empty state. If allowEmpty was not TRUE when v was initialized, this procedure will always return FALSE.

PROCEDURE TakeFocus (v          : T;
                     time       : VBT.TimeStamp;
                     alsoSelect : BOOLEAN       := TRUE):
  BOOLEAN;
<* LL = VBT.mu *>
Cause the type-in area to grab the keyboard focus. If the focus could be grabbed and if alsoSelect is set, the type-in area will make its entire text the primary selection. Returns whether the keyboard focus could be acquired.

END NumericVBT.