Object <- Canvas |
|
|
ActualPixelSize PixelSize |
Define Class Canvas;
abstract;
inherits from Object;
// current canvas
intrinsic CurrentCanvas(): Canvas;
// call to get the current canvas that will be used for drawing
intrinsic SetCurrentCanvas(new: Canvas): Canvas;
// call to set the curent canvas; returns the old current canvas
// current clip
intrinsic CurrentClip(): Path;
// call to get the current path that will be used for clipping
intrinsic SetCurrentClip(new: Path): Path;
// call to set the curent clipping path
// returns the old current clip
intrinsic SetCurrentClipBox(new: Box): Path;
// set the current clip to box passed in
// returns the old current clip
intrinsic IntersectCurrentClip(path: Path): Path;
// use this to intersect the current clip with the path parameter
// returns the old current clip
intrinsic IntersectCurrentClipBox(new: Box): Path;
// use this to intersect the current clip with the box parameter
// returns the old current clip
// size and resolution
operation CanvasBounds(var bounds: Box), noMethod;
// call to get the bounds of the canvas
// drawing outside the bounds is ignored
// override when you are defining a new type of canvas
operation EnclosingBounds(var bounds: Box): Boolean, noMethod;
//
operation OffsetCanvas(clip: Path; dh: Micron; dv: Micron), noMethod;
// call to change the origin of both the canvas and the clip path
// override when you are defining a new type of canvas
attribute PixelSize: PixelDot, readOnly, noGetter;
// call to get the nominal pixel size in microns
// this is a nice round size, usually near the actual size
// this size should be used for most scaling decisions
// override when you are defining a new type of canvas
attribute ActualPixelSize: PixelDot, readOnly, noGetter;
// call to get the precise pixel size in microns
// this is the precise size and should be used for
// things that must be exact in size at the expense
// of looking good
// override when you are defining a new type of canvas
operation GridH(h: Micron): Micron, noMethod;
// call to grid a horizontal coordinate to the nearest grid point
// grid points are the places between pixels
// override when you are defining a new type of canvas
operation GridV(v: Micron): Micron, noMethod;
// call to grid a vertical coordinate to the nearest grid point
// grid points are the places between pixels
// override when you are defining a new type of canvas
operation GridDot(var dot: Dot), noMethod;
// call to grid a dot to the nearest grid point
// equivalent to calling GridH and GridV
// override when you are defining a new type of canvas
operation GridBox(var box: Box), noMethod;
// call to grid a box's corners to the nearest grid point
// equivalent to calling GridDot twice on top-left and bottom-right corners
// override when you are defining a new type of canvas
// drawing
// clip is usually a path
// nothing is drawn outside the clip or outside the bounds of the canvs
// nil for clip means clip only to the bounds of the canvas
// colors are expressed as ORGB values (8-bit opacity, 8-bit red, 8-bit green, 8-bit blue)
// modes for fills define whether dithering is to be done and offer some other variations
// modes for other drawing offer variations on pixel transfer but dithering is never done
// fill drawing
operation FillBox(clip: ScanConvertible; box: Box; colorant: Unsigned; mode: Signed), noMethod;
// call to fill a box with color on the canvas
// dithering can be requested by passing modes that are or-ed with pixelDither
operation FillPath(clip: ScanConvertible; path: Path; colorant: Unsigned; mode: Signed), noMethod;
// override when you are defining a new type of canvas
operation SetDitherOrigin(origin: Dot), noMethod;
// call to set the origin for dither-alignment purposes
// use this so the dithering of a filled object is
// aligned relative to the corner of a superview instead of the screen
// override when you are defining a new type of canvas
operation DitherOrigin(var origin: Dot), noMethod;
// call to get the origin for dither-alignment purposes
// use this to get the original dither origin so you
// can restore it after calling SetDitherOrigin
// override when you are defining a new type of canvas
// image drawing
operation CopyPixels(clip: ScanConvertible; dstBox: Box; source: Canvas; srcBox: Box; mode: Signed), noMethod, safe;
// call to draw pixels onto the canvas
// dstBox specifies the box to draw into
// source is a canvas containing the pixels to draw
// srcBox specifies the box within the source pixels to draw from
// if dstBox and srcBox encompass different numbers of pixels the pixels are stretched
// MAGIC CAP 1.0: stretching is not yet implemented for any system canvas subclasses
// override when you are defining a new type of canvas
operation CopyPixelsTile(clip: ScanConvertible; dstBox: Box; source: Canvas; srcBox: Box; mode: Signed), safe;
// call to draw repeating patterns of pixels onto the canvas
// works like CopyPixels except:
// if dstBox and srcBox encompass different number of pixels, the pixel pattern is repeated
// how this works when the source and destination have much different resolutions is not defined
// MAGIC CAP 1.0: each pixel in the source covers one pixel in the target regardless of resolution
// override when you are defining a new type of canvas
operation FillMask(clip: ScanConvertible; dstBox: Box; mask: Canvas; maskBox: Box; colorant: Unsigned; mode: Signed), noMethod;
// call to fill an area with a color filtered through a mask of pixels
// dstBox specifies the box to draw into
// mask is a canvas containing the pixels to draw through
// maskBox specifies the box within the mask pixels to get pixels from
// colorant contains the ORGB-value to draw through
// if dstBox and maskBox encompass different numbers of pixels the pixels are stretched
// MAGIC CAP 1.0: stretching is not yet implemented for any system canvas subclasses
// override when you are defining a new type of canvas
operation FillMaskTile(clip: ScanConvertible; dstBox: Box; mask: Canvas; maskBox: Box; colorant: Unsigned; mode: Signed);
// call to fill an area with a color filtered through a repeating pattern of mask pixels
// works like FillMask except:
// if dstBox and maskBox encompass different number of pixels, the pixel pattern is repeated
// how this works when the source and destination have much different resolutions is not defined
// MAGIC CAP 1.0: each pixel in the source covers one pixel in the target regardless of resolution
// override when you are defining a new type of canvas
operation MaskPixels(clip: ScanConvertible; dstBox: Box; mask: Canvas; maskBox: Box; source: Canvas; srcBox: Box; mode: Signed), noMethod;
// call to draw pixels onto the canvas, filtering through other pixels as a mask
// dstBox specifies the box to draw into
// mask is a canvas containing the pixels to draw through
// maskBox specifies the box within the mask pixels to get pixels from
// source is a canvas containing the pixels to draw
// srcBox specifies the box within the source pixels to draw from
// if dstBox and maskBox encompass different numbers of pixels the mask pixels are stretched
// if dstBox and srcBox encompass different numbers of pixels the source pixels are stretched
// MAGIC CAP 1.0: stretching is not yet implemented for any system canvas subclasses
// override when you are defining a new type of canvas
operation MaskPixelsTile(clip: ScanConvertible; dstBox: Box; mask: Canvas; maskBox: Box; source: Canvas; srcBox: Box; mode: Signed);
// call to fill an area with a color filtered through a repeating pattern of mask pixels
// works like FillMask except:
// if dstBox and maskBox encompass different number of pixels, the mask pixel pattern is repeated
// if dstBox and maskBox encompass different number of pixels, the source pixel pattern is repeated
// how this works when the source and destination have much different resolutions is not defined
// MAGIC CAP 1.0: each pixel in the source covers one pixel in the target regardless of resolution
// override when you are defining a new type of canvas
// text drawing
operation FillText(clip: ScanConvertible; characters: ReadOnlyCharactersPointer; length: Unsigned; var where: Dot; style: TextStyle; mode: Signed), noMethod;
// call to draw text; works like FillMask with the glyphs providing the mask
// <characters> are an array of <length> character codes
// <where> is the baseline starting position of the first character
// after drawing, <where> contains the place where the next character would be drawn
// <style> defines the text style, which determines the font that will be used
// override when you are defining a new type of canvas
// single-pixel drawing
operation ModifyPixel(clip: Path; dot: Dot; colorant: Unsigned), noMethod;
// call to change the single pixel enclosing or just right and below <dot> to <colorant>
// override when you are defining a new type of canvas
operation ReadPixel(dot: Dot): Unsigned, noMethod;
// call to return the color of the single pixel enclosing or just right and below <dot>
// override when you are defining a new type of canvas
// high-level drawing calls
operation FillLine(clip: ScanConvertible; dot1: Dot; dot2: Dot; width: Micron; height: Micron; colorant: Unsigned; mode: Signed);
// call to fill a line with color on the canvas
// dot1 and dot2 are the two endpoints of the line
// by default uses FillBox for horizontal or vertical lines, FillPath for others
// sometimes override when you are defining a new type of canvas to make lines better
operation FrameBox(clip: ScanConvertible; box: Box; thickness: Micron; colorant: Unsigned; mode: Signed);
// call to draw lines inside the edge of <box>
// by default uses one or four calls to FillBox
// sometimes override when you are defining a new type of canvas to make framing faster
operation FramePath(clip: ScanConvertible; path: Path; thickness: Micron; colorant: Unsigned; mode: Signed);
// call to draw lines inside the edge of <path>
// by default uses InsetPath, DiffPath, and FillPath
// sometimes override when you are defining a new type of canvas to make framing better or faster
operation PaintBox(clip: ScanConvertible; box: Box);
// call to fill a box with black
// calls FillBox
// rarely override
operation PaintPath(clip: ScanConvertible; path: Path);
// call to fill a path with black
// calls FillPath
// rarely override
operation EraseBox(clip: ScanConvertible; box: Box);
// call to fill a box with white
// calls FillBox
// rarely override
operation ErasePath(clip: ScanConvertible; path: Path);
// call to fill a path with white
// calls FillPath
// rarely override
operation InvertBox(clip: ScanConvertible; box: Box);
// call to invert a box
// calls FillBox with pixelXOr for <mode>
// rarely override
operation InvertPath(clip: ScanConvertible; path: Path);
// call to invert a path
// calls FillPath with pixelXOr for <mode>
// rarely override
operation HighlightBox(clip: ScanConvertible; box: Box; inset: Micron; thickness: Micron; topColorant: Unsigned; bottomColorant: Unsigned), intrinsic;
// call to add highlights inside a box
// draws four lines of specified <thickness> spaced by <inset> from the edge of <box>
// the lines near the top and left of <box> use <topColorant>
// the lines near the bottom and right of <box> use <bottomColorant>
// screen canvas (avoid using these calls if possible)
intrinsic BufferCanvas(): Canvas;
intrinsic ScreenCanvas(): Canvas;
// call to get the screen canvas
// rarely used to draw directly to the screen
intrinsic SpecialEffectsCanvas(): Canvas;
// call to get the alternate canvas to use for special effects
// rarely used to do effects directly on the screen
// returns screen canvas if it can be used directly, off-screen buffer otherwise
intrinsic UpdateEffects(bounds: Box);
// copies effects drawn in special-effects canvas
// <bounds> is the area of the canvas affected by the effect
end class;