\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#415: Enable Easy Creation of Circular Arc Segments}
\date{October 16, 2012}
\author{Simon Geard}
\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 \#415}&\textbf{Enable Easy Creation of Circular Arc Segments}\\\hline
Author&

Simon Geard \tipmail{simon}{whiteowl.co.uk}
\\
Created&Tuesday, \(\text{16}^{\text{th}}\) October 2012\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.11 $\\
Keywords&Tk\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

Creating a segment of a circular arc is unnecessarily difficult using the \textbf{canvas} arc. This TIP proposes a simple extension of the syntax to support the creation of circular arc segments in a natural way. A similar extension to support the more general elliptical arc segments is outside the scope of this TIP.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

There is scope to enhance arc creation to make it much more useful as was shown by a recent discussion on \url{news:comp.lang.tcl.} The proposal here is the simplest enhancement to enable creation of circular arc segments from a single parameter.

\section{Proposal}

Enhance arc creation to support a new \textbf{-height} option

\begin{quote}
\textit{canvas} \textbf{create arc} \textit{x1 y1 x2 y2} \textbf{-height} \textit{h} ?\textit{options}?
\end{quote}

The new option \textbf{-height} \textit{h} causes the specified coordinates \textit{x1 y1} and \textit{ x2 y2} to be interpreted as the start and end points of the arc's chord. The value of \textit{h} is the (canvas) distance of the arc's mid-point from the chord with the sign of \textit{h} determining the direction of the arc:

\textit{h} \tiprangle{} 0 =\tiprangle{} clockwise \textit{h} \tiplangle{} 0 =\tiprangle{} anticlockwise

If \textit{h} != 0 then the options \textit{-start} and \textit{-extent} are ignored (because they are calculated internally for a given \textit{h}).

Any non-zero value of \textit{h} defines a unique arc.

If \textit{h} = 0 (exactly) the option is ignored and the command is processed as if it wasn't present. In addition

\begin{quote}
\textit{canvas} \textbf{itemcget} \textit{tagOrId} \textit{-{}-height}'
\end{quote}

will always return 0. This behaviour enables introspection without complications. A consequence is that

\begin{quote}
\textit{canvas} \textbf{itemconfigure} \textit{tagOrId} \textit{-{}-height}' \textit{0}
\end{quote}

 is a no-op.

\section{Example}

The following code shows the creation of arcs using the new method, copying them onto another canvas and using a \textbf{scale} widget to dynamically control the arcs
\begingroup\small\begin{verbatim}
# Callback for modifying the arcs' h value
proc deltaHeight {h} {
	global c
	global arcList
	foreach {i hp hm} $arcList {
		$c itemconfigure a_$i -height [expr {$h*$hp}]
		$c itemconfigure b_$i -height [expr {$h*$hm}]
	}
}

# Create the canvas and its duplicate
set c [canvas .c -width 700 -height 700 -bg grey]
set cc [canvas .cc -width 700 -height 700 -bg grey]
pack $c $cc -fill both -expand 1 -side left

# Pretty colours
array set colours {0 red 1 yellow 2 green 3 cyan 4 blue 5 magenta}

# A slider with which to adjust h
set lh 1; # Initial setting for scale
set s [scale .s -from 0.1 -to 15 -resolution 0.1 -variable lh -orient vertical -length 700 -command deltaHeight]
pack $s -side right -fill y

# Create the arcs
for {set i 1} {$i <= 24} {incr i} {
	set col [expr {$i % 6}]
	set hp [expr {$i*10}]
	set hm [expr {-$i*10}]
	lappend arcList $i $hp $hm
	$c create arc 300 200 400 400 -height [expr {$i*10}] -outline $colours($col) -style arc -tags [list aa a_$i]
	$c create arc 300 200 400 400 -height [expr {-$i*10}] -outline $colours($col) -style arc -tags [list aa b_$i]
}

# Serialize
set fh [open "ccopy.tcl" w]
foreach id [$c find withtag aa] {
    puts $fh "\$cc create arc [$c coords $id] \
		-height [$c itemcget $id -height]\
		-start [$c itemcget $id -start] \
		-extent [$c itemcget $id -extent] \
		-outline [$c itemcget $id -outline] \
		-style [$c itemcget $id -style]"
}
close $fh

# Create copy from serialization
source "ccopy.tcl"
\end{verbatim}
\endgroup

\section{Reference Implementation}

A reference implementation for the functionality is available.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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