Reference for the Mosaic class Graphics::Canvas

Graphics::Canvas
AttachBitmap()
BeginDrawing()
CopyBitmap()
DetachBitmap()
DrawBitmapFrame()
DrawBorder()
DrawLine()
DrawText()
EndDrawing()
FillPath()
FillRectangle()
GetBitmap()
ScaleBitmap()
StrokePath()
TileBitmap()
WarpBitmap()
Resources::Bitmap
FrameDelay
FrameSize
NoOfFrames
Core::Resource

SEE ALSO

Using Canvas object.

The class Graphics::Canvas provides a drawing destination for all graphics operations. It is like a bitmap which can be modified by calling the methods of this canvas class. For example, the method FillRectangle() fills an area of the canvas with a color or a color gradient. More sophisticated methods allow text output, scaling or 2D/3D warping of images. The functionality of this canvas class corresponds to the of the underlying Graphics Engine.

Since the canvas inherits from the Resources::Bitmap class it can be handled as an ordinary bitmap. It can e.g. be assigned to a Views::Image view and thus be displayed on the screen.

method Graphics::Canvas AttachBitmap
(
arg handle aBitmap
);

The method AttachBitmap() exists for the integration purpose with the underlying target system. You will never need to invoke this method directly from your GUI application. The method is invoked at the beginning of the screen update.

The method connects the canvas object with the framebuffer.

method void BeginDrawing
(
arg int32 aDstFrameNr
);

The method BeginDrawing() informs the canvas object about the begin of drawing operations. In the parameter aDstFrameNr specify the number of the desired bitmap frame where to perform the drawing operations. The first frame has the number 0, the second 1, and so forth. How many frames are available is determined by the property NoOfFrames.

When the drawing operations are finished, the method EndDrawing() should be called.

method void CopyBitmap
(
arg rect aClip,
arg Resources::Bitmap aBitmap,
arg int32 aFrameNr,
arg rect aDstRect,
arg point aSrcPos,
arg color aColorTL,
arg color aColorTR,
arg color aColorBR,
arg color aColorBL,
arg bool aBlend
);

The method CopyBitmap() copies an area of a aBitmap into the canvas. The bitmap is specified in the parameter aBitmap. In case of a multi-frame bitmap the desired frame can be selected in the parameter aFrameNr.

The area to copy the bitmap is determined by the parameter aDstRect. The optional aSrcPos parameter determines a displacement of the bitmap within this aDstRect area. The parameters aColorTL, aColorTR, aColorBL, aColorBR determine the colors or opacities at the corresponding corners of the aDstRect area.

The parameter aClip limits the drawing operation. Pixel lying outside this area remain unchanged. The last aBlend parameter controls the mode how drawn pixel are combined with the pixel already existing in the destination bitmap. If aBlend is 'true', the drawn pixel are alpha-blended with the background, otherwise the drawn pixel will overwrite the old content.

method Graphics::Canvas DetachBitmap();

The method DetachBitmap() exists for the integration purpose with the underlying target system. You will never need to invoke this method directly from your GUI application. The method is invoked after the screen update is finished and the canvas object should be detached from the framebuffer.

method void DrawBitmapFrame
(
arg rect aClip,
arg Resources::Bitmap aBitmap,
arg int32 aFrameNr,
arg rect aDstRect,
arg Graphics::Edges aEdges,
arg color aColorTL,
arg color aColorTR,
arg color aColorBR,
arg color aColorBL,
arg bool aBlend
);

The method DrawBitmapFrame() draws a free scalable frame by composing it of bitmap segments. These segments are used to draw the frame's corners, to fill its edges and to fill its interior area. The bitmap has thus to contain nine equal segments arranged in three rows and three columns. The top-left segment e.g. is used to draw the top-left corner of the frame. In contrast, the top-middle segment corresponds to the frame's top edge. If the edge is wider than the segment, multiple copies of the segment are used to fill the entire edge. In this manner the entire frame is composed by simply copying bitmap segments.

The bitmap is specified in the parameter aBitmap. In case of a multi-frame bitmap the desired frame can be selected in the parameter aFrameNr. The resulting size of the drawn frame is specified by aDstRect parameter. The parameter aEdges control which edges are drawn and which are omitted. Optionally the copied pixel can be modulated by a color gradient specified by the four parameters aColorTL .. aColorBL.

