Tk_CanvasTextInfo(3tk)

✨ Tk_CanvasTextInfo ✨

okay bestie, welcome to Tk_CanvasTextInfo from the Tk Library Procedures 💅 this one's all about the extra info you need when your canvas items are doing text — think selection drama, input focus, blinking cursors, the whole main character situation 👑

---

🌸 NAME 🌸

Tk_CanvasTextInfo — additional information for managing text items in canvases 💖

---

🎀 SYNOPSIS 🎀

#include <tk.h>

Tk_CanvasTextInfo *
Tk_CanvasGetTextInfo(canvas)

---

🦋 ARGUMENTS 🦋

• Tk_Canvas canvas (in) — a token that identifies a particular canvas widget. it's giving "which canvas are we talking about" energy fr fr

---

💖 DESCRIPTION 💖

so like, textual canvas items? lowkey more complicated to manage than the other items 😭 because of things like the selection and the input focus. that's just the vibe.

Tk_CanvasGetTextInfo can be called by a type manager to grab the extra info it needs for items that display text. the return value is a pointer to a structure that's shared between Tk and all the items that display text 🫶 no cap. the structure looks like this:

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

let's go field by field, bestie, because every single one of these matters 👇

• selBorder — identifies a Tk_3DBorder that you should use for drawing the background under selected text ✨
• selBorderWidth — the width, in pixels, of the raised border around selected text.
• selFgColorPtr — points to an XColor describing the foreground color to use when drawing selected text 🎨
• selItemPtr — points to the item that's currently selected, or NULL if there's no item selected, or if the canvas doesn't have the selection 💀
• selectFirst and selectLast — the indices of the first and last selected characters in selItemPtr, exactly as returned by the indexProc for that item.
• anchorItemPtr — points to the item that currently has the selection anchor. heads up: this is not necessarily the same as selItemPtr 👀
• selectAnchor — an index identifying the anchor position within anchorItemPtr.
• insertBorder — contains a Tk_3DBorder to use when drawing the insertion cursor.
• insertWidth — the total width of the insertion cursor in pixels.
• insertBorderWidth — the width of the raised border around the insertion cursor.
• focusItemPtr — identifies the item that currently has the input focus, or NULL if there's no such item.
• gotFocus — 1 if the canvas widget has the input focus, and 0 otherwise.
• cursorOn — 1 if the insertion cursor should be drawn in focusItemPtr, and 0 if it should not be drawn. Tk toggles this field on and off to make the cursor blink ✨ iconic behaviour honestly

---

the structure returned by Tk_CanvasGetTextInfo is shared between Tk and the type managers 🌈 typically the type manager calls Tk_CanvasGetTextInfo once when an item is created, then saves the pointer in the item's record. Tk will update the info in the Tk_CanvasTextInfo for you — for example, a configure widget command might change the selBorder field, or a select widget command might change the selectFirst field, or Tk might change cursorOn so the insertion cursor flashes on and off during successive redisplays 💫

⚠️ okay important one, bestie: type managers should treat all the fields of the Tk_CanvasTextInfo structure as read-only — with exactly four exceptions: selItemPtr, selectFirst, selectLast, and selectAnchor. that's the whole list, don't get creative 🙈

type managers may change selectFirst, selectLast, and 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 selItemPtr or anchorItemPtr 👑. and if all the selected text in the item gets deleted, the item should set selItemPtr to NULL to indicate there's no longer a selection. periodt. 💅

---

🔥 KEYWORDS 🔥

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

---

and that's the whole page, gorgeous 🫶 this was Tk version 4.0, dated with Tk_CanvasTextInfo(3tk) — go forth and manage your text items, you've absolutely got this 💜✨