sphinxpackageboxes.sty

%% COLORED BOXES
%
% change this info string if making any custom modification
\ProvidesPackage{sphinxpackageboxes}[2022/07/04 v5.1.0 advanced colored boxes]
% Optionally executes \RequirePackage for:
%
% - pict2e.  Ideally we would need a recent version of this package which
%   allows dimensional arguments to its \moveto, \lineto, etc...  but we add
%   ourselves some wrappers equivalent to its v0.4a 2020/08/16 version.


% WIP
% Currently provides
% - box registers \spx@tempboxa, \spx@tempboxb usable in other places
\newbox\spx@tempboxa
\newbox\spx@tempboxb
% - Internal dimens, conditionals, and color parameters
\newif\ifspx@boxes@nobackgroundcolor\spx@boxes@nobackgroundcolortrue
\newif\ifspx@boxes@noshadow         \spx@boxes@noshadowtrue
\newif\ifspx@boxes@noshadowcolor    \spx@boxes@noshadowcolortrue
\newif\ifspx@boxes@nobordercolor    \spx@boxes@nobordercolortrue
%
\newdimen\spx@boxes@border
\newdimen\spx@boxes@border@top
\newdimen\spx@boxes@border@right
\newdimen\spx@boxes@border@bottom
\newdimen\spx@boxes@border@left
%
\newdimen\spx@boxes@padding@top
\newdimen\spx@boxes@padding@right
\newdimen\spx@boxes@padding@bottom
\newdimen\spx@boxes@padding@left
%
\newdimen\spx@boxes@shadow@xoffset
\newdimen\spx@boxes@shadow@yoffset
%
\newdimen\spx@boxes@radius@topleft % only circular arcs, x-radius same as y-radius
\newdimen\spx@boxes@radius@topright
\newdimen\spx@boxes@radius@bottomright
\newdimen\spx@boxes@radius@bottomleft
% colors be defined by \colorlet or other methods:
% spx@boxes@backgroundcolor, spx@boxes@shadowcolor, spx@boxes@bordercolor

%%%%%%%%%%%%%%%%
% MACROS
%
% - \spx@boxes@fcolorbox (4 padding parameters, 4 border widths, 2 shadow widths,
%   and three colors: background, border and shadow; same as in CSS styling)
%
% - \spx@boxes@fcolorbox@insetshadow (same as in CSS styling)
%
% - \spx@boxes@fcolorbox@rounded (used for code-blocks): rounded corners using
%   the picture mode and pict2e package for access to PDF graphics

% This interface is WIP
% MEMO: we have also successfully tested usage of tcolorbox's \tcbox but
% decided to use pict2e.sty for the following reasons:
% 1- an order of magnitude faster for what we want to do,
% 2- orders of magnitude smaller dependency (tcolorbox uses the pgf TeX
%    framework)
% 3- possibility to accomplish already quite fancy boxes with pict2e
%    (and the additional coding as contributed here).

% In this first installment, the caption and continuation hints of code-blocks
% when using \spx@boxes@fcolorbox@rounded
% are done exactly as formerly; only difference is in the rounded corners.
% The space occupied is same, if nothing else is changed.

\def\spx@RequirePackage@PictIIe{%
\IfFileExists{pict2e.sty}
   {\RequirePackage{pict2e}}
   {\PackageWarningNoLine{sphinx}{%
       The package pict2e is required for rounded boxes.\MessageBreak
       It does not seem to be available on your system.\MessageBreak
       The verbatimradius setting will thus be ignored}%
    \AtEndDocument{\PackageWarningNoLine{sphinx}{%
       I issued a warning which may have gotten lost in the\MessageBreak
       gigantic console output: pict2e.sty was not found,\MessageBreak
       and verbatimradius has been ignored}}%
   \def\spx@boxes@fcolorbox@rounded{\spx@boxes@fcolorbox}%
   }%
}%


