class canvas

superclass(es) object
subclass(es) printerCanvas
description The canvas class can be used for drawing on (panel) windows.
see also icon - pen - brush - image - font - customControl

tasks

With the canvas class it is possible to draw on windows using pens, brushes, fonts and images. But before drawing can start the canvas must be initialized and the method startDraw/0 must be called, the method startDraw/0 prepares the canvas class for drawing. It is important that each call to startDraw/0 is matched with a call to stopDraw/0. So to draw on a panel window the following actions are necessary:
1. Create a canvas instance.
2. Call the method init/2 of the canvas instance.
3. Call the method startDraw/0 of the same instance.
4. The canvas can be used for drawing.
5. Call stopDraw/0 to finish drawing.
6. Delete the canvas instance.

Drawing on the canvas is done with the current selected pen, brush and font. The current pen can be set by the method putPen/1, the current brush by putBrush/1 and the current font by putFont/1.

If a string is drawn on the canvas the current background color of the canvas is used to fill the area between the characters of the string, the backgroundcolor can be set by putBackgroundColor/3. The color of the drawn characters is determined by the current text color, this property can be set by the method putTextColor/3.

If a rectangle is drawn the inside of the rectangle is filled using the current brush and the edges of the rectangle are drawn using the current pen. A null pen is useful if a rectangle must be drawn that has no visible border.

methods

init(Window, Output)

func Initialise the canvas instance for drawing on the specified window.
pre The variable Window must refer to a window instance.
post If the canvas was successfully initialized then true is assigned to the variable Output, else false is assigned.
Arrow.gif (1632 bytes) The next step is to call StartDraw/0.

startDraw

func Initialise the canvas instance for drawing.
pre TRUE.
post The canvas is ready for drawing.
Arrow.gif (1632 bytes) Each call to this method must be matched with a call to the method stopDraw/0.

stopDraw

func Tell the canvas instance that drawing has finished.
pre TRUE.
post The canvas instance can no longer be used for drawing.
Arrow.gif (1632 bytes) Each call to this method must be matched with a call to the method startDraw/0.

putInvertOutput(YesNo)

func Enable inverting the output or disable it. If all output is inverted the color of each pixel is replaced by it's opposite color.
pre The variable YesNo must contain true or false.
post If YesNo contained true all output is inverted, else the output is not inverted.

invertOutput(Output)

func Determine if the output is being inverted or not.
pre TRUE.
post If the output is being inverted then true is assigned to Output, else false is assigned to Output.

horDeviceSize(Output)

func Determine the horizontal size of the output device in pixels.
pre TRUE.
post The horizontal size of the output device was assigned to the variable Output.

verDeviceSize(Output)

func Determine the vertical size of the output device in pixels.
pre TRUE.
post The vertical size of the output device was assigned to the variable Output.

visible(point(X, Y), Output)

func Determine if the point is visible on the current window being drawn. The coordinate specified is a window coordinate, a window coordinate is relative to the upper-left corner of the window.
pre The variables X and Y must contain integer values.
post If the specified coordinate is visible then true was assigned to the variable Output, else false was assigned to Output..

visible(rectangle(X, Y, R, B), Output)

func Determine if a part of the rectangle is visible on the current window being drawn. The coordinates specified are window coordinates, a window coordinate is relative to the upper-left corner of the window. The variables X and Y specify the position of the upper-left corner of the rectangle, R and B specify the lower-right corner of the rectangle.
pre The variables X, Y, R and B must contain integer values.
post If a part of the specified rectangle is visible then true was assigned to the variable Output, else false was assigned to Output..

putPen(Pen)

func Set the current pen of the canvas. The current pen is used for drawing lines and for drawing of the lines of rectangles.
pre The variable Pen must refer to an instance of the class pen.
post The current pen of the canvas was set to the instance specified by the value of the variable Pen.

pen(Output)

