PtGraphic

Common resources for graphical widgets

Class hierarchy:

PtWidget → PtBasic → PtGraphic

Immediate subclasses:

• PtArc
• PtBezier
• PtEllipse
• PtGrid
• PtLine
• PtPixel
• PtPolygon
• PtRect

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.

---

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:

• lines
• rectangles
• ellipses
• arcs
• polylines
• points

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:

• Pt_ARG_INSIDE_COLOR
• Pt_ARG_INSIDE_FILL_PATTERN
• Pt_ARG_INSIDE_TRANS_PATTERN

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)}

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.

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.

---

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:

Pt_ARG_DASH_LIST

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

Pt_ARG_DASH_SCALE

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

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

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

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

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

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

• Pg_BUTT_CAP
• Pg_ROUND_CAP
• Pg_SQUARE_CAP

Pt_ARG_LINE_JOIN

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

• Pg_BEVEL_JOIN
• Pg_BUTT_JOIN
• Pg_MITER_JOIN
• Pg_ROUND_JOIN
• Pg_QROUND_JOIN (quick rounded join)

Pt_ARG_LINE_WIDTH

The line width for any graphically based widget.

Pt_ARG_ORIGIN

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

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

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.