%% progressbar.tex %% Copyright 2010-2014 Marcel Jira % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3c % of this license or (at your option) any later version. % The latest version of this license is in % http://www.latex-project.org/lppl.txt % and version 1.3c or later is part of all distributions of LaTeX % version 2005/12/01 or later. % % This work has the LPPL maintenance status `maintained'. % % The Current Maintainer of this work is Marcel Jira. % % This work consists of the files progressbar.sty and progressbar.tex. % \documentclass{ltxdoc} \usepackage[T1]{fontenc} \usepackage[utf8]{inputenc} \usepackage[english]{babel} \usepackage{listings} \lstset{basicstyle=\ttfamily\small\mdseries,linewidth=\linewidth,breaklines=true,escapeinside={(*}{*)},} \usepackage{progressbar} \usepackage{hyperref} \title{\texttt{progressbar}} \author{by Marcel Jira} \date{2013/01/06} \begin{document} \maketitle \begin{abstract} This package allows you to easily visualize shares of total amounts in the form of a bar. So basically you can convert a number like $0.735$ to \progressbar{0.735} using the command \lstinline+\progressbar{0.735}+. Of course also a lot of customizations are possible (like this: \progressbar[emptycolor=yellow,filledcolor=red,linecolor=blue,subdivisions=4,roundnessr=0.5,tickscolor=green,tickswidth=1,ticksheight=1]{0.735}). \end{abstract} \noindent\progressbar[width=\textwidth,heighta=3cm,filledcolor=red,emptycolor=green,borderwidth=5pt,tickswidth=2.5pt,roundnessr=0.5,subdivisions=20]{0.55} \begin{lstlisting}[basicstyle=\ttfamily\normalsize\mdseries] \progressbar[width=textwidth, heighta=3cm, filledcolor=red, emptycolor=green, borderwidth=5pt, tickswidth=2.5pt, roundnessr=0.5, subdivisions=20]{0.55} \end{lstlisting} \tableofcontents \section{Installation} Make sure the file \texttt{progressbar.sty} is placed somewhere, where \LaTeX can find it. Usually that means, you simply download the package \texttt{progressbar} with the \LaTeX-package-manager of your choice. \subsection{Dependencies} You also have to ensure that all packages needed by \texttt{progressbar} are present (some package-managers do this for you). The dependencies are: \begin{itemize} \item calc \item kvsetkeys \item kvoptions \item tikz \end{itemize} \section{How to use \texttt{progressbar}} \DescribeMacro{\usepackage\{progressbar\}} \DescribeMacro{\usepackage[]\{progressbar\}} Like any other package, to use \texttt{progressbar}, you have to load it first. You do this with \begin{lstlisting} \usepackage{progressbar} \end{lstlisting} or \begin{lstlisting} \usepackage[]{progressbar} \end{lstlisting} (You can find an explanation of all options in the section \ref{options}.) Once you have loaded \texttt{progressbar}, you can use two different commands, described in the following. \subsection{\texttt{\textbackslash{}progressbar}}\label{commandprogressbar} \DescribeMacro{\progressbar\{\}} \DescribeMacro{\progressbar[]\{\}} The command \begin{lstlisting} \progressbar{} \end{lstlisting} will draw you a progressbar with the share \texttt{}. For example \lstinline+\progressbar{0.666}+ gives you this \progressbar{0.666}. You would want to use only numbers in the interval $[0,1]$, although other numbers are also possible (but will look just the same as \lstinline+\progressbar{0}+ or \lstinline+\progressbar{1}+). If you want one specific progressbar to look different than the others, use \begin{lstlisting} \progressbar[]{} \end{lstlisting} instead. This command is just the same as \lstinline+\progressbar{}+ but allows you to manipulate the appearance of the current progressbar. So \lstinline+\progressbar[width=5cm,heightr=1,filledcolor=red,emptycolor=blue!30]{0.75}+ would look like this: \progressbar[width=5cm,heightr=1,filledcolor=red,emptycolor=blue!30]{0.75}. In this case the options are only changed locally. (You can find an explanation of all options in the section \ref{options}.) \subsection{\texttt{\textbackslash{}progressbarchange}} \DescribeMacro{\progressbarchange\{\}} In principle, the command \lstinline+\progressbar{}+ uses the options specified with \lstinline+\usepackage[]{progressbar}+ or the default options (if an option was not specified). As described in the previous section (\ref{commandprogressbar}), you can override these options with \lstinline+\progressbar[]{}+. However, if you want to change the settings for \emph{all} following progressbar, you can use the command \begin{lstlisting} \progressbarchange{} \end{lstlisting} So basically \begin{lstlisting} \progressbar{0.3}\\ \progressbar[roundnessr=0.5,ticksheight=1,tickswidth=1.5pt]{0.4}\\ \progressbar[roundnessr=0.5,ticksheight=1,tickswidth=1.5pt]{0.5}\\ \progressbar[roundnessr=0.5,ticksheight=1,tickswidth=1.5pt]{0.6} \end{lstlisting} gives you the same as \begin{lstlisting} \progressbar{0.3}\\ \progressbarchange{roundnessr=0.5,ticksheight=1,tickswidth=1.5pt} \progressbar{0.4}\\ \progressbar{0.5}\\ \progressbar{0.6} \end{lstlisting} However, keep in mind that in the second case the options are changed globally. Therefore, all following progressbars will keep the changed design (as long as you don't call \lstinline+\progressbarchange{}+ with other options again). (You can find an explanation of all options in the section \ref{options}.) \section{Options}\label{options} \subsection{Global and local options} You can set global options when you load the \texttt{progressbar} with \lstinline+\usepackage[options]{progressbar}+ and with the command \lstinline+\progressbarchange{}+. These options affect all following calls of the commands \lstinline+\progressbar{}+ and \lstinline+\progressbar[]{}+. However, you can override global options with local options specified with \lstinline+\progressbar[]{}+. \subsection{Options, their defaults and how to change them} All listed options can be used globally and locally. You will notice that some of the options are available with the prefix \texttt{r} (standing for relative) aswell as with the prefix \texttt{a} (standing for absolute). I would recommend you to always use those options with the prefix \texttt{r}, as using absolute values might not interact too well with the rest of your documents settings. But as long as you know what you are doing, it's up to you. \DescribeMacro{heightr} default=\texttt{1}\\ The progressbars height as a fraction of the textheight\footnote{I used the capital letter ``I'' as a reference for the textheight}. \begin{lstlisting} \progressbar[heightr=1]{0.1}A progressbar that has the same height as the text\\ \progressbar[heightr=0.5]{0.9}A progressbar that has half the height \end{lstlisting} \progressbar[heightr=1]{0.1} A progressbar that has the same height as the text\\ \progressbar[heightr=0.5]{0.9} A progressbar that has half the height \DescribeMacro{heighta} default=\texttt{unused}\\ With this option you can define the progressbars height absolutely. \begin{lstlisting} \progressbar[heighta=2cm]{0.3} A progressbar that has the height 2~cm\\ \progressbar[heighta=10pt]{0.7} A progressbar that has the height 10~pt\\ \progressbar[heighta=\heightof{a} + 0.8pt]{0.42} A progressbar whose upper border starts at the same height as the letter "a" \end{lstlisting} \progressbar[heighta=2cm]{0.3} A progressbar that has the height 2~cm\\ \progressbar[heighta=10pt]{0.7} A progressbar that has the height 10~pt\\ \progressbar[heighta=\heightof{a} + 0.8pt]{0.42} A progressbar whose upper border starts at the same height as the letter "a"\footnote{The \texttt{\textbackslash{}heightof} command and the possibility of adding is provided by the package \texttt{calc}} \DescribeMacro{roundnessr} default=\texttt{0.15}\\ \texttt{progressbar} allows rounded corners. With this option you can set them as a fraction of the progressbars height. You would not want to use numbers higher than $0.5$. \begin{lstlisting} \progressbar[roundnessr=0.25]{0.8} More rounder corners than the default\\ \progressbar[roundnessr=0.5]{0.5} In fact no more corners -- complete roundness \end{lstlisting} \progressbar[roundnessr=0.25]{0.8} More rounder corners than the default\\ \progressbar[roundnessr=0.5]{0.5} In fact no more corners -- complete roundness \DescribeMacro{roundnessa} default=\texttt{unused}\\ You can also define the corners radius as absolute values. \begin{lstlisting} \progressbar[roundnessa=2pt]{0} Rounded corners radius 2~pt\\ \progressbar[roundnessa=0cm]{1} No rounded corners \end{lstlisting} \progressbar[roundnessa=2pt]{0} Rounded corners radius 2~pt\\ \progressbar[roundnessa=0cm]{1} No rounded corners \DescribeMacro{width} default=\texttt{6em}\\ The width of the progressbar. \begin{lstlisting} \progressbar[width=5cm]{0.123} Width: 5~cm\\ \progressbar[width=20em]{0.785} Width: 20~em \end{lstlisting} \progressbar[width=5cm]{0.123} Width: 5~cm\\ \progressbar[width=20em]{0.785} Width: 20~em \DescribeMacro{borderwidth} default=\texttt{0.8pt}\\ The linewidth of the progressbars border. \begin{lstlisting} \progressbar[borderwidth=2pt]{0.6} Borderwidth: 2~pt\\ \progressbar[borderwidth=0.025em]{0.3} Borderwidth: 0.025~em \end{lstlisting} \progressbar[borderwidth=2pt]{0.6} Borderwidth: 2~pt\\ \progressbar[borderwidth=0.025em]{0.3} Borderwidth: 0.025~em \DescribeMacro{subdivisions} default=\texttt{10}\\ As you may have noticed, (by default) the progressbar also has ticks. Those ticks splits the progressbar in multiple subdivisions. You can define the number of subdivisions with \texttt{subdivisions=}. Therefore the number of ticks is $\texttt{}-1$. \begin{lstlisting} \progressbar[subdivisions=3]{0.666667} 3 subdivisions and 2 ticks\\ \progressbar[subdivisions=15]{0.466667} 15 subdivisions and 14 ticks \end{lstlisting} \progressbar[subdivisions=3]{0.666667} 3 subdivisions and 2 ticks\\ \progressbar[subdivisions=15]{0.466667} 15 subdivisions and 14 ticks \DescribeMacro{tickswidth} default=\texttt{0.4pt}\\ The linewidth of the ticks. \begin{lstlisting} \progressbar[tickswidth=1mm]{0.55} Tickswidth: 1~mm\\ \progressbar[tickswidth=0.1pt]{0.4} Tickswidth: 0.1~pt \end{lstlisting} \progressbar[tickswidth=1mm]{0.55} Tickswidth: 1~mm\\ \progressbar[tickswidth=0.1pt]{0.4} Tickswidth: 0.1~pt \DescribeMacro{ticksheight} default=\texttt{0.33}\\ The height of the ticks as a fraction of the total progressbars height. \begin{lstlisting} \progressbar[ticksheight=0.1]{0.22} Ticksheight: 10 ~\% of the total height\\ \progressbar[ticksheight=1]{0.88} Ticks are end-to-end \end{lstlisting} \progressbar[ticksheight=0.1]{0.22} Ticksheight: 10 ~\% of the total height\\ \progressbar[ticksheight=1]{0.88} Ticks are end-to-end \DescribeMacro{linecolor} default=\texttt{black} \DescribeMacro{tickscolor} default=\texttt{black} \DescribeMacro{emptycolor} default=\texttt{black!10} \DescribeMacro{filledcolor} default=\texttt{black!60}\\ These options should be self-explaining. Just use \texttt{xcolor}-color-definitions (use color names or the syntax \lstinline+!+) for brighter colors). \begin{lstlisting} \progressbar[linecolor=blue,tickscolor=orange,emptycolor=yellow,filledcolor=red]{0.6} \end{lstlisting} \progressbar[linecolor=blue,tickscolor=orange,emptycolor=yellow,filledcolor=red]{0.6} \section{Changelog} \begin{tabbing} \texttt{2014/05/04 v.1.0b\~{}4} \= version control for kvoptions updated (for unknown\\ \> reason required version didn't exist)\\ \texttt{2013/01/06 v.1.0b\~{}3} \= replaced \lstinline+\progressbar@LoadFile@IfExist+ with\\ \> \lstinline+\RequirePackage+\\ \texttt{2012/02/18 v.1.0b\~{}2} \> added version control for kvoptions\\ \texttt{2010/10/02 v1.0b} \> first release - all basic functionality \end{tabbing} \section{Acknoledgment} A big shoutout to the pros from \url{http://www.mrunix.de/} (it's german). They helped me a lot and made \texttt{progressbar} possible. I also want to thank Robin Schneider (\url{https://ypid.wordpress.com/}) and Heiko Oberdiek who called my attention to the problems with\\ \lstinline+\progressbar@LoadFile@IfExist+. \section{Contact} If you have any question concerning \texttt{progressbar} or if you miss a feature, please write me a mail: \href{mailto:mails4me@gmx.at}{\texttt{mails4me@gmx.at}}. \end{document}