% !TeX spellcheck = en_US
% !TeX root = tikz-ext-manual.tex
% Copyright 2022 by Qrrbrbirlbel
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
\clearpage
\section{Scaling Pictures to a Specific Size}
\label{library:scalepicture}

\begin{tikzlibrary}{ext.scalepicture}
  This library scales \tikzname\ pictures to a specific width or height
  by scaling the whole picture.
\end{tikzlibrary}

\begin{multicols}{2}
If one of the keys below are used on a \tikzname\ picture, i.\,e.
as an option to |\tikzpicture| or \texttt{\textbackslash begin\{tikzpicture\}}
the size of the picture\footnote{This is the size of the pseudo-node \texttt{current bounding box}.}
will be measured and written to the \filetype{aux} file
so that it will be available at the next compilation run
and an appropriate scaling for the picture can be installed.

\begin{command}{\tikzextpicturewidth}
  Returns the last measured width of the picture.
  
  This will expand to |0pt| if the picture hasn't been measured before.
\end{command}
\begin{command}{\tikzextpictureheight}
  Returns the last measured height of the picture.
  
  This will expand to |0pt| if the picture hasn't been measured before.
\end{command}

\begin{stylekey}{/tikz/save picture size}
  This key is usually used by the keys provided by this library.
  Normally, this is not needed to be explicitly given.
\end{stylekey}
\subsection{Keeping the aspect ratio}
The following \emph{unstarred} keys do not change the aspect ratio of the picture.

\begin{key}{/tikz/picture width=\meta{dimension}}
  Scales the picture so that the width of the picture will be \meta{dimension}.
  This will keep the aspect ratio the same.
\end{key}

\begin{key}{/tikz/minimum picture width=\meta{dimension}}
  As above but will not change the size of the picture
  if its width is greater than \meta{dimension}.
\end{key}

\begin{key}{/tikz/maximum picture width=\meta{dimension}}
  As above but will not change the size of the picture
  if its width is less than \meta{dimension}.
\end{key}

\begin{key}{/tikz/picture height=\meta{dimension}}
  Scales the picture so that the height of the picture will be \meta{dimension}.
  This will keep the aspect ratio the same.
\end{key}

\begin{key}{/tikz/minimum picture height=\meta{dimension}}
  As above but will not change the size of the picture
  if its height is greater than \meta{dimension}.
\end{key}

\begin{key}{/tikz/maximum picture height=\meta{dimension}}
  As above but will not change the size of the picture
  if its height is less than \meta{dimension}.
\end{key}

\begin{key}{/tikz/minimum picture size=\marg{width}\marg{height}}
  Scales the picture so that its height will be at least \meta{width}
  and its height will be at least \meta{height}.
\end{key}

\begin{key}{/tikz/maximum picture size=\marg{width}\marg{height}}
  Scales the picture so that its height will be at most \meta{width}
  and its height will be at most \meta{height}.
\end{key}

\subsection{Changing the aspect ratio.}
The following \emph{starred} keys do change the aspect ratio.
\begin{key}{/tikz/picture width*=\meta{dimension}}
  Scales the picture so that the width of the picture will be \meta{dimension}.
  This will only scale the $x$ axis.
\end{key}

\begin{key}{/tikz/minimum picture width*=\meta{dimension}}
  As above but will not change the size of the picture
  if its width is greater than \meta{dimension}.
\end{key}

\begin{key}{/tikz/maximum picture width*=\meta{dimension}}
  As above but will not change the size of the picture
  if its width is less than \meta{dimension}.
\end{key}

\begin{key}{/tikz/picture height*=\meta{dimension}}
  Scales the picture so that the height of the picture will be \meta{dimension}.
  This will only scale the $y$ axis.
\end{key}

\begin{key}{/tikz/picture size*=\marg{width}\marg{height}}
  Scales the picture so that its width will be \meta{width}
  and its height will be \meta{height}.
  
  This will scale both axes but independent from each other.
\end{key}
\end{multicols}