Document canvas current item/clipping behaviour more precisely. [Bug 1774593]

2 files changed, 46 insertions, 16 deletions

diff --git a/ChangeLog b/ChangeLog
index dec9388..c314879 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
 2007-12-30  Donal K. Fellows  <dkf@users.sf.net>
 
+	* doc/canvas.n: Documented exact behaviour of items with respect to
+	when they are the current item. [Bug 1774593] Also documented the
+	clipping behaviour of window items.
+
 	* library/demos/nl.msg: Corrected following testing "in the field" by
 	Arjen Markus. [Bug 1860802]
 
diff --git a/doc/canvas.n b/doc/canvas.n
index 3db6174..7cf44d3 100644
--- a/doc/canvas.n
+++ b/doc/canvas.n
@@ -6,7 +6,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: canvas.n,v 1.32 2007/12/17 15:24:45 dkf Exp $
+'\" RCS: @(#) $Id: canvas.n,v 1.33 2007/12/30 23:35:05 dkf Exp $
 '\"
 .so man.macros
 .TH canvas n 8.3 Tk "Tk Built-In Commands"
@@ -155,7 +155,8 @@ all the items in the canvas.
 The tag \fBcurrent\fR is managed automatically by Tk;
 it applies to the \fIcurrent item\fR, which is the
 topmost item whose drawn area covers the position of
-the mouse cursor.
+the mouse cursor (different item types interpret this in varying ways; see the
+individual item type documentation for details).
 If the mouse is not in the canvas widget or is not over
 an item, then no item has the \fBcurrent\fR tag.
 .PP
@@ -1195,7 +1196,9 @@ After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR
 pairs, each of which sets one of the configuration options
 for the item.  These same \fIoption\fR\-\fIvalue\fR pairs may be
 used in \fBitemconfigure\fR widget commands to change the item's
-configuration.
+configuration. An arc item becomes the current item when the mouse pointer is
+over any part that is painted or (when fully transparent) that would be
+painted if both the \fB\-fill\fR and \fB\-outline\fR options were non-empty.
 .PP
 The following standard options are supported by arcs:
 .CS
@@ -1259,14 +1262,16 @@ Bitmaps are created with widget commands of the following form:
 \fIpathName \fBcreate bitmap \fIx y \fR?\fIoption value option value ...\fR?
 \fIpathName \fBcreate bitmap \fIcoordList\fR ?\fIoption value option value ...\fR?
 .CE
-The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR specify the coordinates of a
+The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR (which must have two
+elements) specify the coordinates of a
 point used to position the bitmap on the display (see the \fB\-anchor\fR
 option below for more information on how bitmaps are displayed).
 After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR
 pairs, each of which sets one of the configuration options
 for the item.  These same \fIoption\fR\-\fIvalue\fR pairs may be
 used in \fBitemconfigure\fR widget commands to change the item's
-configuration.
+configuration. A bitmap item becomes the current item when the mouse pointer
+is over any part of its bounding box.
 .PP
 The following standard options are supported by bitmaps:
 .CS
@@ -1332,7 +1337,8 @@ After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR
 pairs, each of which sets one of the configuration options
 for the item.  These same \fIoption\fR\-\fIvalue\fR pairs may be
 used in \fBitemconfigure\fR widget commands to change the item's
-configuration.
+configuration. An image item becomes the current item when the mouse pointer
+is over any part of its bounding box.
 .PP
 The following standard options are supported by images:
 .CS
@@ -1377,7 +1383,9 @@ After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR
 pairs, each of which sets one of the configuration options
 for the item.  These same \fIoption\fR\-\fIvalue\fR pairs may be
 used in \fBitemconfigure\fR widget commands to change the item's
-configuration.
+configuration. A line item is the current item whenever the mouse pointer is
+over any segment of the line, whether drawn or not and whether or not the line
+is smoothed.
 .PP
 The following standard options are supported by lines:
 .CS
@@ -1489,7 +1497,9 @@ After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR
 pairs, each of which sets one of the configuration options
 for the item.  These same \fIoption\fR\-\fIvalue\fR pairs may be
 used in \fBitemconfigure\fR widget commands to change the item's
