Class ScrollController

Inheritance:

Object  »
  Controller  »
    MouseMenuController  »
      ScrollController

This controller implements control for vertical scrolling using a scrollBar. It is a MouseMenuController that creates a scrollBar, rather than menus. The subclasses add the button menus. This controller keeps control as long as the cursor is inside the view or the scrollBar area.

Squeak follows the tradition of Smalltalk-80 to display a scrollbar only for as long as the view is active. The vertical scrollbar of an active window is placed to the left of the window - where most of the text is. In virtually all currently used windowing systems the scrollbars are permanently displayed. The advantage of the display-on-activation policy is that it is not necessary to keep a possibly great number of scrollbars up-to-date.

A scrollBar is a rectangular area representing the length of the information being viewed. It contains an inner rectangle - the marker - whose top y-coordinate represents the relative position of the information visible on the screen with respect to all of the information, and whose size represents the relative amount of that information visible on the screen. The user controls which part of the information is visible by pressing the red (left-most) button. If the cursor is to the right of the inner rectangle (in the 'scroll up' area), the window onto the visible information moves upward, if the cursor is to the left (in the 'scroll down' area), the window moves downward, and if the cursor is inside, the inner rectangle is grabbed and moved to a desired position.

The subclass ListController modifies scrolling for list views; the subclass ParagraphEditor modifies scrolling for text views.

Instance Variables:

• scrollBar - Quadrangle
  This quadrangle keeps the position and the display properties of the scrollbar.

• marker - Quadrangle
  This quadrangle keeps the position and the display properties of the marker, the rectangular are that is displayed in the scrollbar to give you a hint which part of the scrollable view content is currently visible.

• savedArea - Form
  As long as the scrollbar is visible, the portion of the display that is covered by the scrollbar is stored in this form. When the scrollbar is removed, its display area is restored from the savedArea and the savedArea is deleted.

• menuBar - Quadrangle
  An incompletely initialized instance of Quadrangle is assigned to this variable in method initialize, but not used. (Method menuBarContainsCursor references the variable, but this method is never sent.)

• savedMenuBarArea - ?
  This instance variable is currently not used.

The Mathematics of Scrolling

The following diagram shows a scrollbar with its marker and the document with its currently visible part:

The useable height of the scrollbar is scrollbar inside height, the height of the marker is marker height. The marker is always entirely visible in the scrollbar, its possible offsets from the origin of the scrollbar are in the range

0 to: scrollbar inside height - marker height

The height of the entire document is view  boundingBox height, the height of the display field is view window height. The possible offsets of the visible part of the document from the origin of the document are in the range

0 to: view boundingBox height - view window height

By convention, the marker height represents the relative amount of information that is visible display field of the window. This is expressed by the following equation:

     marker height             view window height
 -----------------------  =  -----------------------
 scrollbar inside height     view boundingBox height

For the height of the marker we obtain (in method computeMarkerRegion):

((view window height asFloat /
      view boundingBox height *
        scrollBar inside height
 )
      rounded min: scrollBar inside height)

For efficiency reasons, the computation is performed with floats. The result is rounded because an integer height is needed. The final

<...> min: scrollBar inside height

limits the maximal height of the marker to the useable height of the scrollbar.

alfa :=
  (marker top - scrollbar top /(scrollbar height - marker height)) rounded

The Scroll Algorithm

Scrolling is implemented with the support of class WindowingTransformation. WindowingTransformation>>scrollBy:

Mandatory Protocol of Views that use Scrolling

To use scrolling, a view has to use a subclass of ScrollController as its controller. Such views have to implement these instance methods:

• Methods sent from the controller to obtain information from the view:

  • apparentDisplayBox
    Answers a rectangle, the enlarged inset display box of the view. This rectangle is used to compute the size and position of the scrollbar. The enlargement is 2 pixel in each direction, which is suitable for a view with a two-pixel border.

  • boundingBox
    Answers a rectangle, the entire virtual area to be presented.

  • window
    Answers a rectangle. The rectangle describes the position of the view content relative to the view viewport.

• Methods sent from the controller to communicate a changed scroll position to the view:

  • scrollBy: aPoint
    This method is required to answer a boolean value. The value true indicates that scrolling was needed, the value false indicates that no scrolling was performed.
    The x component of aPoint specifies the amount of scrolling in the x direction; the y component specifies the amount of scrolling in the y direction. The amounts are specified in the receiver's local coordinate system. Scroll the receiver up or down, left or right. The window of the receiver is kept stationary and the subViews and other objects in the receiver are translated relative to it. Scrolling doesn't change the insetDisplayBox or the viewport since the change in the transformation is canceled by the change in the window. In other words, all display objects in the view, except the window, are translated by the scrolling operation.
    The value of aPoint y is the vertical scroll amount. This value is negative when the scroll marker is moved down, this shifts the view contents up. A positive value indicates that the scroll marker was moved up, this gesture shifts the the view contents down.
    Note: Some subclasses that support only vertical scrolling redefine the method scrollBy: for use with an anInteger argument.
    Note: subclasses may override to return false if no scrolling takes place.

Important Instance Methods:

• initialize
  Creates values for the instance variables scrollbar and marker.

• controlInitialize
  Aligns the scrollbar with the view and the marker with the scrollbar and displays both the scrollbar and its marker. The display region that is needed to display the scrollbar is saved in instance variable savedArea for later restoration.

• controlTerminate
  Removes the scrollbar and restores the display from the savedArea.

• controlActivity
  Checks whether scrolling or normal activity is requested.

• isControlActive
  Control is active for as long as the mouse pointer is placed within the view or the scrollbar.

• computeMarkerRegion
  answer a Rectangle that defines the size (but not the position) of the marker.

• markerDelta
  ***

• markerRegion: aRectangle
  Used to move the marker. The method removes the marker from the scrollbar, moves it to aRectangle and display it again.

• moveMarker
  ***

• moveMarker: anInteger anchorMarker: anchorMarker
  Used to move the marker while its position prior to scrolling (the 'anchor') remains visible. The method erases the current marker form the screen, moves it to its new position and redisplays both the anchor and the relocated marker.

• moveMarkerTo: aRectangle
  ***

• scrollAbsolute
  This method processes the mouse movements when the marker is grabbed with the mouse.

• scrollAmount
  This method computes and answers the scroll amount that is used to scroll the view when either a scroll up or a scroll down activity is processed. Scroll up and scroll down are needed for documents that are such large that scrollAbsolute can show only portions of the document. In this situation scrolling in the scroll up and scroll down regions is needed to scroll a large document in small steps. It is crucial to ensure that the scroll amount that is computed by this method does not exceed view insetDisplayBox height for vertical scrolling.

• scrollDown
  This method processes the red button click when the mouse cursor points into the 'scroll down' region of the scrollbar. The scroll down region is the scrollbar area to the left of the marker.

• scrollUp
  This method processes the red button click when the mouse cursor points into the 'scroll up' region of the scrollbar. The scroll up region is the scrollbar area to the right of the marker.