summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/progressbar/progressbar.tex
blob: e398033da894746478960dfbe383c92102ce69d2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
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}