TIP #96: Add [tk caret] Command and Tk_SetCaretPos API
_____________________________________________________________________________
TIP:	96
Title:	Add [tk caret] Command and Tk_SetCaretPos API
Version:	$Revision: 1.4 $
Authors:	Jeff Hobbs <JeffH@ActiveState.com>
State:	Final
Type:	Project
Tcl-Version:	8.4
Vote:	Done
Created:	Wed May 29 00:00:00 UTC 2002
Abstract
This TIP proposes to add a [[tk caret]] command and [[Tk_SetCaretPos]] 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).
Rationale
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.
Specification
   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
Comments
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.
Copyright
This document has been placed in the public domain.
_____________________________________________________________________________
Colophon
TIP AutoGenerator - written by Donal K. Fellows