[Previous] [Contents] [Index] [Next]

PtScrollbar

A scrollbar

Class hierarchy:

PtWidget → PtBasic → PtGauge → PtScrollbar

For more information, see the diagram of the widget hierarchy.

PhAB icon:

PtScrollBar button in PhAB

Public header:

<photon/PtScrollbar.h>

Description:

A PtScrollbar widget provides a scrollbar. It returns values (via callbacks) that indicate a value within the provided range.

PtScrollBar

A PtScrollbar widget.

A scrollbar consists of the following parts:

Trough
A shaded box, oriented horizontally or vertically, that represents the total range.
Handle
A shaded button-like object that moves through the trough. Its range of motion is limited by the trough.
Stepper arrows
Arrow buttons drawn at either end of the trough that let the handle slide forward or back by incremental amounts. The width of a stepper arrow in a horizontal scrollbar is automatically set to be 3/4 of the height of the scrollbar. Similarly, the height of a stepper arrow in a vertical scrollbar is set to 3/4 of the scrollbar's width.

A scrollbar can return values from minimum to (maximum - size-of-handle + 1). You'll find the returned values useful for implementing scrolling areas, text viewers/editors, and so on.

The handle size is determined by the Pt_ARG_SLIDER_SIZE resource. If you don't set this resource, the handle size is one-tenth of the specified range.

The handle's value is represented by its relative position within the trough. The size of the trough represents the allowable range of values.

Your application can also control the handle's size. You can change it to indicate an object's size and the portion viewed when the scrollbar is used for scrolling.

Scrolling is the action of controlling which part of an object is displayed when the object is too large to view all at once. By default, the trough's size visually represents the scroll region — the total length of the object being viewed; you can use the Pt_SCROLLBAR_FIXED_SLIDER_SIZE bit in the Pt_ARG_SCROLLBAR_FLAGS to override this.

The edge of the handle represents your current relative position within the object. The handle's size represents the proportion of the entire object that is currently in view.

Sliding the handle within the trough controls which portion of the object is displayed. Your application is responsible for changing the display of the object in response to any change in the handle's position.

Mouse actions

When the mouse button is pressed, the result depends on the location of the pointer.

If the pointer is: the handle:
On either arrow Moves up or down one increment (holding down the mouse button repeats the action)
In the trough Moves up or down one page increment (holding down the mouse button repeats the action)
On the handle Starts a drag action

If you hold down the Ctrl and click the button while pointing at the trough, the slider jumps to the pointer's position.

Keyboard actions

If you press: The handle moves:
↑ Up one increment
↓ Down one increment
→ Right one increment
← Left one increment
Ctrl-↑ Up one page increment
Ctrl-↓ Down one page increment
Ctrl-→ Right one page increment
Ctrl-← Left one page increment
Home To the top or left (depending on the orientation)
End To the bottom or right (depending on the orientation)

New resources:

Resource C type Pt type Default
Pt_ARG_INCREMENT long Scalar 1
Pt_ARG_MIN_SLIDER_SIZE unsigned short Scalar 10
Pt_ARG_PAGE_INCREMENT int Scalar -1
Pt_ARG_SCROLLBAR_FLAGS unsigned short Flag 0
Pt_ARG_SLIDER_SIZE int Scalar 1/10th of range
Pt_CB_SCROLL_MOVE PtCallback_t * Link NULL

Pt_ARG_INCREMENT

C type Pt type Default
long Scalar 1

The value the widget scrolls by when you click the arrow buttons.

Pt_ARG_MIN_SLIDER_SIZE

C type Pt type Default
unsigned short Scalar 10

The minimum length of the handle, in pixels.

Pt_ARG_PAGE_INCREMENT

C type Pt type Default
int Scalar -1

The handle increment to be used when the scrollbar is moved by a page. If this value is -1, the value for Pt_ARG_SLIDER_SIZE is used.

Pt_ARG_SCROLLBAR_FLAGS

C type Pt type Default
unsigned short Flag 0

Flags that control the appearance and behavior of the scrollbar. The valid bits are:

Pt_SCROLLBAR_FIXED_SLIDER_SIZE
Make the scrollbar slider a fixed size, as specified by Pt_ARG_MIN_SLIDER_SIZE.
Pt_SCROLLBAR_FOCUSED
Cause the scrollbar to be rendered as if it has focus even if it doesn't. This is useful in applications where one widget collects keystrokes and directs specific keys to other widgets.
Pt_SCROLLBAR_SHOW_ARROWS
Display arrow buttons at the ends of the trough.

Pt_ARG_SLIDER_SIZE

C type Pt type Default
int Scalar 1/10th of range

The length of the handle, in the range of 1 to (Pt_ARG_MAXIMUM - Pt_ARG_MINIMUM).

Pt_CB_SCROLL_MOVE

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the callbacks that the scrollbar invokes when the scroll position changes.

