Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

18    Scroll Bars

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

This chapter provides reference material for the scroll bar API.

The header file ScrollBar.h declares the API that this chapter describes. For more information on scroll bars, see the section "Scroll Bars" in the Palm OS Programmer's Companion, vol. I.

Scroll Bar Data Structures ^TOP^

ScrollBarAttrType Struct ^TOP^

Purpose

The ScrollBarAttrType bit field defines a scroll bar's visible characteristics.

Prototype 

typedef struct {
  UInt16 usable:1;
  UInt16 visible:1;
  UInt16 hilighted:1;
  UInt16 shown:1;
  UInt16 activeRegion:4;
} ScrollBarAttrType;

Fields

usable
If not set, the scroll bar object is not considered part of the current interface of the application, and it doesn't appear on screen.
visible
If set, the scroll bar is allowed to be displayed on the screen. If both visible and shown are true, then the scroll bar is actually displayed on the screen.
hilighted
true if either the up arrow or the down arrow is highlighted.
shown
Set if the scroll bar is visible and if maxValue > minValue. (See ScrollBarType.)
activeRegion
The region of the scroll bar that is receiving the pen down events. Possible values are:
sclUpArrow
The up arrow.
sclDownArrow
The down arrow.
sclUpPage
The region between the scroll car and the up arrow.
sclDownPage
The region between the scroll car and the down arrow.
sclCar
The scroll car.

ScrollBarPtr Typedef ^TOP^

Purpose

The ScrollBarPtr type defines a pointer to a ScrollBarType structure.

Prototype 

typedef ScrollBarType *ScrollBarPtr;

You pass the ScrollBarPtr as an argument to all scroll bar functions. You can obtain the ScrollBarPtr using the function FrmGetObjectPtr() in this way:

scrollBarPtr = FrmGetObjectPtr(frm, 
  FrmGetObjectIndex(frm, scrollBarID));

where scrollBarID is the resource ID assigned when you created the scroll bar.

ScrollBarType Struct ^TOP^

Purpose

The ScrollBarType represents a scroll bar.

WARNING! PalmSource, Inc. does not support or provide backward compatibility for the ScrollBarType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.

Prototype 

typedef struct {
  RectangleType bounds;
  UInt16 id;
  ScrollBarAttrType attr;
  Int16 value;
  Int16 minValue;
  Int16 maxValue;
  Int16 pageSize;
  Int16 penPosInCar;
  Int16 savePos;
} ScrollBarType;

Your code should treat the ScrollBarType structure as opaque. Use the functions described in this chapter to retrieve and set each value. Do not attempt to change structure member values directly.

Fields

bounds
Position (using absolute coordinates) and size (in pixels) of the scroll bar on the screen. For example, to access the bounds of an object in a form whose ID is kObjectID:
{
RectangleType rect;
FormPtr formP = FrmGetActiveForm();
FrmGetObjectBounds(formP, FrmGetObjectIndex(formP, kObjectID), &rect);
}
id
ID value you specified when you created the scroll bar object.
attr
Scroll bar's attributes. See ScrollBarAttrType.
value
Current value of the scroll bar. This value is used to determine where to position the scroll car (the dark region in the scroll bar that indicates the position in the document). Access with SclGetScrollBar().
The number given is typically a number relative to minValue and maxValue. These values have nothing to do with any physical characteristics of the object that the scroll bar is attached to, such as the number of lines in the object.
This value is typically set to 0 initially and then adjusted programmatically with SclSetScrollBar().
minValue
Minimum value. When value equals minValue, the scroll car is positioned at the very top of the scrolling region. This value is typically 0. Access with SclGetScrollBar().
maxValue
Maximum value. When value equals maxValue, the scroll car is positioned at the very bottom of the scrolling region. This value is typically set to 0 initially and then adjusted programmatically with SclSetScrollBar(). Access with SclGetScrollBar().
pageSize
Number of lines to scroll when user scrolls one page. Access with SclGetScrollBar().
penPosInChar
Used internally.
savePos
Used internally.

Scroll Bar Resources ^TOP^

The Scroll Bar Resource (tSCL) represents a scroll bar. See Palm OS User Interface Guidelines for more information.

Scroll Bar Functions ^TOP^

SclDrawScrollBar Function ^TOP^

Purpose

Draw a scroll bar.

Declared In

ScrollBar.h

Prototype 

void SclDrawScrollBar (
   ScrollBarType *bar
)

Parameters

→ bar
Pointer to a scroll bar structure (see ScrollBarType).

Returns

Returns nothing.

Comments

This function is called internally by SclSetScrollBar() and FrmDrawForm(). You rarely need to call it yourself.

Compatibility

Implemented only if 2.0 New Feature Set is present.

SclGetScrollBar Function ^TOP^

Purpose

Retrieve a scroll bar's current position, its range, and the size of a page.

Declared In

