The canvas type

Purpose

A canvas is a general purpose region object. It is a gateway for the application programmer to have direct access to all events which occur in it, for example to be used as the drawing area in a graphics program. This definitely is the object where you can receive the most events through the action routines.

A canvas doesn't know what is in it. The contents have to be drawn using a user supplied routine. Therefore the size of the canvas has to be given explicitly. To allow for scrolling etc., the canvas also has an origin, which is the coordinate at the top left corner of the canvas. The origin is there only for information (to be used by the action routines) and is not used by the canvas type itself.

A canvas can react to the events which can occur inside it. A user supplied routine can be called when the pointer enters or exits the canvas, when a timeout occurs inside the canvas, or when the pointer is moved. Other events which can be reacted upon are a HIT, DO, or dragging (see below). An action routine can also be called when the canvas is resized.

Dragging is a HIT or a DO which lasts longer than is normal - usually whilst moving the pointer, i.e. keeping the mouse button pressed whilst moving the mouse. A difference is made between dragging with a HIT and dragging with a DO. An event is generated both when the dragging starts and when it ends, and you can set action routines which will return to SBasic with that event. During dragging, the pointer is not allowed to move outside the canvas region. It the user does attempt to move outside, the pointer position will be adjusted to stay inside the canvas. This can also be trapped, for example to scroll the canvas automatically when it occurs.

The Type Word

When creating this type of object, the type parameter is:

PW('TYPE_CANVAS')

The tags