func Get the current pen of the canvas.
pre TRUE.
post The current pen of the canvas was assigned to the variable Output. If the canvas has no current pen then no value is assigned to Output.

putBrush(Brush)

func Set the current brush of the canvas. The current brush is used for filling areas inside rectangles.
pre The variable Brush must refer to an instance of the class brush.
post The current brush of the canvas was set to the instance specified by the value of the variable Brush.

brush(Output)

func Get the current brush of the canvas.
pre TRUE.
post The current brush of the canvas was assigned to the variable Output. If the canvas has no current brush then no value is assigned to Output.

putFont(Height, Name, Bold, Italic, Strikethrough, Underline, clr(R, G, B))

func Set the properties of the font to use by the canvas for drawing text. The height, name, bold, italic, strikethrough, underline and color properties of the font can be specified. The height is in pixels.
pre The variable Height must contain an integer value, the name variable must be a string. The variables Bold, Italic, Strikethrough and Underline must have boolean values (true or false). The variables R, G and B must be integers in the range [0, 255].
post The properties of the font were changed according to the specified parameters.

putFont(Height, Name, Bold)

func Set the height, name and bold properties of the font to use by the canvas for drawing text. The height is in pixels.
pre The variable Height must contain an integer value, the name variable must be a string. The variable Bold must have the boolean value true or false.
post The properties of the font were changed according to the specified parameters.

putFont(Font)

func Set the current font of the canvas. The current font is used drawing text.
pre The variable Font must refer to an instance of the class font.
post The current font of the canvas was set to the instance specified by the value of the variable Font.

font(Output)

func Get the current font of the canvas.
pre TRUE.
post The current font of the canvas was assigned to the variable Output. If the canvas has no current font then no value is assigned to Output.

putTextAlignment(Hor, Ver)

func Set the horizontal and vertical text alignment, these alignments are used when text is drawn. The horizontal alignment must be one of the following values: left, center and right. The vertical alignment can be one of the values: top and bottom.
pre The variable Hor must contain one of the following values: left, center or right. The variable Ver must contain one of values: top or bottom.
post The horizontal and vertical alignment of text to draw was set.

leftText(Output)

func Determine if the text is left aligned.
pre TRUE.
post If the text is left aligned then true is assigned to Output, else false is assigned to Output.

centeredText(Output)

func Determine if the text is centered.
pre TRUE.
post If the text is centered then true is assigned to Output, else false is assigned to Output.

rightText(Output)

func Determine if the text is right aligned.
pre TRUE.
post If the text is right aligned then true is assigned to Output, else false is assigned to Output.

topText(Output)/1

func Determine if the top of the text is aligned to the specified coordinates.
pre TRUE.
post If the top of the text is aligned to the specified coordinates then true is assigned to Output, else false is assigned to Output.

bottomText(Output)

func Determine if the bottom of the text is aligned to the specified coordinates.
pre TRUE.
post If the bottom of the text is aligned to the specified coordinates then true is assigned to Output, else false is assigned to Output.

charHeight(Output)

func Determine the height of characters of the current font.
pre TRUE.
post The height of characters in pixels is assigned to Output.

averageCharWidth(Output)

func Determine the average width of a character, not all characters of a truetype font have the same width.
pre TRUE.
post The average width of a character from the current font is assigned to Output.

textExtent(String, point(X, Y))

func Determine the dimensions of a string if it is drawn on the canvas with the current font.
pre The variable String must contain a string value.
post The width and height of the area necessary for drawing the specified text are assigned to X and Y.

textRectangle(String, Width, point(X, Y))

func Determine the height of a rectangle if a string is drawn inside a specified number of pixels. The variable Width contains the maximum width of the rectangle.
pre The variable String must contain a string value and Width must contain an integer.
post The width and height of the area necessary for drawing the specified text are assigned to X and Y.

backgroundColor(R, G, B)

