PtGraphic

Common resources for graphical widgets

Class hierarchy:

PtWidgetPtBasicPtGraphic

Immediate subclasses:

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

PhAB icon:

None — not normally instantiated.

Public header:

<photon/PtGraphic.h>

Description:

The PtGraphic superclass provides the common resources used by all graphic widgets. Graphical widgets provide attributes for color, fills, patterns, line thickness, joins, and much more.

When you want to incorporate simple, static drawings in your interface, use the subclasses of PtGraphic.


Note: Don't call the Pg... drawing primitives directly, as they aren't redrawn when widgets are damaged and repaired. If you need to draw something that can't be done with these widgets, do your drawing inside a PtRaw widget. For more information, see the Raw Drawing and Animation chapter of the Photon Programmer's Guide.

Each graphical widget draws a single graphical primitive. The provided primitives are:

You can build up a drawing by creating one widget for each of the graphical primitives you need. You should create the widgets from back to front, so that their stacking order is correct and they consequently appear correct when drawn to the screen. You should also place the widgets in a container widget (i.e a subclass of PtContainer).

Origin and coordinates

All the vector graphics widgets are defined by an origin and a set of coordinates.

The origin is an offset from the graphic widget's origin, which is used as the origin of the coordinate space for the graphics primitive.

The set of coordinates is implemented as an array of PhPoint_t structures (see the Photon Library Reference). Each coordinate specifies a vertex or control point of the primitive. Here's a code fragment to illustrate:

PhPoint_t points[]=
    { { 0, 0},
      {40,40},
      {40, 5},
      { 0, 0}};
PtSetArg(&argt[0], Pt_ARG_POINTS, points, 4 ) ;
PtCreateWidget( PtPolygon, parent, 1, argt ) ;

Each of the coordinates defining the primitive is relative to the graphics widget's origin.

You can specify the graphics widget's origin by setting Pt_ARG_ORIGIN. This resource takes a PhPoint_t as a value. This point is the origin of the primitive's coordinate space, in pixels, relative to the widget's origin.

The set of points is specified using the array resource Pt_ARG_POINTS. The number of points required in the array — and the interpretation of those points — depends on the type of graphics primitive being defined.

Line attributes

When drawing the points for the primitive, the widget uses its associated line drawing attributes to determine the color and drawing style to use. These line drawing attributes are specified using the following resources defined by the PtGraphic widget class:

Pt_ARG_LINE_WIDTH
The curve's width, in pixels.
Pt_ARG_LINE_CAP
The cap style for capping off the curve's start and end points.
Pt_ARG_LINE_JOIN
The join style for connecting any intermediate vertices in the curve.

Colors

The graphics primitives use the following resources (defined by PtBasic) to determine their colors and patterns:

Pt_ARG_COLOR
The widget's line color.
Pt_ARG_FILL_COLOR
The color of the rectangular area occupied by the widget (i.e. its extent).
Pt_ARG_FILL_PATTERN
The stipple pattern to use to fill the extent.

The graphics primitives that can draw a closed curve may also use these resources (defined by PtGraphic) for the inside of the curve:

Creating a drawing

To create a drawing composed of several graphical widgets, you should first create a container-class widget to place the widgets in. If you wish, set the border width and margins of the container to zero.

At this point, you may create the graphics primitives and position them within the container widget. You may choose to position and size the graphics widgets in one of several ways, but the simplest is to place them all at position (0,0), which is adequate for most purposes.

The origin resource, Pt_ARG_ORIGIN, provides a reference point or datum for all the primitives added to the container-class widget. This resource defines a coordinate space for each graphic, allowing maximum flexibility for positioning and sizing primitives.

For example, the origin lets you create a library of symbols defined in their own coordinate space. You can then use the origin to place the symbol anywhere in the drawing, and the widget itself doesn't need to be positioned. The only thing you have to do then is scale the symbol itself.

Sizing the primitives

If you know the overall dimensions of the drawing, you may want to explicitly set the dimensions of the graphics widgets as you create them. You might also want to set the dimensions if you want to have a standard symbol clipped to obtain a new shape. The figure below illustrates how a five-pointed star is drawn when Pt_ARG_ORIGIN is set to (50,50) and the dimensions of the widget are fixed at 101 x 101 pixels. The star is constructed from this set of points:

{(95, -31), (-58, 81), (0, -100), (58, 81), (-95, -31)}

poly fig


A five-pointed star before clipping.

Note the resulting bounding box of the widget as well as the origin of the polygon's coordinate space, which is fixed at position (50,50) of the widget's canvas.


clipped poly fig


The star after clipping.

If you don't need special clipping, however, you should use the graphics widget's resize policy or another geometry management mechanism to determine the widget's size. The default resize policy for graphics is Pt_RESIZE_...AS_REQUIRED for both the width and height. To fix the dimensions of the widget as shown in the case above, you have to override the default resize policy. For more information, see the Pt_ARG_RESIZE_FLAGS resource in the description of PtWidget.

Grouping elements of the drawing

