\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#164: Add Rotate Subcommand to the Canvas Widget}
\date{November 17, 2003}
\author{Arjen Markus, Dimitrios Zachariadis, 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 \#164}&\textbf{Add Rotate Subcommand to the Canvas Widget}\\\hline
Author&

Arjen Markus \tipmail{arjen.markus}{wldelft.nl}
\par
Dimitrios Zachariadis \tipmail{dzach}{hol.gr}
\par
Donal K. Fellows \tipmail{donal.k.fellows}{manchester.ac.uk}
\\
Created&Monday, \(\text{17}^{\text{th}}\) November 2003\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.5 $\\
Keywords&Tk, canvas\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes to add a \textit{rotate} subcommand to the canvas widget to facilitate rotating items in very much the same way as is now possible with scaling and moving.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The canvas currently allows a programmer to scale and move items, but the third common affine transformation, rotation, is not supported. This can in itself be simulated by a script (simply get the coordinates of all items involved, transform them and set the new coordinates), but if you have several hundreds or even thousands of items this gets very slow.

Rotation is easy for polygons and lines: simply transform the coordinates. For circles and circular arcs new bounding boxes must be calculated and in addition for arcs the starting angle must be changed.

Implementing rotation should consider what to do with items that can not (easily) be rotated: text items, rectangles, non-circular ovals and arcs, widgets and images. Currently, text can not be drawn at an arbitrary angle, so I propose to only transform the coordinates at which the text is ``anchored''. A similar strategy can be used for widgets and images.

For rectangles and general ovals and arcs there are two choices:
\begin{itemize}
\item{}
Transforming the item into a polygon would solve the definition problem (these items are defined by a bounding box and the orientation is implicitly assumed), but might break scripts that look for a particular type of item.
\item{}
Therefore we will simply calculate a new bounding box and \textit{ignore changes in orientation}.
\end{itemize}

\section{Proposal}

Canvases will have a new subcommand, \textbf{rotate}, which will rotate the coordinates of chosen items by a specified angle about a specified point.

\begin{quote}
\textit{canvas} \textbf{rotate} \textit{itemOrTag} \textit{x} \textit{y} \textit{angle}
\end{quote}

Note that most of the arguments are very similar to the canvas's \textbf{scale} subcommand. \textit{Angle} is measured in degrees, with positive values indicating anti-clockwise rotation.

\subsection{Canvas Item C API Alterations}

[These are required for this TIP, but are not yet done.]

\section{Reference Implementation}

A reference implementation does \textit{not} yet exist.

\section{Future Work}

Should we also consider the possibility of reflections in a line?

Should we also consider more general linear transformations (to be specified via a 2x2 matrix)? What about full affine transformations (i.e. with the translation components)?

If we implement these from the start, we need to do only a little more work.

\section{Comments}

It might be useful to utilize the -anchor Tk option in all canvas items and add a new ``-anchoroffset \$x,\$y'' option, where \$x \$y be canvas distances relevant to the anchor position. Once defined, or with their default values, the -anchor and -anchoroffset values combined will provide the item's center, for placement and rotation purposes. Item sets, constituting symbols, can then be manipulated easily.

It could probably be beneficial to add an -angle option (and an accomplanying -angleunit one), to persist a rotation angle in the configuration database. The presence of an angle value other than zero would help negate rotation, thus re-instating the item to its initial orientation.

\section{Copyright}

This document is placed in the public domain.

\section{Colophon}

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