\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#97: Moving Vertices of Canvas Items}
\date{June 07, 2002}
\author{Agnar Renolen, 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 \#97}&\textbf{Moving Vertices of Canvas Items}\\\hline
Author&

Agnar Renolen \tipmail{agnar.renolen}{emap.no}
\par
Donal K. Fellows \tipmail{donal.k.fellows}{manchester.ac.uk}
\\
Created&Friday, \(\text{7}^{\text{th}}\) June 2002\\
Type&Project\\
Tcl Version&\(8.6\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.10 $\\
Keywords&Tk\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes a canvas subcommand (or possibly two) that allows for replacing characters in text objects and to move individual vertices of line and polygon items.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Interactive graphics programs often allow users to modify shapes of objects by selecting and dragging the vertices. Moving one vertex of a canvas item in the current version of Tk, (at least as far as I can find out from the documentation), can only be done by first removing the coordinate by \textbf{dchars} and then insert the new one by \textbf{insert}, or for geometric items like lines and polygons using the \textbf{coords} command to obtain and reset the coordinates, after having modified the coordinate list by \textbf{lreplace}.

The most important issue here, I think, is performance. I believe that the current way of moving a vertex can be slow in some scenarios.

The \textbf{rchars} canvas subcommand is proposed merely to conform with the \textbf{dchars} and \textbf{insert} commands, which both operate on lines, polygons and text items, hence \textbf{rchars} should do that as well.

\section{Specification}

Two canvas widget subcommands are proposed: \textbf{imove} and \textbf{rchars}. The following subcommand is proposed to move a vertex of any canvas item:

\begin{quote}
\textit{canvas} \textbf{imove} \textit{tagOrID index x y}
\end{quote}

This subcommand will move the \textit{index}th coordinate of the items identified by \textit{tagOrID} to the new position given by \textit{x} and \textit{y}. The \textit{index} value will be processed according to normal canvas index rules (see the INDICES section of the \textbf{canvas} manual). The subcommand will only work for line and polygon items (or any third party items that set the TK\_MOVABLE\_POINTS flag).

The following command provides a similar functionality, but conforms to the model of the current \textbf{insert} and \textbf{dchars} subcommands.

\begin{quote}
\textit{canvas} \textbf{rchars} \textit{tagOrID first last string}
\end{quote}

This command will:
\begin{description}
\item[for text items]
replace the characters in the range \textit{first} and \textit{last} (inclusive) with the characters in \textit{string}.
\item[for line and polygon items]
replace the coordinates in the range \textit{first} and \textit{last} (inclusive) with the coordinate list specified in \textit{string} (subject to the requirement that the coordinate list is an even number of floating point numbers).
\end{description}

In both cases, \textit{first} and \textit{last} will be processed according to the rules in the INDICES section of the \textbf{canvas} manual page.

At the C level, the only change is the addition of a new flag, \textbf{TK\_MOVABLE\_POINTS}. If this flag is set in the \textit{alwaysRedraw} field of the item type structure, it implies that the item supplies non-NULL \textit{dcharsProc}, \textit{indexProc} and \textit{insertProc} fields, and gives them semantics equivalent to the line and polygon items (i.e. that the methods will work with the coordinate list). Note that text items, despite having all the required methods, do not set the flag because those methods work with character indices.

\subsection{Notes}

The \textbf{imove} subcommand is not strictly necessary as the \textbf{rchars} subcommand can be used to obtain the same result. However, I believe that a separate \textbf{imove} subcommand will be easier to understand for users than the \textbf{rchars} subcommand, though the latter is still necessary as it allows for more complex processing such as insertion or deletion of points.

\section{Reference Implementation}

See Patch 2157629[\url{https://sourceforge.net/support/tracker.php?aid=2157629}].

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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