-configuration.
+configuration. An oval item becomes the current item when the mouse pointer is
+over any part that is painted or (when fully transparent) that would be
+painted if both the \fB\-fill\fR and \fB\-outline\fR options were non-empty.
 .PP
 The following standard options are supported by ovals:
 .CS
@@ -1537,7 +1547,9 @@ After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR
 pairs, each of which sets one of the configuration options
 for the item.  These same \fIoption\fR\-\fIvalue\fR pairs may be
 used in \fBitemconfigure\fR widget commands to change the item's
-configuration.
+configuration. A polygon item is the current item whenever the mouse pointer
+is over any part of the polygon, whether drawn or not and whether or not the
+outline is smoothed.
 .PP
 The following standard options are supported by polygons:
 .CS
@@ -1622,7 +1634,8 @@ following form:
 \fIpathName \fBcreate rectangle \fIx1 y1 x2 y2 \fR?\fIoption value option value ...\fR?
 \fIpathName \fBcreate rectangle \fIcoordList\fR ?\fIoption value option value ...\fR?
 .CE
-The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR or \fIcoordList\fR give
+The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR or \fIcoordList\fR
+(which must have four elements) give
 the coordinates of two diagonally opposite corners of the rectangle
 (the rectangle will include its upper and left edges but not
 its lower or right edges).
@@ -1630,7 +1643,10 @@ After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR
 pairs, each of which sets one of the configuration options
 for the item.  These same \fIoption\fR\-\fIvalue\fR pairs may be
 used in \fBitemconfigure\fR widget commands to change the item's
-configuration.
+configuration. A rectangle item becomes the current item when the mouse
+pointer is over any part that is painted or (when fully transparent) that
+would be painted if both the \fB\-fill\fR and \fB\-outline\fR options were
+non-empty.
 .PP
 The following standard options are supported by rectangles:
 .CS
@@ -1672,14 +1688,16 @@ form:
 \fIpathName \fBcreate text \fIx y \fR?\fIoption value option value ...\fR?
 \fIpathName \fBcreate text \fIcoordList\fR ?\fIoption value option value ...\fR?
 .CE
-The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR specify the coordinates of a
+The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR (which must have two
+elements) specify the coordinates of a
 point used to position the text on the display (see the options
 below for more information on how text is displayed).
 After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR
 pairs, each of which sets one of the configuration options
 for the item.  These same \fIoption\fR\-\fIvalue\fR pairs may be
 used in \fBitemconfigure\fR widget commands to change the item's
-configuration.
+configuration. A text item becomes the current item when the mouse pointer
+is over any part of its bounding box.
 .PP
 The following standard options are supported by text items:
 .CS
@@ -1753,14 +1771,18 @@ Window items are created with widget commands of the following form:
 \fIpathName \fBcreate window \fIx y \fR?\fIoption value option value ...\fR?
 \fIpathName \fBcreate window \fIcoordList\fR ?\fIoption value option value ...\fR?
 .CE
-The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR specify the coordinates of a
+The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR (which must have two
+elements) specify the coordinates of a
 point used to position the window on the display (see the \fB\-anchor\fR
 option below for more information on how bitmaps are displayed).
 After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR
 pairs, each of which sets one of the configuration options
 for the item.  These same \fIoption\fR\-\fIvalue\fR pairs may be
 used in \fBitemconfigure\fR widget commands to change the item's
-configuration.
+configuration. Theoretically, a window item becomes the current item when the
+mouse pointer is over any part of its bounding box, but in practice this
+typically does not happen because the mouse pointer ceases to be over the
+canvas at that point.
 .PP
 The following standard options are supported by window items:
 .CS
@@ -1801,7 +1823,11 @@ the canvas widget or a child of some ancestor of the canvas widget.
 Note:  due to restrictions in the ways that windows are managed, it is not
 possible to draw other graphical items (such as lines and images) on top
 of window items.  A window item always obscures any graphics that
-overlap it, regardless of their order in the display list.
+overlap it, regardless of their order in the display list. Also note that
+window items, unlike other canvas items, are not clipped for display by their
+containing canvas's border, and are instead clipped by the parent widget of
+the window specified by the \fB\-window\fR option; when the parent widget is
+the canvas, this means that the window item can overlap the canvas's border.
 .SH "APPLICATION-DEFINED ITEM TYPES"
 .PP
 It is possible for individual applications to define new item