An additional clipping area aClip limits the operation. All pixel lying outside this area will not be drawn. The last aBlend parameter controls the mode how drawn pixel are combined with the pixel already existing in the destination bitmap. If aBlend is 'true', the drawn pixel are alpha-blended with the background, otherwise the drawn pixel will overwrite the old content.

method void DrawBorder
(
arg rect aClip,
arg rect aDstRect,
arg int32 aEdgeWidth,
arg color aColorTL,
arg color aColorTR,
arg color aColorBR,
arg color aColorBL,
arg bool aBlend
);

The method DrawBorder() draws a hollow rectangle in an area of canvas. The area is determined by the parameter aDstRect. The parameter aEdgeWidth determine the width of the border's edge. The parameters aColorTL, aColorTR, aColorBL, aColorBR determine the colors at the corresponding corners of the aDstRect area.

The parameter aClip limits the drawing operation. Pixel lying outside this area remain unchanged. The last aBlend parameter controls the mode how drawn pixel are combined with the pixel already existing in the destination bitmap. If aBlend is 'true', the drawn pixel are alpha-blended with the background, otherwise the drawn pixel will overwrite the old content.

method void DrawLine
(
arg rect aClip,
arg point aDstPos1,
arg point aDstPos2,
arg color aColor1,
arg color aColor2,
arg bool aBlend
);

The method DrawLine() draws a line into the canvas. The line will be drawn from the aDstPos1 point to the aDstPos2 point with the given colors aColor1 and aColor2.

The parameter aClip limits the drawing operation. Pixel lying outside this area remain unchanged. The last aBlend parameter controls the mode how drawn pixel are combined with the pixel already existing in the destination bitmap. If aBlend is 'true', the drawn pixel are alpha-blended with the background, otherwise the drawn pixel will overwrite the old content.

method void DrawText
(
arg rect aClip,
arg Resources::Font aFont,
arg string aString,
arg int32 aOffset,
arg int32 aCount,
arg rect aDstRect,
arg point aSrcPos,
arg int32 aMinWidth,
arg Views::Orientation aOrientation,
arg color aColorTL,
arg color aColorTR,
arg color aColorBR,
arg color aColorBL,
arg bool aBlend
);

The method DrawText() draws the text row passed in the parameter aString into the canvas. The font to draw the text is passed in the parameter aFont. The parameter aOffset determines within aString the sign to start the drawing operation. If aOffset is zero, the operation starts with the first sign. The parameter aCount determines the max. number of following sigs to draw. If aCount is -1, all signs until the end of the string are drawn.

The area to draw the text is determined by the parameter aDstRect. The parameter aOrientation controls the rotation of the text. The parameter aSrcPos determines the base line position of the text relative to a corner of aDstRect, which by taking in account the specified text orientation serves as the origin for the draw operation. For example, if the parameter aOrientation is Views::Orientation.Rotated_270, the text is drawn aSrcPos pixel relative to the bottom-right corner of aDstRect. The parameter aMinWidth determines the min. width in pixel of the drawn text row regardless of the specified rotation. If necessary the space signs within the text will be stretched to fill this area. The parameters aColorTL, aColorTR, aColorBL, aColorBR determine the colors at the corresponding corners of the aDstRect area.

The parameter aClip limits the drawing operation. Pixel lying outside this area remain unchanged. The last aBlend parameter controls the mode how drawn pixel are combined with the pixel already existing in the destination bitmap. If aBlend is 'true', the drawn pixel are alpha-blended with the background, otherwise the drawn pixel will overwrite the old content.

method void EndDrawing();

The method EndDrawing() informs the canvas object about the end of drawing operations. Thereupon all still pending operations are flushed and all associated views notified to update their appearance. To begin drawing operations use the method BeginDrawing().

method void FillPath
(
arg rect aClip,
arg Graphics::Path aPath,
arg rect aDstRect,
arg bool aFlipY,
arg point aOffset,
arg color aColorTL,
arg color aColorTR,
arg color aColorBR,
arg color aColorBL,
arg bool aBlend,
arg bool aAntialiased,
arg Graphics::FillRule aFillRule
);

