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

31    Scroll Bar Reference

User Interface

Exploring Palm OS®

This chapter provides reference material for the scroll bar API.

Scroll Bar Structures and Types
Scroll Bar Events
Scroll Bar Functions and Macros

The header file ScrollBar.h declares the API that this chapter describes. For more information on scroll bars, see "Scroll Bars."

Scroll Bar Structures and Types ^TOP^

ScrollBarType Struct ^TOP^

Purpose

Internal structure representing a scroll bar. The ScrollBarPtr defines a pointer to a ScrollBarType structure.

Declared In

ScrollBar.h

Prototype

typedef struct ScrollBarType ScrollBarType;
typedef ScrollBarType *ScrollBarPtr

Fields

None.

Scroll Bar Events ^TOP^

frmScrollPrvRefreshEvent ^TOP^

Purpose

Used to update the display of a scroll bar.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct sclRepeat {
   struct ScrollBarType *pScrollBar;
   uint16_t scrollBarID;
   uint16_t firstTapTime;
   int32_t value;
   int32_t newValue;
   uint32_t time;
} sclRepeat

Fields

pScrollBar
Pointer to the scroll bar structure.
scrollBarID
Resource ID of the scroll bar.
firstTapTime
System-ticks count when the first pen down that started this sequence of refresh events occurred.
value
Initial position of the scroll bar.
newValue
New position of the scroll bar. Given value and newValue, you can tell how much you have scrolled.
time
System-ticks count when the event is added to the queue. Used to determine when the next event should occur.

The following fields in the EventType structure are set for this event:

penDown
Always true.
screenX
Draw window-relative position of the pen in standard coordinates (number of coordinates from the left bound of the window).
screenY
Draw window-relative position of the pen in coordinates (number of coordinates from the top of the window).

Comments

Applications do not respond to this event. It is used by the system to refresh the display.

sclEnterEvent ^TOP^

Purpose

Sent when penDownEvent occurs within the bounds of a list.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct sclEnter {
   struct ScrollBarType *pScrollBar;
   uint16_t scrollBarID;
   _BA32_PADDING_16(1)
} sclEnter

Fields

pScrollBar
Pointer to the scroll bar structure.
scrollBarID
Resource ID of the scroll bar.

Comments

Applications usually don't have to handle this event. Instead, wait for a sclExitEvent or sclRepeatEvent.

sclExitEvent ^TOP^

Purpose

Sent when the user lifts the pen from the scroll bar.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct sclExit {
   struct ScrollBarType *pScrollBar;
   uint16_t scrollBarID;
   _BA32_PADDING_16(1)
   int32_t value;
   int32_t newValue;
} sclExit

Fields

pScrollBar
Pointer to the scroll bar structure.
scrollBarID
Resource ID of the scroll bar.
value
Initial position of the scroll bar
newValue
New position of the scroll bar. Given value and newValue, you can tell how much you have scrolled.

Comments

Applications that want to implement non-dynamic scrolling should wait for this event, then scroll the item using the values provided in value and newValue. Return true to indicate that you've handled the event.

Note that this event is sent regardless of previous sclRepeatEvents. If, however, the application has implemented dynamic scrolling, it doesn't have to respond to this event.

sclRepeatEvent ^TOP^

Purpose

Sent when the pen is continually held within the bounds of a scroll bar.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct sclRepeat {
   struct ScrollBarType *pScrollBar;
   uint16_t scrollBarID;
   uint16_t firstTapTime;
   int32_t value;
   int32_t newValue;
   uint32_t time;
} sclRepeat

Fields

pScrollBar
Pointer to the scroll bar structure.
scrollBarID
Resource ID of the scroll bar.
firstTapTime
System-ticks count when the first pen down that started this sequence of repeat events occurred.
value
Initial position of the scroll bar.
newValue
New position of the scroll bar. Given value and newValue, you can actually tell how much you have scrolled.
time
System-ticks count when the event is added to the queue. Used to determine when the next event should occur.

The following fields in the EventType structure are set for this event:

penDown
Always true.
screenX
Draw window-relative position of the pen in standard coordinates (number of coordinates from the left bound of the window).
screenY
Draw window-relative position of the pen in coordinates (number of coordinates from the top of the window).

Comments

Applications that implement dynamic scrolling should watch for this event. In dynamic scrolling, the display is updated as the user drags the scroll bar (not after the user releases the scroll bar). Return true to indicate that you've handled the event.

Scroll Bar Functions and Macros ^TOP^

SclDrawScrollBar Function ^TOP^

Purpose

Draws a scroll bar.

Declared In

ScrollBar.h

Prototype

void SclDrawScrollBar (
   const ScrollBarPtr bar
)

Parameters

bar
Pointer to a scroll bar structure.

Returns

Nothing.

Comments

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

SclGetScrollBar Function ^TOP^

Purpose

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

Declared In

ScrollBar.h

Prototype

void SclGetScrollBar (
   const ScrollBarPtr bar,
   int32_t *valueP,
   int32_t *minP,
   int32_t *maxP,
   int32_t *pageSizeP
)

Parameters

bar
Pointer to a scroll bar structure.
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 element.
maxP
A value representing the bottom of the user interface element.
pageSizeP
Pointer to size of a page (used when page scrolling).

Returns

Nothing.

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().

SclHandleEvent Function ^TOP^

Purpose

Handles events that affect a scroll bar.

Declared In

ScrollBar.h

Prototype

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

Parameters

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

Returns

true if the event was handled.

Comment

When a penDownEvent occurs, the scroll bar sends an sclEnterEvent. While the pen is held down, it sends a sclRepeatEvent. Applications that implement dynamic scrolling should catch this event and scroll the item each time one arrives.

When a penUpEvent occurs and the pen is within the bounds of the scroll bar, it adds a sclExitEvent. Applications that implement non-dynamic scrolling should catch sclExitEvent and scroll the item when it arrives. Applications that implement dynamic scrolling can ignore this event.

When a penMoveEvent occurs and the pen is within the bounds of the car, this function moves the car in the same direction as the pen.

SclSetScrollBar Function ^TOP^

Purpose

Sets 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 (
   const ScrollBarPtr bar,
   int32_t value,
   const int32_t min,
   const int32_t max,
   const int32_t pageSize
)

Parameters

bar
Pointer to a scroll bar structure.
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 the item that can be displayed on a the screen at one time (used when page scrolling).

Returns

Nothing.

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 UI element, 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.

For scrolling text fields, you can use the FldGetScrollValues() function to retrieve the values that you pass to SclSetScrollBar(). 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.

This function may display a fatal error message if the min parameter is greater than the max parameter.

Example

The following code shows how to use the function FldGetScrollValues() to compute the values you pass for value, min, and max:


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.

See Also

SclGetScrollBar()