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
ScrollBarType Struct
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
Scroll Bar Events
frmScrollPrvRefreshEvent
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
andnewValue
, 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
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
Comments
Applications usually don't have to handle this event. Instead, wait for a sclExitEvent
or sclRepeatEvent
.
sclExitEvent
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
andnewValue
, 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
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
andnewValue
, 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
SclDrawScrollBar Function
Purpose
Declared In
ScrollBar.h
Prototype
void SclDrawScrollBar (
const ScrollBarPtr bar
)
Parameters
Returns
Comments
This function is called internally by SclSetScrollBar()
and FrmDrawForm()
. You rarely need to call it yourself.
SclGetScrollBar Function
Purpose
Retrieves a scroll bar's current position, its range, and the size of a page.
Declared In
ScrollBar.h
Prototype
void SclGetScrollBar ( const ScrollBarPtrbar
, 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
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
Purpose
Handles events that affect a scroll bar.
Declared In
ScrollBar.h
Prototype
Boolean SclHandleEvent ( const ScrollBarPtrbar
, 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
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 ScrollBarPtrbar
, int32_tvalue
, const int32_tmin
, const int32_tmax
, const int32_tpageSize
)
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
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.