%//// \spx@boxes@fcolorbox
% This box will have the same baseline as its argument (which is typeset in
% horizontal mode).  It takes into account four border widths parameters, four
% padding parameters, two shadow widths (each possibly negative), and three
% colors: background, border and shadow.  Its boundary box takes into account
% all of shadow, border and padding.
% The parameters are interpreted as in CSS styling.
% For the shadow inset variant see \spx@boxes@fcolorbox@insetshadow
\long\def\spx@boxes@fcolorbox#1{%
  \hbox{%
  \spx@boxes@fcolorbox@init
  \setbox\spx@tempboxa
   \hbox{\kern\dimexpr\spx@boxes@border@left+\spx@boxes@padding@left\relax
         {#1}%
         \kern\dimexpr\spx@boxes@padding@right+\spx@boxes@border@right\relax}%
  \ht\spx@tempboxa
     \dimexpr\ht\spx@tempboxa+\spx@boxes@border@top+\spx@boxes@padding@top\relax
  \dp\spx@tempboxa
     \dimexpr\dp\spx@tempboxa+\spx@boxes@padding@bottom+\spx@boxes@border@bottom\relax
  % reserve space to shadow if on left
  \ifspx@boxes@noshadow\else
    \ifdim\spx@boxes@shadow@xoffset<\z@\kern-\spx@boxes@shadow@xoffset\fi
  \fi
  % BACKGROUND
  % draw background and move back to reference point
  \ifspx@boxes@nobackgroundcolor\else
   {\color{spx@boxes@backgroundcolor}%
    \vrule\@height\ht\spx@tempboxa
          \@depth\dp\spx@tempboxa
          \@width\wd\spx@tempboxa
    \kern-\wd\spx@tempboxa
    }%
  \fi
  % BOX SHADOW
  % draw shadow and move back to reference point
  \ifspx@boxes@noshadow\else
  \vbox{%
    \moveright\spx@boxes@shadow@xoffset
    \hbox{\lower\spx@boxes@shadow@yoffset
          \vbox{\ifspx@boxes@noshadowcolor\else\color{spx@boxes@shadowcolor}\fi
                \ifdim\spx@boxes@shadow@yoffset<\z@
                  \hrule\@height-\spx@boxes@shadow@yoffset
                  \kern\spx@boxes@shadow@yoffset
                \fi
                \setbox\spx@tempboxb\hb@xt@\wd\spx@tempboxa{%
                 \ifdim\spx@boxes@shadow@xoffset<\z@\vrule\@width-\spx@boxes@shadow@xoffset\fi
                 \hss
                 \ifdim\spx@boxes@shadow@xoffset>\z@\vrule\@width\spx@boxes@shadow@xoffset\fi
                 }%
                \ht\spx@tempboxb\ht\spx@tempboxa
                \dp\spx@tempboxb\dp\spx@tempboxa
                \box\spx@tempboxb
                \ifdim\spx@boxes@shadow@yoffset>\z@
                  \kern-\spx@boxes@shadow@yoffset
                  \hrule\@height\spx@boxes@shadow@yoffset
                \fi
                \kern-\dp\spx@tempboxa
               }% end of \vbox, attention it will have zero depth if yoffset>0
          \kern-\wd\spx@tempboxa
          \ifdim\spx@boxes@shadow@xoffset>\z@
            \kern-\spx@boxes@shadow@xoffset
          \fi
         }% end of \hbox, attention its depth is only yoffset if yoffset>0
       }% end of \vbox
  \fi % end of shadow drawing, and we are back to horizontal reference point
  % BOX BORDER
  \vbox{\ifspx@boxes@nobordercolor\else\color{spx@boxes@bordercolor}\fi
        \hrule\@height\spx@boxes@border@top
           \kern-\spx@boxes@border@top
        \setbox\spx@tempboxb\hb@xt@\wd\spx@tempboxa
                  {\vrule\@width\spx@boxes@border@left
                   \hss\vrule\@width\spx@boxes@border@right
                  }%
            \ht\spx@tempboxb\ht\spx@tempboxa
            \dp\spx@tempboxb\dp\spx@tempboxa
        \box\spx@tempboxb
        \kern-\spx@boxes@border@bottom
        \hrule\@height\spx@boxes@border@bottom
        \kern-\dp\spx@tempboxa
       }% attention this box has zero depth due to \hrule at bottom
  % step back to horizontal reference point
  \kern-\wd\spx@tempboxa
  % end of border drawing
  % CONTENTS
  % adjust the total depth to include the bottom shadow
  \ifspx@boxes@noshadow\else
    \ifdim\spx@boxes@shadow@yoffset>\z@
      \dp\spx@tempboxa\dimexpr\dp\spx@tempboxa+\spx@boxes@shadow@yoffset\relax
    \fi
  \fi
  \box\spx@tempboxa
  % include lateral shadow in total width
  \ifspx@boxes@noshadow\else
    \ifdim\spx@boxes@shadow@xoffset>\z@\kern\spx@boxes@shadow@xoffset\fi
  \fi
  }%
}