The method FillPath() fills within the rectangular area aDstRect of canvas a polygon determined by data stored in the Graphics::Path object aPath. All path coordinates are assumed as being relative to the top-left corner of the aDstRect area, or if the parameter aFlipY is 'true', relative to the bottom-left corner. With the parameter aFlipY equal 'true' the path coordinates are additionally mirrored vertically causing the positive Y-axis to point upwards. With the parameter aOffset the origin of the path coordinate system can be moved within aDstRect. Accordingly modifying this value scrolls the displayed path content.

The parameters aColorTL, aColorTR, aColorBL, aColorBR determine the colors at the corresponding corners of the aDstRect area. If the parameter aAntialiased is 'true', the method applies antialiasing while rasterizing the path pixel. The parameter aFillRule controls the fill algorithm how it treats nested polygon areas. The possible values are specified in Graphics::FillRule.

The parameter aClip limits the drawing operation. Pixel lying outside this area remain unchanged. The aBlend parameter controls the mode how drawn pixel are combined with the pixel already existing in the destination bitmap. If aBlend is 'true', the drawn pixel are alpha-blended with the background, otherwise the drawn pixel will overwrite the old content.

method void FillRectangle
(
arg rect aClip,
arg rect aDstRect,
arg color aColorTL,
arg color aColorTR,
arg color aColorBR,
arg color aColorBL,
arg bool aBlend
);

The method FillRectangle() fills an area of canvas. The area is determined by the parameter aDstRect. The parameters aColorTL, aColorTR, aColorBL, aColorBR determine the colors at the corresponding corners of the aDstRect area.

The parameter aClip limits the drawing operation. Pixel lying outside this area remain unchanged. The last aBlend parameter controls the mode how drawn pixel are combined with the pixel already existing in the destination bitmap. If aBlend is 'true', the drawn pixel are alpha-blended with the background, otherwise the drawn pixel will overwrite the old content.

method handle GetBitmap();

The method GetBitmap() returns a handle identifying the Canvas bitmap. Knowing this bitmap, you can implement native code to directly invoke Graphics Engine drawing functions with the Canvas as drawing destination.

method void ScaleBitmap
(
arg rect aClip,
arg Resources::Bitmap aBitmap,
arg int32 aFrameNr,
arg rect aDstRect,
arg rect aSrcRect,
arg color aColorTL,
arg color aColorTR,
arg color aColorBR,
arg color aColorBL,
arg bool aBlend,
arg bool aFilter
);

The method ScaleBitmap() copies and scales an area of a aBitmap into the canvas. The bitmap is specified in the parameter aBitmap and the desired area to copy in aSrcRect. In case of a multi-frame bitmap the desired frame can be selected in the parameter aFrameNr.

The destination area in canvas is determined by the parameter aDstRect. The parameters aColorTL, aColorTR, aColorBL, aColorBR determine the colors or opacities at the corresponding corners of the aDstRect area.

The parameter aClip limits the drawing operation. Pixel lying outside this area remain unchanged. The aBlend parameter controls the mode how drawn pixel are combined with the pixel already existing in the destination bitmap. If aBlend is 'true', the drawn pixel are alpha-blended with the background, otherwise the drawn pixel will overwrite the old content. The last parameter aFilter controls the bi-linear filter. If aFilter is 'true', the source bitmap pixel will be bi-linear filtered in order to get better output.

method void StrokePath
(
arg rect aClip,
arg Graphics::Path aPath,
arg rect aDstRect,
arg bool aFlipY,
arg point aOffset,
arg float aWidth,
arg Graphics::PathCap aStartCapStyle,
arg Graphics::PathCap aEndCapStyle,
arg Graphics::PathJoin aJoinStyle,
arg float aMiterLimit,
arg color aColorTL,
arg color aColorTR,
arg color aColorBR,
arg color aColorBL,
arg bool aBlend,
arg bool aAntialiased
);

The method StrokePath() strokes within the rectangular area aDstRect of canvas a path determined by data stored in the Graphics::Path object aPath. All path coordinates are assumed as being relative to the top-left corner of the aDstRect area, or if the parameter aFlipY is 'true', relative to the bottom-left corner. With the parameter aFlipY equal 'true' the path coordinates are mirrored vertically causing the positive Y-axis to point upwards. With the parameter aOffset the origin of the path coordinate system can be moved within aDstRect. Accordingly modifying this value scrolls the displayed path content.

