162 lines
6.4 KiB
Groff
162 lines
6.4 KiB
Groff
'\"
|
|
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
|
'\"
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|
'\"
|
|
'\" SCCS: @(#) CanvTkwin.3 1.8 96/08/27 13:21:54
|
|
'\"
|
|
.so man.macros
|
|
.TH Tk_CanvasTkwin 3 4.1 Tk "Tk Library Procedures"
|
|
.BS
|
|
.SH NAME
|
|
Tk_CanvasTkwin, Tk_CanvasGetCoord, Tk_CanvasDrawableCoords, Tk_CanvasSetStippleOrigin, Tk_CanvasWindowCoords, Tk_CanvasEventuallyRedraw, Tk_CanvasTagsOption \- utility procedures for canvas type managers
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <tk.h>\fR
|
|
.sp
|
|
Tk_Window
|
|
\fBTk_CanvasTkwin\fR(\fIcanvas\fR)
|
|
.sp
|
|
int
|
|
\fBTk_CanvasGetCoord\fR(\fIinterp, canvas, string, doublePtr\fR)
|
|
.sp
|
|
\fBTk_CanvasDrawableCoords\fR(\fIcanvas, x, y, drawableXPtr, drawableYPtr\fR)
|
|
.sp
|
|
\fBTk_CanvasSetStippleOrigin\fR(\fIcanvas, gc\fR)
|
|
.sp
|
|
\fBTk_CanvasWindowCoords\fR(\fIcanvas, x, y, screenXPtr, screenYPtr\fR)
|
|
.sp
|
|
\fBTk_CanvasEventuallyRedraw\fR(\fIcanvas, x1, y1, x2, y2\fR)
|
|
.sp
|
|
Tk_OptionParseProc *\fBTk_CanvasTagsParseProc\fR;
|
|
.sp
|
|
Tk_OptionPrintProc *\fBTk_CanvasTagsPrintProc\fR;
|
|
.SH ARGUMENTS
|
|
.AS Tk_ItemType *drawableXPtr
|
|
.AP Tk_Canvas canvas in
|
|
A token that identifies a canvas widget.
|
|
.AP Tcl_Interp *interp in/out
|
|
Interpreter to use for error reporting.
|
|
.AP char *string in
|
|
Textual description of a canvas coordinate.
|
|
.AP double *doublePtr out
|
|
Points to place to store a converted coordinate.
|
|
.AP double x in
|
|
An x coordinate in the space of the canvas.
|
|
.AP double y in
|
|
A y coordinate in the space of the canvas.
|
|
.AP short *drawableXPtr out
|
|
Pointer to a location in which to store an x coordinate in the space
|
|
of the drawable currently being used to redisplay the canvas.
|
|
.AP short *drawableYPtr out
|
|
Pointer to a location in which to store a y coordinate in the space
|
|
of the drawable currently being used to redisplay the canvas.
|
|
.AP GC gc out
|
|
Graphics context to modify.
|
|
.AP short *screenXPtr out
|
|
Points to a location in which to store the screen coordinate in the
|
|
canvas window that corresponds to \fIx\fR.
|
|
.AP short *screenYPtr out
|
|
Points to a location in which to store the screen coordinate in the
|
|
canvas window that corresponds to \fIy\fR.
|
|
.AP int x1 in
|
|
Left edge of the region that needs redisplay. Only pixels at or to
|
|
the right of this coordinate need to be redisplayed.
|
|
.AP int y1 in
|
|
Top edge of the region that needs redisplay. Only pixels at or below
|
|
this coordinate need to be redisplayed.
|
|
.AP int x2 in
|
|
Right edge of the region that needs redisplay. Only pixels to
|
|
the left of this coordinate need to be redisplayed.
|
|
.AP int y2 in
|
|
Bottom edge of the region that needs redisplay. Only pixels above
|
|
this coordinate need to be redisplayed.
|
|
.BE
|
|
|
|
.SH DESCRIPTION
|
|
.PP
|
|
These procedures are called by canvas type managers to perform various
|
|
utility functions.
|
|
.PP
|
|
\fBTk_CanvasTkwin\fR returns the Tk_Window associated with a particular
|
|
canvas.
|
|
.PP
|
|
\fBTk_CanvasGetCoord\fR translates a string specification of a
|
|
coordinate (such as \fB2p\fR or \fB1.6c\fR) into a double-precision
|
|
canvas coordinate.
|
|
If \fIstring\fR is a valid coordinate description then \fBTk_CanvasGetCoord\fR
|
|
stores the corresponding canvas coordinate at *\fIdoublePtr\fR
|
|
and returns TCL_OK.
|
|
Otherwise it stores an error message in \fIinterp->result\fR and
|
|
returns TCL_ERROR.
|
|
.PP
|
|
\fBTk_CanvasDrawableCoords\fR is called by type managers during
|
|
redisplay to compute where to draw things.
|
|
Given \fIx\fR and \fIy\fR coordinates in the space of the
|
|
canvas, \fBTk_CanvasDrawableCoords\fR computes the corresponding
|
|
pixel in the drawable that is currently being used for redisplay;
|
|
it returns those coordinates in *\fIdrawableXPtr\fR and *\fIdrawableYPtr\fR.
|
|
This procedure should not be invoked except during redisplay.
|
|
.PP
|
|
\fBTk_CanvasSetStippleOrigin\fR is also used during redisplay.
|
|
It sets the stipple origin in \fIgc\fR so that stipples drawn
|
|
with \fIgc\fR in the current offscreen pixmap will line up
|
|
with stipples drawn with origin (0,0) in the canvas's actual
|
|
window.
|
|
\fBTk_CanvasSetStippleOrigin\fR is needed in order to guarantee
|
|
that stipple patterns line up properly when the canvas is
|
|
redisplayed in small pieces.
|
|
Redisplays are carried out in double-buffered fashion where a
|
|
piece of the canvas is redrawn in an offscreen pixmap and then
|
|
copied back onto the screen.
|
|
In this approach the stipple origins in graphics contexts need to
|
|
be adjusted during each redisplay to compensate for the position
|
|
of the off-screen pixmap relative to the window.
|
|
If an item is being drawn with stipples, its type manager typically
|
|
calls \fBTk_CanvasSetStippleOrigin\fR just before using \fIgc\fR
|
|
to draw something; after it is finished drawing, the type manager
|
|
calls \fBXSetTSOrigin\fR to restore the origin in \fIgc\fR back to (0,0)
|
|
(the restore is needed because graphics contexts are shared, so
|
|
they cannot be modified permanently).
|
|
.PP
|
|
\fBTk_CanvasWindowCoords\fR is similar to \fBTk_CanvasDrawableCoords\fR
|
|
except that it returns coordinates in the canvas's window on the
|
|
screen, instead of coordinates in an off-screen pixmap.
|
|
.PP
|
|
\fBTk_CanvasEventuallyRedraw\fR may be invoked by a type manager
|
|
to inform Tk that a portion of a canvas needs to be redrawn.
|
|
The \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR arguments
|
|
specify the region that needs to be redrawn, in canvas coordinates.
|
|
Type managers rarely need to invoke \fBTk_CanvasEventuallyRedraw\fR,
|
|
since Tk can normally figure out when an item has changed and make
|
|
the redisplay request on its behalf (this happens, for example
|
|
whenever Tk calls a \fIconfigureProc\fR or \fIscaleProc\fR).
|
|
The only time that a type manager needs to call
|
|
\fBTk_CanvasEventuallyRedraw\fR is if an item has changed on its own
|
|
without being invoked through one of the procedures in its Tk_ItemType;
|
|
this could happen, for example, in an image item if the image is
|
|
modified using image commands.
|
|
.PP
|
|
\fBTk_CanvasTagsParseProc\fR and \fBTk_CanvasTagsPrintProc\fR are
|
|
procedures that handle the \fB\-tags\fR option for canvas items.
|
|
The code of a canvas type manager won't call these procedures
|
|
directly, but will use their addresses to create a \fBTk_CustomOption\fR
|
|
structure for the \fB\-tags\fR option. The code typically looks
|
|
like this:
|
|
.CS
|
|
static Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc,
|
|
Tk_CanvasTagsPrintProc, (ClientData) NULL
|
|
};
|
|
|
|
static Tk_ConfigSpec configSpecs[] = {
|
|
...
|
|
{TK_CONFIG_CUSTOM, "\-tags", (char *) NULL, (char *) NULL,
|
|
(char *) NULL, 0, TK_CONFIG_NULL_OK, &tagsOption},
|
|
...
|
|
};
|
|
.CE
|
|
|
|
.SH KEYWORDS
|
|
canvas, focus, item type, redisplay, selection, type manager
|