Desktop Canvas
From Xojo Documentation
Contents
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.
Events
- 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
- 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.
- Normally tabs move the focus to the next control. If you want the Canvas to instead trigger the KeyDown event, set AcceptTabs to True.
- 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.
- 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
- 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.
- Call this method to redraw the entire Canvas or just a portion 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.
- 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 AllowFocusRing property to True. This can be done either in code or in the Inspector. The Canvas control also has an AllowTabs 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 AllowTabs is off, pressing Tab causes the Canvas control to lose the focus. The next control in the entry order gets the focus. If AllowTabs 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 AllowFocus and AllFocusRing properties are set to True, the Canvas control indicates focus on macOS by drawing a border around the control.
On Windows and Linux, the AllowFocusRing 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:
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:
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:
Drawing Objects in the Canvas
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:
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:
g.DrawPicture(Image, Left, Top)
If Selected Then
Const kBorder = 2
// Draw selection rectangel around the image
g.PenSize = kBorder
g.DrawingColor = TextColor
g.DrawRectangle(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
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
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
Canvas-related videos:
See Also
Canvas, Graphics class; UserGuide:Windows UI Guidelines, UserGuide:Updating Code That Used the Graphics Property topics