head	1.10;
access;
symbols
	core-8-5-9:1.7
	core-8-5-8:1.7
	macosx-cocoa-merge:1.9
	macosx-cocoa-premerge:1.9
	macosx-carbon-freeze:1.9
	core-8-5-7:1.7
	core-8-5-6:1.7
	core-8-6-b1:1.9
	core-8-6-a3:1.8
	core-8-5-5:1.7
	core-8-6-a2:1.8
	core-8-5-4:1.7
	core-8-5-3:1.7
	core-8-6-a1:1.7
	core-8-4-19:1.3
	core-8-5-branch:1.7.0.2
	core-8-5-2:1.7
	core-8-4-18:1.3
	core-8-5-1:1.7
	core-8-4-17:1.3
	core-8-5-0:1.7
	core-8-5-b3:1.6
	core-8-5-b2:1.5
	core-8-4-16:1.3
	core-8-5-b1:1.5
	core-stablilizer-merge:1.5
	core-stabilizer-branch:1.5.0.2
	core-stabilizer-merge:1.7
	core-8-4-15:1.3
	core-8-5-a6:1.5
	core-8-5-a5:1.4
	core-8-4-14:1.3
	core-8-5-a4:1.4
	core-8-4-13:1.3
	core-8-4-12:1.3
	core-8-4-11:1.3
	core-8-5-a3:1.4
	core-8-4-10:1.3
	core-8-4-9-branch:1.3.0.6
	core-8-5-a2:1.4
	core-8-4-9:1.3
	core-8-4-8:1.3
	core-8-4-7:1.3
	core-8-5-a1:1.3
	core-8-4-6:1.3
	core-8-4-5:1.3
	mistachkin-dev-branch:1.3.0.4
	core-8-4-4:1.3
	core-8-4-3:1.3
	core-8-4-branch:1.3.0.2
	core-8-4-2:1.3
	core-8-4-1:1.3
	core-8-3-5:1.2
	core-8-4-0:1.3
	macosx-8-4-merge-2002-08-31-trunk:1.3
	macosx-8-4-premerge-2002-08-31-branch:1.2.24.1
	macosx-8-4-premerge-2002-08-31-trunk:1.3
	macosx-8-4-merge-2002-08-30-branch:1.2.24.1
	macosx-8-4-merge-2002-08-30-trunk:1.3
	macosx-8-4-merge-2002-08-20-branch:1.2.24.1
	macosx-8-4-merge-2002-08-20-trunk:1.3
	core-8-4-b2:1.3
	core-8-4-b1:1.3
	macosx-premerge-6-9-02:1.2.24.1
	core-8-4-a4:1.3
	core-8-3-4:1.2
	macosx-8-4-branch:1.2.0.24
	macosx-8-4-branchpoint:1.2
	core-8-4-a3:1.2
	core-8-3-3:1.2
	dgp-privates-into-namespace:1.2.0.22
	tclpro-1-5-0:1.2
	core-8-4-win-speedup:1.2.0.20
	core-8-4-a2:1.2
	tclpro-1-4-1:1.2
	tclpro-1-4-0:1.2
	core-8-3-2:1.2
	ajuba-ajuba2-2-1-base:1.2
	ajuba-ajuba2-2-0:1.2
	core-8-4-a1:1.2
	core-8-3-1-branch:1.2.0.18
	core-8-3-1:1.2
	scriptics-sc-2-0-b5:1.2
	scriptics-sc-2-0-fixed:1.2
	scriptics-sc-2-0-b2:1.2
	scriptics-sc-2-0-b1:1.2
	core-8-3-0:1.2
	core-8-3-b2:1.2
	core-8-3-b1:1.2
	scriptics-sc-1-1:1.2
	scriptics-sc-1-1-b1:1.2
	core-8-2-3:1.2
	scriptics-sc-1-1-branch:1.2.0.16
	scriptics-sc-1-1-base:1.2
	scriptics-sc-1-0:1.2
	scriptics-sc-1-0-branch:1.2.0.14
	scriptics-sc-1-0-base:1.2
	core-8-2-2:1.2
	core-8-2-1:1.2
	scriptics-bc-1-0-b1:1.2
	core-8-2-1-branch:1.2.0.12
	scriptics-tclpro-1-3-0:1.2
	core-8-2-0:1.2
	core-8-2-b3-branch:1.2.0.10
	core-8-2-b3-base:1.2
	scriptics-tclpro-1-3-b4:1.2
	core-8-2-b2:1.2
	scriptics-tclpro-1-3-b3:1.2
	core-8-2-b1:1.2
	scriptics-tclpro-1-3-b2:1.2
	merge-to-mainline-5/21/99:1.2
	scriptics-tclpro-1-3-b2-branch:1.2.0.8
	core-8-1-1:1.2
	scriptics-tclpro-1-3-b1:1.2
	core-8-1-1-base:1.2
	core-8-1-0:1.2
	merge-to-mainline-4-29-99:1.2
	merge-to-mainline-4-23-99:1.2
	core-8-1-branch-old:1.1.0.4
	core-8-0-6-branch:1.2.0.6
	core-8-0-6-base:1.2
	core-8-0-5:1.2
	core-8-1-b3:1.1.4.1
	core-8-1-b2:1.1.4.1
	dev-8-1-stubs-branch:1.1.4.1.0.2
	dev-stubs-branch:1.2.0.4
	scriptics-tclpro-1-2:1.2
	scriptics-tclpro-1-2-b2:1.2
	core-8-1-merge-2/10/99:1.2
	core-8-0-5-branch:1.2.0.2
	core-8-0-5-base:1.2
	scriptics-tclpro-1-2-b1:1.2
	scriptics-tclpro-1-2-a1:1.2
	core-8-1-b1:1.1.4.1
	core-8-0-4:1.2
	core-8-1-a2:1.1
	core-8-0-2:1.1
	core-8-0-3:1.2;
