Class Documentation

Name:Scroll
Version:1.0
ID:ID_SCROLL
Status:Unspecified
Category:GUI
Date:May 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 1999-2001. All rights reserved.
Short:  This class is used to create scrollbars and sliders.



Description

The Scroll class provides a facility for creating scrollbars that allow the user to move drawable objects within their containers. It can also be used to scroll contents or 'pages' of information (useful for Text Editors for instance). In either case, it is most useful in situations where the available graphics space is not sufficient for the amount of information that needs to be shown. The Scroll class in itself is only designed to provide scrolling functionality, i.e. it does not create any gadgetry or graphics for the scrollbar. For that reason, complete scrollbars are usually created using scripts, and it is recommended that you refer to the 'templates:scrollbar.dml' file to see how this is done.

The Scroll class is designed to provide scrolling in 3 different directions - along the X, Y, or Z axis. You can combine the different axis, so a diagonal scrolling gadget could be created for example. It is also possible to create buttons that are attached to the Scroll object. Refer to the Left, Right, Up, Down, In and Out fields for more information.

You can use the Scroll class to create fixed or proportional scrollbars depending on what the situation dictates. Where possible you should use proportional scrolling as it is the easier of the two to set up. All you need to do is specify the page size (which represents the width or height of the graphical content) and the view size (the 'window' into the information). If you are going to create a fixed scrollbar, you will need to calculate the correct scale based on the size of the scrollbar and the area that is to be scrolled. Refer to the Scale field for more information on how this works.

Some objects are supportive of scrolling - for example, the TextList class supports horizontal and vertical scrolling through its HScroll and VScroll fields. Objects that support scrollbars expect to be connected directly to an appropriate Scroll object. Once that connection is established, they will take over the Scroll object so that the page size and positioning is always managed correctly. In such cases it is not necessary for you to pre-calculate the scale or page and view sizes.

Methods

The Scroll class implements the following methods:

UpdateScroll  Updates the dimensions of a scroll object's slider.

Structure

The Scroll object consists of the following public fields:

Down  Can refer to a drawable object representing a 'down button'.
Drawable  Defines the 'slider' that represents the Scroll object.
Flags  Special Scroll flags.
In  Can refer to a drawable object representing an 'in button'.
Intersect  This field is used for managing intersecting scrollbars.
Left  Can refer to a drawable object representing a 'left button'.
Out  Can refer to a drawable object representing an 'out button'.
PageSize  Defines the size of the page that is to be scrolled.
Position  Reflects the current position of the page within the view.
Right  Can refer to a drawable acting as the 'right button'.
Scale  Reflects the size ratio between the page and the scrollbar.
Unit  Defines the amount of movement used when a scroll button is pressed.
Up  Can refer to a drawable acting as the 'up button'.
ViewSize  Defines the size of the view that contains the page.
Method:UpdateScroll()
Short:Updates the dimensions of a scroll object's slider.
Arguments:
DOUBLE PageSize  The size of the page.
DOUBLE Position  The current position within the page.
DOUBLE ViewSize  The size of the view of the page.

After a Scroll object has been initialised, the best way to make any changes to the PageSize, Position or ViewSize is to use the UpdateScroll() method. When you call this method the Scroll object will update the size and position of the slider so that it correctly reflects the new values.

This method is typically used by programs and classes that have scrollbar awareness.

 

Field:Down
Short:Can refer to a drawable object representing a 'down button'.
Type:OBJECTID
Status:Read/Write

If you are using the Scroll object to create a fully featured vertical scrollbar, you will most likely want to create 'down and up buttons' on either side of the slider. To create a button you will need to create a drawable object with appropriate graphics, then refer to it via this field. The Scroll object will listen to the drawable for UserClick and UserClickRelease events that tell it when the button has been pressed. When that happens, the slider will automatically move downwards and the position of the page will be updated.

 

Field:Drawable
Short:Defines the 'slider' that represents the Scroll object.
Type:OBJECTID
Status:Read/Write

In order to work correctly, a Scroll object must be related to a drawable that acts as a slider. In most cases you should initialise the Scroll object to the drawable that will act as the slider. If you do not do this then you will have to tell the Scroll object exactly what drawable is acting as the slider, and thus will need to refer to the slider object via the Drawable field.

 

Field:Flags
Short:Special Scroll flags.
Type:LONG
Prefix:SCF
Status:Read/Write

Flags supported by the Scroll object are as follows:

FlagDescription
AUTOHIDEIf this flag is turned on then the Scroll object will automatically hide the container of the slider when the size of the view exceeds or is equal to the size of the page.
HORIZONTAL  If the Scroll object's slider will represent horizontal movement, set this flag.
VERTICALIf the Scroll object's slider will represent vertical movement, set this flag.
DEPTHIf the Scroll object's slider will represent depth-based (Z axis) movement, set this flag.

 

Field:In
Short:Can refer to a drawable object representing an 'in button'.
Type:OBJECTID
Status:Read/Write

If you are using the Scroll object to create a fully featured depth-based (Z axis) scrollbar, you may want to create 'in and out buttons' on either side of the slider. To create a button you will need to create a drawable object with appropriate graphics, then refer to it via this field. The Scroll object will listen to the drawable for UserClick and UserClickRelease events that tell it when the button has been pressed. When that happens, the slider will automatically move in the relevant direction and the position of the page will be updated.

Note that depth-based scrollbars may be oriented vertically or horizontally - either way, the movement will be translated to the Z axis.

 

Field:Intersect
Short:This field is used for managing intersecting scrollbars.
Type:OBJECTID
Status:Read/Init

