Tk_CanvasTkwin (3)
utility procedures for canvas type managers
SYNOPSIS
#include <tk.h>
Tk_Window
Tk_CanvasTkwin(canvas)
int
Tk_CanvasGetCoord(interp, canvas, string, doublePtr)
Tk_CanvasDrawableCoords(canvas, x, y, drawableXPtr, drawableYPtr)
Tk_CanvasSetStippleOrigin(canvas, gc)
Tk_CanvasWindowCoords(canvas, x, y, screenXPtr, screenYPtr)
Tk_CanvasEventuallyRedraw(canvas, x1, y1, x2, y2)
Tk_OptionParseProc *Tk_CanvasTagsParseProc;
Tk_OptionPrintProc *Tk_CanvasTagsPrintProc;
ARGUMENTS
Tk_ItemType *drawableXPtr
Tk_Canvas canvas in
A token that identifies a canvas widget.
Tcl_Interp *interp in/out
Interpreter to use for error reporting.
char *string in
Textual description of a canvas coordinate.
double *doublePtr out
Points to place to store a converted coordinate.
double x in
An x coordinate in the space of the canvas.
double y in
A y coordinate in the space of the canvas.
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.
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.
GC gc out
Graphics context to modify.
short *screenXPtr out
Points to a location in which to store the screen coordinate in the
canvas window that corresponds to x.
short *screenYPtr out
Points to a location in which to store the screen coordinate in the
canvas window that corresponds to y.
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.
int y1 in
Top edge of the region that needs redisplay. Only pixels at or below
this coordinate need to be redisplayed.
int x2 in
Right edge of the region that needs redisplay. Only pixels to
the left of this coordinate need to be redisplayed.
int y2 in
Bottom edge of the region that needs redisplay. Only pixels above
this coordinate need to be redisplayed.
DESCRIPTION
These procedures are called by canvas type managers to perform various
utility functions.
Tk_CanvasTkwin returns the Tk_Window associated with a particular
canvas.
Tk_CanvasGetCoord translates a string specification of a
coordinate (such as 2p or 1.6c) into a double-precision
canvas coordinate.
If string is a valid coordinate description then Tk_CanvasGetCoord
stores the corresponding canvas coordinate at *doublePtr
and returns TCL_OK.
Otherwise it stores an error message in interp->result and
returns TCL_ERROR.
Tk_CanvasDrawableCoords is called by type managers during
redisplay to compute where to draw things.
Given x and y coordinates in the space of the
canvas, Tk_CanvasDrawableCoords computes the corresponding
pixel in the drawable that is currently being used for redisplay;
it returns those coordinates in *drawableXPtr and *drawableYPtr.
This procedure should not be invoked except during redisplay.
Tk_CanvasSetStippleOrigin is also used during redisplay.
It sets the stipple origin in gc so that stipples drawn
with gc in the current offscreen pixmap will line up
with stipples drawn with origin (0,0) in the canvas's actual
window.
Tk_CanvasSetStippleOrigin 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 Tk_CanvasSetStippleOrigin just before using gc
to draw something; after it is finished drawing, the type manager
calls XSetTSOrigin to restore the origin in gc back to (0,0)
(the restore is needed because graphics contexts are shared, so
they cannot be modified permanently).
Tk_CanvasWindowCoords is similar to Tk_CanvasDrawableCoords
except that it returns coordinates in the canvas's window on the
screen, instead of coordinates in an off-screen pixmap.
Tk_CanvasEventuallyRedraw may be invoked by a type manager
to inform Tk that a portion of a canvas needs to be redrawn.
The x1, y1, x2, and y2 arguments
specify the region that needs to be redrawn, in canvas coordinates.
Type managers rarely need to invoke Tk_CanvasEventuallyRedraw,
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 configureProc or scaleProc).
The only time that a type manager needs to call
Tk_CanvasEventuallyRedraw 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.
Tk_CanvasTagsParseProc and Tk_CanvasTagsPrintProc are
procedures that handle the -tags 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 Tk_CustomOption
structure for the -tags option. The code typically looks
like this:
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},
...
};
KEYWORDS
canvas, focus, item type, redisplay, selection, type manager
'\"
'\" Copyright (c) 1990-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" RCS: @(#) $Id: WindowId.3,v 1.2 1998/09/14 18:22:54 stanton Exp $
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\" Start paragraph describing an argument to a library procedure.
'\" type is type of argument (int, etc.), in/out is either "in", "out",
'\" or "in/out" to describe whether procedure reads or modifies arg,
'\" and indent is equivalent to second arg of .IP (shouldn't ever be
'\" needed; use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\" Give maximum sizes of arguments for setting tab stops. Type and
'\" name are examples of largest possible arguments that will be passed
'\" to .AP later. If args are omitted, default tab stops are used.
'\"
'\" .BS
'\" Start box enclosure. From here until next .BE, everything will be
'\" enclosed in one large box.
'\"
'\" .BE
'\" End of box enclosure.
'\"
'\" .CS
'\" Begin code excerpt.
'\"
'\" .CE
'\" End code excerpt.
'\"
'\" .VS ?version? ?br?
'\" Begin vertical sidebar, for use in marking newly-changed parts
'\" of man pages. The first argument is ignored and used for recording
'\" the version when the .VS was added, so that the sidebars can be
'\" found and removed when they reach a certain age. If another argument
'\" is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\" End of vertical sidebar.
'\"
'\" .DS
'\" Begin an indented unfilled display.
'\"
'\" .DE
'\" End of indented unfilled display.
'\"
'\" .SO
'\" Start of list of standard options for a Tk widget. The
'\" options follow on successive lines, in four columns separated
'\" by tabs.
'\"
'\" .SE
'\" End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\" Start of description of a specific option. cmdName gives the
'\" option's name as specified in the class command, dbName gives
'\" the option's name in the option database, and dbClass gives
'\" the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\" Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.2 1998/09/14 18:39:54 stanton Exp $
'\"
'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
t .wh -1.3i ^B
^l \n(.l
b
'\" # Start an argument description
AP
!"\\$4"" .TP \\$4
\{\
!"\\$2"" .TP \\n()Cu
.TP 15
|