A viewport for viewing a large virtual area
PtWidget → PtBasic → PtContainer → PtScrollArea
Immediate subclasses:
For more information, see the diagram of the widget hierarchy.
None — not normally instantiated.
<photon/PtScrollArea.h>
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:
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.
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.
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 |
C type | Pt type | Default |
---|---|---|
unsigned short | Flag | Pt_SCROLLAREA_ENABLE_PAN |
These flags control the behavior of the scroll area. Valid bits include:
C type | Pt type | Default |
---|---|---|
int | Scalar | 10 |
The number of pixels that the widget scrolls by when you click the horizontal arrow buttons.
C type | Pt type | Default |
---|---|---|
int | Scalar | 10 |
The number of pixels that the widget scrolls by when you click the vertical arrow buttons.
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.
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.
C type | Pt type | Default |
---|---|---|
uint32_t | Scalar | 0 |
The horizontal position of the displayed portion of the scrollable area.
C type | Pt type | Default |
---|---|---|
uint32_t | Scalar | 0 |
The vertical position of the displayed portion of the scrollable area.
C type | Pt type | Default |
---|---|---|
PgColor_t | Scalar | Pg_LGREY |
Sets the color of the widget's scrollbars.
C type | Pt type | Default |
---|---|---|
uint8_t | Scalar | Pt_AS_REQUIRED |
Controls the visibility of the horizontal scrollbar. Possible values:
C type | Pt type | Default |
---|---|---|
uint8_t | Scalar | 15 |
The height, in pixels, of the horizontal scrollbar. The minimum height is 6 pixels.
C type | Pt type | Default |
---|---|---|
uint8_t | Scalar | Pt_AS_REQUIRED |
Controls the visibility of the scrollbar. Possible values:
C type | Pt type | Default |
---|---|---|
uint8_t | Scalar | 15 |
The width, in pixels, of the vertical scrollbar. The minimum width is 6 pixels.
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:
These callbacks should return Pt_CONTINUE.
If the widget modifies an inherited resource, the “Default override” column indicates the new value. This modification affects any subclasses of the widget.
The PtScrollArea widget defines the following convenience function: