PtSlider

A widget for choosing a value from a range

Class hierarchy:

PtWidget → PtBasic → PtGauge → PtSlider

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

PhAB icon:

Public header:

<photon/PtSlider.h>

Description:

A PtSlider widget lets you choose numerical values within a specified range from minimum to maximum.

A PtSlider widget.

A slider consists of a narrow trough (representing the total range), a movable handle, and optional tick marks. The handle — which appears on top of the trough — represents the current position within the range. You can specify the size of the handle by setting Pt_ARG_SLIDER_HANDLE_WIDTH.

If you want to create your own style of slider, you can specify:

• Pt_ARG_SLIDER_IMAGE to replace the default handle
• Pt_ARG_SLIDER_TROUGH_IMAGE1 and Pt_ARG_SLIDER_TROUGH_IMAGE2 to replace the default trough.

A PtSlider widget with a custom handle and trough.

You need to set Pt_ARG_SLIDER_FLAGS appropriately to use these images.

Mouse actions

When you press the mouse button, the result depends on the location of the pointer.

If you hold down the Ctrl key and click in the trough, the handle jumps to the position of the pointer.

Keyboard actions

where:

• The size of a “page” is determined by the Pt_ARG_SLIDER_MULTIPLE resource.
• The locations of the minimum and maximum value depend on the Pt_ARG_ORIENTATION and Pt_ARG_GAUGE_FLAGS resources inherited from PtGauge.

New resources:

Pt_ARG_SLIDER_FLAGS

Valid flags:

Pt_SLIDER_IMAGE

Use the image specified by Pt_ARG_SLIDER_IMAGE as the slider handle.

Pt_SLIDER_TROUGH_IMAGE

Use the images specified by Pt_ARG_SLIDER_TROUGH_IMAGE1 and Pt_ARG_SLIDER_TROUGH_IMAGE2 as the trough.

Pt_ARG_SLIDER_HANDLE_COLOR

The color of the slider handle. See PgColor_t in the Photon Library Reference.

Pt_ARG_SLIDER_HANDLE_WIDTH

The width of the slider handle.

Pt_ARG_SLIDER_IMAGE

You can use this resource to create your own style of slider. It specifies an image to be used as the slider's handle. For more information about the PhImage_t structure, see the Photon Library Reference.

---

The widget ignores this resource unless you set Pt_SLIDER_IMAGE in Pt_ARG_SLIDER_FLAGS.

---

Pt_ARG_SLIDER_INCREMENT

The slider increment when you press the cursor keys.

Pt_ARG_SLIDER_MULTIPLE

The slider increment when you click the pointer button in the trough, or you press Pg Up or Pg Down.

Pt_ARG_SLIDER_TICK_MAJOR_DIV

The number of major divisions.

Pt_ARG_SLIDER_TROUGH_IMAGE1, Pt_ARG_SLIDER_TROUGH_IMAGE2

You can use these resources to create your own style of slider. Use them to specify the images to be displayed as the trough. The slider becomes the same size as Pt_ARG_SLIDER_TROUGH_IMAGE1.

---

The widget ignores these resources unless you set Pt_SLIDER_TROUGH_IMAGE in Pt_ARG_SLIDER_FLAGS.

---

If you specify just Pt_ARG_SLIDER_TROUGH_IMAGE1, it's used as the background for the entire slider.

If you specify both images:

• Pt_ARG_SLIDER_TROUGH_IMAGE1 is displayed from the minimum value of the slider to the current handle position.
• Pt_ARG_SLIDER_TROUGH_IMAGE2 is displayed from the current handle position to the maximum value.

---

If the image specified by Pt_ARG_SLIDER_TROUGH_IMAGE2 is a different size than the one specified by Pt_ARG_SLIDER_TROUGH_IMAGE1, you should use a non-transparent color to avoid drawing artifacts when the handle position changes.

---

By default, the maximum value is on the right side of a horizontal slider. The widget displays the first image to the left of the handle, and the second image to the right. If you set Pt_GAUGE_MAX_ON_LEFT in the Pt_ARG_GAUGE_FLAGS resource (inherited from PtGauge), the widget displays the first image to the right of the handle, and the second image to the left.

You get similar results with a vertical slider if you set Pt_GAUGE_MAX_ON_TOP.

---

The images aren't rotated if you change the slider's Pt_ARG_ORIENTATION resource (inherited from PtGauge). You should create horizontal images for a horizontal slider, and vertical images for a vertical slider.

---

For more information about the PhImage_t structure, see the Photon Library Reference.

Pt_CB_SLIDER_MOVE

A list of PtCallback_t structures that define the callbacks that the slider invokes when the handle position changes.

If you've set the Pt_CALLBACKS_ACTIVE bit set in the widget's Pt_ARG_FLAGS resource, these callbacks are also invoked when your application changes the handle position by calling PtSetResource() or PtSetResources().

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

reason

Pt_CB_SLIDER_MOVE

reason_subtype

One of the following:

• Pt_SLIDER_INCREMENT
• Pt_SLIDER_DECREMENT
• Pt_SLIDER_MULTIPLE_INCREMENT
• Pt_SLIDER_MULTIPLE_DECREMENT
• Pt_SLIDER_DRAGGED
• Pt_SLIDER_RELEASED
• Pt_SLIDER_TO_MIN
• Pt_SLIDER_TO_MAX
• Pt_SLIDER_JUMP
• Pt_SLIDER_SET

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 PtSliderCallback_t structure that contains at least the following member:

int position;

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