\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#96: Add [tk caret] Command and Tk\_SetCaretPos API}
\date{May 29, 2002}
\author{Jeff Hobbs}
\urlstyle{sf}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0pt}
\def\tipversion$#1${\texttt{\$#1\$}}
\def\tiplangle#1{\ensuremath{<}}
\def\tiprangle#1{\ensuremath{>}}
\def\tipbar#1{\ensuremath{|}}
\def\tipmail#1#2{\(\langle\){\small\expandafter\url{#1@#2}}\(\rangle\)}
\ifx\pdfoutput\undefined
\newcommand{\tipimage}[2]{\typeout{Make sure you download #1.eps}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.eps}}{\includegraphics[width=0.8\textwidth]{#1.eps}}}
\newcommand{\tipxref}[1]{}
\newcommand{\tipxrefend}{}
\else
\newcommand{\tipimage}[2]{\typeout{Make sure you create #1.pdf}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.pdf}}{\includegraphics[width=0.8\textwidth]{#1.pdf}}}
\pdfcatalog{/PageMode /UseOutlines}
\newcommand{\tipxref}[1]{\pdfannotlink attr {/C [0.5 0.5 1.0] /Border [0 0 1]} goto name {#1}}
\newcommand{\tipxrefend}{\pdfendlink}
\fi
\newenvironment{tipabstract}{\begin{abstract}}{\end{abstract}}
\begin{document}\maketitle
\begin{center}\begin{tabularx}{\linewidth}{|r@{: }X|}\hline
\textbf{TIP \#96}&\textbf{Add [tk caret] Command and Tk\_SetCaretPos API}\\\hline
Author&

Jeff Hobbs \tipmail{JeffH}{ActiveState.com}
\\
Created&Wednesday, \(\text{29}^{\text{th}}\) May 2002\\
Type&Project\\
Tcl Version&\(8.4\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.4 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes to add a [tk caret] command and [Tk\_SetCaretPos] C API to manage \textit{carets} in Tk. \textit{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).
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{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
\begingroup\small\begin{verbatim}
   catch {tk caret $w -x $x -y $y}
\end{verbatim}
\endgroup

will suffice to work across versions.

\section{Specification}
\begingroup\small\begin{verbatim}
   tk caret window ?-x xPos? ?-y yPos? ?-height height?
   void Tk_SetCaretPos (Tk_Window tkwin, int x, int y, int height)
\end{verbatim}
\endgroup

\textit{-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 \textit{-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.

\section{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: \textit{tk/mac/tkMacXStubs.c}

File: \textit{tk/win/tkWinX.c}

File: \textit{tk/unix/tkUnixKey.c}

Function: \textit{Tk\_SetCaretPos}

\section{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.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\end{document}