Occasionally you'll want to group together a number of graphical primitives and define them as a group or unit. All the primitives within the group are defined in terms of their common origin, and the unit may be repositioned or resized without affecting the group's components. You can do this simply by creating a container-class widget and placing the widgets for the graphical primitives within it.


Note: Using this technique, you can create a complex drawing composed of a number of subdrawings. There's no limit to the number of drawings that can be nested in this way. The only limiting factor here is the number of resources consumed. In a system with constrained memory, many deeply nested drawings may consume too much memory.

New resources:

Resource C type Pt type Default
Pt_ARG_DASH_LIST char, short Array NULL
Pt_ARG_DASH_SCALE long Scalar 0
Pt_ARG_GRAPHIC_FLAGS char Flag 0
Pt_ARG_INSIDE_COLOR PgColor_t Scalar Pg_TRANSPARENT
Pt_ARG_INSIDE_FILL_PATTERN PgPattern_t Struct Pg_PAT_FULL
Pt_ARG_INSIDE_TRANS_PATTERN PgPattern_t Struct Pg_PAT_NONE
Pt_ARG_LINE_CAP unsigned short Scalar Pg_BUTT_CAP
Pt_ARG_LINE_JOIN unsigned short Scalar Pg_MITER_JOIN
Pt_ARG_LINE_WIDTH long Scalar 0
Pt_ARG_ORIGIN PhPoint_t Struct 0,0
Pt_ARG_POINTS PhPoint_t *, short Array NULL
Pt_CB_RESCALE PtCallback_t * Link NULL

Pt_ARG_DASH_LIST

C type Pt type Default
char, short Array NULL

An array of bytes that describes the on and off bits for stroke operations.

Pt_ARG_DASH_SCALE

C type Pt type Default
long Scalar 0

A scaling factor that's applied to each of the bits in the dash list to determine the number of pixels for each dash. For information on setting this factor, see PgSetStrokeDash() in the Photon Library Reference.

Pt_ARG_GRAPHIC_FLAGS

C type Pt type Default
char Flag 0

Possible values:

Pt_FLOAT_POS
Adjust the position and origin of the widget, but leave the graphic in place relative to the widget's parent. The upper left corner of the widget's canvas is at the upper left corner of the bounding box described by the point array. Depending on its resize policy, the widget may resize to fit the rendering.
Pt_FLOAT_ORIGIN
Adjust the origin of the graphic, but leave the widget in place relative to its parent. The upper left corner of the bounding box described by the point array is at the upper left corner of the widget's canvas.

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

Pt_ARG_INSIDE_COLOR

C type Pt type Default
PgColor_t Scalar Pg_TRANSPARENT

The color of the inside of the graphic. See PgColor_t in the Photon Library Reference.

Pt_ARG_FILL_COLOR (inherited from PtBasic) is the color of the widget's extent (i.e. the rectangular area that the widget occupies).

Pt_ARG_INSIDE_FILL_PATTERN

C type Pt type Default
PgPattern_t Struct Pg_PAT_FULL

The background pattern of the inside of the graphic. You can't edit this resource in PhAB.

Pt_ARG_FILL_PATTERN (inherited from PtBasic) is the fill pattern of the widget's extent (i.e. the rectangular area that the widget occupies).

Pt_ARG_INSIDE_TRANS_PATTERN

C type Pt type Default
PgPattern_t Struct Pg_PAT_NONE

The transparency pattern for the inside of the graphic. You can use this resource for “ghosting” widgets. You can't edit this resource in PhAB.

Pt_ARG_TRANS_PATTERN (inherited from PtBasic) is the transparency pattern of the widget's extent (i.e. the rectangular area that the widget occupies).

Pt_ARG_LINE_CAP

C type Pt type Default
unsigned short Scalar Pg_BUTT_CAP

Defines how the ends of thick lines are drawn; see PgSetStrokeCap(). Possible values:

Pt_ARG_LINE_JOIN

C type Pt type Default
unsigned short Scalar Pg_MITER_JOIN

Defines how thick lines are connected; see PgSetStrokeJoin(). Possible values:

Pt_ARG_LINE_WIDTH

C type Pt type Default
long Scalar 0

The line width for any graphically based widget.

Pt_ARG_ORIGIN

C type Pt type Default
PhPoint_t Struct 0,0

A PhPoint_t structure that specifies the offset from the upper left corner of the widget's canvas. The graphic is rendered with its origin at:

(widget position) + (Pt_ARG_ORIGIN)

Pt_ARG_POINTS

C type Pt type Default
PhPoint_t *, short Array NULL

An array of points (PhPoint_t structures) describing the graphic. The number of points required in the array and the interpretation of those points depend on the type of graphics primitive being defined.

Pt_CB_RESCALE

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the callbacks that the widget invokes if its Pt_ARG_DIM or Pt_ARG_AREA resource is modified. You can use this callback to rescale the widget.

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

reason
Pt_CB_RESCALE
reason_subtype
0 (not used).
event
NULL (not used).
cbdata
A pointer to a PhArea_t structure (see the Photon Library Reference) that indicates the old area of the widget (prior to the area/dimension change). You can retrieve the current area by calling PtGetResources().

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 Pg_TRANSPARENT
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