locks; strict;
comment	@# @;


1.10
date	2010.02.17.19.21.17;	author nijtmans;	state Exp;
branches;
next	1.9;

1.9
date	2008.11.01.12.25.14;	author dkf;	state Exp;
branches;
next	1.8;

1.8
date	2008.06.30.22.57.00;	author dkf;	state Exp;
branches;
next	1.7;

1.7
date	2007.12.13.15.23.42;	author dgp;	state Exp;
branches;
next	1.6;

1.6
date	2007.10.29.16.04.12;	author dkf;	state Exp;
branches;
next	1.5;

1.5
date	2007.01.05.00.00.48;	author nijtmans;	state Exp;
branches
	1.5.2.1;
next	1.4;

1.4
date	2004.09.19.16.05.36;	author dkf;	state Exp;
branches;
next	1.3;

1.3
date	2002.01.25.21.09.36;	author dgp;	state Exp;
branches;
next	1.2;

1.2
date	98.09.14.18.22.45;	author stanton;	state Exp;
branches
	1.2.20.1
	1.2.24.1;
next	1.1;

1.1
date	98.04.01.09.39.59;	author rjohnson;	state Exp;
branches
	1.1.4.1;
next	;

1.1.4.1
date	98.09.30.02.15.18;	author stanton;	state Exp;
branches;
next	;

1.2.20.1
date	2002.04.02.20.57.53;	author hobbs;	state Exp;
branches;
next	;

1.2.24.1
date	2002.02.05.02.25.13;	author wolfsuit;	state Exp;
branches;
next	;

1.5.2.1
date	2007.11.01.16.37.10;	author dgp;	state Exp;
branches;
next	;


desc
@@


1.10
log
@CONSTify everything related to Tk_ConfigSpec
@
text
@'\"
'\" 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.
'\" 
'\" RCS: @@(#) $Id: CanvTkwin.3,v 1.9 2008/11/01 12:25:14 dkf Exp $
'\" 
.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 "const 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 \fBTCL_OK\fR.
Otherwise it stores an error message in the interpreter result and
returns \fBTCL_ERROR\fR.
.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 will not 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:
.PP
.CS
static const Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc,
    Tk_CanvasTagsPrintProc, (ClientData) NULL
};

static const Tk_ConfigSpec configSpecs[] = {
    ...
    {TK_CONFIG_CUSTOM, "\-tags", NULL, NULL,
        NULL, 0, TK_CONFIG_NULL_OK, &tagsOption},
    ...
};
.CE
.SH KEYWORDS
canvas, focus, item type, redisplay, selection, type manager
@


