PtScrollbar

A scrollbar

Class hierarchy:

PtWidget --> PtBasic --> PtScrollbar

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

PhAB icon:

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.

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 allow the handle to 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. Similarily, 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, minus the size of the handle. 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 equals 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.

The handle's size can also be programmatically controlled. These parameters may be altered to visually represent information about an object's size and proportion viewed when the scrollbar is used for scrolling.

Scrolling is the action of controlling how much of an object is displayed when the object is too large to view all at once. When a scrollbar is used for scrolling, the trough's size visually represents the scroll region - the total length of the object being viewed.

The edge of the handle represents the user's 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 will control which portion of the object is displayed. The 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.

Keyboard actions

New resources:

Pt_ARG_DIRECTION

Display the maximum value at the top or left, depending on the orientation.

Pt_ARG_INCREMENT

The value the widget will scroll by when the user clicks the arrow buttons.

Pt_ARG_MAXIMUM

The maximum scrollbar value.

Pt_ARG_MINIMUM

The minimum scrollbar value.

Pt_ARG_MIN_SLIDER_SIZE

The minimum length of the handle, in pixels.

Pt_ARG_ORIENTATION

The orientation of the scrollbar:

• Pt_HORIZONTAL
• Pt_VERTICAL

Setting this resource sets or clears the Pt_SCROLLBAR_HORIZONTAL bit of the Pt_ARG_SCROLLBAR_FLAGS resource.

Pt_ARG_PAGE_INCREMENT

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

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

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_HORIZONTAL

Make the scrollbar horizontal instead of vertical.

This flag is also set or cleared when you set the Pt_ARG_ORIENTATION resource.

Pt_SCROLLBAR_INVERTED

Place the maximum at the bottom of a vertical scrollbar or the right of a horizontal one.

Pt_SCROLLBAR_SHOW_ARROWS

Display arrow buttons at the ends of the trough.

Pt_ARG_SCROLL_POSITION

The current handle value.

Pt_ARG_SHOW_ARROWS

Indicates whether or not the scrollbar includes increment/decrement arrow buttons. Default is on.

Pt_ARG_SLIDER_SIZE

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

Pt_CB_SCROLL_MOVE

The list of 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, this callback is also invoked when the position of the scrollbar is changed by a call to 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 the event associated with the callback.

cbdata

A pointer to a PtScrollbarCallback_t structure that contains at least the following members:

• unsigned action - one of the following:

  Pt_SCROLL_DECREMENT

  The scrollbar has been decreased by one increment.

  Pt_SCROLL_INCREMENT

  The scrollbar has been increased by one increment.

  Pt_SCROLL_PAGE_INCREMENT

  The scrollbar has been increased by one page.

  Pt_SCROLL_PAGE_DECREMENT

  The scrollbar has been decreased by one page.

  Pt_SCROLL_TO_MAX

  The handle part of the scrollbar has been moved to the maximum value.

  Pt_SCROLL_TO_MIN

  The handle has been moved to the minimum value.

  Pt_SCROLL_DRAGGED

  The handle is being dragged.

  Pt_SCROLL_RELEASED

  The handle part has been released after having been dragged.

  Pt_SCROLL_SET

  The position of the handle was changed by a call to PtSetResources(), and the widget has the Pt_CALLBACKS_ACTIVE bit set in its Pt_ARG_FLAGS resource.

• int position - a value corresponding to the handle's location.

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.

Pt_ARG_BANDWIDTH_THRESHOLD

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