Contexts and Imager State
Context: TYPE ~ REF ContextRep;
Error: ERROR [error: ErrorDesc];
ErrorDesc:
TYPE ~
RECORD [code:
ATOM, explanation:
ROPE];
GetClass:
PROC [context: Context]
RETURNS [
ATOM];
Returns an ATOM that identifies the context class.
PutProp: PROC [context: Context, key: REF, val: REF];
GetProp:
PROC [context: Context, key:
REF]
RETURNS [val:
REF];
Operations on context.propList; propList is saved and restored by DoSave and DoSaveAll.
DoSave: PROC [context: Context, action: PROC];
DoSaveAll:
PROC [context: Context, action:
PROC];
These save imager variables, call the action procedure, then restore imager variables.
DoSave restores all but the current position and correctMeasure.
DoSaveAll restores everything.
Transformations and Current Position
Two important parts of the Imager state help clients to position the objects that make up an image; these are the
current transformation and the
current position. The basic procedure for changing the current transformation is:
ConcatT: PROC [context: Context, m: Transformation];
ConcatT premultiplies the current transformation by an arbitrary transformation. Procedures for building general transformations are in the ImagerTransformation interface. If you just want to do something simple, the following convenience procedures may be handy.
ScaleT: PROC [context: Context, s: REAL];
Scale2T: PROC [context: Context, s: VEC];
RotateT: PROC [context: Context, a: REAL];
TranslateT: PROC [context: Context, t: VEC];
ScaleT applies a uniform scaling factor; Scale2T scales independently in x and y; RotateT applies a counterclockwise rotation (measured in degrees); and TranslateT translates the origin.
Move:
PROC [context: Context];
Translates the origin to the current position.
Trans:
PROC [context: Context];
Translates the origin to the grid point nearest the current position.
SetXY: PROC [context: Context, p: VEC];
SetXYI:
PROC [context: Context, x, y:
INTEGER];
Sets the current position.
SetXYRel: PROC [context: Context, v: VEC];
SetXYRelI:
PROC [context: Context, x, y:
INTEGER];
Adds a relative displacement to the current position.
SetXRel: PROC [context: Context, x: REAL];
SetXRelI:
PROC [context: Context, x:
INTEGER];
Equivalent to SetXYRel[context, x, 0]
SetYRel: PROC [context: Context, y: REAL];
SetYRelI:
PROC [context: Context, y:
INTEGER];
Equivalent to SetXYRel[context, 0, y]
Text and Spacing Correction
SetFont:
PROC [context: Context, font: Font];
Sets the font for subsequent Show operations.
SetAmplifySpace:
PROC [context: Context, amplifySpace:
REAL];
Sets the scale factor for widths of `amplified' characters.
Show:
PROC [context: Context, string: XStringProc, xrel:
BOOL ←
FALSE];
Shows a string of characters in the current font, starting at the current position.
If xrel~TRUE, every other char means SetXRel[context, char.code-128].
ShowChar:
PROC [context: Context, char:
CHAR];
Shows an 8-bit character (in Character Set 0).
ShowXChar:
PROC [context: Context, char: XChar];
Shows a 16-bit Xerox Character Code.
ShowRope:
PROC [context: Context, rope:
ROPE,
start:
INT ← 0, len:
INT ←
INT.
LAST, xrel:
BOOL ←
FALSE];
Shows characters from a ROPE, using the Xerox String Encoding.
ShowText:
PROC [context: Context, text:
REF
READONLY
TEXT,
start:
NAT ← 0, len:
NAT ←
NAT.
LAST, xrel:
BOOL ←
FALSE];
Shows characters from a REF TEXT, using the Xerox String Encoding.
StartUnderline:
PROC [context: Context];
Remembers the starting x position for an underline.
MaskUnderline: PROC [context: Context, dy, h: REAL];
MaskUnderlineI:
PROC [context: Context, dy, h:
INTEGER];
Draws an underline from the StartUnderline point to the current position.
The underline's top is dy below the current position; its height is h.
Example: StartUnderline[ctx]; ShowRope[ctx, "underlined"]; MaskUnderline[ctx, 3, 1];
CorrectMask: PROC [context: Context];
CorrectSpace:
PROC [context: Context, v:
VEC];
Note "correction space" opportunities for Correct; see Correct, below.
Usually, font characters call these implicitly within Show.
Space: PROC [context: Context, x: REAL];
SpaceI:
PROC [context: Context, x:
INTEGER];
Use Space rather than SetXRel to make correctable spaces inside Correct.
Equivalent to { SetXRel[ctx, x]; CorrectSpace[ctx, [x, 0]] }.
SetCorrectMeasure:
PROC [context: Context, v:
VEC];
Sets the expected line measure for subsequent Correct operations.
SetCorrectTolerance:
PROC [context: Context, v:
VEC];
Sets the line measure tolerance for subsequent Correct operations.
SetCorrectShrink:
PROC [context: Context, correctShrink:
REAL];
Sets the allowable fraction of space shrink for subsequent Correct operations.
Correct:
PROC [context: Context, action:
PROC];
Ensures reasonable spacing of text (or other masks) even if the imager approximates fonts.
Like DoSave[context, action], but adjusts "correction space" if necessary to ensure that the net change in current position is within correctTolerance of correctMeasure.
Note that Correct may (or may not) invoke action twice.
See the Interpress Standard, section 4.10, and the Introduction to Interpress, section 10.
DontCorrect:
PROC [context: Context, action:
PROC, saveCP:
BOOL ←
FALSE];
Disables correction, calls action, then restores correction state.
If saveCP~TRUE, also saves and restores current position.
For relevant examples, see the Introduction to Interpress, section 10.6.
Color and Pixel Arrays
SetColor:
PROC [context: Context, color: Color];
Sets the current color.
MakeGray:
PROC [f:
REAL]
RETURNS [ConstantColor];
Returns a constant gray; f is the fraction of absorptance, from 0 (white) to 1 (black).
black: READONLY ConstantColor; -- MakeGray[1]
white: READONLY ConstantColor; -- MakeGray[0]
SetGray:
PROC [context: Context, f:
REAL];
Equivalent to SetColor[context, MakeGray[f]]
SetSampledColor:
PROC [context: Context, pa: PixelArray,
m: Transformation ←
NIL, colorOperator: ColorOperator];
Equivalent to SetColor[context, MakeSampledColor[pa, Concat[m, T], colorOperator].
Better than direct use of MakeSampledColor, since you don't need to know T.
SetSampledBlack:
PROC [context: Context, pa: PixelArray,
m: Transformation ←
NIL, clear:
BOOL ←
FALSE];
Equivalent to SetColor[context, MakeSampledBlack[pa, Concat[m, T], clear].
Better than direct use of MakeSampledBlack, since you don't need to know T.
Masks and Clipping
MaskFill:
PROC [context: Context, path: PathProc, parity:
BOOL ←
FALSE];
Fills with the current color the interior of the region outlined by the specified path.
Closes each trajectory in the path with a straight line, if necessary.
If parity~FALSE, the mask includes all points with nonzero winding number.
If parity~TRUE, the mask includes all points with odd winding number.
MaskFillTrajectory:
PROC [context: Context, trajectory: Trajectory, parity:
BOOL ←
FALSE];
Fills the region described by a Trajectory.
MaskFillOutline:
PROC [context: Context, outline: Outline, parity:
BOOL ←
FALSE];
Fills the region described by an Outline.
MaskRectangle: PROC [context: Context, r: Rectangle];
MaskRectangleI:
PROC [context: Context, x, y, w, h:
INTEGER];
Fills the rectangle [x, y], [x+w, y], [x+w, y+h], [x, y+h].
Box:
TYPE ~
RECORD [xmin, ymin, xmax, ymax:
REAL];
MaskBox:
PROC [context: Context, box: Box];
Fills the rectangle [xmin, ymin], [xmax, ymin], [xmax, ymax], [xmin, ymax].
A convenience for former users of Graphics.DrawBox.
SetStrokeWidth:
PROC [context: Context, strokeWidth:
REAL];
Establishes the width for subsequent strokes.
StrokeEnd:
TYPE ~ {square, butt, round};
square: square off each end after extending the stroke by half strokeWidth
butt: square off each end flush with the endpoint
round: round each end with a semicircular cap of strokeWidth diameter
SetStrokeEnd:
PROC [context: Context, strokeEnd: StrokeEnd];
Establishes the endpoint style for subsequent strokes.
StrokeJoint:
TYPE ~ {mitered, round};
mitered: extend segment sides until they meet (acute angles make long, sharp corners)
round: join segments in a circle of strokeWidth diameter
SetStrokeJoint:
PROC [context: Context, strokeJoint: StrokeJoint];
Establishes the joint style for subsequent strokes.
MaskStroke:
PROC [context: Context, path: PathProc, closed:
BOOL ←
FALSE];
Fills with the current color a stroke whose centerline is the specified path.
The current strokeWidth and strokeJoint determine the stroke's width and joint style.
If closed~FALSE, the current strokeEnd determines the stroke's endpoint style.
If closed~TRUE, each trajectory is closed, if necessary, with a straight line.
MaskStrokeTrajectory:
PROC [context: Context, trajectory: Trajectory, closed:
BOOL ←
FALSE];
Fills a stroke along a trajectory.
MaskVector: PROC [context: Context, p1, p2: VEC];
MaskVectorI:
PROC [context: Context, x1, y1, x2, y2:
INTEGER];
Fills a stroke along the line joining p1 and p2.
MaskPixel:
PROC [context: Context, pa: PixelArray];
Uses a pixel array as a mask; pa must have one bit per pixel.
MaskBits:
PROC [context: Context, base:
LONG
POINTER, wordsPerLine:
NAT,
sMin, fMin, sSize, fSize:
NAT, tx, ty:
INTEGER ← 0];
SetPriorityImportant:
PROC [context: Context, priorityImportant:
BOOL];
If priorityImportant~TRUE, subsequent Mask operations will retain correct priority order.
SetNoImage:
PROC [context: Context, noImage:
BOOL];
If noImage~TRUE, subsequent Mask operations will not change the output.
Clip:
PROC [context: Context, path: PathProc, parity, exclude:
BOOL ←
FALSE];
Clips subsequent masks to the interior of a region described (as for MaskFill) by a path.
If exclude~TRUE, clips to the exterior of the region instead of the interior.
This region is itself clipped by any clipping region previously in force.
ClipOutline:
PROC [context: Context, outline: Outline, parity, exclude:
BOOL ←
FALSE];
Clips to an outline.
ClipRectangle: PROC [context: Context, r: Rectangle, exclude: BOOL ← FALSE];
ClipRectangleI:
PROC [context: Context, x, y, w, h:
INTEGER, exclude:
BOOL ←
FALSE];
Clips to the rectangle [x, y], [x+w, y], [x+w, y+h], [x, y+h].