Class Documentation

Name:ScrollBar
Version:1.0
ID:ID_SCROLLBAR
Status:Beta
Category:GUI
Date:December 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 2003. All rights reserved.
Short:  The ScrollBar class creates scroll-bars for the user interface.



Description

The ScrollBar class simplifies the creation and management of scrollbars as part of the user interface. A scrollbar is a rectangular gadget that typically sits at the far-right or bottom of a scrollable page. A slider is present in the scrollbar and performs the scrolling action when it is dragged with the mouse. Buttons may be present at either end of the scrollbar for the purpose of micro-scrolling.

The definitions for new scrollbars are loaded by default from the environment file "templates:scrollbardef.xml". You can change the template file prior to initialisation by setting the Template field. For information on how to develop customised scrollbars, please refer to the documentation for the Template field.

The ScrollBar class is closely related to the Scroll class. To configure the size of the scrollable page and the viewable area, you need to communicate that information to the Scroll class. More information is available in the Scroll class documentation.

To create a new scrollbar, you need to specify the scrollbar's scrolling direction at a minimum. The following example illustrates:

  <scrollbar direction="horizontal"/>

The positioning of the scrollbar will be automatically calculated for you based on this information. To link a scrollbar to an object, such as a text viewing area, you will need to extract the scroll object from the scrollbar and pass it to the scrollable object. Here is an example:

  <scrollbar name="vsb" direction="vertical"/>
  <text vscroll="[vsb.scroll]" .../>

If a new scrollbar is created without being hooked into another object, it will send scroll messages to its parent drawable.

Actions

The ScrollBar class supports the following actions:

Hide  Removes the scrollbar from the display.
Redimension  Changes the size and position of the scrollbar.
Resize  Alters the size of the scrollbar.
Show  Puts the scrollbar on display.

Structure

The ScrollBar object consists of the following public fields:

Bottom  The bottom coordinate of the scrollbar.
Breadth  The breadth of the scrollbar is defined here.
Drawable  The drawable that will contain the scrollbar graphic.
Flags  Optional flags may be set here.
Height  Defines the height of a scrollbar.
Right  The right coordinate of the scrollbar.
Template  Defines the makeup of the scrollbar using a pre-defined template.
Width  Defines the width of a scrollbar.
XCoord  The horizontal position of a scrollbar.
XOffset  The horizontal offset of a scrollbar.
YCoord  The vertical position of a scrollbar.
YOffset  The vertical offset of a scrollbar.
Field:Bottom
Short:The bottom coordinate of the scrollbar.
Type:LONG
Status:Get

The bottom coordinate of the scrollbar (calculated as YCoord + Height) is readable from this field.


Field:Breadth
Short:The breadth of the scrollbar is defined here.
Type:LONG
Status:Read/Init

The breadth of the scrollbar can be altered in this field. The breadth of the scrollbar will either be its width (if vertical) or height (if horizontal). The breadth of the scrollbar is user-definable and should not be changed without good reason.


Field:Drawable
Short:The drawable that will contain the scrollbar graphic.
Type:OBJECTID
Status:Read/Init

The drawable that will contain the scrollbar graphic is set here. If this field is not set prior to initialisation, the scrollbar will attempt to scan for the correct drawable by analysing its parents until it finds a suitable candidate.


Field:Flags
Short:Optional flags may be set here.
Type:LONG
Status:Read/Init

Optional flags that may be set against a scrollbar object are as follows:

FlagDescription
HIDEThis flag may be set on initialisation in order to hide the scrollbar on its creation (applies to script usage only).
CONSTANTBy default, a scrollbar will automatically remove itself from the display when the area to be scrolled is smaller than the size of the view. You can turn off this behaviour by setting the CONSTANT option, which ensures that the scrollbar is always on display.
NOINTERSECTIf you create two scrollbars in the same drawable space, they will automatically be configured to intersect with each other. You can turn off this behaviour by setting the NOINTERSECT flag.

Field:Height
Short:Defines the height of a scrollbar.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

A scrollbar can be given a fixed or relative height by setting this field to the desired value. To set a relative height, use the FD_PERCENT flag when setting the field.


Field:Right
Short:The right coordinate of the scrollbar.
Type:LONG
Status:Get

