PtScrollArea

A viewport for viewing a large virtual area

Class hierarchy:

PtWidgetPtBasicPtContainerPtScrollArea

Immediate subclasses:

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

PhAB icon:

None — not normally instantiated.

Public header:

<photon/PtScrollArea.h>

Description:

PtScrollArea is a metaclass that supports scrolling and panning for its subclasses. It combines scrollbar widgets and an area that provides a viewport onto a virtual display area. Typically, the virtual area is larger than the viewing area; the scrollbar widgets let you bring any part of the virtual area into view.

As for other widgets, you can set the physical size of a PtScrollArea with its Pt_ARG_AREA resource (inherited from PtWidget). The virtual size depends on its Pt_ARG_SCROLLAREA_MAX_X and Pt_ARG_SCROLLAREA_MAX_Y resources.

Any anchorable children of a PtScrollArea widget anchor to the virtual size, not the physical size.

If the virtual area's size is greater than the viewport's size, you'll need horizontal and/or vertical scrollbars to control the viewport's position. The dimensions are checked when the widget is realized to determine if scrollbars are necessary. Pt_ARG_SCROLLBAR_X_DISPLAY and Pt_ARG_SCROLLBAR_Y_DISPLAY indicate when the scrollbars should be displayed:

Scrolling notification

When you move either the vertical or horizontal scrollbar to change the viewport's position, the Pt_CB_SCROLLAREA_SCROLLED callbacks are invoked to notify your application that the viewport has been moved. You may use these callbacks to keep two related viewports synchronized with each other by monitoring both viewports and updating the position of the alternate viewport when one of them scrolls. See Scrolling control below.

Scrolling control

The scrollbars provided by the scrollable area let you vary the position of the viewport between (0,0) and (xmax, ymax), where xmax and ymax are the maximum positions in x and y. These are equal to the virtual area's size in the specified dimension minus the viewport's size in that dimension.

The size of the handle used by the scrollbar to represent the viewport's position within the virtual area is the viewport's size relative to the virtual area's size.

The handle may be moved by incremental amounts by clicking on either of the arrow buttons in the scrollbar. You can control the increment by setting the increment resource corresponding to the scrollbar:

These specify the number of pixels to increment the viewport's position by when one of the stepper buttons in the scrollbar is pressed.

You can pan the viewport by holding down the Alt key, pointing inside the viewport, and dragging.

You can also update the viewport's position under program control. To move the viewport, you simply set a new position using the Pt_ARG_SCROLLAREA_POS_X and Pt_ARG_SCROLLAREA_POS_Y resources.

New resources:

Resource C type Pt type Default
Pt_ARG_SCROLLAREA_FLAGS unsigned short Flag See below
Pt_ARG_SCROLLAREA_INCREMENT_X int Scalar 10
Pt_ARG_SCROLLAREA_INCREMENT_Y int Scalar 10
Pt_ARG_SCROLLAREA_MAX_X uint32_t Scalar 0
Pt_ARG_SCROLLAREA_MAX_Y uint32_t Scalar 0
Pt_ARG_SCROLLAREA_POS_X uint32_t Scalar 0
Pt_ARG_SCROLLAREA_POS_Y uint32_t Scalar 0
Pt_ARG_SCROLLAREA_SCROLLBAR_COLOR PgColor_t Scalar Pg_LGREY
Pt_ARG_SCROLLBAR_X_DISPLAY uint8_t Scalar Pt_AS_REQUIRED
Pt_ARG_SCROLLBAR_X_HEIGHT uint8_t Scalar 15
Pt_ARG_SCROLLBAR_Y_DISPLAY uint8_t Scalar Pt_AS_REQUIRED
Pt_ARG_SCROLLBAR_Y_WIDTH uint8_t Scalar 15
Pt_CB_SCROLLAREA_SCROLLED PtCallback_t * Link NULL

Pt_ARG_SCROLLAREA_FLAGS

C type Pt type Default
unsigned short Flag Pt_SCROLLAREA_ENABLE_PAN

These flags control the behavior of the scroll area. Valid bits include:

Pt_SCROLLAREA_IGNORE_KEYS
Prevent the scroll area from handling and consuming the arrow keys, Pg Up, Pg Dn, Home, or End.
Pt_SCROLLAREA_ENABLE_PAN
Allow you to pan the scroll area by Alt-clicking and dragging anywhere in the client (viewport) area.

Pt_ARG_SCROLLAREA_INCREMENT_X

C type Pt type Default
int Scalar 10

The number of pixels that the widget scrolls by when you click the horizontal arrow buttons.

Pt_ARG_SCROLLAREA_INCREMENT_Y

C type Pt type Default
int Scalar 10

The number of pixels that the widget scrolls by when you click the vertical arrow buttons.

Pt_ARG_SCROLLAREA_MAX_X

C type Pt type Default
uint32_t Scalar 0

The width (in pixels) of the total scrollable area. This is the widget's virtual width. To specify the displayed portion of this scrollable area, use Pt_ARG_AREA.

Pt_ARG_SCROLLAREA_MAX_Y

C type Pt type Default
uint32_t Scalar 0

The height (in pixels) of the total scrollable area. This is the widget's virtual height. To specify the displayed portion of this scrollable area, use Pt_ARG_AREA.