If you are using a Scroll object in an arrangement that involves dual scrollbars (e.g. horizontal and vertical bars) then you may need to use the Intersect field if there is an overlap between the two. The purpose of this is to keep the scrollbars neatly arranged if one of them disappears (which can occur when the AUTOHIDE flag is being used).

Here is a basic diagram that illustrates a typical arrangement of dual scrollbars

   .------------------------.
   |                   .--. |
   |                   |  | |
   |                   |  | |
   |                   |oo| |
   |                   |oo| |
   |                   |oo| |
   |                   |  | |
   | .---------------. |  | |
   | |    OOO        | |  | |
   |.^---------------^ ^--^.|
   ^------------------------^

If the vertical bar in the diagram was to disappear as a result of auto-hiding, the horizontal bar would look out of place as a large gap would be present to the right of it. In this case we would want the horizontal bar to react by extending its width to cover the gap uncovered by the vertical bar when it is hidden. To do this, the Intersect field must be set to refer to the vertical bar's drawable.

Note that it is not necessary to set the Intersect field of the vertical scrollbar - this is because its height always matches that of its container.

 

Field:Left
Short:Can refer to a drawable object representing a 'left button'.
Type:OBJECTID
Status:Read/Write

If you are using the Scroll object to create a fully featured horizontal scrollbar, you will most likely want to create 'left and right buttons' on either side of the slider. To create a button you will need to create a drawable object with appropriate graphics, then refer to it via this field. The Scroll object will listen to the drawable for UserClick and UserClickRelease events that tell it when the button has been pressed. When that happens, the slider will automatically move to the left and the position of the page will be updated.

 

Field:Out
Short:Can refer to a drawable object representing an 'out button'.
Type:OBJECTID
Status:Read/Write

If you are using the Scroll object to create a fully featured depth-based (Z axis) scrollbar, you may want to create 'in and out buttons' on either side of the slider. To create a button you will need to create a drawable object with appropriate graphics, then refer to it via this field. The Scroll object will listen to the drawable for UserClick and UserClickRelease events that tell it when the button has been pressed. When that happens, the slider will automatically move in the relevant direction and the position of the page will be updated.

Note that depth-based scrollbars may be oriented vertically or horizontally - either way, the movement will be translated to the Z axis.

 

Field:PageSize
Short:Defines the size of the page that is to be scrolled.
Type:DOUBLE
Status:Read/Init

The page size of the area that is being scrolled is declared through this field. The page size should almost always be larger than the view size, because the page lies 'under' the view. There are legitimate exceptions however, so this rule is not enforced.

 

Field:Position
Short:Reflects the current position of the page within the view.
Type:DOUBLE
Status:Read/Init

As the page moves within the view, the exact position of the page must be recorded so that the Scroll gadget is correctly positioned within the scrollbar area. When setting up a Scroll object, you may need to set the Position value if the page starts at a certain offset within the view. Otherwise, you should leave the field at the default position of 0.

Please note that the Position value is always negative, and if you try to set a positive value then it will be automatically converted to a negative number.

 

Field:Right
Short:Can refer to a drawable acting as the 'right button'.
Type:OBJECTID
Status:Read/Write

If you are using the Scroll object to create a fully featured horizontal scrollbar, you will most likely want to create 'left and right buttons' on either side of the slider. To create a button you will need to create a drawable object with appropriate graphics, then refer to it via this field. The Scroll object will listen to the drawable for UserClick and UserClickRelease events that tell it when the button has been pressed. When that happens, the slider will automatically move to the right and the position of the page will be updated.

 

Field:Scale
Short:Reflects the size ratio between the page and the scrollbar.
Type:DOUBLE
Status:Read/Write

Every time that the Scroll gadget moves, it will send a message to the destination object telling it to scroll in a given direction, by a certain value. That value is heavily affected by the Scale field, which is supposed to reflect the size ratio between the page and the scrollbar. The adjustment formula looks like this:

   ScrollValue = Scale * GadgetMovement

So if the Scroll gadget was to move 5 pixels to the left and the Scale was set to 2.5, then the object that represents the page would be told to move by a value of 12.5:

  12.5 = 5 * 2.5

In most cases you should not set the Scale field as it will be automatically calculated from the PageSize and ViewSize values. However, if you are designing a non-proportional scrollbar then you might have a valid reason for setting the Scale field directly rather than giving PageSize and ViewSize values. If this is case, then calculating your own Scale is permitted, but only for non-proportional (fixed) scrollbars.

 

Field:Unit
Short:Defines the amount of movement used when a scroll button is pressed.
Type:DOUBLE
Status:Read/Write

If you have attached buttons to a Scroll object through the In, Out, Left, Right, Up or Down fields then you may want to specify the amount of units to use when a related button is pressed. Example: If the unit is set to 15 and the scroll position is currently set to 60, pressing a negative button would change the position to 45.

The Unit value should normally be positive, but if you set it to 0 or less then the Unit will be dynamically calculated to match the size of the slider.

 

Field:Up
Short:Can refer to a drawable acting as the 'up button'.
Type:OBJECTID
Status:Read/Write

If you are using the Scroll object to create a fully featured vertical scrollbar, you will most likely want to create 'down and up buttons' on either side of the slider. To create a button you will need to create a drawable object with appropriate graphics, then refer to it via this field. The Scroll object will listen to the drawable for UserClick and UserClickRelease events that tell it when the button has been pressed. When that happens, the slider will automatically move upwards and the position of the page will be updated.

 

Field:ViewSize
Short:Defines the size of the view that contains the page.
Type:DOUBLE
Status:Read/Write

The ViewSize defines the width or height of the area that is viewing the page. The view should almost always be smaller than the size of the page, because the view sits above it. There are legitimate exceptions however, so this particular rule is not enforced.