Class Documentation
Scroll |
1.0 |
ID_SCROLL |
Unspecified |
GUI |
May 2001 |
Rocklyte Systems |
Rocklyte Systems (c) 1999-2001. All rights reserved. |
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. |
UpdateScroll() |
Updates the dimensions of a scroll object's slider. |
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:
AUTOHIDE | If 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. |
VERTICAL | If the Scroll object's slider will represent vertical movement, set this flag. |
DEPTH | If 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.
|
|