Class Documentation
Scroll |
1.0 |
ID_SCROLL |
Stable |
GUI |
December 2003 |
Rocklyte Systems |
Rocklyte Systems (c) 1999-2003. All rights reserved. |
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:
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. |
AddScrollButton() |
AddButton |
Registers a new button with the scroll object. |
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.
ERR_Okay | The button was registered successfully. |
ERR_Args | The required arguments were not specified. |
|
|
UpdateScroll() |
Updates the dimensions of a scroll object's slider. |
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:
AUTOHIDE | If 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. |
VERTICAL | If the scroll object's slider will represent vertical movement, set this flag. |
RELATIVE | Forces 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.
|
|