TIP 96: Add [tk caret] Command and Tk_SetCaretPos API

Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2017 Conference, Houston/TX, US, Oct 16-20
Send your abstracts to tclconference@googlegroups.com
by Aug 21.
Author:		Jeff Hobbs <JeffH@ActiveState.com>
State:		Final
Type:		Project
Created:	29-May-2002
Tcl-Version:	8.4
Vote:		Done


This TIP proposes to add a [tk caret] command and [TkSetCaretPos] C API to manage _carets in Tk. caret is the term for where text of graphics will be inserted. It is necessary for correct accessibility functionality (to know where to shift focus), and for location the IME or XIM input box to handle complex character input (e.g. Asian character sets).


Tk has up until now not managed the caret within its windows. This has led to it being not Windows Accessibility certifiable. On Windows, this also cause the IME window to show in the top-left corner of the window (somewhat OK for entries, bad for text widgets). On X, this meant that Tk had to use the root-window style XIM input, which is a poor second to over-the-spot XIM input. Managing the caret corrects these problems.

Exposing the functionality at the Tcl level allows extension writers to use the functionality without having to make Tk version API checks. A simple

   catch {tk caret $w -x $x -y $y}

will suffice to work across versions.


   tk caret window ?-x xPos? ?-y yPos? ?-height height?
   void Tk_SetCaretPos (Tk_Window tkwin, int x, int y, int height)

-height specifies the height of the input line and is important because Windows and X interpret the x,y coordinates differently (top-left and bottom-left respectively), so it must be adjusted by height for X. If no height is specified, the height of the window passed in will be used.

I chose to use the -option value format because it allows for future extensibility. There are APIs to control the font and other aspects of the IME/XIM input window that appears, but management of these is not covered in this tip.

Reference Implementation

The Tk_SetCaretPos implementation is currently in the core. It needs to be modified to move the caret information to be per display, instead of per process.

File: tk/mac/tkMacXStubs.c

File: tk/win/tkWinX.c

File: tk/unix/tkUnixKey.c

Function: Tk_SetCaretPos


The current implementation at the C level was implemented with the assistance of Keiichi Takahashi (BitWalk), Koiichi Yamamoto, Moo Kim (NCR), and Mike Fabian (SuSE). It has been tested on Windows 98/2000/XP and SuSE 7.3 using kinput/canna2.


This document has been placed in the public domain.