diff options
Diffstat (limited to 'doc/CanvTxtInfo.3')
| -rw-r--r-- | doc/CanvTxtInfo.3 | 104 |
1 files changed, 104 insertions, 0 deletions
diff --git a/doc/CanvTxtInfo.3 b/doc/CanvTxtInfo.3 new file mode 100644 index 0000000..47b37f7 --- /dev/null +++ b/doc/CanvTxtInfo.3 @@ -0,0 +1,104 @@ +'\" +'\" 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. +'\" +'\" SCCS: @(#) CanvTxtInfo.3 1.8 96/03/26 18:03:51 +'\" +.so man.macros +.TH Tk_CanvasTextInfo 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_CanvasTextInfo \- additional information for managing text items in canvases +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_CanvasTextInfo * +\fBTk_CanvasGetTextInfo\fR(\fIcanvas\fR) +.SH ARGUMENTS +.AS Tk_Canvas canvas +.AP Tk_Canvas canvas in +A token that identifies a particular canvas widget. +.BE + +.SH DESCRIPTION +.PP +Textual canvas items are somewhat more complicated to manage than +other items, due to things like the selection and the input focus. +\fBTk_CanvasGetTextInfo\fR may be invoked by a type manager +to obtain additional information needed for items that display text. +The return value from \fBTk_CanvasGetTextInfo\fR is a pointer to +a structure that is shared between Tk and all the items that display +text. +The structure has the following form: +.CS +typedef struct Tk_CanvasTextInfo { + Tk_3DBorder \fIselBorder\fR; + int \fIselBorderWidth\fR; + XColor *\fIselFgColorPtr\fR; + Tk_Item *\fIselItemPtr\fR; + int \fIselectFirst\fR; + int \fIselectLast\fR; + Tk_Item *\fIanchorItemPtr\fR; + int \fIselectAnchor\fR; + Tk_3DBorder \fIinsertBorder\fR; + int \fIinsertWidth\fR; + int \fIinsertBorderWidth\fR; + Tk_Item *\fIfocusItemPtr\fR; + int \fIgotFocus\fR; + int \fIcursorOn\fR; +} Tk_CanvasTextInfo; +.CE +The \fBselBorder\fR field identifies a Tk_3DBorder that should be +used for drawing the background under selected text. +\fIselBorderWidth\fR gives the width of the raised border around +selected text, in pixels. +\fIselFgColorPtr\fR points to an XColor that describes the foreground +color to be used when drawing selected text. +\fIselItemPtr\fR 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. +\fIselectFirst\fR and \fIselectLast\fR give the indices of the first +and last selected characters in \fIselItemPtr\fR, as returned by the +\fIindexProc\fR for that item. +\fIanchorItemPtr\fR points to the item that currently has the selection +anchor; this is not necessarily the same as \fIselItemPtr\fR. +\fIselectAnchor\fR is an index that identifies the anchor position +within \fIanchorItemPtr\fR. +\fIinsertBorder\fR contains a Tk_3DBorder to use when drawing the +insertion cursor; \fIinsertWidth\fR gives the total width of the +insertion cursor in pixels, and \fIinsertBorderWidth\fR gives the +width of the raised border around the insertion cursor. +\fIfocusItemPtr\fR identifies the item that currently has the input +focus, or NULL if there is no such item. +\fIgotFocus\fR is 1 if the canvas widget has the input focus and +0 otherwise. +\fIcursorOn\fR is 1 if the insertion cursor should be drawn in +\fIfocusItemPtr\fR and 0 if it should not be drawn; this field +is toggled on and off by Tk to make the cursor blink. +.PP +The structure returned by \fBTk_CanvasGetTextInfo\fR +is shared between Tk and the type managers; typically the type manager +calls \fBTk_CanvasGetTextInfo\fR 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 \fBconfigure\fR widget command might change the \fIselBorder\fR +field, or a \fBselect\fR widget command might change the \fIselectFirst\fR +field, or Tk might change \fIcursorOn\fR in order to make the insertion +cursor flash on and off during successive redisplays. +.PP +Type managers should treat all of the fields of the Tk_CanvasTextInfo +structure as read-only, except for \fIselItemPtr\fR, \fIselectFirst\fR, +\fIselectLast\fR, and \fIselectAnchor\fR. +Type managers may change \fIselectFirst\fR, \fIselectLast\fR, and +\fIselectAnchor\fR 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 \fIselItemPtr\fR or \fIanchorItemPtr\fR). +If all of the selected text in the item is deleted, the item should +set \fIselItemPtr\fR to NULL to indicate that there is no longer a +selection. + +.SH KEYWORDS +canvas, focus, insertion cursor, selection, selection anchor, text |