eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'Scroller':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: Scroller


Inheritance:

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

Package:
stx:libwidg
Category:
Views-Interactors
Version:
rev: 1.224 date: 2018/11/16 14:59:52
user: cg
file: Scroller.st directory: libwidg
module: stx stc-classLibrary: libwidg
Author:
Claus Gittinger

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).


Related information:

    ScrollBar
    ScrollableView
    HVScrollableView

Class protocol:

defaults
o  handleLightFormOn: aDisplay
answer the form used for the handles light area;
cache the one for Display for the next round

o  handleShadowFormOn: aDisplay
answer the form used for the handles shadow area;
cache the one for Display for the next round

o  updateStyleCache
extract values from the styleSheet and cache them in class variables

usage example(s):

     self updateStyleCache


Instance protocol:

accessing
o  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)

o  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)

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

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

o  start: start stop: stop
set the range.
(not used with Scrollers, but provided for subclasses)

o  start: start stop: stop step: step
set the range.
(not used with Scrollers, but provided for subclasses)

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

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

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

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

o  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)

o  thumbHeight
answer the thumbs height (in percent by default)

o  thumbHeight: aNumber
set the thumbs height (in percent by default)

o  thumbOrigin
answer the thumbs origin (in percent by default)

o  thumbOrigin: aNumber
set the thumbs origin (in percent by default)

o  thumbOrigin: originNumber thumbHeight: heightNumber
set both thumbs height and origin (in percent by default)

accessing-behavior
o  action: aBlock
for protocol compatibility; same as scrollAction:

o  asynchronousOperation

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

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

o  enabled
return enable/disable state of the scoller

o  enabled: aBoolean
enable/disable the scoller

o  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.

o  scrollAction
answer the scroll action block

o  scrollAction: aBlock
set the scroll action, aBlock which is evaluated when scrolled

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

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

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

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

o  synchronousOperation

accessing-bg & border
o  allViewBackground: something if: condition
ignore here for all scrollers (I want my own background)

usage example(s):

^ super allViewBackground:something

accessing-look
o  is3D
return true, if I use a 3D style

o  orientation
return the scrollers orientation (#vertical or #horizontal)

o  orientation: aSymbol
set the scrollers orientation (#vertical or #horizontal)

o  thumb
for compatibility with scrollBars, return the receiver

o  thumbColor
return the thumbs color

o  thumbColor: aColor
change the color of the thumb

autoRepeat
o  installRepeat

o  installRepeat: repeatDelay
protect against races

o  pagedAbovePointer

o  pagedBelowPointer

o  repeatPageDown
stop scroll

o  repeatPageUp
stop scroll

drawing
o  drawEdgedLineFrom: x1 y: y1 toX: x2 y: y2 level: lvl lightColor: lightColor shadowColor: shadowColor
iris style - draw tallys

o  drawHandleFormAtX: x y: y
styles with a handle in the middle (NeXT) use this

o  drawTallyMarks
draw the thumb

o  drawThumb
draw the thumb

o  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).

event handling
o  buttonControlPress: button x: x y: y
mouse-click with control - jump to top/bottom

o  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

o  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.

o  buttonRelease: button x: x y: y
mouse-button was released - if scroll-mode is asynchronous, the scroll
action is now performed

o  buttonShiftPress: button x: x y: y
mouse-click with shift - jump to position

o  changeCursorFor: p
update the mouse cursor

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

o  keyPress: key x: x y: y
stupid - due to delegation, this is never invoked ...

o  keyRelease: key x: x y: y
stupid - due to delegation, this is never invoked ...

o  pointerEnter: state x: x y: y
mouse-button left view
redraw thumb if enteredColor ~~ thumbColor

o  pointerLeave: state
mouse-button left view
redraw thumb if enteredColor ~~ thumbColor

o  redraw
redraw

o  redrawX: x y: y width: w height: h
thumb hidden

o  sizeChanged: how
size of scroller changed - recompute thumbs frame and redraw it

o  update: something with: aParameter from: changedObject
handle update from a model (if any)

focus handling
o  wantsFocusWithButtonPress
no, do not catch the keyboard focus on button click

forced scroll
o  pageDown
page down/right

o  pageUp
page up/left

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

o  scrollStep: delta
step by some delta

o  scrollToBeginning
scroll to the beginning

o  scrollToEnd
scroll to the end

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

forwarding changed origin
o  tellOthers
the ST-80 way of notifying scrolls

initialization
o  defaultExtent
compute my extent from sub-components

o  fetchDeviceResources
fetch device colors, to avoid reallocation at redraw time

o  initCursor
set the cursor - a hand

o  initStyle
initialize style dep. stuff

o  initialize
initialize - setup instvars from defaults

o  realize

private
o  absFromPercent: percent
given a percentage, compute number of pixels

o  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.

o  percentFromAbs: absValue
given a number of pixels, compute percentage

o  startMove

o  updateBackground
make my background grey, whenever disabled

private-scrollbar & scrollview interface
o  setThumbFor: aView
get contents and size info from aView and adjust thumb

o  setThumbHeightFor: aView
get contents and size info from aView and adjust thumb height

o  setThumbOriginFor: aView
get contents and size info from aView and adjust thumb origin

queries
o  computePreferredExtent
return my preferredExtent

o  isMiniScroller

o  isScrolling
true, if thumb is being moved (by user)

o  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.

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


Examples:


basic scroller setup:
    |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
setting its thumb-height:
    |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
setting its thumb-origin:
    |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
a scroller with action block (ST/X style):
    |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
setting its range:
    |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
create a scroller in its default extent and have it positioned at the side; beside another view:
    |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
using a model (ST-80 style):
    |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
using a different changeSelector:
    |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


ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Tue, 21 Jan 2020 05:12:56 GMT