func Determine the current background color, this is the color used to fill the background area when text is being drawn on the canvas.
pre TRUE.
post The red, green and blue values of the color are assigned to the variables R, G and B.

putBackgroundColor(R, G, B)

func Set the current background color, this color is used to fill the background area when text is drawn.
pre The variables R, G and B must contain integer values which must be in the range [0, 255].
post The current background color of the canvas was changed to the color specified by the values of the variables.

textColor(R, G, B)

func Get the current text color, this color is used to draw the characters.
pre TRUE.
post The red, green and blue values of the current text color are assigned to the variables R, G and B.

putTextColor(R, G, B)

func Set the current text color, this color is used to draw the characters on the canvas.
pre The variables R, G and B must contain integer values which must be in the range [0, 255].
post The current text color of the canvas was changed to the color specified by the values of the variables.

drawStr(point(X, Y), String)

func Draw a string starting at the specified coordinate. How the coordinate is interpreted is determined by the text alignment, see putTextAlignment/2.
pre The variables X and Y must contain integer values and String must contain a string value.
post The text was drawn at the specified position.

drawStr(rectangle(X, Y, R, B), String)

func Draw a string starting inside the specified rectangle. How the coordinates are interpreted is determined by the text alignment, see putTextAlignment/2.
pre The variables X, Y, R and B must contain integer values and String must contain a string value.
post The text was drawn inside the specified rectangle.

drawGrayStr(point(X, Y), String)

func Draw a grayed string starting at the specified coordinate. How the coordinate is interpreted is determined by the text alignment, see putTextAlignment/2.
pre The variables X and Y must contain integer values and String must contain a string value.
post The grayed text was drawn at the specified position.

drawGrayStr(rectangle(X, Y, R, B), String)

func Draw a grayed string starting inside the specified rectangle. How the coordinates are interpreted is determined by the text alignment, see putTextAlignment/2.
pre The variables X, Y, R and B must contain integer values and String must contain a string value.
post The grayed text was drawn inside the specified rectangle.

drawString(point(X, Y), String, point(OutX, OutY))

func Draw a string starting at the specified coordinate. How the coordinate is interpreted is determined by the text alignment, see putTextAlignment/2.
pre The variables X and Y must contain integer values and String must contain a string value.
post The text was drawn at the specified position and the width and height of the area used for drawing the text are assigned to OutX and OutY.

drawString(rectangle(X, Y, R, B), String, point(OutX, OutY))

func Draw a string inside the specified rectangle. How the coordinates are interpreted is determined by the text alignment, see putTextAlignment/2.
pre The variables X, Y, R and B must contain integer values and String must contain a string value.
post The text was drawn inside the rectangle and the width and height of the area used for drawing the text are assigned to OutX and OutY.

drawGrayString(point(X, Y), String, point(OutX, OutY))

func Draw a grayed string starting at the specified coordinate. How the coordinate is interpreted is determined by the text alignment, see putTextAlignment/2.
pre The variables X and Y must contain integer values and String must contain a string value.
post The grayed text was drawn at the specified position and the width and height of the area used for drawing the text are assigned to OutX and OutY.

drawGrayString(rectangle(X, Y, R, B), String, point(OutX, OutY))

func Draw a grayed string inside the specified rectangle. How the coordinates are interpreted is determined by the text alignment, see putTextAlignment/2.
pre The variables X, Y, R and B must contain integer values and String must contain a string value.
post The grayed text was drawn inside the rectangle and the width and height of the area used for drawing the text are assigned to OutX and OutY.

drawStringEx(rectangle(X, Y, R, B), String, Draw, SingleLine, point(OutX, OutY))

