\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#442: Display text in progressbars}
\date{February 17, 2016}
\author{Ren\'{e} Zaumseil, Kevin B Kenny, Andreas Leitgeb, Kevin Kenny}
\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 \#442}&\textbf{Display text in progressbars}\\\hline
Author&

Ren\'{e} Zaumseil \tipmail{rzaumseil}{kkg.ch}
\par
Kevin B Kenny \tipmail{kevin.b.kenny}{gmail.com}
\par
Andreas Leitgeb \tipmail{avl}{logic.at}
\par
Kevin Kenny \tipmail{Kevin.B.Kenny}{gmail.com}
\\
Created&Wednesday, \(\text{17}^{\text{th}}\) February 2016\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.11 $\\
Keywords&Tk\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

Horizontal progress bars should support the ability to display text inside the progress bar. Buttons should allow justification of multiline texts.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

It is often useful to be able to display text directly on top of a progress bar. This text might be a description of the progress percentage, what is currently being done, or even just a label giving the overall task that is progressing.

The \textbf{ttk::progressbar} command can easily enhanced to provide this support, and there is no interference with existing code as this functionality can be done by just introducing new options. The options required are from the list of usual Tk well-known option names.

Also the \textbf{ttk::button} command can easily be enhanced to provide justification of multiline text.

\section{Specification}

Text will be displayed only on horizontal \textbf{ttk::progressbar}. To control the text appearance the following new options will be added:
\begin{description}
\item[-text]
The string to display.
\item[-font]
The font used to render the text.
\item[-foreground]
The color of the text.
\item[-anchor]
The anchoring of the text.
\item[-justify]
The justification of the string.
\item[-wraplength]
The length at which the string will be automatically wrapped.
\end{description}

To justify multiline text in \textbf{ttk::button} a new option will be added:
\begin{description}
\item[-justify]
The justification of the string.
\end{description}

\section{Notes for future improvements}

The underlying Tk text rendering engine supports rotated text, which would make support on vertical progress bars possible. But control of the rotation angle might be required (according to whether the text is rotated left or right, or stays unrotated).

The most contrasting color of the text will depend where on the progress bar it is placed. This is not an effect that is simply reproduced with the Tk script level, but is easy to apply during rendering.

\section{Implementation}

A patch implementing these changes and updating the documentation is available in the fossil repository in the tip-442 branch.

Implementation is heavily borrowed from the \textbf{ttk::label} widget featuring these same options. The names, meanings, and default values of the options are the same as for \textbf{ttk::label}. The rendering and processing is the same as for this latter widget.

\section{Example of use}
\begingroup\small\begin{verbatim}
    package require Tk
    proc moveit {} {
      for {set i 0} {$i < 100} {incr i} {
        .p step ; update ; after 100
      }
    }
    pack [ttk::progressbar .p -value 0 -maximum 50 -orient horizontal -length 500]
    .p configure -anchor c -foreground blue -justify right \
            -text "-anchor c -foreground blue -justify right -wraplength 100" \
            -wraplength 100
    moveit
    .p configure -anchor e -font {Arial 10 bold} -foreground green -justify center \
            -text "-anchor e -font {Arial 10 bold} -foreground green -justify center -wraplength 250" \
            -wraplength 250
    moveit
    .p configure -text "-anchor w -foreground red -justify left -wraplength 50" \
            -anchor w -foreground red -justify left -wraplength 50
    moveit
    .p configure -orient vertical -text "Cannot be seen"
    moveit
\end{verbatim}
\endgroup

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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