To draw onto a canvas, get its device context via get-dc. There are two basic approaches to updating a canvas:

• Drawing normally occurs during the canvas’s on-paint callback. The canvas% class supports a paint-callback initialization argument to be called from the default on-paint method.

  A canvas’s on-paint method is called automatically as an event when the windowing system determines that the canvas must be updated, such as when the canvas is first shown or when it is resized. Use the refresh method to explicitly trigger an on-paint call from the windowing system. (Multiple refresh requests before on-paint can be called are coaleced into a single on-paint call.)

  Before the windowing system calls on-paint, it may erase the canvas’s background (see erase), depending on the style of the canvas (e.g., as determined by the style initialization argument for canvas%). Even when the canvas’s style suppresses explicit clearing of the canvas, a canvas may be erased by the windowing system due to window-moving and -resizing operations. For a transparent canvas, “erased” means that the canvas’s parent window shows through.

• Drawing can also occur at any time outside an on-paint call from the windowing system, including from threads other than the handler thread of the canvas’s eventspace. Drawing outside an on-paint callback from the system is transient in the sense that windowing activity can erase the canvas, but the drawing is persistent as long as no windowing refresh is needed.

  Calling an on-paint method directly is the same as drawing outside an on-paint callback from the windowing system. For a canvas%, use refresh-now to force an immediate update of the canvas’s content that is otherwise analogous to queueing an update with refresh.

Drawing to a canvas’s drawing context actually renders into an offscreen buffer. The buffer is automatically flushed to the screen asynchronously, explicitly via the flush method, or explicitly via flush-display—unless flushing has been disabled for the canvas. The suspend-flush method suspends flushing for a canvas until a matching resume-flush calls; calls to suspend-flush and resume-flush can be nested, in which case flushing is suspended until the outermost suspend-flush is balanced by a resume-flush. An on-paint call from the windowing system is implicitly wrapped with suspend-flush and resume-flush calls, as is a call to a paint procedure by refresh-now.

In the case of a transparent canvas, line and text smoothing can depend on the window that serves as the canvas’s background. For example, smoothing may color pixels differently depending on whether the target context is white or gray. Background-sensitive smoothing is supported only if a relatively small number of drawing commands are recorded in the canvas’s offscreen buffer, however.

When tab-focus is enabled for a canvas% object, Tab, arrow, Enter, and Escape keyboard events are consumed by a frame’s default on-traverse-char method. (In addition, a dialog’s default method consumes Escape key events.) Otherwise, on-traverse-char allows the keyboard events to be propagated to the canvas.

For an editor-canvas% object, handling of Tab, arrow, Enter, and Escape keyboard events is determined by the allow-tab-exit method.

The result is #f if the canvas was created with the 'transparent style, otherwise it is always a color% object.

For example, when a canvas on Mac OS resides on a Retina display, it has a backing scale of 2, and so the results from get-scaled-client-size will be twice as large as results from get-client-size. If the same canvas’s frame is dragged to a non-Retina screen, its backing scale can change to 1, in which case get-scaled-client-size and get-client-size will produce the same value. Whether a canvas’s backing scale can change depends on the platform.

The size reported by get-scaled-client-size may match a viewport size for OpenGL drawing in canvas% instance with the 'gl style. On Mac OS, however, the viewport will match the scaled size unless the canvas is created with a gl-config% specification that is adjusted to high-resolution mode via set-hires-mode. See also get-gl-client-size in canvas%.

Added in version 1.13 of package gui-lib.

The minimum height is ignored when it is smaller than the canvas’s graphical minimum height. See Geometry Management for more information.

The minimum width is ignored when it is smaller than the canvas’s graphical minimum width. See Geometry Management for more information.

Default implementation: Does nothing.

Default implementation: Does nothing.

When on-paint is called in response to a system expose event and only a portion of the canvas is newly exposed, any drawing operations performed by on-paint are clipped to the newly-exposed region; however, the clipping region as reported by get-clipping-region does not change.

Default implementation: Does nothing.

See also accept-tab-focus and on-traverse-char in top-level-window<%> .

Default implementation: Does nothing.

If the canvas was created with the 'transparent style, an exn:fail:contract exception is raised.