UserGuide

Desktop Canvas

From Xojo Documentation

A Canvas control can be used to display a picture or image from a file or graphics drawn in code. The Canvas control has access to the drawing tools belonging to the Graphics class; with these tools you can programmatically draw objects within the Canvas. If your app requires a type of control that is not built-in, you can use a Canvas control and the Graphics drawing commands to draw the controls you need.

The Canvas control can get the focus, so you can emulate any other type of control that you would like to get the focus.

Canvas controls can be used to create extremely sophisticated controls, such as the Layout Editor in Xojo itself.

Refer to Canvas in Reference Guide for details on all its events, properties and methods.

Below is a list of commonly used events, properties and methods.

Canvas Library Icon

Events

Paint

The Paint event is called when the Canvas needs to redraw itself. This could be called automatically by the operating system or by a call to Refresh or Invalidate. Use the supplied graphics object (g) for all Canvas drawing.

Properties

AcceptFocus

Since Canvas controls are often used to create custom controls, you use this property if you want the Canvas to be able to get focus.

AcceptTabs

Normally tabs move the focus to the next control. If you want the Canvas to instead trigger the KeyDown event, set AcceptTabs to True.

Backdrop

Specifies the image that is used as the background for the Canvas. You will get better performance and reliability by drawing your image in the Paint event rather than using Backdrop.

DoubleBuffer

Indicates that all Canvas drawing should be double-buffered in order to reduce flicker. This property is only meaningful on Windows since macOS and Linux both double-buffer automatically in the OS. When DoubleBuffer is True, you should also set EraseBackground to False for best performance.

EraseBackground

Indicates whether the entire Canvas should be erased before it is redrawn. This property is only meaningful on Windows. Setting it to False can improve performance.

UseFocusRing

Since Canvas controls are often used to create custom controls, you use this property if you want the Canvas to have a focus ring around it when it has focus (macOS only).

Methods

Invalidate

Call this method to tell the operating system to redraw the Canvas when it is doing other redrawing. You can optionally specify a parameter to erase the background before redrawing.

Refresh

Call this method to redraw the Canvas as soon as possible. You can optionally specify a parameter to erase the background before redrawing. Calling this method frequently can slow your app. In most cases it is better to call Invalidate instead.

RefreshRect

Immediately redraws only the portion of the Canvas specified by the supplied X, Y, Width and Height coordinates. You can optionally specify a parameter to erase the background before redrawing.

Scroll

Use the Scroll method to scroll the contents of the Canvas.

Handling Focus

Since the Canvas control can get the focus, you can use it to create custom controls of any type that can get the focus. For example, you can use the Canvas to simulate controls that don’t get the focus on macOS, such as buttons and pop-up menus. Unlike other controls that can get the focus, the ability of a Canvas to accept the focus is turned off by default. In order for a Canvas control to receive the focus, you must set the AcceptFocus property to True. This can be done either in code or in the Inspector. The Canvas control also has an AcceptTabs property that indicates whether pressing Tab selects the next control in the window or sends the Tab keystroke to the Canvas control for processing. If AcceptTabs is off, pressing Tab causes the Canvas control to lose the focus. The next control in the entry order gets the focus. If AcceptTabs is on, the Canvas control detects the Tab key as if it were any other key and allows your code to detect and respond to the Tab key.

If the AcceptFocus and UseFocusRing properties are set to True, the Canvas control indicates focus on macOS by drawing a border around the control.

On Windows and Linux, the UseFocusRing property has no effect. There is no visual indicator of focus that works automatically. However, it is easy to simulate a focus ring by manually drawing it in the Paint event handler. See the Canvas control entry in the Language Reference for an example of how to do this.

Usage

In most situations you will use the Paint event handler to draw something in the Canvas. The paint event handler provides you with a parameter containing the Graphics object that you can draw into. To draw a picture in your project:

g.DrawPicture(0, 0, MyPicture)

To do animation, you use a Timer that tells the Canvas to update periodically. This code is in a Timer set to update every 200ms (1/8 second) and it increases a property for the X position of a drawing:

X = X + 10 // X is a property
Canvas1.Invalidate(False)

The Canvas paint event handler just draws a simple rectangle at the X position. The result is the rectangle will march across the canvas:

If X > g.Width Then X = 0
g.ForeColor = &cff0000
g.FillRect(X, 30, 50, 50)

Drawing Objects in the Canvas

Drawing Objects in Canvas Example

You can use a Canvas to do powerful things such as draw objects, move them, remove them and more.

The general technique to do this is to create your own class, add a Draw method to it and then pass in the Graphics parameter from the Canvas paint event. The class uses this to draw itself to the Canvas.

You can then have an array of class objects and to draw them the Paint event in your Canvas just calls the Draw method on each one like this:

For Each co As CanvasObject In mCanvasObjects
co.Draw(g)
Next

The Draw method can draw whatever you want. For example, this code draws a picture that is assigned to the object and optionally draws a selection rectangle around it if the object's Selected property is True:

// Draws the object on the canvas.
g.DrawPicture(Image, Left, Top)

If Selected Then
Const kBorder = 2
// Draw selection rectangel around the image
g.PenHeight = kBorder
g.PenWidth = kBorder
g.ForeColor = TextColor
g.DrawRect(Left - kBorder, Top - kBorder, Width + kBorder * 2, Height + kBorder * 2)
End If

This example demonstrates how to do all these things. It has a large Canvas on the window with several buttons that let you add and manage the objects on the Canvas: Examples/Graphics and Multimedia/ObjectsInCanvas

Example Projects

Graph Test Example

Xojo includes many example projects that demonstrate the use of Canvas:

  • Examples/Graphics and Multimedia/CanvasAreas
  • Examples/Graphics and Multimedia/CanvasDragRect
  • Examples/Graphics and Multimedia/CanvasDragDrag
  • Examples/Graphics and Multimedia/CanvasDrawString
  • Examples/Graphics and Multimedia/CanvasScrolling
  • Examples/Graphics and Multimedia/CanvasZoom
  • Examples/Graphics and Multimedia/Dice
  • Examples/Graphics and Multimedia/DrawingWithThreads
  • Examples/Graphics and Multimedia/Fire
  • Examples/Graphics and Multimedia/FlowChart
  • Examples/Graphics and Multimedia/GradientExample
  • Examples/Graphics and Multimedia/GraphicalClock
  • Examples/Graphics and Multimedia/GraphTest
  • Examples/Graphics and Multimedia/GridLockExample
  • Examples/Graphics and Multimedia/Pinball
  • Examples/Graphics and Multimedia/Sparkler
  • Examples/Graphics and Multimedia/WaveLetter
SpaceRocks Game

In addition there are several example games that make use of Canvas:

  • Examples/Games/2K
  • Examples/Games/BlockAttack
  • Examples/Games/Combat
  • Examples/Games/FallingBlocks
  • Examples/Games/Jewels
  • Examples/Games/Sliders
  • Examples/Games/SpaceRocks

See Also

Canvas, Graphics class; UserGuide:Windows UI Guidelines, UserGuide:Updating Code That Used the Graphics Property topics