diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3box.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3box.dtx | 223 |
1 files changed, 222 insertions, 1 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3box.dtx b/Master/texmf-dist/source/latex/l3kernel/l3box.dtx index 26fb88edd96..bc24a673fa1 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3box.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3box.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2023-03-30} +% \date{Released 2023-04-19} % % \maketitle % @@ -874,6 +874,70 @@ % dependent on the height of the original and \emph{vice versa}. % \end{function} % +% \section{Viewing part of a box} +% +% \begin{function}[updated = 2023-04-14] +% { +% \box_set_clipped:N, \box_set_clipped:c, +% \box_gset_clipped:N, \box_gset_clipped:c +% } +% \begin{syntax} +% \cs{box_set_clipped:N} \meta{box} +% \end{syntax} +% Clips the \meta{box} in the output so that only material inside the +% bounding box is displayed in the output. The updated \meta{box} is an +% hbox, irrespective of the nature of the \meta{box} before the clipping is +% applied. Additional box levels are also generated by this operation. +% +% \begin{texnote} +% Clipping is implemented by the driver, and as such the full content of +% the box is placed in the output file. Thus clipping does not remove +% any information from the raw output, and hidden material can therefore +% be viewed by direct examination of the file. +% \end{texnote} +% \end{function} +% +% \begin{function}[added = 2019-01-23] +% { +% \box_set_trim:Nnnnn, \box_set_trim:cnnnn, +% \box_gset_trim:Nnnnn, \box_gset_trim:cnnnn +% } +% \begin{syntax} +% \cs{box_set_trim:Nnnnn} \meta{box} \Arg{left} \Arg{bottom} \Arg{right} \Arg{top} +% \end{syntax} +% Adjusts the bounding box of the \meta{box} \meta{left} is removed from +% the left-hand edge of the bounding box, \meta{right} from the right-hand +% edge and so fourth. All adjustments are \meta{dim exprs}. +% Material outside of the bounding box is still displayed in the output +% unless \cs{box_set_clipped:N} is subsequently applied. +% The updated \meta{box} is an +% hbox, irrespective of the nature of the \meta{box} before the trim +% operation is applied. +% Additional box levels are also generated by this operation. +% The behavior of the operation where the trims requested is +% greater than the size of the box is undefined. +% \end{function} +% +% \begin{function}[added = 2019-01-23] +% { +% \box_set_viewport:Nnnnn, \box_set_viewport:cnnnn, +% \box_gset_viewport:Nnnnn, \box_gset_viewport:cnnnn +% } +% \begin{syntax} +% \cs{box_set_viewport:Nnnnn} \meta{box} \Arg{llx} \Arg{lly} \Arg{urx} \Arg{ury} +% \end{syntax} +% Adjusts the bounding box of the \meta{box} such that it has lower-left +% co-ordinates (\meta{llx}, \meta{lly}) and upper-right co-ordinates +% (\meta{urx}, \meta{ury}). All four co-ordinate positions are +% \meta{dim exprs}. Material outside of the bounding box is +% still displayed in the output unless \cs{box_set_clipped:N} is +% subsequently applied. +% The updated \meta{box} is an +% hbox, irrespective of the nature of the \meta{box} before the viewport +% operation is applied. +% Additional box levels are also generated by this operation. +% \end{function} +% % \section{Primitive box conditionals} % % \begin{function}[EXP]{\if_hbox:N} @@ -2298,6 +2362,163 @@ % \end{macrocode} % \end{macro} % +% \subsection{Viewing part of a box} +% +% \begin{macro}{\box_set_clipped:N, \box_set_clipped:c, \box_gset_clipped:N, \box_gset_clipped:c} +% A wrapper around the driver-dependent code. +% \begin{macrocode} +\cs_new_protected:Npn \box_set_clipped:N #1 + { \hbox_set:Nn #1 { \@@_backend_clip:N #1 } } +\cs_generate_variant:Nn \box_set_clipped:N { c } +\cs_new_protected:Npn \box_gset_clipped:N #1 + { \hbox_gset:Nn #1 { \@@_backend_clip:N #1 } } +\cs_generate_variant:Nn \box_gset_clipped:N { c } +% \end{macrocode} +% \end{macro} +% +% \begin{macro} +% { +% \box_set_trim:Nnnnn, \box_set_trim:cnnnn, +% \box_gset_trim:Nnnnn, \box_gset_trim:cnnnn +% } +% \begin{macro}{\@@_set_trim:NnnnnN} +% Trimming from the left- and right-hand edges of the box is easy: kern the +% appropriate parts off each side. +% \begin{macrocode} +\cs_new_protected:Npn \box_set_trim:Nnnnn #1#2#3#4#5 + { \@@_set_trim:NnnnnN #1 {#2} {#3} {#4} {#5} \box_set_eq:NN } +\cs_generate_variant:Nn \box_set_trim:Nnnnn { c } +\cs_new_protected:Npn \box_gset_trim:Nnnnn #1#2#3#4#5 + { \@@_set_trim:NnnnnN #1 {#2} {#3} {#4} {#5} \box_gset_eq:NN } +\cs_generate_variant:Nn \box_gset_trim:Nnnnn { c } +\cs_new_protected:Npn \@@_set_trim:NnnnnN #1#2#3#4#5#6 + { + \hbox_set:Nn \l_@@_internal_box + { + \__kernel_kern:n { -#2 } + \box_use:N #1 + \__kernel_kern:n { -#4 } + } +% \end{macrocode} +% For the height and depth, there is a need to watch the baseline is +% respected. Material always has to stay on the correct side, so trimming +% has to check that there is enough material to trim. First, the bottom +% edge. If there is enough depth, simply set the depth, or if not move +% down so the result is zero depth. \cs{box_move_down:nn} is used in both +% cases so the resulting box always contains a \tn{lower} primitive. +% The internal box is used here as it allows safe use of \cs{box_set_dp:Nn}. +% \begin{macrocode} + \dim_compare:nNnTF { \box_dp:N #1 } > {#3} + { + \hbox_set:Nn \l_@@_internal_box + { + \box_move_down:nn \c_zero_dim + { \box_use_drop:N \l_@@_internal_box } + } + \box_set_dp:Nn \l_@@_internal_box { \box_dp:N #1 - (#3) } + } + { + \hbox_set:Nn \l_@@_internal_box + { + \box_move_down:nn { (#3) - \box_dp:N #1 } + { \box_use_drop:N \l_@@_internal_box } + } + \box_set_dp:Nn \l_@@_internal_box \c_zero_dim + } +% \end{macrocode} +% Same thing, this time from the top of the box. +% \begin{macrocode} + \dim_compare:nNnTF { \box_ht:N \l_@@_internal_box } > {#5} + { + \hbox_set:Nn \l_@@_internal_box + { + \box_move_up:nn \c_zero_dim + { \box_use_drop:N \l_@@_internal_box } + } + \box_set_ht:Nn \l_@@_internal_box + { \box_ht:N \l_@@_internal_box - (#5) } + } + { + \hbox_set:Nn \l_@@_internal_box + { + \box_move_up:nn { (#5) - \box_ht:N \l_@@_internal_box } + { \box_use_drop:N \l_@@_internal_box } + } + \box_set_ht:Nn \l_@@_internal_box \c_zero_dim + } + #6 #1 \l_@@_internal_box + } +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro} +% { +% \box_set_viewport:Nnnnn, \box_set_viewport:cnnnn, +% \box_gset_viewport:Nnnnn, \box_gset_viewport:cnnnn +% } +% \begin{macro}{\@@_viewport:NnnnnN} +% The same general logic as for the trim operation, but with absolute +% dimensions. As a result, there are some things to watch out for in the +% vertical direction. +% \begin{macrocode} +\cs_new_protected:Npn \box_set_viewport:Nnnnn #1#2#3#4#5 + { \@@_set_viewport:NnnnnN #1 {#2} {#3} {#4} {#5} \box_set_eq:NN } +\cs_generate_variant:Nn \box_set_viewport:Nnnnn { c } +\cs_new_protected:Npn \box_gset_viewport:Nnnnn #1#2#3#4#5 + { \@@_set_viewport:NnnnnN #1 {#2} {#3} {#4} {#5} \box_gset_eq:NN } +\cs_generate_variant:Nn \box_gset_viewport:Nnnnn { c } +\cs_new_protected:Npn \@@_set_viewport:NnnnnN #1#2#3#4#5#6 + { + \hbox_set:Nn \l_@@_internal_box + { + \__kernel_kern:n { -#2 } + \box_use:N #1 + \__kernel_kern:n { #4 - \box_wd:N #1 } + } + \dim_compare:nNnTF {#3} < \c_zero_dim + { + \hbox_set:Nn \l_@@_internal_box + { + \box_move_down:nn \c_zero_dim + { \box_use_drop:N \l_@@_internal_box } + } + \box_set_dp:Nn \l_@@_internal_box { - \@@_dim_eval:n {#3} } + } + { + \hbox_set:Nn \l_@@_internal_box + { \box_move_down:nn {#3} { \box_use_drop:N \l_@@_internal_box } } + \box_set_dp:Nn \l_@@_internal_box \c_zero_dim + } + \dim_compare:nNnTF {#5} > \c_zero_dim + { + \hbox_set:Nn \l_@@_internal_box + { + \box_move_up:nn \c_zero_dim + { \box_use_drop:N \l_@@_internal_box } + } + \box_set_ht:Nn \l_@@_internal_box + { + (#5) + \dim_compare:nNnT {#3} > \c_zero_dim + { - (#3) } + } + } + { + \hbox_set:Nn \l_@@_internal_box + { + \box_move_up:nn { - \@@_dim_eval:n {#5} } + { \box_use_drop:N \l_@@_internal_box } + } + \box_set_ht:Nn \l_@@_internal_box \c_zero_dim + } + #6 #1 \l_@@_internal_box + } +% \end{macrocode} +% \end{macro} +% \end{macro} + +% % \begin{macrocode} %</package> % \end{macrocode} |