func Draw a string inside the specified rectangle. How the coordinates are interpreted is determined by the text alignment, see putTextAlignment/2. The value of parameter Draw determines if the drawing is actually done and the parameter SingleLine determines if the text is drawn on a single line or if the text may be broken into several pieces in order to fit in the rectangle.
If the '&' character is encountered in the text then this character is not drawn but the character following the '&' character is underlined.
pre The variables X, Y, R and B must contain integer values and String must contain a string value. The variables Draw and SingleLine must both contain true or false.
post The text was drawn inside the rectangle and the width and height of the area used for drawing the text are assigned to OutX and OutY.

moveTo(point(X, Y))

func Move the current draw position for lines to the coordinate specified by X and Y. The lineTo/1 method draws a line from the current position to the it's coordinate.
pre The variables X and Y must contain integer values.
post The new current position of the canvas was set to the value of X and Y.

drawLine(point(X, Y))

func Draw a line from the current position to the coordinate specified by X and Y. The moveTo/1 method can adjust the current draw position of the canvas. The line is drawn using the current pen of the canvas.
pre The variables X and Y must contain integer values.
post A line was drawn from the current position to the position specified by the variables X and Y.

drawLine(point(X, Y), point(ToX, ToY))

func Draw a line from the point(X, Y) to point(ToX, ToY). The line is drawn using the current pen of the canvas.
pre The variables X, Y, ToX and ToY must contain integer values.
post A line was drawn from point(X, Y) to point(ToX, ToY) on the canvas.

drawColoredLine(point(X, Y), Width, R, G, B)

func Draw a colored line from the current position to the coordinate specified by X and Y. The moveTo/1 method can adjust the current draw position of the canvas. The line is drawn using the specified properties and the current pen of the canvas is not changed. The width of the line to draw is the value of the parameter Width. The color of the line is determined by the parameters R, G and B.
pre The variables X and Y must contain integer values. The Width, R, G, and B variables must contain integers. The values of R, G, and B must be in the range [0, 255].
post A colored line was drawn from the current position to the position specified by the variables X and Y. The current pen of the canvas was not changed.

drawColoredLine(point(X, Y), point(ToX, ToY), Width, R, G, B)

func Draw a colored line from the point(X, Y) to point(ToX, ToY).  The line is drawn using the specified properties and the current pen of the canvas is not changed. The width of the line to draw is the value of the parameter Width. The color of the line is determined by the parameters R, G and B.
pre The variables X, Y, ToX and ToY must contain integer values. The Width, R, G, and B variables must contain integers. The values of R, G, and B must be in the range [0, 255].
post A colored line was drawn from point(X, Y) to point(ToX, ToY) on the canvas. The current pen of the canvas was not changed.

drawPoint(point(X, Y))

func Draw a single point on the canvas. The point is drawn using the current pen of the canvas.
pre The variables X and Y must contain integer values.
post A point was drawn at the specified position.

drawFillRect(rectangle(X, Y, R, B))

func Draw a filled rectangle on the canvas. The lines of the rectangle are drawn with the current pen and the inside of the rectangle is filled with the current brush.
pre The variables X, Y, R and B must contain integer values.
post A filled rectangle was drawn.

drawFillRect(rectangle(X, Y, R, B), UsePen)

func Draw a filled rectangle on the canvas. The lines of the rectangle are drawn with the current pen if the value of the parameter UsePen is true and the inside of the rectangle is filled with the current brush. If UsePen is false then no pen is used to draw the lines of the rectangle.
pre The variables X, Y, R and B must contain integer values. The parameter UsePen must contain a boolean value.
post A filled rectangle was drawn.

drawFillRect(rectangle(X, Y, R, B), UsePen, ColorR, ColorG, ColorB)

func Draw a filled rectangle on the canvas. The lines of the rectangle are drawn with the current pen if the value of the parameter UsePen is true and the inside of the rectangle is filled with a brush of the color specified by the parameters ColorR, ColorG, ColorB. If UsePen is false then no pen is used to draw the lines of the rectangle. The current brush of the canvas is not changed.
pre The variables X, Y, R and B must contain integer values. The parameter UsePen must contain a boolean value. The values of ColorR, ColorG, and ColorB must be integers in the range [0, 255].
post A filled rectangle was drawn.

