#  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.
#
#

=head1 NAME

Tk_CanvasTextInfo - additional information for managing text items in canvases

=for category C Programming

=head1 SYNOPSIS

B<#include E<lt>tk.hE<gt>>

Tk_CanvasTextInfo *
B<Tk_CanvasGetTextInfo>(I<canvas>)

=head1 ARGUMENTS

=over 4

=item Tk_Canvas canvas (in)

A token that identifies a particular canvas widget.

=back

=head1 DESCRIPTION

Textual canvas items are somewhat more complicated to manage than
other items, due to things like the selection and the input focus.
B<Tk_CanvasGetTextInfo> may be invoked by a type manager
to obtain additional information needed for items that display text.
The return value from B<Tk_CanvasGetTextInfo> is a pointer to
a structure that is shared between Tk and all the items that display
text.
The structure has the following form:

 typedef struct Tk_CanvasTextInfo {
 	Tk_3DBorder selBorder;
 	int selBorderWidth;
 	XColor *selFgColorPtr;
 	Tk_Item *selItemPtr;
 	int selectFirst;
 	int selectLast;
 	Tk_Item *anchorItemPtr;
 	int selectAnchor;
 	Tk_3DBorder insertBorder;
 	int insertWidth;
 	int insertBorderWidth;
 	Tk_Item *focusItemPtr;
 	int gotFocus;
 	int cursorOn;
 } Tk_CanvasTextInfo;

The B<selBorder> field identifies a Tk_3DBorder that should be
used for drawing the background under selected text.
I<selBorderWidth> gives the width of the raised border around
selected text, in pixels.
I<selFgColorPtr> points to an XColor that describes the foreground
color to be used when drawing selected text.
I<selItemPtr> points to the item that is currently selected, or
NULL if there is no item selected or if the canvas doesn't have the
selection.
I<selectFirst> and I<selectLast> give the indices of the first
and last selected characters in I<selItemPtr>, as returned by the
I<indexProc> for that item.
I<anchorItemPtr> points to the item that currently has the selection
anchor;  this is not necessarily the same as I<selItemPtr>.
I<selectAnchor> is an index that identifies the anchor position
within I<anchorItemPtr>.
I<insertBorder> contains a Tk_3DBorder to use when drawing the
insertion cursor;  I<insertWidth> gives the total width of the
insertion cursor in pixels, and I<insertBorderWidth> gives the
width of the raised  border around the insertion cursor.
I<focusItemPtr> identifies the item that currently has the input
focus, or NULL if there is no such item.
I<gotFocus> is 1 if the canvas widget has the input focus and
0 otherwise.
I<cursorOn> is 1 if the insertion cursor should be drawn in
I<focusItemPtr> and 0 if it should not be drawn;  this field
is toggled on and off by Tk to make the cursor blink.

The structure returned by B<Tk_CanvasGetTextInfo>
is shared between Tk and the type managers;  typically the type manager
calls B<Tk_CanvasGetTextInfo> once when an item is created and
then saves the pointer in the item's record.
Tk will update information in the Tk_CanvasTextInfo;  for example,
a B<configure> method might change the I<selBorder>
field, or a B<select> method might change the I<selectFirst>
field, or Tk might change I<cursorOn> in order to make the insertion
cursor flash on and off during successive redisplays.

Type managers should treat all of the fields of the Tk_CanvasTextInfo
structure as read-only, except for I<selItemPtr>, I<selectFirst>,
I<selectLast>, and I<selectAnchor>.
Type managers may change I<selectFirst>, I<selectLast>, and
I<selectAnchor> to adjust for insertions and deletions in the
item (but only if the item is the current owner of the selection or
anchor, as determined by I<selItemPtr> or I<anchorItemPtr>).
If all of the selected text in the item is deleted, the item should
set I<selItemPtr> to NULL to indicate that there is no longer a
selection.

=head1 KEYWORDS

canvas, focus, insertion cursor, selection, selection anchor, text
