Defined in Graphics.Def Abstract Inherits from Object
The Magic Cap graphics system defines objects of class Canvas to provide an area to draw into and a coordinate system for drawing. Viewable objects use Canvas objects to direct their drawing.
Class Canvas is a direct descendant of class Object. Canvas is an abstract class; you'll never create or use an object of class Canvas. Instead, you'll use objects of canvas subclasses, such as class PixelMap. Even then, you'll probably never create objects of Canvas subclasses; the system creates these objects and passes them to you sometimes.
Instantiate: rarely Subclass: rarely Call its methods: sometimes
Whenever you create a new class of viewable object, you override Draw to define how to draw the objects. The system passes in a canvas when it calls your Draw method. This is probably the only interaction your packages will have with canvas objects, and you probably won't do much with it. If you call the inherited Draw, you should just pass the canvas object that was passed in to your Draw.
If you create a subclass of class Canvas, you will need to override many of its methods. Class Canvas provides a framework but does not implement most of the framework itself.
Class Canvas defines three kinds of operations:
Grid points are the places between pixels.
Many of the methods of class Canvas take a parameter called colorant. The colorant is a color expressed as an ORGB value: 8 bits of opacity information, 8 bits of red, 8 bits of green, and 8 bits of blue. Magic Cap 1.0 doesn't do anything with most of this color information, since it only displays 4 shades of gray.
The interface file Graphics.h defines several color names you can use as your colorants. They are:
| Color name | Value |
| rgbAlpha | 0xFF000000 |
| rgbTransparent | 0x00000000 |
| rgbOpaque | rgbAlpha |
| rgbRed | (rgbOpaque | 0x00FFFF) |
| rgbGreen | (rgbOpaque | 0xFF00FF) |
| rgbBlue | (rgbOpaque | 0xFFFF00) |
| rgbCyan | (rgbOpaque | 0xFF0000) |
| rgbMagenta | (rgbOpaque | 0x00FF00) |
| rgbYellow | (rgbOpaque | 0x0000FF) |
| rgbDarkRed | (rgbOpaque | 0x80FFFF) |
| rgbDarkGreen | (rgbOpaque | 0xFF80FF) |
| rgbDarkBlue | (rgbOpaque | 0xFFFF80) |
| rgbWhite | rgbOpaque |
| rgbGray12 | (rgbOpaque | 0x202020) |
| rgbGray20 | (rgbOpaque | 0x333333) |
| rgbLtGray | (rgbOpaque | 0x555555) |
| rgbGray49 | (rgbOpaque | 0x7F7F7F) |
| rgbGray51 | (rgbOpaque | 0x808080) |
| rgbDkGray | (rgbOpaque | 0xAAAAAA) |
| rgbBlack | (rgbOpaque | 0xFFFFFF) |
The file Graphics.h defines other constants you'll use with the methods of class Canvas.
The clip parameter used by many methods is usually a path. Nothing is drawn outside a clip or outside the bounds of a canvas. If you pass nilObject as a clip parameter, your drawing will be clipped to the bounds of the canvas and not clipped any further.
The modes for fills define whether dithering is to be done and offer some other variations. Dithering can be requested by passing modes that are or-ed with pixelDither. The modes for other drawing offer variations on pixel transfer, but dithering is never done.
Class Canvas has the following methods you might call:
| Method | Description |
|---|---|
| Size and resolution | |
| CanvasBounds | Gets the bounds of the canvas |
| EnclosingBounds | Does nothing; override with your own method |
| OffsetCanvas | Changes the origin of both the canvas and the clip path |
| GridH | Snaps a horizontal coordinate to the nearest grid point |
| GridV | Snaps a vertical coordinate to the nearest grid point |
| GridDot | Snaps a dot to the nearest grid point |
| GridBox | Snaps a box's corners to the nearest grid point |
| Drawing filled regions | |
| FillBox | Fills a box with color on the canvas |
| FillPath | Does nothing; override when you are defining a new type of canvas |
| SetDitherOrigin | Sets the origin for dither-alignment purposes |
| DitherOrigin | Gets the origin for dither-alignment purposes |
| Drawing images | |
| CopyPixels | Draws pixels onto the canvas |
| CopyPixelsTile | Draws repeating patterns of pixels onto the canvas |
| FillMask | Fills an area with a color filtered through a mask of pixels |
| FillMaskTile | Fills an area with a color filtered through a repeating pattern of mask pixels |
| MaskPixels | Draws pixels onto the canvas, filtering through other pixels as a mask |
| MaskPixelsTile | Fills an area with a color filtered through a repeating pattern of mask pixels |
| Drawing text | |
| FillText | Draws text |
| Drawing single pixels | |
| ModifyPixel | Changes the single pixel enclosing or just right and below the given dot to | the given colorant |
| ReadPixel | Returns the color of the single pixel enclosing or just right and below the | given dot |
| High-level drawing calls | |
| FillLine | Fills a line with color on the canvas |
| FrameBox | Draws lines inside the edge of the given box |
| FramePath | Draws lines inside the edge of the given path |
| PaintBox | Fills a box with black |
| PaintPath | Fills a path with black |
| EraseBox | Fills a box with white |
| ErasePath | Fills a path with white |
| InvertBox | Inverts a box |
| InvertPath | Inverts a path |
| HiliteBox | Adds highlights inside a box |
| ScreenCanvas | Gets the screen canvas |
| SpecialEffectsCanvas | Gets the alternate canvas to use for special effects |
| UpdateEffects | Copies effects drawn in special-effects canvas |
Most of these methods do nothing, but are implemented for subclasses of class Canvas. They're listed here to give you a handy reference.
Class Canvas doesn't define any fields.
Class Canvas defines the following attributes:
| Attribute | Type | Description |
|---|---|---|
| ActualPixelSize | PixelDot | The precise size of a pixel in microns |
| PixelSize | PixelDot | The nominal size of a pixel in microns |
There are several methods in this section that require a transfer mode when drawing. The transfer mode determines how the pixels at the destination are combined with the pixels in the source image. The system defines a set of constants for the transfer modes, as follows:
enum
{
pixelCopy = 0x0,
pixelHilite = 0x1, /* Not fully supported */
pixelDark = 0x2,
pixelLite = 0x3,
pixelXor = 0x5,
pixelOr = 0x6,
pixelAnd = 0x7
/* 0x8 through 0x1F reserved for basic modes */
};
enum
{
pixelLogic = 0x4,
pixelDither = 0x20
};
Version Note: More information about these constants will appear in future drafts of this book. For now, you can usually use pixelDither|pixelCopy as the transfer mode.
operation FillBox(clip: ScanConvertible; box: Box; colorant: Unsigned; mode: Signed), noMethod Call: sometimes Override: always
Call FillBox to draw a box filled with a color. The box passed in box is clipped to the path passed in clip. The RGB value passed in colorant is used to fill the box according to the given transfer mode.
operation FillLine(clip: ScanConvertible; dot1: Dot; dot2: Dot; width: Micron; height: Micron; colorant: Unsigned; mode: Signed) Call: sometimes Override: always
Call FillLine to draw a line in color. The line is drawn from dot1 to dot2, at the thickness passed in width, clipped to the path passed in clip. The RGB value passed in colorant is used to color the line according to the given transfer mode.
operation FillPath(clip: ScanConvertible; path: Path; colorant: Unsigned; mode: Signed), noMethod Call: sometimes Override: always
Call FillPath to fill a path in color. The given path is clipped to the path passed in clip. The RGB value passed in colorant is used to fill the path according to the given transfer mode.