Pt_ARG_SCROLLAREA_POS_X

C type Pt type Default
uint32_t Scalar 0

The horizontal position of the displayed portion of the scrollable area.

Pt_ARG_SCROLLAREA_POS_Y

C type Pt type Default
uint32_t Scalar 0

The vertical position of the displayed portion of the scrollable area.

Pt_ARG_SCROLLAREA_SCROLLBAR_COLOR

C type Pt type Default
PgColor_t Scalar Pg_LGREY

Sets the color of the widget's scrollbars.

Pt_ARG_SCROLLBAR_X_DISPLAY

C type Pt type Default
uint8_t Scalar Pt_AS_REQUIRED

Controls the visibility of the horizontal scrollbar. Possible values:

Pt_NEVER
Don't display.
Pt_ALWAYS
Always display.
Pt_AS_REQUIRED
Display if the visible dimension is less than the virtual dimension.

Pt_ARG_SCROLLBAR_X_HEIGHT

C type Pt type Default
uint8_t Scalar 15

The height, in pixels, of the horizontal scrollbar. The minimum height is 6 pixels.

Pt_ARG_SCROLLBAR_Y_DISPLAY

C type Pt type Default
uint8_t Scalar Pt_AS_REQUIRED

Controls the visibility of the scrollbar. Possible values:

Pt_NEVER
Don't display.
Pt_ALWAYS
Always display.
Pt_AS_REQUIRED
Display if the visible dimension is less than the virtual dimension.

Pt_ARG_SCROLLBAR_Y_WIDTH

C type Pt type Default
uint8_t Scalar 15

The width, in pixels, of the vertical scrollbar. The minimum width is 6 pixels.

Pt_CB_SCROLLAREA_SCROLLED

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the callbacks that the PtScrollArea widget invokes when its scrollbars are moved.

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 positions of the scrollbars by calling PtSetResource() or PtSetResources().

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

reason
Pt_CB_SCROLLAREA_SCROLLED
reason_subtype
One of:
event
A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked, or NULL if there's no event.
cbdata
A pointer to a PtScrollAreaCallback_t structure that contains at least:
int32_t old_x, old_y
The x and y positions before this change.
int32_t new_x, new_y
The current x and y positions (after the change).

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_RIGHT_ANCHORED_LEFT|
Pt_BOTTOM_ANCHORED_TOP
Pt_ARG_ANCHOR_OFFSETS PtWidget
Pt_ARG_AREA PtWidget
Pt_ARG_BANDWIDTH_THRESHOLD PtBasic Not used by this class.
Pt_ARG_BASIC_FLAGS PtBasic Pt_ALL_ETCHES | Pt_ALL_OUTLINES | Pt_FLAT_FILL
Pt_ARG_BEVEL_WIDTH PtWidget 0
Pt_ARG_BITMAP_CURSOR PtWidget
Pt_ARG_BEVEL_COLOR PtBasic
Pt_ARG_BEVEL_CONTRAST PtBasic
Pt_ARG_COLOR PtBasic
Pt_ARG_CONTAINER_FLAGS PtContainer
Pt_ARG_CONTRAST PtBasic
Pt_ARG_CURSOR_COLOR PtWidget
Pt_ARG_CURSOR_OVERRIDE PtContainer
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
Pt_ARG_FILL_LAYOUT_INFO PtContainer
Pt_ARG_FILL_PATTERN PtBasic
Pt_ARG_FLAGS PtWidget |= Pt_GETS_FOCUS | Pt_HIGHLIGHTED | Pt_SET | Pt_REGION
Pt_ARG_GRID_LAYOUT_DATA PtWidget
Pt_ARG_GRID_LAYOUT_INFO PtContainer
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_LAYOUT_INFO PtContainer
Pt_ARG_LIGHT_BEVEL_COLOR PtBasic
Pt_ARG_LIGHT_FILL_COLOR PtBasic
Pt_ARG_MARGIN_HEIGHT PtBasic
Pt_ARG_MARGIN_WIDTH PtBasic
Pt_ARG_MAXIMUM_DIM PtWidget
Pt_ARG_MINIMUM_DIM PtWidget
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_ROW_LAYOUT_INFO PtContainer
Pt_ARG_STYLE PtBasic
Pt_ARG_TITLE PtContainer
Pt_ARG_TITLE_FONT PtContainer
Pt_ARG_TRANS_PATTERN PtBasic
Pt_ARG_USER_DATA PtWidget
Pt_ARG_WIDTH PtWidget
Pt_CB_ACTIVATE PtBasic
Pt_CB_ARM PtBasic
Pt_CB_BALLOONS PtContainer
Pt_CB_BLOCKED PtWidget
Pt_CB_CHILD_ADDED_REMOVED PtContainer
Pt_CB_CHILD_GETTING_FOCUS PtContainer
Pt_CB_CHILD_LOSING_FOCUS PtContainer
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_RESIZE PtContainer
Pt_CB_UNREALIZED PtWidget

Convenience functions:

The PtScrollArea widget defines the following convenience function:

PtScrollAreaCanvas()
Get the viewport canvas, as opposed to the widget canvas