---

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.

If the pointer is:	the handle will:
on either arrow	move up or down one increment (holding down the mouse button repeats the action)
in the trough	move up or down one page increment (holding down the mouse button repeats the action)
on the handle	start a drag action

Keyboard actions

If the user presses:	the handle will move:
/\	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_DIRECTION	int	Boolean	Off
Pt_ARG_INCREMENT	long	Scalar	1
Pt_ARG_MAXIMUM	int	Scalar	19
Pt_ARG_MINIMUM	int	Scalar	0
Pt_ARG_MIN_SLIDER_SIZE	int	Scalar	5
Pt_ARG_ORIENTATION	int	Boolean	Pt_VERTICAL
Pt_ARG_PAGE_INCREMENT	int	Scalar	-1
Pt_ARG_SCROLLBAR_FLAGS	short	Scalar	0
Pt_ARG_SCROLL_POSITION	int	Scalar	0
Pt_ARG_SHOW_ARROWS	int	Boolean	On
Pt_ARG_SLIDER_SIZE	int	Scalar	1/10th of range
Pt_CB_SCROLL_MOVE	PtCallback_t *	Link	NULL

Pt_ARG_DIRECTION

C type	Pt type	Default
int	Boolean	Off

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

Pt_ARG_INCREMENT

C type	Pt type	Default
long	Scalar	1

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

Pt_ARG_MAXIMUM

C type	Pt type	Default
int	Scalar	19

The maximum scrollbar value.

Pt_ARG_MINIMUM

C type	Pt type	Default
int	Scalar	0

The minimum scrollbar value.

Pt_ARG_MIN_SLIDER_SIZE

C type	Pt type	Default
int	Scalar	5

The minimum length of the handle, in pixels.

Pt_ARG_ORIENTATION

C type	Pt type	Default
int	Boolean	Pt_VERTICAL

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

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
short	Scalar	0

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

C type	Pt type	Default
int	Scalar	0

The current handle value.

Pt_ARG_SHOW_ARROWS

C type	Pt type	Default
int	Boolean	On

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

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

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.

Resource	Inherited from	Default override
Pt_ARG_AREA	PtWidget
Pt_ARG_BANDWIDTH_THRESHOLD	PtBasic	Ph_BAUD_SLOW (see below)
Pt_ARG_BITMAP_CURSOR	PtWidget
Pt_ARG_BORDER_WIDTH	PtWidget	1
Pt_ARG_BOT_BORDER_COLOR	PtBasic
Pt_ARG_COLOR	PtBasic	Pg_GRAY
Pt_ARG_CURSOR_COLOR	PtWidget
Pt_ARG_CURSOR_TYPE	PtWidget
Pt_ARG_DATA	PtWidget
Pt_ARG_DIM	PtWidget
Pt_ARG_EFLAGS	PtWidget
Pt_ARG_FILL_COLOR	PtBasic	Pg_MGRAY
Pt_ARG_FILL_PATTERN	PtBasic
Pt_ARG_FLAGS	PtWidget	|=Pt_GETS_FOCUS| Pt_HIGHLIGHTED| Pt_SET| Pt_SELECTABLE| Pt_SELECT_NOREDRAW
Pt_ARG_HELP_TOPIC	PtWidget
Pt_ARG_HIGHLIGHT_ROUNDNESS	PtBasic
Pt_ARG_MARGIN_HEIGHT	PtBasic	2
Pt_ARG_MARGIN_WIDTH	PtBasic	2
Pt_ARG_POS	PtWidget
Pt_ARG_RESIZE_FLAGS	PtWidget
Pt_ARG_TOP_BORDER_COLOR	PtBasic
Pt_ARG_TRANS_PATTERN	PtBasic
Pt_ARG_USER_DATA	PtWidget
Pt_CB_ACTIVATE	PtBasic
Pt_CB_ARM	PtBasic
Pt_CB_BLOCKED	PtWidget
Pt_CB_DESTROYED	PtWidget
Pt_CB_DISARM	PtBasic
Pt_CB_GOT_FOCUS	PtBasic
Pt_CB_HOTKEY	PtWidget
Pt_CB_LOST_FOCUS	PtBasic
Pt_CB_MENU	PtBasic
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.

---