%//// \spx@boxes@fcolorbox@insetshadow
% The parameters are interpreted as in CSS styling.
\long\def\spx@boxes@fcolorbox@insetshadow#1{%
  \hbox{%
  \spx@boxes@fcolorbox@insetshadow@init
  \setbox\spx@tempboxa
   \hbox{\kern\dimexpr\spx@boxes@border@left+\spx@boxes@padding@left\relax
         {#1}%
         \kern\dimexpr\spx@boxes@padding@right+\spx@boxes@border@right\relax}%
  \ht\spx@tempboxa
     \dimexpr\ht\spx@tempboxa+\spx@boxes@border@top+\spx@boxes@padding@top\relax
  \dp\spx@tempboxa
     \dimexpr\dp\spx@tempboxa+\spx@boxes@padding@bottom+\spx@boxes@border@bottom\relax
  % BACKGROUND
  % draw background and move back to reference point
  \ifspx@boxes@nobackgroundcolor\else
   {\color{spx@boxes@backgroundcolor}%
    \vrule\@height\ht\spx@tempboxa
          \@depth\dp\spx@tempboxa
          \@width\wd\spx@tempboxa
    \kern-\wd\spx@tempboxa
    }%
  \fi
  % BOX SHADOW
  % draw shadow and move back to reference point
  \ifspx@boxes@noshadow\else
    \hbox{\vbox{\ifspx@boxes@noshadowcolor\else\color{spx@boxes@shadowcolor}\fi
% NOTA BENE
% We deliberately draw shadow partially under an area later covered by frame
% with the idea to avoid anti-aliasing problems but in fact this may be a bad
% idea with border is thin
% Would need some testing and possibly refactoring
                \ifdim\spx@boxes@shadow@yoffset>\z@
                  \hrule\@height\dimexpr\spx@boxes@border@top+\spx@boxes@shadow@yoffset\relax
                  \kern-\spx@boxes@shadow@yoffset
                  \kern-\spx@boxes@border@top
                \fi
                \setbox\spx@tempboxb\hb@xt@\wd\spx@tempboxa{%
                 \ifdim\spx@boxes@shadow@xoffset>\z@
                  \vrule\@width\dimexpr\spx@boxes@border@left+\spx@boxes@shadow@xoffset\relax\fi
                 \hss
                 \ifdim\spx@boxes@shadow@xoffset<\z@
                  \vrule\@width\dimexpr-\spx@boxes@shadow@xoffset+\spx@boxes@border@right\relax\fi
                 }%
                \ht\spx@tempboxb\ht\spx@tempboxa
                \dp\spx@tempboxb\dp\spx@tempboxa
                \box\spx@tempboxb
                \ifdim\spx@boxes@shadow@yoffset<\z@
                  \kern\spx@boxes@shadow@yoffset
                  \kern-\spx@boxes@border@bottom
                  \hrule\@height\dimexpr-\spx@boxes@shadow@yoffset+\spx@boxes@border@bottom\relax
                \fi
                \kern-\dp\spx@tempboxa
               }% end of \vbox, attention it will have zero depth if yoffset<0
          \kern-\wd\spx@tempboxa
         }% end of \hbox, attention its depth is only |yoffset| if yoffset<0
  \fi % end of inset shadow drawing, and we are back to horizontal reference point
  % BOX BORDER
  \vbox{\ifspx@boxes@nobordercolor\else\color{spx@boxes@bordercolor}\fi
        \hrule\@height\spx@boxes@border@top
           \kern-\spx@boxes@border@top
        \setbox\spx@tempboxb\hb@xt@\wd\spx@tempboxa
                  {\vrule\@width\spx@boxes@border@left
                   \hss\vrule\@width\spx@boxes@border@right
                  }%
            \ht\spx@tempboxb\ht\spx@tempboxa
            \dp\spx@tempboxb\dp\spx@tempboxa
        \box\spx@tempboxb
        \kern-\spx@boxes@border@bottom
        \hrule\@height\spx@boxes@border@bottom
        \kern-\dp\spx@tempboxa
       }% attention this box has zero depth due to \hrule at bottom
  % step back to horizontal reference point
  \kern-\wd\spx@tempboxa
  % end of border drawing
  % CONTENTS
  \box\spx@tempboxa
  }%
}