The right coordinate of the scrollbar (calculated as XCoord + Width) is readable from this field.


Field:Template
Short:Defines the makeup of the scrollbar using a pre-defined template.
Type:STRING
Status:Init

Customised scrollbars can be created by writing a template file and then referring to its location in this field. You will be required to configure the look of the scrollbar for both vertical and horizontal arrangements. This is done by writing a series of script procedures for the different areas of the scrollbar.

The following extract is from the default templates:scrollbardef.xml file. Notice that there are three areas to define, all of which relate to the creation of a vertical scrollbar. The procedures are: vbar - defines the background graphic for the entire scrollbar area; vslider - defines the graphical content of the slider; vbuttons - creates the buttons for the scrollbar. For a horizontal scrollbar the procedures are named hbar, hslider and hbuttons. A special 'scroll' argument may be referenced if you need to talk to the scroll object that controls the scrollbar slider. This is necessary for registering buttons in the scrollbar (note use of the Scroll class' AddButton method).

<dml procedure="vbar">
  <set object="[owner]" width="18" topmargin="=[owner.width]-1" bottommargin="=[owner.width]-1"/>
  <gradient firstcolour="192,192,192" lastcolour="90,90,90" direction="vertical"/>
  <box border="64,64,64"/>
</dml>

<dml procedure="vslider">
  <box boxes="(r0,0,!0,!0) (r1,1,!1,!1)" highlight="64,64,64"
    highlight(1)="255,255,255" shadow="64,64,64" shadow(1)="175,175,175" colour="230,230,230"/>
  <image src="environment:images/scrollbar" align="center"/>
</dml>

<dml procedure="vbuttons">
  <button x="0" y="0" height="[owner.width]" xoffset="0" flags="!nofocus">
    <arrow drawable="[owner.region]" align="center" arrowwidth="7" arrowheight="4" direction="up" colour="60,60,60"/>
    <action method="addbutton" object="[{scroll}]" &button="[owner]" &direction="1"/>
  </button>

  <button x="0" yoffset="0" height="[owner.width]" xoffset="0" flags="!nofocus">
    <arrow drawable="[owner.region]" align="center" arrowwidth="7" arrowheight="4" direction="down" colour="60,60,60"/>
    <action method="addbutton" object="[{scroll}]" &button="[owner]" &direction="2"/>
  </button>
</dml>

Field:Width
Short:Defines the width of a scrollbar.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

A scrollbar can be given a fixed or relative width by setting this field to the desired value. To set a relative width, use the FD_PERCENT flag when setting the field.


Field:XCoord
Short:The horizontal position of a scrollbar.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The horizontal position of a scrollbar can be set to an absolute or relative coordinate by writing a value to the XCoord field. To set a relative/percentage based value, you must use the FD_PERCENT flag or the value will be interpreted as fixed. Negative values are permitted.


Field:XOffset
Short:The horizontal offset of a scrollbar.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The XOffset has a dual purpose depending on whether or not it is set in conjunction with an X coordinate or a Width based field.

If set in conjunction with an X coordinate then the scrollbar will be drawn from that X coordinate up to the width of the container, minus the value given in the XOffset. This means that the width of the ScrollBar is dynamically calculated in relation to the width of the container.

If the XOffset field is set in conjunction with a fixed or relative width then the scrollbar will be drawn at an X coordinate calculated from the formula "XCoord = ContainerWidth - ScrollBarWidth - XOffset".


Field:YCoord
Short:The vertical position of a scrollbar.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The vertical position of a ScrollBar can be set to an absolute or relative coordinate by writing a value to the YCoord field. To set a relative/percentage based value, you must use the FD_PERCENT flag or the value will be interpreted as fixed. Negative values are permitted.


Field:YOffset
Short:The vertical offset of a scrollbar.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The YOffset has a dual purpose depending on whether or not it is set in conjunction with a Y coordinate or a Height based field.

If set in conjunction with a Y coordinate then the scrollbar will be drawn from that Y coordinate up to the height of the container, minus the value given in the YOffset. This means that the height of the scrollbar is dynamically calculated in relation to the height of the container.

If the YOffset field is set in conjunction with a fixed or relative height then the scrollbar will be drawn at a Y coordinate calculated from the formula "YCoord = ContainerHeight - ScrollBarHeight - YOffset".