PtScrollbar
![[Previous]](prev.gif) |
![[Contents]](contents.gif) |
![[Index]](keyword_index.gif) |
![[Next]](next.gif) |
PtScrollbar
A scrollbar
Class hierarchy:
PtWidget --> PtBasic --> PtGauge --> PtScrollbar
For more information, see the diagram of the widget hierarchy.
PhAB icon:
Public header:
<photon/PtScrollbar.h>
Description:
A PtScrollbar widget provides a scrollbar. It returns values (via callbacks) that indicate a value within the provided range.
A PtScrollbar widget.
A scrollbar consists of the following parts:
- Trough
- A shaded box, oriented horizontally or vertically, that represents the total range.
- Handle
- A shaded button-like object that moves through the trough. Its range of motion is limited by the trough.
- Stepper arrows
- Arrow buttons drawn at either end of the trough that let the handle slide forward or back by incremental amounts. The width of a stepper arrow in a horizontal scrollbar is automatically set to be 3/4 of the height of the scrollbar. Similarly, the height of a stepper arrow in a vertical scrollbar is set to 3/4 of the scrollbar's width.
A scrollbar can return values from minimum to (maximum - size-of-handle + 1). You'll find the returned values useful for implementing scrolling areas, text viewers/editors, and so on.
The handle size is determined by the Pt_ARG_SLIDER_SIZE resource. If you don't set this resource, the handle size is one-tenth of the specified range.
The handle's value is represented by its relative position within the trough. The size of the trough represents the allowable range of values.
Your application can also control the handle's size. You can change it to indicate an object's size and the portion viewed when the scrollbar is used for scrolling.
Scrolling is the action of controlling which part of an object is displayed when the object is too large to view all at once. By default, the trough's size visually represents the scroll region -- the total length of the object being viewed; you can use the Pt_SCROLLBAR_FIXED_SLIDER_SIZE bit in the Pt_ARG_SCROLLBAR_FLAGS to override this.
The edge of the handle represents your current relative position within the object. The handle's size represents the proportion of the entire object that is currently in view.
Sliding the handle within the trough controls which portion of the object is displayed. Your application is responsible for changing the display of the object in response to any change in the handle's position.
Mouse actions
When the mouse button is pressed, the result depends on the location of the pointer.
| If the pointer is: | the handle: |
|---|---|
| On either arrow | Moves up or down one increment (holding down the mouse button repeats the action) |
| In the trough | Moves up or down one page increment (holding down the mouse button repeats the action) |
| On the handle | Starts a drag action |
If you hold down the Ctrl and click the button while pointing at the trough, the slider jumps to the pointer's position.
Keyboard actions
| If you press: | The handle moves: |
|---|---|
| /\ | Up one increment |
| \/ | Down one increment |
| --> | Right one increment |
| <-- | Left one increment |
| Ctrl-/\ | Up one page increment |
| Ctrl-\/ | Down one page increment |
| Ctrl---> | Right one page increment |
| Ctrl-<-- | Left one page increment |
| Home | To the top or left (depending on the orientation) |
| End | To the bottom or right (depending on the orientation) |
New resources:
| Resource | C type | Pt type | Default |
|---|---|---|---|
| Pt_ARG_INCREMENT | long | Scalar | 1 |
| Pt_ARG_MIN_SLIDER_SIZE | ushort_t | Scalar | 10 |
| Pt_ARG_PAGE_INCREMENT | int | Scalar | -1 |
| Pt_ARG_SCROLLBAR_FLAGS | unsigned short | Flag | 0 |
| Pt_ARG_SLIDER_SIZE | int | Scalar | 1/10th of range |
| Pt_CB_SCROLL_MOVE | PtCallback_t * | Link | NULL |
Pt_ARG_INCREMENT
| C type | Pt type | Default |
|---|---|---|
| long | Scalar | 1 |
The value the widget scrolls by when you click the arrow buttons.
Pt_ARG_MIN_SLIDER_SIZE
| C type | Pt type | Default |
|---|---|---|
| ushort_t | Scalar | 10 |
The minimum length of the handle, in pixels.
Pt_ARG_PAGE_INCREMENT
| C type | Pt type | Default |
|---|---|---|
| int | Scalar | -1 |
The handle increment to be used when the scrollbar is moved by a page. If this value is -1, the value for Pt_ARG_SLIDER_SIZE is used.
Pt_ARG_SCROLLBAR_FLAGS
| C type | Pt type | Default |
|---|---|---|
| unsigned short | Flag | 0 |
Flags that control the appearance and behavior of the scrollbar. The valid bits are:
- Pt_SCROLLBAR_FIXED_SLIDER_SIZE
- Make the scrollbar slider a fixed size, as specified by Pt_ARG_MIN_SLIDER_SIZE.
- Pt_SCROLLBAR_FOCUSED
- Cause the scrollbar to be rendered as if it has focus even if it doesn't. This is useful in applications where one widget collects keystrokes and directs specific keys to other widgets.
- Pt_SCROLLBAR_SHOW_ARROWS
- Display arrow buttons at the ends of the trough.
Pt_ARG_SLIDER_SIZE
| C type | Pt type | Default |
|---|---|---|
| int | Scalar | 1/10th of range |
The length of the handle, in the range of 1 to (Pt_ARG_MAXIMUM - Pt_ARG_MINIMUM).
Pt_CB_SCROLL_MOVE
| C type | Pt type | Default |
|---|---|---|
| PtCallback_t * | Link | NULL |
A list of PtCallback_t structures that define the callbacks that the scrollbar invokes when the scroll position changes.
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 position of the scrollbar by calling PtSetResource() or PtSetResources().
Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:
- reason
- Pt_CB_SCROLL_MOVE
- reason_subtype
- 0 (not used).
- event
- A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked.
- cbdata
- A pointer to a PtScrollbarCallback_t structure
that contains at least the following members:
- unsigned action -- 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 handle part of the scrollbar has been moved to the maximum value.
- Pt_SCROLL_TO_MIN
- The handle has been moved to the minimum value.
- Pt_SCROLL_DRAGGED
- The handle is being dragged.
- Pt_SCROLL_RELEASED
- The handle part has been released after having been dragged.
- Pt_SCROLL_SET
- The position of the handle was changed by a call to PtSetResources(), and the widget has the Pt_CALLBACKS_ACTIVE bit set in its Pt_ARG_FLAGS resource.
- Pt_SCROLL_JUMP
- You jumped to a specific location by Ctrl-clicking on the scrollbar.
- int position -- a value corresponding to the handle's location.
- unsigned action -- one of the
following:
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.
Pt_ARG_BANDWIDTH_THRESHOLD
The threshold value for graphics bandwidth (as reported by PtQuerySystemInfo()) that defines a slow connection.
|
|
|
|