%%%%%%%%
% \spx@boxes@fcolorbox@rounded
%
% Various radii but only one borderwidth. No shadow

% wrappers for pict2e usage if old
% Better not to copy over 2020 pict2e definitions in case
% something internal changes
% However our wrappers will work ONLY with dimensional inputs
% (and not 0, only \z@...)
% No need to pre-expand the arguments
\def\spx@moveto(#1,#2){\moveto(\strip@pt\dimexpr#1,\strip@pt\dimexpr#2)}
\def\spx@lineto(#1,#2){\lineto(\strip@pt\dimexpr#1,\strip@pt\dimexpr#2)}
% attention here the [N] is mandatory
\def\spx@circlearc[#1]#2#3#4%#5#6
   {\circlearc[#1]{\strip@pt\dimexpr#2}{\strip@pt\dimexpr#3}{\strip@pt\dimexpr#4}}

% This macro will when executed in a picture environment prepare a path which
% is both used for filling backround color and stroking border
% The coordinate origin in the LaTeX picture environment will be at half the
% border width (d/2, d/2), d = constant border width
\def\spx@boxes@roundedpath{%
  \spx@moveto(\spx@boxes@radius@bottomleft,\z@)% \z@ not 0 as our \spx@moveto is quite dumb
  \spx@lineto(\wd\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@bottomright,\z@)%
  \spx@circlearc[2]{\wd\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@bottomright}%
                {\spx@boxes@radius@bottomright}%
                {\spx@boxes@radius@bottomright}{-90}{0}%
  \spx@lineto(\wd\spx@tempboxa-\spx@boxes@border,%
              \ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@topright)%
  \spx@circlearc[2]{\wd\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@topright}
                {\ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@topright}%
                {\spx@boxes@radius@topright}{0}{90}%
  \spx@lineto(\spx@boxes@radius@topleft,\ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border)%
  \spx@circlearc[2]{\spx@boxes@radius@topleft}%
                {\ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@topleft}%
                {\spx@boxes@radius@topleft}{90}{180}%
  \spx@lineto(\z@,\spx@boxes@radius@bottomleft)%
  \spx@circlearc[2]{\spx@boxes@radius@bottomleft}%
                   {\spx@boxes@radius@bottomleft}%
                   {\spx@boxes@radius@bottomleft}{180}{270}%
}% end of definition of \spx@boxes@roundedpath
\def\spx@boxes@roundedpath@opentop{%
  \spx@moveto(\z@,\ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border)%
  \spx@lineto(\z@,\spx@boxes@radius@bottomleft)%
  \spx@circlearc[2]{\spx@boxes@radius@bottomleft}%
                   {\spx@boxes@radius@bottomleft}%
                   {\spx@boxes@radius@bottomleft}{180}{270}%
  \spx@lineto(\wd\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@bottomright,\z@)%
  \spx@circlearc[2]{\wd\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@bottomright}%
                {\spx@boxes@radius@bottomright}%
                {\spx@boxes@radius@bottomright}{-90}{0}%
  \spx@lineto(\wd\spx@tempboxa-\spx@boxes@border,%
              \ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border)%
}% end of definition of \spx@boxes@roundedpath@opentop
\def\spx@boxes@roundedpath@openbottom{%
  \spx@moveto(\wd\spx@tempboxa-\spx@boxes@border,\z@)%
  \spx@lineto(\wd\spx@tempboxa-\spx@boxes@border,%
              \ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@topright)%
  \spx@circlearc[2]{\wd\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@topright}
                {\ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@topright}%
                {\spx@boxes@radius@topright}{0}{90}%
  \spx@lineto(\spx@boxes@radius@topleft,\ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border)%
  \spx@circlearc[2]{\spx@boxes@radius@topleft}%
                {\ht\spx@tempboxa+\dp\spx@tempboxa-\spx@boxes@border-\spx@boxes@radius@topleft}%
                {\spx@boxes@radius@topleft}{90}{180}%
  \spx@lineto(\z@,\z@)%
}% end of definition of \spx@boxes@roundedpath@openbottom

\long\def\spx@boxes@fcolorbox@rounded #1{%
  \hbox{\vbox{%
   \setlength{\unitlength}{1pt}%
   \spx@boxes@fcolorbox@init
   \setbox\spx@tempboxa
   \hbox{\kern\dimexpr\spx@boxes@border+\spx@boxes@padding@left\relax
         {#1}%
         \kern\dimexpr\spx@boxes@padding@right+\spx@boxes@border\relax}%
   \ht\spx@tempboxa
     \dimexpr\ht\spx@tempboxa+\spx@boxes@border+\spx@boxes@padding@top\relax
   \dp\spx@tempboxa
     \dimexpr\dp\spx@tempboxa+\spx@boxes@padding@bottom+\spx@boxes@border\relax
% work around for "old" LaTeX (we could use the "picture" package, this
% would add another dependency)
   \hbox{\begin{picture}%
      (\strip@pt\wd\spx@tempboxa,\strip@pt\dimexpr\ht\spx@tempboxa+\dp\spx@tempboxa)%
      (\strip@pt\dimexpr-.5\spx@boxes@border,\strip@pt\dimexpr-.5\spx@boxes@border)%
              \color{spx@boxes@backgroundcolor}%
              \spx@boxes@roundedpath\fillpath
              \color{spx@boxes@bordercolor}%
\ifdim\spx@boxes@border>\z@
% even with \spx@boxes@border set to 0pt as done if verbatimwithframe=false
% stroke will produce a visible contour, so we exclude doing it in that case
              \linethickness{\spx@boxes@border}%
              \ifdim\spx@boxes@border@top=\z@
                    \spx@boxes@roundedpath@opentop
              \else
              \ifdim\spx@boxes@border@bottom=\z@
                    \spx@boxes@roundedpath@openbottom
              \else\spx@boxes@roundedpath
              \fi\fi
              \strokepath
\fi
   \end{picture}}%
   % now the contents
   \kern-\dimexpr\ht\spx@tempboxa+\dp\spx@tempboxa\relax
   \box\spx@tempboxa
   }% end of \vbox
  }% end of \hbox
}%


\endinput