summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/progressbar/progressbar.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/progressbar/progressbar.tex')
-rw-r--r--macros/latex/contrib/progressbar/progressbar.tex242
1 files changed, 242 insertions, 0 deletions
diff --git a/macros/latex/contrib/progressbar/progressbar.tex b/macros/latex/contrib/progressbar/progressbar.tex
new file mode 100644
index 0000000000..e398033da8
--- /dev/null
+++ b/macros/latex/contrib/progressbar/progressbar.tex
@@ -0,0 +1,242 @@
+%% 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[<options>]{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{<number>}
+\end{lstlisting}
+will draw you a progressbar with the share \texttt{<number>}. 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[<options>]{<number>}
+\end{lstlisting}
+instead. This command is just the same as \lstinline+\progressbar{<number>}+ 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{<number>}+ uses the options specified with \lstinline+\usepackage[<options>]{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[<options>]{<number>}+. However, if you want to change the settings for \emph{all} following progressbar, you can use the command
+\begin{lstlisting}
+\progressbarchange{<options>}
+\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{<options>}+ 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{<options>}+. These options affect all following calls of the commands \lstinline+\progressbar{<number>}+ and \lstinline+\progressbar[<options>]{<number>}+.
+
+However, you can override global options with local options specified with \lstinline+\progressbar[<options>]{<number>}+.
+
+\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=<number>}. Therefore the number of ticks is $\texttt{<number>}-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+<color-name>!<number between 0 and 100>+) 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}