The thickness of the path is determined by the parameter aWidth and is expressed in pixel. The parameters aStartCapStyle and aEndCapStyle determine how the start/end position of the path are displayed. The possible values are specified in Graphics::PathCap. Furthermore the parameter aJoinStyle controls how the line segments of the path are connected together. Here the possible values are specified in Graphics::PathJoin. Please note, if aJoinStyle is Graphics::PathJoin.Miter, the additional parameter aMiterLimit determines the max. ratio between the length of the miter and the half of the path thickness (aWidth / 2). If this limit is exceeded, the affected corner is joined with an ordinary bevel (Graphics::PathJoin.Bevel) instead of miter.

The parameters aColorTL, aColorTR, aColorBL, aColorBR determine the colors at the corresponding corners of the aDstRect area. If the parameter aAntialiased is 'true', the method applies antialiasing while rasterizing the path pixel.

The parameter aClip limits the drawing operation. Pixel lying outside this area remain unchanged. The aBlend parameter controls the mode how drawn pixel are combined with the pixel already existing in the destination bitmap. If aBlend is 'true', the drawn pixel are alpha-blended with the background, otherwise the drawn pixel will overwrite the old content.

method void TileBitmap
(
arg rect aClip,
arg Resources::Bitmap aBitmap,
arg int32 aFrameNr,
arg rect aDstRect,
arg rect aSrcRect,
arg point aSrcPos,
arg color aColorTL,
arg color aColorTR,
arg color aColorBR,
arg color aColorBL,
arg bool aBlend
);

The method TileBitmap() fills an area of the canvas with multiple copies of an area of the bitmap. The bitmap is specified in the parameter aBitmap and the desired area to copy in aSrcRect. In case of a multi-frame bitmap the desired frame can be selected in the parameter aFrameNr.

The area to fill in canvas is determined by the parameter aDstRect. The optional aSrcPos parameter determines a displacement of the bitmap tiles within this aDstRect area. The parameters aColorTL, aColorTR, aColorBL, aColorBR determine the colors or opacities at the corresponding corners of the aDstRect area.

The parameter aClip limits the drawing operation. Pixel lying outside this area remain unchanged. The last aBlend parameter controls the mode how drawn pixel are combined with the pixel already existing in the destination bitmap. If aBlend is 'true', the drawn pixel are alpha-blended with the background, otherwise the drawn pixel will overwrite the old content.

method void WarpBitmap
(
arg rect aClip,
arg Resources::Bitmap aBitmap,
arg int32 aFrameNr,
arg float aDstX1,
arg float aDstY1,
arg float aDstW1,
arg float aDstX2,
arg float aDstY2,
arg float aDstW2,
arg float aDstX3,
arg float aDstY3,
arg float aDstW3,
arg float aDstX4,
arg float aDstY4,
arg float aDstW4,
arg rect aSrcRect,
arg color aColor1,
arg color aColor2,
arg color aColor3,
arg color aColor4,
arg bool aBlend,
arg bool aFilter
);

The method WarpBitmap() performs the projection of a rectangular source bitmap area onto a four corner polygon within the destination canvas. The bitmap is specified in the parameter aBitmap and the desired area to copy in aSrcRect. In case of a multi-frame bitmap the desired frame can be selected in the parameter aFrameNr.

The destination polygon is determined by the coordinates aX1,aY1 .. aX4,aY4. The coefficients aW1 .. aW4 are responsible for the perspective distortion. The parameters aColor1, aColor2, aColor3, aColor4 determine the colors or opacities at the corresponding corners of the polygon area. The parameter aClip limits the drawing operation. Pixel lying outside this area remain unchanged. The aBlend parameter controls the mode how drawn pixel are combined with the pixel already existing in the destination bitmap. If aBlend is 'true', the drawn pixel are alpha-blended with the background, otherwise the drawn pixel will overwrite the old content. The last parameter aFilter controls the bi-linear filter. If aFilter is 'true', the source bitmap pixel will be bi-linear filtered in order to get better output.