Class Documentation

Name:Scroll
Version:1.0
ID:ID_SCROLL
Status:Stable
Category:GUI
Date:December 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 1999-2003. All rights reserved.
Short:  This class is used to aid in the creation of 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 or helper classes, such as the ScrollBar class.

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 Text 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:

AddScrollButton  Registers a new button with the scroll object.
UpdateScroll  Updates the dimensions of a scroll object's slider.

Structure

The Scroll object consists of the following public fields:

Axis  The axis that the scroll object represents can be defined here.
Drawable  Defines the 'slider' that represents the scroll object.
Field  Reference to an object field that should be updated with the scroll value.
Flags  Special scroll flags.
Intersect  This field is used for managing intersecting scrollbars.
Monitor  Objects can be monitored for scroll requests by setting this field.
Object  Refers to the object that will receive the scroll action.
PageSize  Defines the size of the page that is to be scrolled.
Position  Reflects the current position of the page within the view.
SliderSize  Can refer to a drawable acting as the 'right button'.
Unit  Defines the amount of movement used when a scroll button is pressed.
ViewSize  Defines the size of the view that contains the page.
Method:AddScrollButton()
Synonym:AddButton
Short:Registers a new button with the scroll object.
Arguments:
OBJECTID Button  Reference to a Button, Render object or any class type that supports UserClick and UserClickRepeat actions..
LONG Direction  The direction that the button represents - SD_NEGATIVE or SD_POSITIVE.

If you are using the scroll object to create a complete scrollbar, you may want to create buttons at either end of the bar. You will need to register new buttons with the scroll object, which you may do by calling the AddButton method.

A button is typically created from the Button or Render classes, but you may use any object type that belongs to a class supporting the UserClick and UserClickRepeat actions. To register the button you need to provide the AddScrollButton method with the button's unique ID. The Direction represented by the button must also be specified as SD_NEGATIVE or SD_POSITIVE.

Result
ERR_Okay  The button was registered successfully.
ERR_Args  The required arguments were not specified.

Method:UpdateScroll()
Short:Updates the dimensions of a scroll object's slider.
Arguments:
LONG PageSize  The size of the page. Set to zero for no change.
LONG ViewSize  The size of the view of the page. Set to zero for no change.
LONG Position  The current position within the page.
LONG Unit  The unit size to use for micro-scrolling. Set to zero for no change, or -1 to enable jump scrolling.

After a scroll object has been initialised, the only way to make 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:Axis
Short:The axis that the scroll object represents can be defined here.
Type:LONG
Status:Read/Set

When a scroll slider is moved, scroll messages are sent for one axis only - either X, Y, or Z. You need to define the axis here using one of the constants AXIS_X, AXIS_Y or AXIS_Z. The axis does not necessarily have to match the orientation of the scrollbar. For instance, a horizontal scrollbar can send vertical scroll messages if you use AXIS_Y.


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:Field
Short:Reference to an object field that should be updated with the scroll value.
Type:STRING
Status:Set

If you would like to write the position of a scroll object to a field belonging to another object (refer to the Object field), you can make reference to the field name here. By doing this, whenever the scroll object updates its internal position value, it will also write that value to the referenced field name.


Field:Flags
Short:Special scroll flags.
Type:LONG
Prefix:SCF
Status:Read/Set

Flags supported by the scroll object are as follows:

FlagDescription
AUTOHIDEIf this flag is 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.
RELATIVEForces relative scrolling through the Scroll action rather than the default ScrollToPoint.

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

When two scroll objects are used to create opposing scrollbars (e.g. horizontal and vertical bars) then you should set 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 will occur if the viewable area is larger than the size of the scrollable page).

The Intersect field must be set to a valid scroll object that represents the opposing scrollbar. The opposing scroll object does not need to have its Intersect field set.

If you use the ScrollBar class, intersections are managed automatically.


Field:Monitor
Short:Objects can be monitored for scroll requests by setting this field.
Type:OBJECTID
Status:Set

To monitor an object for scroll requests, set this field to a valid object ID. This feature is often used to support the wheel mouse, for instances where the mouse is positioned over a drawable area and the wheel is used. The use of the wheel will cause Scroll messages to be sent from the mouse to the underlying drawable. By setting this field to the drawable area that is being scrolled, the scrollbar can receive and respond to the scroll messages.


Field:Object
Short:Refers to the object that will receive the scroll action.
Type:OBJECTID
Status:Read/Write

The Object field must refer to a foreign object that will receive Scroll notification calls whenever the scroll object is moved.


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

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. If the page is smaller than the view, the scroll object will serve no purpose until the circumstances are changed.


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

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.


Field:SliderSize
Short:Can refer to a drawable acting as the 'right button'.
Type:LONG
Status:Read/Init

The SliderSize field can be read if you need to know the size of the slider represented by a scroll object. You can also set this field during initialisation if you would like a fixed slider to be used (this results in a non-proportional scrollbar).


Field:Unit
Short:Defines the amount of movement used when a scroll button is pressed.
Type:LONG
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:ViewSize
Short:Defines the size of the view that contains the page.
Type:LONG
Status:Read/Set

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.