TIP:		96
Title:		Add [tk caret] Command and Tk_SetCaretPos API
Version:	$Revision: 1.4 $
Author:		Jeff Hobbs <JeffH@ActiveState.com>
State:		Final
Type:		Project
Created:	29-May-2002
Tcl-Version:	8.4
Vote:		Done
Post-History:	

~ 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.
