Dashboard Programming Topics

Using Scroll Areas

Apple provides JavaScript classes that allow you to declare a scroll area and associated scroll bars. The classes that provide this, AppleScrollArea and AppleScrollbar, are two of the Apple Classes included in OS X v10.4.3 and later.

Working with Scroll Areas

Include the AppleScrollArea and AppleScrollbar classes in your HTML file

Provide a <div> element in your HTML for the scrollable content

Provide a <div> element in your HTML for the scroll bar

Declare an onload handler, a JavaScript function called when your widget loads that constructs AppleScrollArea and AppleScrollbar objects

Place the content and scroll bar <div> elements using CSS

Construct your scroll area and scroll bars using the AppleScrollArea and AppleScrollbar classes in JavaScript

By default, the AppleScrollbar uses artwork supplied by Apple to represent the various parts of the scroll bar. It is possible to provide your own artwork as well.

There are two types of scroll bars available to you: vertical and horizontal. You should take into account which type of scroll bar you want to use when designing and coding your widget. Both are subclasses of the AppleScrollbar class and are used in JavaScript to construct the type of scroll bar you want to use. Figure 25 shows an example of a standard vertical scroll bar inside a scroll area (the entire white area is the scroll area).

Figure 25 A vertical scroll bar created from the AppleScrollbar class

Scroll Areas and Scroll Bars, in HTML

In order to declare a scroll area and to use it in JavaScript, you need to include the AppleScrollArea and AppleScrollbar classes in your widget's HTML file, provide <div> elements that represent your scrollable content and your scroll bars in your widget's structure, and have an onload handler that's called when your widget's HTML is loaded. The handler is used in JavaScript to construct the scroll areas and scroll bars.

First, you need to include the AppleScrollArea and AppleScrollbar classes in your main HTML file. If you're planning backward compatibility with pre-OS X v.10.4.3 versions, follow the directions in Backwards Compatible Usage and include this path:

Important: In addition to copying the AppleScrollbar.js file into your widget, you need to copy the Images directory from /System/Library/WidgetResources/ into your widget's bundle and edit AppleScrollbar.js so that any references to the image's paths point to the local copies instead. The file contains paths that look like:

Once you've included the AppleScrollArea and AppleScrollbar classes, you also need to declare <div> elements for your scrollable content and a scroll bar:

<body onload="setup();">

...

<div id="myScrollArea">...</div>

<div id="myScrollbar"></div>

...

</body>

The only attribute required of either <div> element is an id, which is used by CSS to position scroll area and scroll bar, and by JavaScript to construct them. The id attribute is required over the class attribute because elements with id attributes can be accessed via JavaScript.

Also note the declaration of an onload handler within the <body> tag. This handler is called when your widget's HTML is loaded. It's used to construct the AppleScrollArea and AppleScrollbar objects in your JavaScript, as discussed in Scroll Areas and Scroll Bars, in JavaScript.

Scroll Areas and Scroll Bars, in CSS

Now that the scroll area and scroll bar are properly declared in your HTML file, you need to position them in your CSS. This entails including a style with the element's name and any other placement parameters you see fit to use:

#myScrollArea {

position: absolute;

top: 10px;

bottom: 10px;

left: 10px;

right: 30px;

}

#myScrollbar {

position: absolute;

top: 10px;

bottom: 10px;

right: 10px;

width: 19px;

}

Note the scroll bar's width attribute. A value of 19px is used here because the default artwork provided by Apple for the scroll bar is 19 pixels wide. If you are providing custom artwork for a scroll bar, use the width of your artwork instead.

If your scroll area is using a horizontal scroll bar, use the height attribute in place of the width attribute. If you are using the artwork provided by Apple, specify scroll bar heights as 19 pixels.

Scroll Areas and Scroll Bars, in JavaScript

In your HTML file, you included an onload handler as an attribute of the <body> tag. That handler is called once Dashboard has loaded your widget's HTML file and is used to call the constructors for the AppleScrollArea class and an AppleScrollbar subclass. First, you construct the scroll bar.

Based on which type of scroll bar you are using, you call the constructor for either an AppleHorizontalScrollbar or AppleVerticalScrollbar. The constructors are defined as:

Table 3AppleScrollbar Subclasses

Horizontal Scroll Bar Constructor

Vertical Scroll Bar Constructor

AppleHorizontalScrollbar(scrollbar)

AppleVerticalScrollbar(scrollbar)

Both constructors take in a DOM object that represents where the scroll bar should be built. The DOM object is the <div> that you defined in your HTML and placed in your CSS.

The AppleScrollArea constructor also takes in a DOM object. This is the <div> specified in your HTML as the scrollable content:

AppleScrollArea(content)

In your JavaScript, your onload handler needs to use the AppleScrollArea constructor and the constructor for a subclass of AppleScrollbar. For a vertical scroll bar, your onload handler code looks like:

var gMyScrollArea, gMyScrollbar;

function setup()

{

gMyScrollbar = new AppleVerticalScrollbar(

document.getElementById("myScrollbar")

);

gMyScrollArea = new AppleScrollArea(

document.getElementById("myScrollArea")

);

gMyScrollArea.addScrollbar(gMyScrollbar);

}

In the last line of the setup() function, the addScrollbar method is called. This associates the constructed scroll bar with the scroll area, meaning that any interaction on the scroll bar effects the associated scroll area.

You can associate scroll areas and scroll bars via addScrollbar or you can add them as additional arguments to the AppleScrollArea constructor:

AppleScrollArea(content, scrollbar, ...)

The AppleScrollArea constructor can accept any number of scroll bars.

These methods and properties are also available to AppleScrollArea objects and allow you to modify its behavior:

Table 4AppleScrollArea object properties and methods

Option

Type

Explanation

gMyScrollArea.scrollsVertically

Property

Read/Write; determines if the scroll area scrolls vertically

gMyScrollArea.scrollsHorizontally

Property

Read/Write; determines if the scroll area scrolls horizontally

gMyScrollArea.singlepressScrollPixels

Property

Read/Write; the number of pixels the scroll area scrolls when an arrow key is pressed

gMyScrollArea.viewHeight

Property

Read only; the height of the scroll area

gMyScrollArea.viewToContentHeightRatio

Property

Read only; the ratio of the height of the view versus the total amount of content shown

gMyScrollArea.viewWidth

Property

Read only; the width of the scroll area

gMyScrollArea.viewToContentWidthRatio

Property

Read only; the ratio of the width of the view versus the total amount of content shown