---

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:

Resource	C type	Pt type	Default
Pt_ARG_GAUGE_FLAGS	short int	Flag	0
Pt_ARG_GAUGE_FONT	char *	String	"TextFont09"
Pt_ARG_GAUGE_H_ALIGN	unsigned char	Scalar	Pt_CENTER
Pt_ARG_GAUGE_V_ALIGN	unsigned char	Scalar	Pt_CENTER
Pt_ARG_GAUGE_VALUE	long	Scalar	0
Pt_ARG_GAUGE_VALUE_PREFIX	char *	String	NULL
Pt_ARG_GAUGE_VALUE_SUFFIX	char *	String	NULL
Pt_ARG_MAXIMUM	long	Scalar	100
Pt_ARG_MINIMUM	long	Scalar	0
Pt_ARG_ORIENTATION	char	Boolean	Pt_HORIZONTAL
Pt_CB_GAUGE_VALUE_CHANGED	PtCallback_t *	Link	NULL

Pt_ARG_GAUGE_FLAGS

C type	Pt type	Default
short int	Flag	0

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

C type	Pt type	Default
char *	String	"TextFont09"

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

Pt_ARG_GAUGE_H_ALIGN

C type	Pt type	Default
unsigned char	Scalar	Pt_CENTER

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

C type	Pt type	Default
unsigned char	Scalar	Pt_CENTER

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

C type	Pt type	Default
long	Scalar	0

The gauge's current value.

Pt_ARG_GAUGE_VALUE_PREFIX

C type	Pt type	Default
char *	String	NULL

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

Pt_ARG_GAUGE_VALUE_SUFFIX

C type	Pt type	Default
char *	String	NULL

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

Pt_ARG_MAXIMUM

C type	Pt type	Default
long	Scalar	100

The maximum value of the gauge.

Pt_ARG_MINIMUM

C type	Pt type	Default
long	Scalar	0

The minimum value of the gauge.

Pt_ARG_ORIENTATION

C type	Pt type	Default
char	Boolean	Pt_HORIZONTAL

The orientation of the gauge; one of:

• Pt_HORIZONTAL
• Pt_VERTICAL

Pt_CB_GAUGE_VALUE_CHANGED

C type	Pt type	Default
PtCallback_t *	Link	NULL

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.

Resource	Inherited from	Default override
Pt_ARG_ANCHOR_FLAGS	PtWidget
Pt_ARG_ANCHOR_OFFSETS	PtWidget
Pt_ARG_AREA	PtWidget
Pt_ARG_BANDWIDTH_THRESHOLD	PtBasic	Not used by this class.
Pt_ARG_BASIC_FLAGS	PtBasic
Pt_ARG_BEVEL_WIDTH	PtWidget	0
Pt_ARG_BITMAP_CURSOR	PtWidget
Pt_ARG_BEVEL_COLOR	PtBasic
Pt_ARG_BEVEL_CONTRAST	PtBasic
Pt_ARG_COLOR	PtBasic
Pt_ARG_CONTRAST	PtBasic
Pt_ARG_CURSOR_COLOR	PtWidget
Pt_ARG_CURSOR_TYPE	PtWidget
Pt_ARG_DARK_BEVEL_COLOR	PtBasic
Pt_ARG_DARK_FILL_COLOR	PtBasic
Pt_ARG_DATA	PtWidget
Pt_ARG_DIM	PtWidget
Pt_ARG_EFLAGS	PtWidget
Pt_ARG_EXTENT	PtWidget
Pt_ARG_FILL_COLOR	PtBasic
Pt_ARG_FILL_PATTERN	PtBasic
Pt_ARG_FLAGS	PtWidget
Pt_ARG_HEIGHT	PtWidget
Pt_ARG_HELP_TOPIC	PtWidget
Pt_ARG_HIGHLIGHT_ROUNDNESS	PtBasic
Pt_ARG_INLINE_COLOR	PtBasic
Pt_ARG_LIGHT_BEVEL_COLOR	PtBasic
Pt_ARG_LIGHT_FILL_COLOR	PtBasic
Pt_ARG_MARGIN_HEIGHT	PtBasic
Pt_ARG_MARGIN_WIDTH	PtBasic
Pt_ARG_MAXIMUM_DIM	PtWidget
Pt_ARG_MINIMUM_DIM	PtWidget
Pt_ARG_OUTLINE_COLOR	PtBasic
Pt_ARG_POINTER	PtWidget
Pt_ARG_POS	PtWidget
Pt_ARG_RESIZE_FLAGS	PtWidget
Pt_ARG_STYLE	PtBasic
Pt_ARG_TRANS_PATTERN	PtBasic
Pt_ARG_USER_DATA	PtWidget
Pt_ARG_WIDTH	PtWidget
Pt_CB_ACTIVATE	PtBasic
Pt_CB_ARM	PtBasic
Pt_CB_BLOCKED	PtWidget
Pt_CB_DESTROYED	PtWidget
Pt_CB_DISARM	PtBasic
Pt_CB_DND	PtWidget
Pt_CB_FILTER	PtWidget
Pt_CB_GOT_FOCUS	PtBasic
Pt_CB_HOTKEY	PtWidget
Pt_CB_IS_DESTROYED	PtWidget
Pt_CB_LOST_FOCUS	PtBasic
Pt_CB_MENU	PtBasic
Pt_CB_OUTBOUND	PtWidget
Pt_CB_RAW	PtWidget
Pt_CB_REALIZED	PtWidget
Pt_CB_REPEAT	PtBasic
Pt_CB_UNREALIZED	PtWidget

---