ScrollBar.h

Prototype 

void SclGetScrollBar (
   const ScrollBarType *bar,
   Int16 *valueP,
   Int16 *minP,
   Int16 *maxP,
   Int16 *pageSizeP
)

Parameters

→ bar
Pointer to a scroll bar structure (see ScrollBarType).
← valueP
A value representing the scroll car's current position. (The scroll car is the dark region that indicates the position in the document.)
← minP
A value representing the top of the user interface object.
← maxP
A value representing the bottom of the user interface object.
← pageSizeP
Pointer to size of a page (used when page scrolling).

Returns

Returns the scroll bar's current values in valueP, minP, maxP, and pageSizeP.

Comments

You might use this function immediately before calling SclSetScrollBar() to update the scroll bar. SclGetScrollBar returns the scroll bar's current values, which you can then adjust as necessary and pass to SclSetScrollBar.

Compatibility

Implemented only if 2.0 New Feature Set is present.

See Also

SclSetScrollBar()

SclHandleEvent Function ^TOP^

Purpose

Handles events that affect a scroll bar.

Declared In

ScrollBar.h

Prototype 

Boolean SclHandleEvent (
   ScrollBarType *bar,
   const EventType *event
)

Parameters

→ bar
Pointer to a scroll bar structure (see ScrollBarType).
→ event
Pointer to an event (EventType).

Returns

Returns true if the event was handled.

Comments

When a penDownEvent occurs, the scroll bar sends an sclEnterEvent to the event queue.

When an sclEnterEvent occurs, the scroll bar determines what its new value should be based on which region of the scroll bar is receiving the pen down events. It then sends either an sclRepeatEvent or an sclExitEvent to the event queue.

When the user holds and drags the scroll bar with the pen, the scroll bar sends a sclRepeatEvent. Applications that implement dynamic scrolling should catch this event and move the text each time one arrives.

When the user releases the pen from the scroll bar, the scroll bar sends a sclExitEvent. Applications that implement non-dynamic scrolling should catch this event and move the text when sclExitEvent arrives. Applications that implement dynamic scrolling can ignore this event.

Compatibility

Implemented only if 2.0 New Feature Set is present.

SclSetScrollBar Function ^TOP^

Purpose

Set the scroll bar's current position, its range, and the size of a page. If the scroll bar is visible and its minimum and maximum values are not equal, it's redrawn.

Declared In

ScrollBar.h

Prototype 

void SclSetScrollBar (
   ScrollBarType *bar,
   Int16 value,
   Int16 min,
   Int16 max,
   Int16 pageSize
)

Parameters

→ bar
Pointer to a scroll bar structure (see ScrollBarType).
→ value
The position the scroll car should move to. (The scroll car is the dark region that indicates the position in the document.)
→ min
Minimum value.
→ max
Maximum value.
→ pageSize
Number of lines of text that can be displayed on a the screen at one time (used when page scrolling).

Returns

Returns nothing. May display a fatal error message if the min parameter is greater than the max parameter.

Comments

Call this function when the user adds or deletes text in a field or when a table row is added or deleted.

For scrolling fields, your application should catch the fldChangedEvent and update the scroll bar at that time.

The max parameter is computed as:

number of lines of text – page size + overlap

where number of lines of text is the total number of lines or rows needed to display the entire object, page size is the number of lines or rows that can be displayed on the screen at one time, and overlap is the number of lines or rows from the bottom of one page to be visible at the top of the next page.

For example, if you have 100 lines of text and 10 lines show on a page, the max value would be 90 or 91, depending on the overlap. So if value is greater than or equal to 90 or 91, the scroll car is at the very bottom of the scrolling region.

You can use the FldGetScrollValues() function to compute the values you pass for value, min, and max. For example:

FldGetScrollValues (fld, &scrollPos,  
  &textHeight,  &fieldHeight); 
  
if (textHeight > fieldHeight) 
  maxValue = textHeight - fieldHeight; 
else if (scrollPos) 
  maxValue = scrollPos; 
else 
  maxValue = 0; 
  
SclSetScrollBar (bar, scrollPos, 0, maxValue,  
  fieldHeight-1);

In this case, textHeight is the number of lines of text and fieldHeight is the page size. No lines overlap when you scroll one page. Notice that if the page size is greater than the lines of text, then max equals min, which means that the scroll bar is not displayed.

For scrolling tables, there is no equivalent to FldGetScrollValues. Your application must scroll the table itself and keep track of the scroll values. See the ListViewUpdateScrollers function in the Memo example application (MemoMain.c) for an example of setting scroll bar values for a table.

Compatibility

Implemented only if 2.0 New Feature Set is present.

See Also

SclGetScrollBar()

 
   

Copyright © 1996-2004, PalmSource, Inc. and its affiliates. All rights reserved.
Write Us | Training | Knowledge Base | Legal


Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index