Class: Scroller

• Inheritance
• Description
• Class protocol
  • defaults
• Instance protocol
  • accessing
  • accessing-behavior
  • accessing-bg & border
  • accessing-look
  • autoRepeat
  • change & update
  • drawing
  • event handling
  • focus handling
  • forced scroll
  • forwarding changed origin
  • initialization
  • private
  • private-scrollbar & scrollview interface
  • queries
• Examples

Inheritance:

   Object
   |
   +--GraphicsMedium
      |
      +--DisplaySurface
         |
         +--SimpleView
            |
            +--View
               |
               +--Scroller
                  |
                  +--HorizontalScroller
                  |
                  +--MiniScroller
                  |
                  +--Slider

Package:

stx:libwidg

Category:

Views-Interactors

Version:

rev: 1.242 date: 2024/02/12 17:05:11

user: cg

file: Scroller.st directory: libwidg

module: stx stc-classLibrary: libwidg

Description:

this class implements the scroller for scrollbars.
it can also be used by itself for scrollbars without step-buttons.
When moved, either a predefined action is performed (scrollAction),
or a model is informed via the changeMsg (which is #value: by default).

The scroller can work synchronous (i.e. every move leads to an immediate evaluation
of the action, or asynchronous (i.e. perform action on end-of move).
By default, scrollers are synchronous. Asynchronous operation makes sense, 
if the scroll operation (redraw) is expensive and takes a long time.

This class is used both for concrete instances (vertical scrollers)
and as an abstract superclass for horizontalScrollers, sliders and
miniScrollers.

  range:
the value passed to the model or via the action blocks is scaled according
to the min/maxRange instance variables.
These default to 0..100 for percentage values.
It does not make sense to change the range for scrollbar-scrollers,
but may be useful with Sliders or in special applications.

  style stuff:

Beside the obvious 3D rectangle, a scroller may draw a know-form
(as in NeXT) or little tally marks (as on SGI) in itself.
These are controlled by the shadowForm, lightForm, tallyLevel and tallyMarks
instance variables. All of this is initialized from the styleSheet.

  [Instance variables:]

thumbOrigin                 <Number>        origin of thumb (in percent)
thumbHeight                 <Number>        height of thumb (in percent)
thumbColor                  <Color>         color of thumb
thumbFrameColor             <Color>         color of the frame around the thumb
scrollAction                <Block>         1 arg block to be evaluated when scrolled
                                            (arg is position in percent)
orientation                 <Symbol>        #horizontal or #vertical
thumbFrame                  <Rectangle>     frame of thumb in pixels (cached)
thumbLevel                  <Number>        level of thumb if 3d
scrolling                   <Boolean>       true during scroll
pressOffset                 <Number>        temporary (offset into frame when move started)
synchronousOperation        <Boolean>       true if synchronous (i.e. don't wait till release
                                            to perform action)
shadowForm                  <Form>          bitmap of knob if any (shadow part)
lightForm                   <Form>          bitmap of knob if any (light part)
inset                       <Integer>       number of pixels to inset thumb from view borders
thumbShadowColor            <Color>         color do draw dark parts of thumb
thumblightColor             <Color>         color to draw light parts of thumb
thumbEdgeStyle              <SymbolOrNil>   #soft or nil
thumbHalfShadowColor        <Color>         used to draw smooth edges
thumbHalfLightColor         <Color>         used to draw smooth edges
thumbFrameSizeDifference    <Integer>       number of pixels the thumb is larger than 
                                            it should be (can be negative for mswin-style)
tallyLevel                  <Integer>       if not zero, specifies if tally-marks should
                                            go into or out of the display (actually only <0/>0 is checked)
                                            I dont know of a better word for these ...
tallyMarks                  <Integer>       number of tally marks
fixThumbHeight              <Boolean>       perform 'wrong' height computation a la mswindows
rangeStart                  <Number>        the range of the scroller
rangeEnd                                    (defaults to 0..100)
rangeStep                                   not currently implemented

  [style settings:]

scrollerLevel               <Integer>       the level of the scroller w.r.t. its enclosing view
scrollerBorderWidth         <Integer>       the borderWidth (ignored for 3D styles)

scrollerViewBackground      <Color>         the viewBackground (color or image)
scrollerShadowColor         <Color>         the color of 3D shadowed edges (ignored in 2D styles)
scrollerLightColor          <Color>         the color of 3D lighted edges (ignored in 2D styles)

scrollerThumbColor          <Color>         the thumbs color (color or image)
scrollerThumbShadowColor    <Color>         the color of the thumbs shadowed edges (ignored in 2D styles)
scrollerThumbLightColor     <Color>         the color of the thumbs shadowed edges (ignored in 2D styles)
scrollerThumbEdgeStyle      <Symbol>        the edge style for the thumb (#soft or nil)
scrollerThumbLevel          <Integer>       the 3D height of the thumb
scrollerThumbHalfShadowColor<Color>         the halfShadow for soft edged thumbs
scrollerThumbHalfLightColor <Color>         the halfLight for soft edged thumbs
scrollerThumbFrameColor     <Color>         if non-nil, a rectangle is drawn around the thumb is this color
scrollerThumbInset          <Integer>       inset of thumb from the scrollers boundary
scrollerThumbFixHeight      <Boolean>       if true, use a fix thumb height (as in mswindows)
scrollerGhostColor          <Color>         the color in which a ghost-rectangle is drawn
scrollerGhostFrameColor     <Color>         if non-nil, a rectangle is drawn around the ghost is this color
scrollerGhostLevel          <Color>         the 3D level of the ghost rectangle
scrollerNTallyMarks         <Integer>       number of tally-marks to draw on the thumb
scrollerTallyLevel          <Integer>       the 3D level of any tally marks
scrollerSnapBack            <Boolean>       win95 behavior: snap back to original position if scrollers view
                                            is left by mouse (with some distance)
scrollerMiddleButtonJump    <Boolean>       xterm behavior: middle button has shift-click behavior
                                            (positions absolute to click position)

notice: for mswindows style, we force a WRONG thumb-frame
computation, to make the thumb have constant size; 
if you dont like that (I do not :-), 
set scrollerThumbFixHeight to false (in the StyleSheet).

copyright
COPYRIGHT (c) 1989 by Claus Gittinger
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

 defaultHorizontalScrollerHeight

 defaultVerticalScrollerWidth

 handleLightFormOn: aDisplay

answer the form used for the handles light area;
cache the one for Display for the next round

 handleShadowFormOn: aDisplay

answer the form used for the handles shadow area;
cache the one for Display for the next round

 updateStyleCache

extract values from the styleSheet and cache them in class variables

Usage example(s):

self updateStyleCache

Instance protocol:

 keyboardStep

return the scrollers keyboard step. If non-nil,
that's the stepping value used with cursorUp/cursorDown keys.
(not used with Scrollers, but provided for subclasses)

 keyboardStep: aNumber

set the scrollers keyboard step. If non-nil,
that's the stepping value used with cursorUp/cursorDown keys.
(not used with Scrollers, but provided for subclasses)

 start

return the scrollers range min.
(not used with Scrollers, but provided for subclasses)

 start: start

set the scrollers range min.
(not used with Scrollers, but provided for subclasses)

 start: start stop: stop

set the range.
(not used with Scrollers, but provided for subclasses)

 start: start stop: stop step: step

set the range.
(not used with Scrollers, but provided for subclasses)

 step

return the scrollers range step.
(not used with Scrollers, but provided for subclasses)

 step: step

set the scrollers range step.
(not used with Scrollers, but provided for subclasses)

 stop

return the scrollers range max.
(not used with Scrollers, but provided for subclasses)

 stop: stop

set the scrollers range max.
(not used with Scrollers, but provided for subclasses)

 thumbFrame

return the area used by the thumbFrame (in device coordinates).
Allows access to the thumbs physical screen position, for
example to position a label below (see Slider-Examples)

 thumbHeight

answer the thumbs height (in percent by default)

 thumbHeight: aNumber

set the thumb's height (in percent by default)

 thumbOrigin

answer the thumb's origin (in percent by default)

 thumbOrigin: aNumber

set the thumb's origin (in percent by default)

 thumbOrigin: originNumber thumbHeight: heightNumber

set both thumbs height and origin (in percent by default)

 action: aBlock

for protocol compatibility; same as scrollAction:

 asynchronousOperation

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 beAsynchronous

set scroll-mode to be asynchronous - scroll action is only performed after
scrolling, when mouse-button is finally released (no tracking).

 beSynchronous

set scroll-mode to be synchronous - scroll action is performed for
every movement of thumb (tracking).

 enabled

return enable/disable state of the scoller

 enabled: aBoolean

enable/disable the scoller

 isSynchronous

return true if the scroll-mode is synchronous.
If true, the scroll action is performed for every movement of the thumb (tracking).
If false, the scroll action is only performed at the end.

 scrollAction

answer the scroll action block

 scrollAction: aBlock

set the scroll action, aBlock which is evaluated when scrolled.
The block will be called with positionInPercent as argument.

 scrollDownAction: aBlock

ignored -
but implemented, so that scroller can be used in place of a scrollbar

 scrollLeftAction: aBlock

ignored -
but implemented, so that scroller can be used in place of a scrollbar

 scrollRightAction: aBlock

ignored -
but implemented, so that scroller can be used in place of a scrollbar

 scrollUpAction: aBlock

ignored -
but implemented, so that scroller can be used in place of a scrollbar

 synchronousOperation

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 allViewBackground: something if: condition

ignore here for all scrollers (I want my own background)

Usage example(s):

^ super allViewBackground:something

 is3D

return true, if I use a 3D style

 orientation

return the scrollers orientation (#vertical or #horizontal)

 orientation: aSymbol

set the scrollers orientation (#vertical or #horizontal)

 thumb

for compatibility with scrollBars, return the receiver

 thumbColor

return the thumbs color

 thumbColor: aColor

change the color of the thumb

 installRepeat

 installRepeat: repeatDelay

protect against races

 pagedAbovePointer

 pagedBelowPointer

 repeatPageDown

stop scroll

 repeatPageUp

stop scroll

 update: something with: aParameter from: changedObject

handle update from a model (if any)

 drawEdgedLineFrom: x1 y: y1 toX: x2 y: y2 level: lvl lightColor: lightColor shadowColor: shadowColor

iris style - draw tallys

 drawHandleFormAtX: x y: y

styles with a handle in the middle (NeXT) use this

 drawTallyMarks

draw the thumb

 drawThumb

draw the thumb

 drawThumbBackgroundInX: x y: y width: w height: h

draw part of the thumbs background; defined as a separate
method, to allow drawing of arbitrary patterns under thumb
(see ColorSlider).

 buttonControlPress: button x: x y: y

mouse-click with control - jump to top/bottom

 buttonMotion: state x: x y: y

mouse-button was moved while pressed;
redraw thumb at its new position and, if scroll-mode is asynchronous,
the scroll action is performed

 buttonPress: button x: x y: y

button was pressed - if above thumb, page up; if below thumb, page down;
otherwise start scrolling.
If either shift is pressed, or the 'scrollerMiddleButtonJump' styleSheet
value is true and its the middle button, do a jump to the clicked position.

 buttonRelease: button x: x y: y

mouse-button was released - if scroll-mode is asynchronous, the scroll
action is now performed

 buttonShiftPress: button x: x y: y

mouse-click with shift - jump to position

 changeCursorFor: p

update the mouse cursor

 highlightThumbForPointerX: x y: y

if x/y is within the thumb frame, highlight it

 keyPress: key x: x y: y

stupid - due to delegation, this is never invoked ...

 keyRelease: key x: x y: y

stupid - due to delegation, this is never invoked ...

 pointerEnter: state x: x y: y

mouse-button left view
redraw thumb if enteredColor ~~ thumbColor

 pointerLeave: state

mouse-button left view
redraw thumb if enteredColor ~~ thumbColor

 redraw

redraw

 redrawX: x y: y width: w height: h

thumb hidden

 sizeChanged: how from: oldExtentOrNil

size of scroller changed - recompute thumbs frame and redraw it

 wantsFocusWithButtonPress

no, do not catch the keyboard focus on button click

 pageDown

page down/right

 pageUp

page up/left

 scrollDown: amountToScroll

compatibility with SimpleView.
This allows mouse wheel actions on Scrollers & Wheels
Note: this is used for horizontal scrollers, too (scrollRight)

 scrollStep: delta

step by some delta

 scrollToBeginning

scroll to the beginning

 scrollToEnd

scroll to the end

 scrollUp: amountToScroll

compatibility with SimpleView.
This allows mouse wheel actions on Scrollers & Wheels
Note: this is used for horizontal scrollers, too (scrollLeft)

 tellOthers

the ST-80 way of notifying scrolls

 defaultExtent

compute my extent from sub-components

 fetchDeviceResources

fetch device colors, to avoid reallocation at redraw time

 initCursor

set the cursor - a hand

 initStyle

initialize style dep. stuff

 initialize

initialize - setup instvars from defaults

 realize

(comment from inherited method)
realize - make visible;
realizing is done very late (after layout is fixed) to avoid
visible rearranging of windows on the screen

 absFromPercent: percent

given a percentage, compute number of pixels

 computeThumbFrame

compute the thumb's frame (a rectangle) whenever thumb is moved,
changed height or the scroller's size has changed.
We take care, that the thumb will not become too small (i.e.
invisible or uncatchable).
Also, for mswindows style, its height/width is constant.

 percentFromAbs: absValue

given a number of pixels, compute percentage

 startMove

 updateBackground

make my background grey, whenever disabled

 setThumbFor: aView

get contents and size info from aView and adjust thumb

 setThumbHeightFor: aView

get contents and size info from aView and adjust thumb height

 setThumbOriginFor: aView

get contents and size info from aView and adjust thumb origin

 computePreferredExtent

return my preferredExtent

 isMiniScroller

 isScrolling

true, if thumb is being moved (by user)

 thumbVisible

return true, if the thumb is usable i.e. its visible & movable.
Can be used by the scrollBar to decide if it should hide the scroller.

 verticalScrollStep

mouse wheel: scroll by keyboardStep or a quarter of a page
Note: this is used for horizontal scrollers, too

Examples:

    |top s|

    top := StandardSystemView new extent:200@200.
    s := Scroller in:top.
    s origin:(0.0@0.0) corner:(20@1.0).
    s thumbHeight:10.  'percent'.     
    top open

    |top s|

    top := StandardSystemView new extent:200@200.
    s := Scroller in:top.
    s origin:(0.0@0.0) corner:(20@1.0).
    s thumbHeight:50.  'percent'.     
    top open

    |top s|

    top := StandardSystemView new extent:200@200.
    s := Scroller in:top.
    s origin:(0.0@0.0) corner:(20@1.0).
    s thumbHeight:10.  'percent'.     
    s thumbOrigin:30.  'percent'.     
    top open

    |top s|

    top := StandardSystemView new extent:200@200.
    s := Scroller in:top.
    s origin:(0.0@0.0) corner:(20@1.0).
    s thumbHeight:10.  'percent'.     
    s scrollAction:[:percent | Transcript show:'moved to: '; showCR:percent asFloat].
    top open

    |top s|

    top := StandardSystemView new extent:200@200.
    s := Scroller in:top.
    s origin:(0.0@0.0) corner:(20@1.0).
    s thumbHeight:10.  'percent'.     
    s scrollAction:[:percent | Transcript show:'moved to: '; showCR:percent asFloat].
    s start:0 stop:1.
    top open

    |top s v|

    top := StandardSystemView new extent:200@200.
    s := Scroller in:top.
    s origin:(0.0@0.0) corner:(0.0@1.0).
    s rightInset:(s preferredExtent x negated).
    s thumbHeight:10.
    s level:1.

    v := View in:top.
    v origin:0.0@0.0 corner:1.0@1.0.
    v leftInset:(s preferredExtent x).
    v viewBackground:Color red.
    v level:2.

    top open

    |top s m|

    m := 0 asValue.
    InspectorView openOn:m monitor:'value'.  'look at value'.

    top := StandardSystemView new extent:200@200.
    s := Scroller in:top.
    s origin:(0.0@0.0) corner:(20@1.0).
    s thumbHeight:10.  'percent'.     
    s model:m.
    top open

    |top s1 s2 m|

    m := Plug new.
    m respondTo:#value1: with:[:v | Transcript show:'scroller 1 moved to: '; showCR:v].
    m respondTo:#value2: with:[:v | Transcript show:'scroller 2 moved to: '; showCR:v].

    top := StandardSystemView new extent:200@200.
    s1 := Scroller in:top.
    s1 origin:(0.0@0.0) corner:(20@1.0).
    s1 thumbHeight:10.  'percent'.     
    s1 model:m; change:#value1:.

    s2 := Scroller in:top.
    s2 origin:(30@0.0) corner:(50@1.0).
    s2 thumbHeight:10.  'percent'.     
    s2 model:m; change:#value2:.
    top open

    |top s|

    top := StandardSystemView new extent:200@200.
    s := MiniScroller in:top.
    s level:0.
    s origin:(0.0@0.0) corner:(s preferredWidth@1.0).
    s thumbHeight:10.  'percent'.     
    top open