\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#119: Angled Text on a Canvas}
\date{November 18, 2002}
\author{Simon Geard, Donal K. Fellows}
\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 \#119}&\textbf{Angled Text on a Canvas}\\\hline
Author&

Simon Geard \tipmail{simon.geard}{ntlworld.com}
\par
Donal K. Fellows \tipmail{donal.k.fellows}{manchester.ac.uk}
\\
Created&Monday, \(\text{18}^{\text{th}}\) November 2002\\
Type&Project\\
Tcl Version&\(8.6\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.8 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

The current text object on a canvas does not support the creation of text strings at an arbitrary angle. For some applications this is limitation is sufficiently serious to disqualify Tk from use. This TIP removes this restriction.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Using a Tk canvas to display e.g. an engineering drawing from a CAD application is limited --- such applications will output angled text and there is simply no way of displaying such text on a canvas.

Another consideration is the competition. Both Qt and Java canvas objects support angled text on their canvas object --- most new users would I believe be surprised to discover that this functionality is not supported.

Due to the internal architecture of Tk a side effect of this work would be to enable buttons (and possibly other widgets) to have their text written at an angle as well. This TIP does not expose that functionality.

\section{Implementation}

At the command level there would be an extra attribute, \textit{-angle}, added to the canvas's text object:
\begingroup\small\begin{verbatim}
<canvas> create text <x> <y> -text <str> ?-angle <angle>? ...
\end{verbatim}
\endgroup

where the angle is specified in degrees. Manipulation of the angle would be done in the usual way through the \textit{itemconfigure} and \textit{itemcget} subcommands:
\begingroup\small\begin{verbatim}
<canvas> itemconfigure <tag> -angle <angle>
\end{verbatim}
\endgroup

Note that PostScript naturally supports rotation of text.

\section{Reference Implementation}

I have done an initial assessment of the amount of work required and have and have created a patch to implement it in Tk 8.4.5 . This initial work was fairly straightforward but the internal housekeeping work maintaining and interacting with an angled box will be more substantial. The patch (uploaded to SourceForge [\url{http://sf.net/tracker/?func=detail&aid=1611359&group_id=12997&atid=312997}]) is for X only. It doesn't use any X extensions and should work for X11R3 and above. I don't know how it would be done on non-X systems but hopefully they'll (Win \& MacOS at least) provide native tools to make their implementation straightforward as well.

\subsection{Implementation Notes}

The implementation was tricky to develop, because it was wholly different on each rendering platform (X11 is two, depending on which font rendering engine is used). This delayed implementation of this TIP for a whole release.
\begin{description}
\item[Classic X11]
Uses a general monochrome pixmap rotation engine.
\item[X11 + Xft]
Generates rotated versions of the fonts by installing a rotation matrix, caching them in the subfont management engine.
\item[Win32]
Generates rotated versions of the fonts using the built-in font rotation suport, caching them in the subfont management engine.
\item[MacOS X]
Applies the rotation to the Current Transformation Matrix immediately before rendering.
\end{description}

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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