PtScrollArea

A viewport for viewing a large virtual area

Class hierarchy:

PtWidget → PtBasic → PtContainer → PtScrollArea

Immediate subclasses:

• PtScrollContainer

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:

• Pt_NEVER — never display the scrollbars.
• Pt_ALWAYS — display the scrollbars even if they're not needed.
• Pt_AS_REQUIRED — display the scrollbars only if they're needed.

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:

• Pt_ARG_SCROLLAREA_INCREMENT_X
• Pt_ARG_SCROLLAREA_INCREMENT_Y

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:

Pt_ARG_SCROLLAREA_FLAGS

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

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

Pt_ARG_SCROLLAREA_INCREMENT_Y

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

Pt_ARG_SCROLLAREA_MAX_X

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

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

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

Pt_ARG_SCROLLAREA_POS_Y

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

Pt_ARG_SCROLLAREA_SCROLLBAR_COLOR

Sets the color of the widget's scrollbars.

Pt_ARG_SCROLLBAR_X_DISPLAY

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

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

Pt_ARG_SCROLLBAR_Y_DISPLAY

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

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

Pt_CB_SCROLLAREA_SCROLLED

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:

• Pt_SCROLLAREA_X_CHANGED — change in x (horizontal) position.
• Pt_SCROLLAREA_Y_CHANGED — change in y (vertical) position.
• Pt_SCROLLAREA_XY_CHANGED — simultaneous change in both axes.

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.

Convenience functions:

The PtScrollArea widget defines the following convenience function:

PtScrollAreaCanvas()

Get the viewport canvas, as opposed to the widget canvas