PtScrollArea

A viewport for viewing a large virtual area

Class hierarchy:

PtWidget --> PtBasic --> PtContainer --> PtScrollArea

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

PhAB icon:

Public header:

<photon/PtScrollArea.h>

Description:

A PtScrollArea widget combines one or more scrollbar widgets and an area that provides a viewport onto a virtual display area. The virtual display area is a container for other widgets. Typically, the virtual area is larger than the viewing area; the scrollbar widgets let you bring any part of the virtual area into view.

A PtScrollArea widget acts as a viewport.

Like other widgets, PtScrollArea's physical size is set with its Pt_ARG_AREA resource. The virtual size depends on its Pt_ARG_SCROLL_AREA_MAX_X and Pt_ARG_SCROLL_AREA_MAX_Y resources.

PtScrollArea's resize policy affects only its virtual size, not its physical size. Its anchors, on the other hand, affect only its physical size, with one exception: if the physical size exceeds the virtual size, the virtual size temporarily grows to fill the physical canvas.

Any anchorable children of a PtScrollArea widget will 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.

If the virtual area's size is significantly greater than that of the viewport (such as when a large textual document is being viewed), it's usually impractical in terms of performance and memory to use a scrolling area. This is because the widget for the virtual area keeps the entire contents of the object in memory and always renders the entire object. In these cases, you should use scrollbars and directly control which portion of the object is displayed.

Scrolling notification

When the user moves either the vertical or horizontal scrollbar to change the viewport's position, a callback may be invoked to notify the application that the viewport has been moved. You may use this 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.

The callbacks provided by the PtScrollArea class and their meanings are:

• Pt_CB_SCROLLED_X - the horizontal scrollbar has been moved
• Pt_CB_SCROLLED_Y - the vertical scrollbar has been moved

Scrolling control

The scrollbars provided by the scrollable area let the user 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_SCROLL_AREA_INCREMENT_X
• Pt_ARG_SCROLL_AREA_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 also update the viewport's position under program control. To move the viewport, you simply set a new position using the Pt_ARG_SCROLL_AREA_POS_X and Pt_ARG_SCROLL_AREA_POS_Y resources.

Layout

Scrollable areas always use absolute positioning for the layout of their children.

Anchors and resize policy

Anchors between a scrollable area and its parent will affect the scrollable area's visible area.

Children of the scrollable area are anchored to its virtual area.

The scrollable area's resize policy is applied to its virtual area. You can set the virtual area's size directly by modifying the resources associated with it. Otherwise, the area will change only under the following conditions:

• The Pt_AUTO_EXTENT flag is set.

  OR

• The scrollable area's resize policy is set to allow it to resize in response to a change in its contents (i.e. any of its children change)

  AND

• one of its children changes size, as a result of its resize policy or a programmatic change

  AND

• you call PtExtentWidget() on the scrollable area after the change.

Other layouts are possible only by making another container, such as a group widget, a child of the scrollable area.

New resources:

Pt_ARG_SCROLL_AREA_FLAGS

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

Pt_SCROLL_AREA_IGNORE_KEYS

Prevents the scroll area from handling and consuming the arrow keys, Pg Up, Pg Dn, Home, or End.

Pt_SCROLL_AREA_TRACK_FOCUS (default)

Scroll automatically to keep the currently focused widget visible.

Pt_ARG_SCROLL_AREA_INCREMENT_X

The number of pixels that the widget will scroll when the user clicks the horizontal arrow buttons.

Pt_ARG_SCROLL_AREA_INCREMENT_Y

The number of pixels that the widget will scroll when the user clicks the vertical arrow buttons.

Pt_ARG_SCROLL_AREA_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_SCROLL_AREA_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_SCROLL_AREA_POS_X

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

Pt_ARG_SCROLL_AREA_POS_Y

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

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. If this resource is set to 0, the default height of 15 pixels is used.

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. If this resource is set to 0, the default width of 15 pixels is used.

Pt_CB_SCROLLED_X, Pt_CB_SCROLLED_Y

The list of 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 the positions of the scrollbars are changed by a call to PtSetResources().

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

reason

Pt_CB_SCROLLED_X or
Pt_CB_SCROLLED_Y.

reason_subtype

0 (not used).

cbdata

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

unsigned action;

where action can be 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 slider part of the scrollbar has been moved to the maximum value.

Pt_SCROLL_TO_MIN

The slider has been moved to the minimum value.

Pt_SCROLL_DRAGGED

The slider part is being dragged.

Pt_SCROLL_RELEASED

The slider part has been released after having been dragged.

int position;

A value corresponding to the slider'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.