If the widget has the Pt_CALLBACKS_ACTIVE bit set in its Pt_ARG_FLAGS resource, these callbacks are also invoked when your application changes the position of the scrollbar by calling PtSetResource() or PtSetResources().

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason
Pt_CB_SCROLL_MOVE
reason_subtype
0 (not used).
event
A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked.
cbdata
A pointer to a PtScrollbarCallback_t structure that contains at least the following members:

These callbacks should return Pt_CONTINUE.

Inherited resources:

If the widget modifies an inherited resource, the “Default override” column indicates the new value. This modification affects any subclasses of the widget.

Resource Inherited from Default override
Pt_ARG_ANCHOR_FLAGS PtWidget
Pt_ARG_ANCHOR_OFFSETS PtWidget
Pt_ARG_AREA PtWidget
Pt_ARG_BANDWIDTH_THRESHOLD PtBasic Ph_BAUD_SLOW (see below)
Pt_ARG_BASIC_FLAGS PtBasic Pt_ALL_ETCHES | Pt_ALL_INLINES
Pt_ARG_BEVEL_WIDTH PtWidget 1
Pt_ARG_BITMAP_CURSOR PtWidget
Pt_ARG_BEVEL_COLOR PtBasic
Pt_ARG_BEVEL_CONTRAST PtBasic
Pt_ARG_COLOR PtBasic Pg_GRAY
Pt_ARG_CONTRAST PtBasic
Pt_ARG_CURSOR_COLOR PtWidget
Pt_ARG_CURSOR_TYPE PtWidget
Pt_ARG_DARK_BEVEL_COLOR PtBasic
Pt_ARG_DARK_FILL_COLOR PtBasic
Pt_ARG_DATA PtWidget
Pt_ARG_DIM PtWidget
Pt_ARG_EFLAGS PtWidget
Pt_ARG_EXTENT PtWidget
Pt_ARG_FILL_COLOR PtBasic Pg_MGRAY
Pt_ARG_FILL_PATTERN PtBasic Pg_PAT_DIAGF8
Pt_ARG_FLAGS PtWidget |=Pt_GETS_FOCUS|
Pt_HIGHLIGHTED|
Pt_SET|
Pt_SELECTABLE|
Pt_SELECT_NOREDRAW
Pt_ARG_GAUGE_FLAGS PtGauge ~Pt_GAUGE_HORIZONTAL
Pt_ARG_GAUGE_FONT PtGauge Not used by this class.
Pt_ARG_GAUGE_H_ALIGN PtGauge Not used by this class.
Pt_ARG_GAUGE_V_ALIGN PtGauge Not used by this class.
Pt_ARG_GAUGE_VALUE PtGauge
Pt_ARG_GAUGE_VALUE_PREFIX PtGauge Not used by this class.
Pt_ARG_GAUGE_VALUE_SUFFIX PtGauge Not used by this class.
Pt_ARG_GRID_LAYOUT_DATA PtWidget
Pt_ARG_HEIGHT PtWidget
Pt_ARG_HELP_TOPIC PtWidget
Pt_ARG_HIGHLIGHT_ROUNDNESS PtBasic
Pt_ARG_INLINE_COLOR PtBasic
Pt_ARG_LAYOUT_DATA PtWidget
Pt_ARG_LIGHT_BEVEL_COLOR PtBasic
Pt_ARG_LIGHT_FILL_COLOR PtBasic
Pt_ARG_MARGIN_HEIGHT PtBasic 2
Pt_ARG_MARGIN_WIDTH PtBasic 2
Pt_ARG_MAXIMUM PtGauge 19
Pt_ARG_MAXIMUM_DIM PtWidget
Pt_ARG_MINIMUM PtGauge 0
Pt_ARG_MINIMUM_DIM PtWidget
Pt_ARG_ORIENTATION PtGauge Pt_VERTICAL
Pt_ARG_OUTLINE_COLOR PtBasic
Pt_ARG_POINTER PtWidget
Pt_ARG_POS PtWidget
Pt_ARG_RESIZE_FLAGS PtWidget
Pt_ARG_ROW_LAYOUT_DATA PtWidget
Pt_ARG_STYLE PtBasic
Pt_ARG_TRANS_PATTERN PtBasic
Pt_ARG_USER_DATA PtWidget
Pt_ARG_WIDTH PtWidget
Pt_CB_ACTIVATE PtBasic
Pt_CB_ARM PtBasic
Pt_CB_BLOCKED PtWidget
Pt_CB_DESTROYED PtWidget
Pt_CB_DISARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_FILTER PtWidget
Pt_CB_GOT_FOCUS PtBasic
Pt_CB_HOTKEY PtWidget
Pt_CB_IS_DESTROYED PtWidget
Pt_CB_LOST_FOCUS PtBasic
Pt_CB_MENU PtBasic
Pt_CB_OUTBOUND PtWidget
Pt_CB_RAW PtWidget
Pt_CB_REALIZED PtWidget
Pt_CB_REPEAT PtBasic
Pt_CB_UNREALIZED PtWidget

Pt_ARG_BANDWIDTH_THRESHOLD

The threshold value for graphics bandwidth (as reported by PtQuerySystemInfo()) that defines a slow connection.

[Previous] [Contents] [Index] [Next]