drawInvertRect(rectangle(X, Y, R, B))

func Draw an inverted filled rectangle on the canvas. The lines of the rectangle are drawn with the current pen and the inside of the rectangle is filled with the current brush.
pre The variables X, Y, R and B must contain integer values.
post A inverted filled rectangle was drawn.

drawRect(rectangle(X, Y, R, B))

func Draw a rectangle on the canvas. The lines of the rectangle are drawn with the current pen.
pre The variables X, Y, R and B must contain integer values.
post A rectangle was drawn.

drawFocusRect(rectangle(X, Y, R, B))

func Draw a focus rectangle on the canvas. The same rectangle is drawn as if it is a control that has the focus.
pre The variables X, Y, R and B must contain integer values.
post A focus rectangle was drawn.

drawEllipse(rectangle(X, Y, R, B))

func An ellipse is drawn inside the specified rectangle. The ellipse is drawn using the current pen.
pre The variables X, Y, R and B must contain integer values.
post A ellipse was drawn inside the rectangle.

drawIcon(point(X, Y), Icon)

func Draw an icon at the specified positions, the coordinate determines the position of the upper-left corner of the icon.
pre The variables X and Y must contain integer values. The variable Icon must refer to an instance of the class icon.
post An icon is drawn on the canvas.

drawImage(point(X, Y), Image)

func Draw an image at the specified positions, the coordinate determines the position of the upper-left corner of the image.
pre The variables X and Y must contain integer values. The variable Image must refer to an instance of the class image.
post An image is drawn on the canvas.

drawImage(rectangle(X, Y, R, B), Image)

func Draw an image inside the rectangle. The image is resized so that it fits inside the destination rectangle.
pre The variables X, Y, R and B must contain integer values. The variable Image must refer to an instance of the class image.
post An image is drawn inside the rectangle on the canvas.

drawImage(point(X, Y), Image, point(FromX, FromY), point(NumX, NumY))

func Draw an image at the specified point(X, Y), the point(FromX, FromY) determines from which pixel on the image is drawn and point(NumX, NumY) determine how many pixels are drawn of the image in the X and Y directions.
pre The variables X, Y, FromX, FromY, NumX and NumY must contain integer values. The variable Image must refer to an instance of the class image.
post An image or part of it was drawn on the canvas.

drawImageTiled(rectangle(X, Y, R, B), Image)

func Tile an image, the specified rectangle is completely filled.
pre The variables X, Y, R, and B must contain integer values. The variable Image must refer to an instance of the class image.
post An image was tiled so the specified rectangle was completely filled.

draw3DBorder(rectangle(X, Y, R, B), Lowered)

func Draw a 3D border along the edges of the specified rectangle. If Lowered is true the rectangle looks like a lowered rectangle, else a raised rectangle is drawn.
pre The variables X, Y, R, and B must contain integer values. The variable Lowered must contain true or false.
post A 3D border was drawn on the canvas.

draw3DBorder(Window, Lowered)

func Draw a 3D border around the specified Window. If Lowered is true the rectangle looks like a lowered rectangle, else a raised rectangle is drawn.
pre The variable Window must refer to a window instance. The variable Lowered must contain true or false.
post A 3D border was drawn on the canvas around the window.

draw3DLine(point(X, Y), point(ToX, ToY), Lowered, Left, Top, Right, Bottom)

func Draw a single 3D line. If Lowered is true the line looks lowered, else it looks raised. If Top is true the top line of a 3D rectangle is drawn, if Left is true the left side of a 3D rectangle is drawn, etc..
pre The variables X, Y, ToX, and ToY must contain integer values. The variables Lowered, Top, Left, Bottom, Right must contain true or false.
post A 3D line was drawn from point(X, Y) to point(ToX, ToY) on the canvas.