PtGauge

Common resources for gauge-type widgets

Class hierarchy:

PtWidget → PtBasic → PtGauge

Immediate subclasses:

• PtMeter
• PtProgress
• PtScrollBar
• PtSlider

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

PhAB icon:

None — not normally instantiated.

Public header:

<photon/PtGauge.h>

Description:

The PtGauge superclass provides common resources for gauge-like widgets, which are capable of displaying a range of values.

New resources:

Pt_ARG_GAUGE_FLAGS

Flags that affect the appearance and behavior of the gauge. Possible values:

Pt_GAUGE_INDETERMINATE

The current value is “unknown.”

Any subclass of PtGauge may observe this bit, but the only widget that currently does is PtProgress.

Pt_GAUGE_INTERACTIVE

Let the user change the value of the gauge interactively at runtime (e.g. by dragging). When the value is changed in this manner, the widget's Pt_CB_GAUGE_VALUE_CHANGED callbacks are invoked.

Any subclass of PtGauge may observe this bit, but the only widget that currently does is PtProgress.

Pt_GAUGE_LIVE

Alter the widget's appearance as time passes to indicate that although the value may not be changing, the application is still working.

Any subclass of PtGauge may observe this bit, but the only widget that currently does is PtProgress.

Pt_GAUGE_MAX_ON_TOP
Pt_GAUGE_MAX_ON_LEFT

The position of the maximum value.

Pt_GAUGE_SHOW_VALUE

Display the value of the gauge.

Pt_GAUGE_VALUE_XOR

XOR the value display with the background (i.e. invert the fill of the typeface).

The default setting for this resource is 0; that is, no flags have been set.

Pt_ARG_GAUGE_FONT

The font used for displaying the value, title, and any other text.

Pt_ARG_GAUGE_H_ALIGN

Controls horizontal alignment. Possible values are:

Pt_LEFT

Draw the value aligned to the left edge.

Pt_RIGHT

Draw the value aligned to the right edge.

Pt_CENTER

Draw the value centered.

Pt_ARG_GAUGE_V_ALIGN

Controls vertical alignment. Possible values are:

Pt_TOP

Draw the value aligned with the top edge.

Pt_BOTTOM

Draw the value aligned with the bottom edge.

Pt_CENTER

Draw the value centered.

Pt_ARG_GAUGE_VALUE

The gauge's current value.

Pt_ARG_GAUGE_VALUE_PREFIX

Text prefixed to the value displayed. For example, a value of Red: results in Red:35.

Pt_ARG_GAUGE_VALUE_SUFFIX

Text appended to the value displayed. For example, a value of % results in 35%.

Pt_ARG_MAXIMUM

The maximum value of the gauge.

Pt_ARG_MINIMUM

The minimum value of the gauge.

Pt_ARG_ORIENTATION

The orientation of the gauge; one of:

• Pt_HORIZONTAL
• Pt_VERTICAL

Pt_CB_GAUGE_VALUE_CHANGED

A list of PtCallback_t structures that define the callbacks that are invoked when the user changes the value of an interactive gauge (i.e. one that has the Pt_GAUGE_INTERACTIVE bit set in its Pt_ARG_GAUGE_FLAGS).

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 value by calling PtSetResource() or PtSetResources().

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

reason

Pt_CB_GAUGE_VALUE_CHANGED

reason_subtype

One of the following:

• Pt_GAUGE_DECREMENT, Pt_GAUGE_INCREMENT — the value decreased or increased by a single unit. The meaning of a “unit” may be specific to the widget (for example, Pt_ARG_INCREMENT) but in the absence of such a binding should be understood to mean 1.
• Pt_GAUGE_MULTIPLE_INCREMENT, Pt_GAUGE_MULTIPLE_DECREMENT — the value decreased or increased by a multiple unit. A multiple unit definition is optional (for example, Pt_ARG_PAGE_INCREMENT) and if the widget doesn't define it, callbacks with this subtype don't occur.
• Pt_GAUGE_TO_MAX, Pt_GAUGE_TO_MIN — the value has gone to the maximum or minimum value of the gauge.
• Pt_GAUGE_DRAGGED — the valued changed because of a drag operation. (In the case of low-bandwidth restrictions, you can disregard callbacks of this subtype)
• Pt_GAUGE_RELEASED — signals the end of a drag (good for low-bandwidth restrictions). Since the value is the same as the last callback of subtype Pt_GAUGE_DRAGGED, you don't need to handle this subtype if you're paying attention to the Pt_GAUGE_DRAGGED subtypes.
• Pt_GAUGE_JUMP — the gauge has jumped to a new value (i.e. none of the criteria for the other subtypes has been met).

event

A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked, or NULL if the callback was invoked because your application changed the value and Pt_CALLBACKS_ACTIVE is set.

cbdata

A pointer to a PtGaugeCallback_t structure, which contains at least:

• long value — the new value for the gauge.

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.