% \iffalse meta-comment % %% File: l3box.dtx Copyright (C) 2005-2011 The LaTeX3 Project %% %% It may be distributed and/or modified under the conditions of the %% LaTeX Project Public License (LPPL), either version 1.3c of this %% license or (at your option) any later version. The latest version %% of this license is in the file %% %% http://www.latex-project.org/lppl.txt %% %% This file is part of the "expl3 bundle" (The Work in LPPL) %% and all files in that bundle must be distributed together. %% %% The released version of this bundle is available from CTAN. %% %% ----------------------------------------------------------------------- %% %% The development version of the bundle can be found at %% %% http://www.latex-project.org/svnroot/experimental/trunk/ %% %% for those people who are interested. %% %%%%%%%%%%% %% NOTE: %% %%%%%%%%%%% %% %% Snapshots taken from the repository represent work in progress and may %% not work or may contain conflicting material! We therefore ask %% people _not_ to put them into distributions, archives, etc. without %% prior consultation with the LaTeX3 Project. %% %% ----------------------------------------------------------------------- % %<*driver|package> \RequirePackage{l3names} \GetIdInfo$Id: l3box.dtx 2478 2011-06-19 21:34:23Z joseph $ {L3 Experimental boxes} % %<*driver> \documentclass[full]{l3doc} \begin{document} \DocInput{\jobname.dtx} \end{document} % % \fi % % \title{^^A % The \pkg{l3box} package\\ Boxes^^A % \thanks{This file describes v\ExplFileVersion, % last revised \ExplFileDate.}^^A % } % % \author{^^A % The \LaTeX3 Project\thanks % {^^A % E-mail: % \href{mailto:latex-team@latex-project.org} % {latex-team@latex-project.org}^^A % }^^A % } % % \date{Released \ExplFileDate} % % \maketitle % % \begin{documentation} % % There are three kinds of box operations: horizontal mode denoted % with prefix |\hbox_|, vertical mode with prefix |\vbox_|, and the % generic operations working in both modes with prefix |\box_|. % % \section{Creating and initialising boxes} % % \begin{function}{\box_new:N, \box_new:c} % \begin{syntax} % \cs{box_new:N} \meta{box} % \end{syntax} % Creates a new \meta{box} or raises an error if the name is % already taken. The declaration is global. The \meta{box} will % initially be void. % \end{function} % % \begin{function}{\box_clear:N, \box_clear:c} % \begin{syntax} % \cs{box_clear:N} \meta{box} % \end{syntax} % Clears the content of the \meta{box} by setting the box equal to % \cs{c_void_box} within the current \TeX{} group level. % \end{function} % % \begin{function}{\box_gclear:N, \box_gclear:c} % \begin{syntax} % \cs{box_gclear:N} \meta{box} % \end{syntax} % Clears the content of the \meta{box} by setting the box equal to % \cs{c_void_box} globally. % \end{function} % % \begin{function}{\box_clear_new:N, \box_clear_new:c} % \begin{syntax} % \cs{box_clear_new:N} \meta{box} % \end{syntax} % If the \meta{box} is not defined, globally creates it. If the \meta{box} % is defined, % clears the content of the \meta{box} by setting the box equal to % \cs{c_void_box} within the current \TeX{} group level. % \end{function} % % \begin{function}{\box_gclear_new:N, \box_gclear_new:c} % \begin{syntax} % \cs{box_gclear_new:N} \meta{box} % \end{syntax} % If the \meta{box} is not defined, globally creates it. If the \meta{box} % is defined, % clears the content of the \meta{box} by setting the box equal to % \cs{c_void_box} globally. % \end{function} % % \begin{function} % {\box_set_eq:NN, \box_set_eq:cN, \box_set_eq:Nc, \box_set_eq:cc} % \begin{syntax} % \cs{box_set_eq:NN} \meta{box1} \meta{box2} % \end{syntax} % Sets the content of \meta{box1} equal to that of \meta{box2}. This % assignment is restricted to the current \TeX{} group level. % \end{function} % % \begin{function} % {\box_gset_eq:NN, \box_gset_eq:cN, \box_gset_eq:Nc, \box_gset_eq:cc} % \begin{syntax} % \cs{box_gset_eq:NN} \meta{box1} \meta{box2} % \end{syntax} % Sets the content of \meta{box1} equal to that of \meta{box2} globally. % \end{function} % % \begin{function} % { % \box_set_eq_clear:NN, \box_set_eq_clear:cN, % \box_set_eq_clear:Nc, \box_set_eq_clear:cc % } % \begin{syntax} % \cs{box_set_eq_clear:NN} \meta{box1} \meta{box2} % \end{syntax} % Sets the content of \meta{box1} within the current \TeX{} group % equal to that of \meta{box2}, then clears \meta{box2} globally. % \end{function} % % \begin{function} % { % \box_gset_eq_clear:NN, \box_gset_eq_clear:cN, % \box_gset_eq_clear:Nc, \box_gset_eq_clear:cc % } % \begin{syntax} % \cs{box_gset_eq_clear:NN} \meta{box1} \meta{box2} % \end{syntax} % Sets the content of \meta{box1} equal to that of \meta{box2}, then % clears \meta{box2}. These assignments are global. % \end{function} % % \section{Using boxes} % % \begin{function}{\box_use:N, \box_use:c} % \begin{syntax} % \cs{box_use:N} \meta{box} % \end{syntax} % Inserts the current content of the \meta{box} onto the current % list for typesetting. % \begin{texnote} % This is the \TeX{} primitive \cs{copy}. % \end{texnote} % \end{function} % % \begin{function}{\box_use_clear:N, \box_use_clear:c} % \begin{syntax} % \cs{box_use_clear:N} \meta{box} % \end{syntax} % Inserts the current content of the \meta{box} onto the current % list for typesetting, then globally clears the content of the % \meta{box}. % \begin{texnote} % This is the \TeX{} primitive \cs{box}. % \end{texnote} % \end{function} % % \begin{function}{\box_move_right:nn, \box_move_left:nn} % \begin{syntax} % \cs{box_move_right:nn} \Arg{dimexpr} \Arg{box function} % \end{syntax} % This function operates in vertical mode, and inserts the % material specified by the \meta{box function} % such that its reference point is displaced horizontally by the given % \meta{dimexpr} from the reference point for typesetting, to the right % or left as appropriate. The \meta{box function} should be % a box opeeration such as |\box_use:N \| or a \enquote{raw} % box specification such as |\vbox:n { xyz }|. % \end{function} % % \begin{function}{\box_move_up:nn, \box_move_down:nn} % \begin{syntax} % \cs{box_move_up:nn} \Arg{dimexpr} \Arg{box function} % \end{syntax} % This function operates in horizontal mode, and inserts the % material specified by the \meta{box function} % such that its reference point is displaced vertical by the given % \meta{dimexpr} from the reference point for typesetting, up % or down as appropriate. The \meta{box function} should be % a box opeeration such as |\box_use:N \| or a \enquote{raw} % box specification such as |\vbox:n { xyz }|. % \end{function} % % \section{Measuring and setting box dimensions} % % \begin{function}{\box_dp:N, \box_dp:c} % \begin{syntax} % \cs{box_dp:N} \meta{box} % \end{syntax} % Calculates the depth (below the baseline) of the \meta{box} % and leaves this in the input stream. The output of this function % is suitable for use in a \meta{dimension expression} for % calculations. % \begin{texnote} % This is the \TeX{} primitive \cs{dp}. % \end{texnote} % \end{function} % % \begin{function}{\box_ht:N, \box_ht:c} % \begin{syntax} % \cs{box_ht:N} \meta{box} % \end{syntax} % Calculates the height (above the baseline) of the \meta{box} % and leaves this in the input stream. The output of this function % is suitable for use in a \meta{dimension expression} for % calculations. % \begin{texnote} % This is the \TeX{} primitive \cs{ht}. % \end{texnote} % \end{function} % % \begin{function}{\box_wd:N, \box_wd:c} % \begin{syntax} % \cs{box_wd:N} \meta{box} % \end{syntax} % Calculates the width of the \meta{box} and leaves this in the % input stream. The output of this function is suitable for use in a % \meta{dimension expression} for calculations. % \begin{texnote} % This is the \TeX{} primitive \cs{wd}. % \end{texnote} % \end{function} % % \begin{function}{\box_set_dp:Nn, \box_set_dp:cn} % \begin{syntax} % \cs{box_set_dp:Nn} \meta{box} \Arg{dimension expression} % \end{syntax} % Set the depth (below the baseline) of the \meta{box} to the value of % the \Arg{dimension expression}. This is a global assignment. % \end{function} % % \begin{function}{\box_set_ht:Nn, \box_set_ht:cn} % \begin{syntax} % \cs{box_set_ht:Nn} \meta{box} \Arg{dimension expression} % \end{syntax} % Set the height (above the baseline) of the \meta{box} to the value of % the \Arg{dimension expression}. This is a global assignment. % \end{function} % % \begin{function}{\box_set_wd:Nn, \box_set_wd:cn} % \begin{syntax} % \cs{box_set_wd:Nn} \meta{box} \Arg{dimension expression} % \end{syntax} % Set the width of the \meta{box} to the value of the % \Arg{dimension expression}. This is a global assignment. % \end{function} % % \section{Box conditionals} % % \begin{function}[EXP,pTF]{\box_if_empty:N, \box_if_empty:c} % \begin{syntax} % \cs{box_if_empty_p:N} \meta{box} % \cs{box_if_empty:NTF} \meta{box} \Arg{true code} \Arg{false code} % \end{syntax} % Tests if \meta{box} is a empty (equal to \cs{c_empty_box}). % The branching versions then leave either % \meta{true code} or \meta{false code} in the input stream, as % appropriate to the truth of the test and the variant of the function % chosen. The logical truth of the test is left in the input stream by % the predicate version. % \end{function} % % \begin{function}[EXP,pTF]{\box_if_horizontal:N, \box_if_horizontal:c} % \begin{syntax} % \cs{box_if_horizontal_p:N} \meta{box} % \cs{box_if_horizontal:NTF} \meta{box} \Arg{true code} \Arg{false code} % \end{syntax} % Tests if \meta{box} is a horizontal box. The branching % versions then leave either \meta{true code} or \meta{false code} % in the input stream, as appropriate to the truth of the test and % the variant of the function chosen. The logical truth of the test % is left in the input stream by the predicate version. % \end{function} % % \begin{function}[EXP,pTF]{\box_if_vertical:N, \box_if_vertical:c} % \begin{syntax} % \cs{box_if_vertical_p:N} \meta{box} % \cs{box_if_vertical:NTF} \meta{box} \Arg{true code} \Arg{false code} % \end{syntax} % Tests if \meta{box} is a vertical box. The branching % versions then leave either \meta{true code} or \meta{false code} % in the input stream, as appropriate to the truth of the test and % the variant of the function chosen. The logical truth of the test % is left in the input stream by the predicate version. % \end{function} % % \section{The last box inserted} % % \begin{variable}{\l_last_box} % This is a box containing the last item added to the current partial % list, except in the case of the main vertical list (main galley), in % which case this box is always void. Notice that although this is % not a constant, it is \emph{not} settable by the programmer but is % instead varied by \TeX{}. % \begin{texnote} % This is the \TeX{} primitive \cs{lastbox} renamed. % \end{texnote} % \end{variable} % % \section{Constant boxes} % % \begin{variable}{\c_empty_box} % This is a permanently empty box, which is neither set as horizontal % nor vertical. % \end{variable} % % \section{Scratch boxes} % % \begin{variable}{\l_tmpa_tl, \l_tmpb_tl} % Scratch boxes for local assignment. These are never used by % the kernel code, and so are safe for use with any \LaTeX3-defined % function. However, they may be overwritten by other non-kernel % code and so should only be used for short-term storage. % \end{variable} % % \section{Viewing box contents} % % \begin{function}{\box_show:N, \box_show:c} % \begin{syntax} % \cs{box_show:N} \meta{box} % \end{syntax} % Writes the contents of \meta{box} to the log file. % \begin{texnote} % This is the \TeX{} primitive \cs{showbox}. % \end{texnote} % \end{function} % % \section{Horizontal mode boxes} % % \begin{function}{\hbox:n} % \begin{syntax} % \cs{hbox:n} \Arg{contents} % \end{syntax} % Typesets the \meta{contents} into a horizontal box of natural % width and then includes this box in the current list for typesetting. % \begin{texnote} % This is the \TeX{} primitive \cs{hbox}. % \end{texnote} % \end{function} % % \begin{function}{\hbox_to_wd:nn} % \begin{syntax} % \cs{hbox_to_wd:nn} \Arg{dimexpr} \Arg{contents} % \end{syntax} % Typesets the \meta{contents} into a horizontal box of width % \meta{dimexpr} and then includes this box in the current list for % typesetting. % \end{function} % % \begin{function}{\hbox_to_zero:n} % \begin{syntax} % \cs{hbox_to_zero:n} \Arg{contents} % \end{syntax} % Typesets the \meta{contents} into a horizontal box of zero width % and then includes this box in the current list for typesetting. % \end{function} % % \begin{function}{\hbox_set:Nn, \hbox_set:cn} % \begin{syntax} % \cs{hbox_set:Nn} \meta{box} \Arg{contents} % \end{syntax} % Typesets the \meta{contents} at natural width and then stores the % result inside the \meta{box}. The assignment is local. % \end{function} % % \begin{function}{\hbox_gset:Nn, \hbox_gset:cn} % \begin{syntax} % \cs{hbox_gset:Nn} \meta{box} \Arg{contents} % \end{syntax} % Typesets the \meta{contents} at natural width and then stores the % result inside the \meta{box}. The assignment is global. % \end{function} % % \begin{function}{\hbox_set_to_wd:Nnn, \hbox_set_to_wd:cnn} % \begin{syntax} % \cs{hbox_set_to_wd:Nnn} \meta{box} \Arg{dimexpr} \Arg{contents} % \end{syntax} % Typesets the \meta{contents} to the width given by the \meta{dimexpr} % and then stores the result inside the \meta{box}. The assignment is % local. % \end{function} % % \begin{function}{\hbox_gset_to_wd:Nnn, \hbox_gset_to_wd:cnn} % \begin{syntax} % \cs{hbox_gset_to_wd:Nnn} \meta{box} \Arg{dimexpr} \Arg{contents} % \end{syntax} % Typesets the \meta{contents} to the width given by the \meta{dimexpr} % and then stores the result inside the \meta{box}. The assignment is % global. % \end{function} % % \begin{function}{\hbox_overlap_right:n} % \begin{syntax} % \cs{hbox_overlap_right:n} \Arg{contents} % \end{syntax} % Typesets the \meta{contents} into a horizontal box of zero width % such that material will protrude to the right of the insertion % point. % \end{function} % % \begin{function}{\hbox_overlap_left:n} % \begin{syntax} % \cs{hbox_overlap_left:n} \Arg{contents} % \end{syntax} % Typesets the \meta{contents} into a horizontal box of zero width % such that material will protrude to the left of the insertion % point. % \end{function} % % \begin{function} % { % \hbox_set_inline_begin:N, \hbox_set_inline_begin:c, % \hbox_set_inline_end: % } % \begin{syntax} % \cs{hbox_set_inline_begin:N} \meta{box} \meta{contents} % ~~\cs{hbox_set_inline_end:} % \end{syntax} % Typesets the \meta{contents} at natural width and then stores the % result inside the \meta{box}. The assignment is local. In contrast % to \cs{hbox_set:Nn} this function does not absorb the argument % when finding the \meta{content}, and so can be used in circumstances % where the \meta{content} may not be a simple argument. % \end{function} % % \begin{function} % { % \hbox_gset_inline_begin:N, \hbox_gset_inline_begin:c, % \hbox_gset_inline_end: % } % \begin{syntax} % \cs{hbox_gset_inline_begin:N} \meta{box} \meta{contents} % ~~\cs{hbox_gset_inline_end:} % \end{syntax} % Typesets the \meta{contents} at natural width and then stores the % result inside the \meta{box}. The assignment is global. In contrast % to \cs{hbox_set:Nn} this function does not absorb the argument % when finding the \meta{content}, and so can be used in circumstances % where the \meta{content} may not be a simple argument. % \end{function} % % \begin{function}{\hbox_unpack:N, \hbox_unpack:c} % \begin{syntax} % \cs{hbox_unpack:N} \meta{box} % \end{syntax} % Unpacks the content of the horizontal \meta{box}, retaining any stretching % or shrinking applied when the \meta{box} was set. % \begin{texnote} % This is the \TeX{} primitive \cs{unhcopy}. % \end{texnote} % \end{function} % % \begin{function}{\hbox_unpack_clear:N, \hbox_unpack_clear:c} % \begin{syntax} % \cs{hbox_unpack_clear:N} \meta{box} % \end{syntax} % Unpacks the content of the horizontal \meta{box}, retaining any stretching % or shrinking applied when the \meta{box} was set. The \meta{box} is % then cleared globally. % \begin{texnote} % This is the \TeX{} primitive \cs{unhbox}. % \end{texnote} % \end{function} % % \section{Vertical mode boxes} % % Vertical boxes inherit their baseline from their contents. The % standard case is that the baseline of the box is at the same position % as that of the last item added to the box. This means that the box % will have no depth unless the last item added to it had depth. As a % result most vertical boxes have a large height value and small or % zero depth. The exception are |_top| boxes, where the reference point % is that of the first item added. These tend to have a large depth and % small height, although the later will typically be non-zero. % % \begin{function}{\vbox:n} % \begin{syntax} % \cs{vbox:n} \Arg{contents} % \end{syntax} % Typesets the \meta{contents} into a vertical box of natural height % and includes this box in the current list for typesetting. % \begin{texnote} % This is the \TeX{} primitive \cs{vbox}. % \end{texnote} % \end{function} % % \begin{function}{\vbox_top:n} % \begin{syntax} % \cs{vbox_top:n} \Arg{contents} % \end{syntax} % Typesets the \meta{contents} into a vertical box of natural height % and includes this box in the current list for typesetting. The % baseline of the box will tbe equal to that of the \emph{first} % item added to the box. % \begin{texnote} % This is the \TeX{} primitive \cs{vtop}. % \end{texnote} % \end{function} % % \begin{function}{\vbox_to_ht:nn} % \begin{syntax} % \cs{vbox_to_ht:n} \Arg{contents} \Arg{dimexpr} % \end{syntax} % Typesets the \meta{contents} into a vertical box of height % \meta{dimexpr} and then includes this box in the current list for % typesetting. % \end{function} % % \begin{function}{\vbox_to_zero:n} % \begin{syntax} % \cs{vbox_to_zero:n} \Arg{contents} % \end{syntax} % Typesets the \meta{contents} into a vertical box of zero height % and then includes this box in the current list for typesetting. % \end{function} % % \begin{function}{\vbox_set:Nn, \vbox_set:cn} % \begin{syntax} % \cs{vbox_set:Nn} \meta{box} \Arg{contents} % \end{syntax} % Typesets the \meta{contents} at natural height and then stores the % result inside the \meta{box}. The assignment is local. % \end{function} % % \begin{function}{\vbox_gset:Nn, \vbox_gset:cn} % \begin{syntax} % \cs{vbox_gset:Nn} \meta{box} \Arg{contents} % \end{syntax} % Typesets the \meta{contents} at natural height and then stores the % result inside the \meta{box}. The assignment is global. % \end{function} % % \begin{function}{\vbox_set_top:Nn, \vbox_set_top:cn} % \begin{syntax} % \cs{vbox_set_top:Nn} \meta{box} \Arg{contents} % \end{syntax} % Typesets the \meta{contents} at natural height and then stores the % result inside the \meta{box}. The baseline of the box will tbe equal % to that of the \emph{first} item added to the box. The assignment is % local. % \end{function} % % \begin{function}{\vbox_gset_top:Nn, \vbox_gset_top:cn} % \begin{syntax} % \cs{vbox_gset_top:Nn} \meta{box} \Arg{contents} % \end{syntax} % Typesets the \meta{contents} at natural height and then stores the % result inside the \meta{box}. The baseline of the box will tbe equal % to that of the \emph{first} item added to the box. The assignment is % global. % \end{function} % % \begin{function}{\vbox_set_to_ht:Nnn, \vbox_set_to_ht:cnn} % \begin{syntax} % \cs{vbox_set_to_ht:Nnn} \meta{box} \Arg{dimexpr} \Arg{contents} % \end{syntax} % Typesets the \meta{contents} to the height given by the % \meta{dimexpr} and then stores the result inside the \meta{box}. % The assignment is local. % \end{function} % % \begin{function}{\vbox_gset_to_ht:Nnn, \vbox_gset_to_ht:cnn} % \begin{syntax} % \cs{vbox_gset_to_ht:Nnn} \meta{box} \Arg{dimexpr} \Arg{contents} % \end{syntax} % Typesets the \meta{contents} to the height given by the % \meta{dimexpr} and then stores the result inside the \meta{box}. % The assignment is global. % \end{function} % % \begin{function} % { % \vbox_set_inline_begin:N, \vbox_set_inline_begin:c, % \vbox_set_inline_end: % } % \begin{syntax} % \cs{vbox_set_inline_begin:N} \meta{box} \meta{contents} % ~~\cs{vbox_set_inline_end:} % \end{syntax} % Typesets the \meta{contents} at natural height and then stores the % result inside the \meta{box}. The assignment is local. In contrast % to \cs{vbox_set:Nn} this function does not absorb the argument % when finding the \meta{content}, and so can be used in circumstances % where the \meta{content} may not be a simple argument. % \end{function} % % \begin{function} % { % \vbox_gset_inline_begin:N, \vbox_gset_inline_begin:c, % \vbox_gset_inline_end: % } % \begin{syntax} % \cs{vbox_gset_inline_begin:N} \meta{box} \meta{contents} % ~~\cs{vbox_set_inline_end:} % \end{syntax} % Typesets the \meta{contents} at natural height and then stores the % result inside the \meta{box}. The assignment is global. In contrast % to \cs{vbox_set:Nn} this function does not absorb the argument % when finding the \meta{content}, and so can be used in circumstances % where the \meta{content} may not be a simple argument. % \end{function} % % \begin{function}{\vbox_set_split_to_ht:NNn} % \begin{syntax} % \cs{vbox_set_split_to_ht:NNn} \meta{box1} \meta{box2} \Arg{dimexpr} % \end{syntax} % Sets \meta{box1} to contain material to the height given by the % \meta{dimexpr} by removing content from the top of \meta{box2} % (which must be a vertical box). % \begin{texnote} % This is the \TeX{} primitive \cs{vsplit}. % \end{texnote} % \end{function} % % \begin{function}{\vbox_unpack:N, \vbox_unpack:c} % \begin{syntax} % \cs{vbox_unpack:N} \meta{box} % \end{syntax} % Unpacks the content of the vertical \meta{box}, retaining any stretching % or shrinking applied when the \meta{box} was set. % \begin{texnote} % This is the \TeX{} primitive \cs{unvcopy}. % \end{texnote} % \end{function} % % \begin{function}{\vbox_unpack_clear:N, \vbox_unpack_clear:c} % \begin{syntax} % \cs{vbox_unpack:N} \meta{box} % \end{syntax} % Unpacks the content of the vertical \meta{box}, retaining any stretching % or shrinking applied when the \meta{box} was set. The \meta{box} % is then cleared globally. % \begin{texnote} % This is the \TeX{} primitive \cs{unvbox}. % \end{texnote} % \end{function} % % \section{Primitive box conditionals} % % \begin{function}[EXP]{\if_hbox:N} % \begin{syntax} % \cs{if_hbox:N} \meta{box} % ~~\meta{true code} % \cs{else:} % ~~\meta{false code} % \cs{fi:} % \end{syntax} % Tests is \meta{box} is a horizontal box. % \begin{texnote} % This is the \TeX{} primitive \cs{ifhbox}. % \end{texnote} % \end{function} % % \begin{function}[EXP]{\if_vbox:N} % \begin{syntax} % \cs{if_vbox:N} \meta{box} % ~~\meta{true code} % \cs{else:} % ~~\meta{false code} % \cs{fi:} % \end{syntax} % Tests is \meta{box} is a vertical box. % \begin{texnote} % This is the \TeX{} primitive \cs{ifvbox}. % \end{texnote} % \end{function} % % \begin{function}[EXP]{\if_box_empty:N} % \begin{syntax} % \cs{if_box_empty:N} \meta{box} % ~~\meta{true code} % \cs{else:} % ~~\meta{false code} % \cs{fi:} % \end{syntax} % Tests is \meta{box} is an empty (void) box. % \begin{texnote} % This is the \TeX{} primitive \cs{ifvoid}. % \end{texnote} % \end{function} % % \end{documentation} % % \begin{implementation} % % \section{\pkg{l3box} implementation} % % \begin{macrocode} %<*initex|package> % \end{macrocode} % % \begin{macrocode} %<*package> \ProvidesExplPackage {\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription} \package_check_loaded_expl: %<*initex|package> % \end{macrocode} % % The code in this module is very straight forward so I'm not going to % comment it very extensively. % % \subsection{Creating and initialising boxes} % % \TestFiles{m3box001.lvt} % % \begin{macro}{\box_new:N,\box_new:c} % Defining a new \meta{box} register: remember that box $255$ is not % generally available. % \begin{macrocode} %<*initex> \alloc_new:nnnN { box } \c_zero \c_max_register_int \tex_mathchardef:D \seq_put_right:Nn \g_box_allocation_seq {255} % %<*package> \cs_new_protected:Npn \box_new:N #1 { \chk_if_free_cs:N #1 \newbox #1 } % \cs_generate_variant:Nn \box_new:N { c } % \end{macrocode} % % \begin{macro}{\box_clear:N, \box_clear:c} % \begin{macro}{\box_gclear:N, \box_gclear:c} % \testfile* % Clear a \meta{box} register. % \begin{macrocode} \cs_new_protected_nopar:Npn \box_clear:N #1 { \box_set_eq:NN #1 \c_empty_box } \cs_new_protected_nopar:Npn \box_gclear:N #1 { \box_gset_eq:NN #1 \c_empty_box } \cs_generate_variant:Nn \box_clear:N { c } \cs_generate_variant:Nn \box_gclear:N { c } % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\box_clear_new:N, \box_clear_new:c} % \begin{macro}{\box_gclear_new:N, \box_gclear_new:c} % \testfile* % Clear or new. % \begin{macrocode} \cs_new_protected_nopar:Npn \box_clear_new:N #1 { \cs_if_exist:NTF #1 { \box_set_eq:NN #1 \c_empty_box } { \box_new:N #1 } } \cs_new_protected_nopar:Npn \box_gclear_new:N #1 { \cs_if_exist:NTF #1 { \box_gset_eq:NN #1 \c_empty_box } { \box_new:N #1 } } \cs_generate_variant:Nn \box_clear_new:N { c } \cs_generate_variant:Nn \box_gclear_new:N { c } % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro} % {\box_set_eq:NN, \box_set_eq:cN, \box_set_eq:Nc, \box_set_eq:cc} % \testfile* % \begin{macro} % {\box_gset_eq:NN, \box_gset_eq:cN, \box_gset_eq:Nc, \box_gset_eq:cc} % \testfile* % Assigning the contents of a box to be another box. % \begin{macrocode} \cs_new_protected_nopar:Npn \box_set_eq:NN #1#2 { \tex_setbox:D #1 \tex_copy:D #2 } \cs_new_protected_nopar:Npn \box_gset_eq:NN { \pref_global:D \box_set_eq:NN } \cs_generate_variant:Nn \box_set_eq:NN { cN , Nc , cc } \cs_generate_variant:Nn \box_gset_eq:NN { cN , Nc , cc } % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro} % { % \box_set_eq_clear:NN, \box_set_eq_clear:cN, % \box_set_eq_clear:Nc, \box_set_eq_clear:cc % } % \testfile* % \begin{macro} % { % \box_gset_eq_clear:NN, \box_gset_eq_clear:cN, % \box_gset_eq_clear:Nc, \box_gset_eq_clear:cc % } % \testfile* % Assigning the contents of a box to be another box. % This clears the second box globally (that's how \TeX{} does it). % \begin{macrocode} \cs_new_protected_nopar:Npn \box_set_eq_clear:NN #1#2 { \tex_setbox:D #1 \tex_box:D #2 } \cs_new_protected_nopar:Npn \box_gset_eq_clear:NN { \pref_global:D \box_set_eq_clear:NN } \cs_generate_variant:Nn \box_set_eq_clear:NN { cN , Nc , cc } \cs_generate_variant:Nn \box_gset_eq_clear:NN { cN , Nc , cc } % \end{macrocode} % \end{macro} % \end{macro} % % \subsection{Measuring and setting box dimensions} % % \begin{macro}{\box_ht:N,\box_ht:c} % \begin{macro}{\box_dp:N,\box_dp:c} % \begin{macro}{\box_wd:N,\box_wd:c} % \testfile* % Accessing the height, depth, and width of a \meta{box} register. % \begin{macrocode} \cs_new_eq:NN \box_ht:N \tex_ht:D \cs_new_eq:NN \box_dp:N \tex_dp:D \cs_new_eq:NN \box_wd:N \tex_wd:D \cs_generate_variant:Nn \box_ht:N { c } \cs_generate_variant:Nn \box_dp:N { c } \cs_generate_variant:Nn \box_wd:N { c } % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % % \begin{macro}{\box_set_ht:Nn, \box_set_ht:cn} % \begin{macro}{\box_set_dp:Nn, \box_set_dp:cn} % \begin{macro}{\box_set_wd:Nn, \box_set_wd:cn} % Measuring is easy: all primitive work. These primitives are not % expandable, so the derived functions are not either. % \begin{macrocode} \cs_new_protected_nopar:Npn \box_set_dp:Nn #1#2 { \box_dp:N #1 \dim_eval:w #2 \dim_eval_end: } \cs_new_protected_nopar:Npn \box_set_ht:Nn #1#2 { \box_ht:N #1 \dim_eval:w #2 \dim_eval_end: } \cs_new_protected_nopar:Npn \box_set_wd:Nn #1#2 { \box_wd:N #1 \dim_eval:w #2 \dim_eval_end: } \cs_generate_variant:Nn \box_set_ht:Nn { c } \cs_generate_variant:Nn \box_set_dp:Nn { c } \cs_generate_variant:Nn \box_set_wd:Nn { c } % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % % \subsection{Using boxes} % % \begin{macro}{\box_use_clear:N, \box_use_clear:c} % \begin{macro}{\box_use:N, \box_use:c} % Using a \meta{box}. These are just \TeX{} primitives with meaningful % names. % \begin{macrocode} \cs_new_eq:NN \box_use_clear:N \tex_box:D \cs_new_eq:NN \box_use:N \tex_copy:D \cs_generate_variant:Nn \box_use_clear:N { c } \cs_generate_variant:Nn \box_use:N { c } % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\box_move_left:nn,\box_move_right:nn} % \begin{macro}{\box_move_up:nn,\box_move_down:nn} % \testfile* % Move box material in different directions. % \begin{macrocode} \cs_new_protected:Npn \box_move_left:nn #1#2 { \tex_moveleft:D \dim_eval:w #1 \dim_eval_end: #2 } \cs_new_protected:Npn \box_move_right:nn #1#2 { \tex_moveright:D \dim_eval:w #1 \dim_eval_end: #2 } \cs_new_protected:Npn \box_move_up:nn #1#2 { \tex_raise:D \dim_eval:w #1 \dim_eval_end: #2 } \cs_new_protected:Npn \box_move_down:nn #1#2 { \tex_lower:D \dim_eval:w #1 \dim_eval_end: #2 } % \end{macrocode} % \end{macro} % \end{macro} % % \subsection{Box conditionals} % % \begin{macro}{\if_hbox:N} % \begin{macro}{\if_vbox:N} % \begin{macro}{\if_box_empty:N} % \testfile* % The primitives for testing if a \meta{box} is empty/void or which % type of box it is. % \begin{macrocode} \cs_new_eq:NN \if_hbox:N \tex_ifhbox:D \cs_new_eq:NN \if_vbox:N \tex_ifvbox:D \cs_new_eq:NN \if_box_empty:N \tex_ifvoid:D % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % % \begin{macro}[pTF]{\box_if_horizontal:N,\box_if_horizontal:c} % \testfile* % \begin{macro}[pTF]{\box_if_vertical:N,\box_if_vertical:c} % \testfile* % \begin{macrocode} \prg_new_conditional:Npnn \box_if_horizontal:N #1 { p , T , F , TF } { \if_hbox:N #1 \prg_return_true: \else: \prg_return_false: \fi: } \prg_new_conditional:Npnn \box_if_vertical:N #1 { p , T , F , TF } { \if_vbox:N #1 \prg_return_true: \else: \prg_return_false: \fi: } \cs_generate_variant:Nn \box_if_horizontal_p:N { c } \cs_generate_variant:Nn \box_if_horizontal:NT { c } \cs_generate_variant:Nn \box_if_horizontal:NF { c } \cs_generate_variant:Nn \box_if_horizontal:NTF { c } \cs_generate_variant:Nn \box_if_vertical_p:N { c } \cs_generate_variant:Nn \box_if_vertical:NT { c } \cs_generate_variant:Nn \box_if_vertical:NF { c } \cs_generate_variant:Nn \box_if_vertical:NTF { c } % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}[pTF]{\box_if_empty:N, \box_if_empty:c} % \testfile* % Testing if a \meta{box} is empty/void. % \begin{macrocode} \prg_new_conditional:Npnn \box_if_empty:N #1 { p , T , F , TF } { \if_box_empty:N #1 \prg_return_true: \else: \prg_return_false: \fi: } \cs_generate_variant:Nn \box_if_empty_p:N { c } \cs_generate_variant:Nn \box_if_empty:NT { c } \cs_generate_variant:Nn \box_if_empty:NF { c } \cs_generate_variant:Nn \box_if_empty:NTF { c } % \end{macrocode} % \end{macro} % \end{macro} % % \subsection{The last box inserted} % % \begin{variable}{\l_last_box} % A different name for this read-only primitive. % \begin{macrocode} \cs_new_eq:NN \l_last_box \tex_lastbox:D % \end{macrocode} % \end{variable} % % \begin{macro}{\box_set_to_last:N, \box_set_to_last:c} % \begin{macro}{\box_gset_to_last:N, \box_gset_to_last:c} % \testfile* % Set a box to the previous box. % \begin{macrocode} \cs_new_protected_nopar:Npn \box_set_to_last:N #1 { \tex_setbox:D #1 \l_last_box } \cs_new_protected_nopar:Npn \box_gset_to_last:N { \pref_global:D \box_set_to_last:N } \cs_generate_variant:Nn \box_set_to_last:N { c } \cs_generate_variant:Nn \box_gset_to_last:N { c } % \end{macrocode} % \end{macro} % \end{macro} % % \subsection{Constant boxes} % % \begin{variable}{\c_empty_box} % \begin{macrocode} %<*package> \cs_new_eq:NN \c_empty_box \voidb@x % %<*initex> \box_new:N \c_empty_box % % \end{macrocode} % \end{variable} % % \subsection{Scratch boxes} % % \begin{variable}{\l_tmpa_box, \l_tmpb_box} % \begin{macrocode} %<*package> \cs_new_eq:NN \l_tmpa_box \@tempboxa % %<*initex> \box_new:N \l_tmpa_box % \box_new:N \l_tmpb_box % \end{macrocode} % \end{variable} % % \subsection{Viewing box contents} % % \begin{macro}{\box_show:N,\box_show:c} % \testfile* % Show the contents of a box and write it into the log file. % \begin{macrocode} \cs_new_eq:NN \box_show:N \tex_showbox:D \cs_generate_variant:Nn \box_show:N { c } % \end{macrocode} % \end{macro} % % \subsection{Horizontal mode boxes} % % \begin{macro}{\hbox:n} % \testfile{m3box002.lvt} % Put a horizontal box directly into the input stream. % \begin{macrocode} \cs_new_protected_nopar:Npn \hbox:n { \tex_hbox:D \scan_stop: } % \end{macrocode} % \end{macro} % % \begin{macro}{\hbox_set:Nn,\hbox_set:cn} % \begin{macro}{\hbox_gset:Nn,\hbox_gset:cn} % \testfile* % \begin{macrocode} \cs_new_protected:Npn \hbox_set:Nn #1#2 { \tex_setbox:D #1 \tex_hbox:D {#2} } \cs_new_protected_nopar:Npn \hbox_gset:Nn { \pref_global:D \hbox_set:Nn } \cs_generate_variant:Nn \hbox_set:Nn { c } \cs_generate_variant:Nn \hbox_gset:Nn { c } % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\hbox_set_to_wd:Nnn,\hbox_set_to_wd:cnn} % \begin{macro}{\hbox_gset_to_wd:Nnn,\hbox_gset_to_wd:cnn} % \testfile* % Storing material in a horizontal box with a specified width. % \begin{macrocode} \cs_new_protected:Npn \hbox_set_to_wd:Nnn #1#2#3 { \tex_setbox:D #1 \tex_hbox:D to \dim_eval:w #2 \dim_eval_end: {#3} } \cs_new_protected_nopar:Npn \hbox_gset_to_wd:Nnn { \pref_global:D \hbox_set_to_wd:Nnn } \cs_generate_variant:Nn \hbox_set_to_wd:Nnn { c } \cs_generate_variant:Nn \hbox_gset_to_wd:Nnn {cnn} % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\hbox_set_inline_begin:N, \hbox_set_inline_begin:c} % \begin{macro}{\hbox_gset_inline_begin:N, \hbox_gset_inline_begin:c} % \begin{macro}{\hbox_set_inline_end:} % \begin{macro}{\hbox_gset_inline_end:} % \testfile* % Storing material in a horizontal box. This type is useful in % environment definitions. % \begin{macrocode} \cs_new_protected_nopar:Npn \hbox_set_inline_begin:N #1 { \tex_setbox:D #1 \tex_hbox:D \c_group_begin_token } \cs_new_protected_nopar:Npn \hbox_gset_inline_begin:N { \pref_global:D \hbox_set_inline_begin:N } \cs_generate_variant:Nn \hbox_set_inline_begin:N { c } \cs_generate_variant:Nn \hbox_gset_inline_begin:N { c } \cs_new_eq:NN \hbox_set_inline_end: \c_group_end_token \cs_new_eq:NN \hbox_gset_inline_end: \c_group_end_token % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % % \begin{macro}{\hbox_to_wd:nn} % \begin{macro}{\hbox_to_zero:n} % \testfile* % Put a horizontal box directly into the input stream. % \begin{macrocode} \cs_new_protected:Npn \hbox_to_wd:nn #1#2 { \tex_hbox:D to \dim_eval:w #1 \dim_eval_end: {#2} } \cs_new_protected:Npn \hbox_to_zero:n #1 { \tex_hbox:D to \c_zero_skip {#1} } % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\hbox_overlap_left:n,} % \begin{macro}{\hbox_overlap_right:n} % Put a zero-sized box with the contents pushed against one side (which % makes it stick out on the other) directly into the input stream. % \begin{macrocode} \cs_new_protected:Npn \hbox_overlap_left:n #1 { \hbox_to_zero:n { \tex_hss:D #1 } } \cs_new_protected:Npn \hbox_overlap_right:n #1 { \hbox_to_zero:n { #1 \tex_hss:D } } % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\hbox_unpack:N, \hbox_unpack:c} % \begin{macro}{\hbox_unpack_clear:N, \hbox_unpack_clear:c} % \testfile* % Unpacking a box and if requested also clear it. % \begin{macrocode} \cs_new_eq:NN \hbox_unpack:N \tex_unhcopy:D \cs_new_eq:NN \hbox_unpack_clear:N \tex_unhbox:D \cs_generate_variant:Nn \hbox_unpack:N { c } \cs_generate_variant:Nn \hbox_unpack_clear:N { c } % \end{macrocode} % \end{macro} % \end{macro} % % \subsection{Vertical mode boxes} % % \begin{macro}{\vbox:n} % \TestFiles{m3box003.lvt} % \begin{macro}{\vbox:n\vbox_top:n} % \TestFiles{m3box003.lvt} % Put a vertical box directly into the input stream. % \begin{macrocode} \cs_new_protected_nopar:Npn \vbox:n { \tex_vbox:D \scan_stop: } \cs_new_protected_nopar:Npn \vbox_top:n { \tex_vtop:D \scan_stop: } % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\vbox_to_ht:nn,\vbox_to_zero:n} % \begin{macro}{\vbox_to_ht:nn,\vbox_to_zero:n} % \testfile* % Put a vertical box directly into the input stream. % \begin{macrocode} \cs_new_protected:Npn \vbox_to_ht:nn #1#2 { \tex_vbox:D to \dim_eval:w #1 \dim_eval_end: {#2} } \cs_new_protected:Npn \vbox_to_zero:n #1 { \tex_vbox:D to \c_zero_dim {#1} } % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\vbox_set:Nn, \vbox_set:cn} % \begin{macro}{\vbox_gset:Nn, \vbox_gset:cn} % \testfile* % Storing material in a vertical box with a natural height. % \begin{macrocode} \cs_new_protected:Npn \vbox_set:Nn #1#2 { \tex_setbox:D #1 \tex_vbox:D {#2} } \cs_new_protected_nopar:Npn \vbox_gset:Nn { \pref_global:D \vbox_set:Nn } \cs_generate_variant:Nn \vbox_set:Nn { c } \cs_generate_variant:Nn \vbox_gset:Nn { c } % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\vbox_set_top:Nn, \vbox_set_top:cn} % \begin{macro}{\vbox_gset_top:Nn, \vbox_gset_top:cn} % \testfile* % Storing material in a vertical box with a natural height and reference % point at the baseline of the first object in the box. % \begin{macrocode} \cs_new_protected:Npn \vbox_set_top:Nn #1#2 { \tex_setbox:D #1 \tex_vtop:D {#2} } \cs_new_protected_nopar:Npn \vbox_gset_top:Nn { \pref_global:D \vbox_set_top:Nn } \cs_generate_variant:Nn \vbox_set_top:Nn { c } \cs_generate_variant:Nn \vbox_gset_top:Nn { c } % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\vbox_set_to_ht:Nnn,\vbox_set_to_ht:cnn} % \begin{macro}{\vbox_gset_to_ht:Nnn,\vbox_gset_to_ht:cnn} % \testfile* % Storing material in a vertical box with a specified height. % \begin{macrocode} \cs_new_protected:Npn \vbox_set_to_ht:Nnn #1#2#3 { \tex_setbox:D #1 \tex_vbox:D to \dim_eval:w #2 \dim_eval_end: {#3} } \cs_new_protected_nopar:Npn \vbox_gset_to_ht:Nnn { \pref_global:D \vbox_set_to_ht:Nnn } \cs_generate_variant:Nn \vbox_set_to_ht:Nnn { c } \cs_generate_variant:Nn \vbox_gset_to_ht:Nnn { c } % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\vbox_set_inline_begin:N, \vbox_set_inline_begin:c} % \begin{macro}{\vbox_gset_inline_begin:N, \vbox_gset_inline_begin:c} % \begin{macro}{\vbox_set_inline_end:} % \begin{macro}{\vbox_gset_inline_end:} % \testfile* % Storing material in a vertical box. This type is useful in % environment definitions. % \begin{macrocode} \cs_new_nopar:Npn \vbox_set_inline_begin:N #1 { \tex_setbox:D #1 \tex_vbox:D \c_group_begin_token } \cs_new_protected_nopar:Npn \vbox_gset_inline_begin:N { \pref_global:D \vbox_set_inline_begin:N } \cs_generate_variant:Nn \vbox_set_inline_begin:N { c } \cs_generate_variant:Nn \vbox_gset_inline_begin:N { c } \cs_new_eq:NN \vbox_set_inline_end: \c_group_end_token \cs_new_eq:NN \vbox_gset_inline_end: \c_group_end_token % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % % \begin{macro}{\vbox_unpack:N, \vbox_unpack:c} % \begin{macro}{\vbox_unpack_clear:N, \vbox_unpack_clear:c} % \testfile* % Unpacking a box and if requested also clear it. % \begin{macrocode} \cs_new_eq:NN \vbox_unpack:N \tex_unvcopy:D \cs_new_eq:NN \vbox_unpack_clear:N \tex_unvbox:D \cs_generate_variant:Nn \vbox_unpack:N { c } \cs_generate_variant:Nn \vbox_unpack_clear:N { c } % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\vbox_set_split_to_ht:NNn} % \testfile* % Splitting a vertical box in two. % \begin{macrocode} \cs_new_protected_nopar:Npn \vbox_set_split_to_ht:NNn #1#2#3 { \tex_setbox:D #1 \tex_vsplit:D #2 to \dim_eval:w #3 \dim_eval_end: } % \end{macrocode} % \end{macro} % % \begin{macrocode} % % \end{macrocode} % % \end{implementation} % % \PrintIndex