1.9
log
@Minor formatting/usage correction
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: CanvTkwin.3,v 1.8 2008/06/30 22:57:00 dkf Exp $
d148 1
a148 1
static Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc,
d152 1
a152 1
static Tk_ConfigSpec configSpecs[] = {
d154 2
a155 2
    {TK_CONFIG_CUSTOM, "\-tags", (char *) NULL, (char *) NULL,
        (char *) NULL, 0, TK_CONFIG_NULL_OK, &tagsOption},
@


1.8
log
@Minor doc updates (removing out of date changebars, improving typedef formatting,
 etc.)
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: CanvTkwin.3,v 1.7 2007/12/13 15:23:42 dgp Exp $
d90 1
a90 1
Otherwise it stores an error message in \fIinterp->result\fR and
d146 1
@


1.7
log
@merge stable branch onto HEAD
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: CanvTkwin.3,v 1.5.2.1 2007/11/01 16:37:10 dgp Exp $
a75 1

a157 1

@


1.6
log
@Lots more GOOBE stuff. Now works with 'make html'!
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: CanvTkwin.3,v 1.5 2007/01/05 00:00:48 nijtmans Exp $
@


1.5
log
@various "const" additions, in line with TIP #27
fix bug #1627732
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: CanvTkwin.3,v 1.4 2004/09/19 16:05:36 dkf Exp $
d143 1
a143 1
The code of a canvas type manager won't call these procedures
@


1.5.2.1
log
@merge updates from HEAD
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: CanvTkwin.3,v 1.5 2007/01/05 00:00:48 nijtmans Exp $
d143 1
a143 1
The code of a canvas type manager will not call these procedures
@


1.4
log
@Standardize style of section refs & public symbols. Remove displayed tabs
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: CanvTkwin.3,v 1.3 2002/01/25 21:09:36 dgp Exp $
d41 1
a41 1
.AP "CONST char" *string in
@


1.3
log
@	* Updated callers of Tcl_SplitList and Tcl_Merge.
	* Updated callers of Tcl_GetStringResult.
	  Rewrote PrintScrollFractions to ScrollFractions to stop scribbling
	  directly on interp->result.
	* Updated callers of Tcl_GetVar, Tcl_GetVar2
	* Updated callers of Tcl_SplitPath, Tcl_JoinPath, and
	  Tcl_TranslateFileName.
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: CanvTkwin.3,v 1.2 1998/09/14 18:22:45 stanton Exp $
d90 1
a90 1
and returns TCL_OK.
d92 1
a92 1
returns TCL_ERROR.
d149 1
a149 1
	Tk_CanvasTagsPrintProc, (ClientData) NULL
d153 4
a156 4
	...
	{TK_CONFIG_CUSTOM, "\-tags", (char *) NULL, (char *) NULL,
		(char *) NULL, 0, TK_CONFIG_NULL_OK, &tagsOption},
	...
@


1.2
log
@Replaced SCCS strings, fixed binary files
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id$
d41 1
a41 1
.AP char *string in
@


1.2.20.1
log
@sync with head
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: CanvTkwin.3,v 1.3 2002/01/25 21:09:36 dgp Exp $
d41 1
a41 1
.AP "CONST char" *string in
@


1.2.24.1
log
@Merge with current TOT
Added support for the wm stackorder command
Fixed crash when selecting Menu items in the Application menu that we didn't
put there.
Added first bits of the use of CG for low-level drawing.  The line-drawing works,
the rest doesn't yet.  You have to set the file static useCGDrawing to 1 and
rebuild to activate this code.
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: CanvTkwin.3,v 1.2 1998/09/14 18:22:45 stanton Exp $
d41 1
a41 1
.AP "CONST char" *string in
@


1.1
log
@Initial revision
@
text
@d7 1
a7 1
'\" SCCS: @@(#) CanvTkwin.3 1.8 96/08/27 13:21:54
@


1.1.4.1
log
@Merged 8.0.3 changes into 8.1
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: CanvTkwin.3,v 1.2 1998/09/14 18:22:45 stanton Exp $
@