Here are the tags for this object. As usual, change tags are also used when creating the object, but query tags are only used for queries.
The change (and creation) tags
PW('CANVAS_POINTER')
Set the pointer which should be used inside the canvas. The parameter is a sprite (the SBasic interface has no way yet to define such a sprite, you can use any sprite generated, e.g. by QPTR).
PW('CANVAS_ACTION_REDRAW')
Set the routine which is used to (re-) draw the canvas. The parameter should be RDRW_ROUTINE. The WindowSub will be set when the redraw routine is called. All the necessary information for redrawing the canvas is supplied in the CanvasInfo parameter (see below).
PW('CANVAS_ACTION_EXIT')
Set the exit routine for the canvas. The parameter should be EXIT_ROUTINE. This routine is called when the pointer exits the area covered by the canvas. It can for example be used to remove the border around something in the canvas.
PW('CANVAS_ACTION_HIT')
Set the routine which should be called when a HIT occurs inside the canvas. The parameter should be HIT_ROUTINE.
PW('CANVAS_ACTION_DO')
Set the routine which should be called when a DO occurs inside the canvas. The parameter should be DO_ROUTINE.
PW('CANVAS_ACTION_MOVE')
Set the routine which should be called when a MOVE occurs inside the canvas. The parameter should be MOVE_ROUTINE.
PW('CANVAS_ACTION_SCALE')
Set the routine which should be called when a the canvas object is scaled. This can be used to extract some information from the size of the canvas. The parameter should be SCALE_ROUTINE.
PW('CANVAS_TIMEOUT')
Set the timeout value for reading the pointer inside the canvas. The parameter should be a number, the timeout. This can be used for example to draw a preview of an action. The TIMEOUT event is only triggered when no other event has occured during the duration set with this tag! (After each other event, the timeout count starts afresh).
PW('CANVAS_SIZE_PIX')
Set the size of the canvas on screen. Two parameters are required, the x and y size, both positive numbers in pixels.
PW('CANVAS_XSIZE_PIX')
Set the width of the canvas on screen. One parameters is required, the width, a positive number in pixels.
PW('CANVAS_YSIZE_PIX')
Set the height of the canvas on screen. One parameters is required, the height, a positive number in pixels.
PW('CANVAS_SIZE')
Set the size of the canvas on screen. Two parameters are required, the x and y size, both positive PROforma numbers.
PW('CANVAS_XSIZE')
Set the width of the canvas on screen. One parameters is required, the width, a positive PROforma number.
PW('CANVAS_YSIZE')
Set the height of the canvas on screen. One parameters is required, the height, a positive Proforma number.
PW('CANVAS_ORIGIN')
Set the current x and y values of the canvas origin. The two parameter values can be in any metric. The origin of a canvas is the position at the top left corner of the visible part of the canvas. It could be in PROforma numbers, lines, pixels, or anything else. The origin is directly passed on to the application programmer (YOU) via the CanvasInfo structure (see below) in the action routines. The default origin is (0,0).
PW('CANVAS_XORIGIN')
Set the current value of the x origin. The parameter value can be in any metric. The origin of a canvas is the position at the top left corner of the visible part of the canvas. It could be in PROforma numbers, lines, pixels, or anything else. The origin is directly passed on to the application programmer (YOU) via the CanvasInfo structure (see below) in the action routines. The default origin is (0,0).
PW('CANVAS_YORIGIN')
Set the current value of the y origin. The parameter value can be in any metric. The origin of a canvas is the position at the top left corner of the visible part of the canvas. It could be in PROforma numbers, lines, pixels, or anything else. The origin is directly passed on to the application programmer (YOU) via the CanvasInfo structure (see below) in the action routines. The default origin is (0,0).
PW('CANVAS_XSCROLL')
Increment the x origin of the canvas with the parameter, a number. The canvas will automatically be redrawn when control is next handed back to ProWesS.
PW('CANVAS_YSCROLL')
Increment the y origin of the canvas with the parameter, a number. The canvas will automatically be redrawn when control is next handed back to ProWesS via PWactivate.
PW('CANVAS_REDRAW')
Tell ProWesS that the canvas object should be redrawn when control is next handed back to ProWesS.
PW('CANVAS_ACTION_HITDRAG')
Set the action routine which should be called when the user starts dragging with a hit. The parameter should be DRAGH_ROUTINE
PW('CANVAS_ACTION_DODRAG')
Set the action routine which should be called when the user starts dragging with a do. The parameter should be DRAGD_ROUTINE.
PW('CANVAS_ACTION_DRAGEND')
Set the action routine which should be called when the user stops dragging. The parameter should be DRAGE_ROUTINE.
PW('CANVAS_ACTION_DRAGADJUST')
When the user is dragging, ProWesS makes sure that the pointer will not move out of the current region (it won't even pass control to children). To prevent the pointer from exiting, the pointer position may be adjusted. Such an event can be trapped by the canvas with this tag and passed on to an action routine which comes back to SBasic. The parameter should be DRAGA_ROUTINE.
The query tags
PW('CANVAS_XORIGIN')
Get the current value of the x origin. This value can be in any metric, as determined by the person who set the origin. The origin can only be modified by setting it, or by scrolling (which can be done either directly or by a scroll object). The origin of a canvas is the position at the top left corner of the visible part of the canvas. Please note that you can only get this once the outline containing the canvas has been activated. Before that, the value is 0.
PW('CANVAS_YORIGIN')
Get the current value of the y origin. This value can be in any metric, as determined by the person who set the origin. The origin can only be modified by setting it, or by scrolling (which can be done either directly or by a scroll object). The origin of a canvas is the position at the top left corner of the visible part of the canvas. Please note that you can only get this once the outline containing the canvas has been activated. Before that, the value is 0.
PW('CANVAS_XSIZE')
Get the current width of the visible part of the canvas. Please note that you can only get this once the outline containing the canvas has been activated. Before that, the value is 0. The value returned is a Proforma number.
PW('CANVAS_YSIZE')
Get the current height of the visible part of the canvas. Please note that you can only get this once the outline containing the canvas has been activated. Before that, the value is 0. The value returned is a Proforma number.
PW('CANVAS_XSIZE_PIX')
Get the current width of the visible part of the canvas. This is the width in pixels. Please note that you can only get this once the outline containing the canvas has been activated. Before that, the value is 0.
PW('CANVAS_YSIZE_PIX')
Get the current height of the visible part of the canvas. This is the heigth in pixels. Please note that you can only get this once the outline containing the canvas has been activated. Before that, the value is 0.

CanvasInfo

When the PWactivate call returns via one of the action routines to SBasic because of an event in a canvas, the add_info parameter contains a pointer to a piece of memory where you can find a structure called the "CanvasInfo". You can PEEK or POKE value into or from this structure. Please note that, in the description below, all values, except the one indicated by "short", are LONG WORDS and so you can calculate the offset at which they lie. The "short" values are words, not long words.

So, to obtain for example the value of yorg, you would use: yorg=PEEK_L(add_info + 4)

typedef struct {
    pt xorg, yorg;	        /* coordinate at topleft in canvas */
		        /* could be any type of size sizeof(int) */

		        /* PROforma coordinates */
    pt xsiz, ysiz;	        /* size of area */
    pt xpos, ypos;	        /* pointer position in area */
    Gstate gstate;	        /* Gstate to draw in */

		        /* window coordinates */
    short xpixsiz, ypixsiz; /* size of area */
    short xpixorg, ypixorg; /* origin of area in window */
    short xpixpos, ypixpos; /* pointer position in area */
    Window window;	        /* window to draw in */

		        /* conversion factors */
    pt Xpix2pt, Ypix2pt;    /* pixel to point conversion */
    pt Xpt2pix, Ypt2pix;    /* point to pixel conversion */
    short zero;	        /* always zero */
    } CanvasInfo;
To allow redrawing (part of) the canvas, the WindowSub is always set to cover the area of the canvas when this structure is passed to a routine.
PROGS, Professional & Graphical Software
last edited 1996 Oct 07 (wl)