PtScrollArea
![[Previous]](prev.gif) |
![[Contents]](contents.gif) |
![[Index]](keyword_index.gif) |
![[Next]](next.gif) |
PtScrollArea
A viewport for viewing a large virtual area
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtScrollArea
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:
- 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:
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:
- 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
|
|
|
|
