The canvas type
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.
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)