# 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