% \iffalse
%%
%% File: mboxfill.dtx Copyright (C) 2005 by Alexander I. Rozhenko
%%
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{mboxfill}
%<package>      [2005/05/13 v1.0 Fill space with mbox (NCC)]
%
% \changes{v1.0}{2005/05/13}{This version was uploaded to CTAN}
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{mboxfill}
\GetFileInfo{mboxfill.sty}
\begin{document}
\title{The \textsf{mboxfill} package\thanks{This file
        has version number \fileversion, last
        revised \filedate.}}
\author{Alexander I. Rozhenko\\rozhenko@oapmg.sscc.ru}
\date{\filedate}
\maketitle
\DocInput{mboxfill.dtx}
\end{document}
%</driver>
% \fi
%
% \section{User Interface}
%
% \DescribeMacro\mboxfill
% This package implements the command
% \begin{quote}
% |\mboxfill|\oarg{width}\oarg{leader-type}\marg{pattern}
% \end{quote}
% filling a free horizontal space with \meta{pattern}.
%
% The \meta{width} parameter specifies a width of box pattern
% to be used as leaders. If it is omitted, the pattern width is used.
% The |\width|, |\height|, |\depth|,
% and |\totalheight| macros can be used in this parameter.
% Length expressions are also allowed if the \textsf{calc}
% package is loaded.
%
% The \meta{leader-type} parameter specifies a type of leaders
% to be used: |c| means |\cleaders|, |x| means |\xleaders|, and
% empty value (default) means |\leaders|. Depending on type, an
% extra space is distributed between fill entries as follows:
% in |c| case, fill entries are centered, in |x| case, fill entries
% are uniformly distributed, and in other cases, fill entries are
% aligned to the multiple of their width counted from the
% left boundary of filled box.
%
% When the specified \meta{width} differs from the pattern
% width, the pattern is centered inside the box to fill with.
% As a consequence, when |x|-leaders are used, a bit of space
% will be left from both sides of fill area. To remove this
% space, use the special value of \meta{leader-type} parameter,
% namely |s|.
%
% Example:
% \begin{quote}
% |\noindent\mboxfill{*}\mbox{}\\|\\
% |\mbox{}\mboxfill[2\width]{+}\mbox{}\\|\\
% |\mbox{}\mboxfill[2\width]{\hfill+}\mbox{}\\|\\
% |\mbox{}\mboxfill[2\width]{+\hfill}\mbox{}\\|\\
% |A text\mboxfill[1.5\width]{*}\mbox{}\\|\\
% |\mbox{}\mboxfill[1.5\width]{*}\mbox{}\\|\\
% |\mbox{}\mboxfill[1.5\width][c]{*}\mbox{}\\|\\
% |\mbox{}\mboxfill[1.5\width][x]{*}\mbox{}\\|\\
% |\mbox{}\mboxfill[1.5\width][s]{*}\mbox{}\\[-2ex]|\\
% |\mbox{}\hrulefill|
% \end{quote}
% It produces the following:
%
% \noindent\mboxfill{*}\mbox{}\\
% \mbox{}\mboxfill[2\width]{+}\mbox{}\\
% \mbox{}\mboxfill[2\width]{\hfill+}\mbox{}\\
% \mbox{}\mboxfill[2\width]{+\hfill}\mbox{}\\
% A text\mboxfill[1.5\width]{*}\mbox{}\\
% \mbox{}\mboxfill[1.5\width]{*}\mbox{}\\
% \mbox{}\mboxfill[1.5\width][c]{*}\mbox{}\\
% \mbox{}\mboxfill[1.5\width][x]{*}\mbox{}\\
% \mbox{}\mboxfill[1.5\width][s]{*}\mbox{}\\[-2ex]
% \mbox{}\hrulefill
%
% \StopEventually{}
%
% \section{The Implementation}
%
%    \begin{macrocode}
%<*package>
\newcommand*\mboxfill[1][\width]{%
  \def\@tempa{\setlength\@tempdima{#1}}%
  \@ifnextchar[{\NCC@mboxfill}{\NCC@mboxfill[]}%
}
\def\NCC@mboxfill[#1]#2{%
  \@begin@tempboxa\hbox{#2}%
%    \end{macrocode}
% Set the required box width in |\@tempdima|:
%    \begin{macrocode}
    \@tempa
%    \end{macrocode}
% Test the case of |s|-leaders. They work like |x|-leaders,
% but a special kern is added to both sides of the fill area
% to compensate extra-space added in the box.
%    \begin{macrocode}
    \edef\@tempa{#1}\def\@tempb{s}%
    \ifx\@tempa\@tempb
      \@tempdimb\width
      \advance\@tempdimb -\@tempdima
      \let\@tempa\xleaders
      \def\@tempb{\kern.5\@tempdimb}%
    \else
%    \end{macrocode}
% Other cases: if leader-type is incorrect, we use |\leaders|.
%    \begin{macrocode}
      \@ifundefined{#1leaders}{\let\@tempa\leaders}%
      {\def\@tempa{\csname#1leaders\endcsname}}%
      \let\@tempb\@empty
    \fi
%    \end{macrocode}
% |\@tempa| contains required leaders, |\@tempb| is a kern or empty.
% Fill the space.
%    \begin{macrocode}
    \leavevmode\@tempb\@tempa
      \hb@xt@\@tempdima{\hss\unhbox\@tempboxa\hss}\hfill\@tempb
  \@end@tempboxa
}
%</package>
%    \end{macrocode}
\endinput
