summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/pdfmanagement-testphase/l3pdfannot.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/pdfmanagement-testphase/l3pdfannot.dtx')
-rw-r--r--macros/latex/contrib/pdfmanagement-testphase/l3pdfannot.dtx159
1 files changed, 114 insertions, 45 deletions
diff --git a/macros/latex/contrib/pdfmanagement-testphase/l3pdfannot.dtx b/macros/latex/contrib/pdfmanagement-testphase/l3pdfannot.dtx
index 94b7a89af8..71ee24f53d 100644
--- a/macros/latex/contrib/pdfmanagement-testphase/l3pdfannot.dtx
+++ b/macros/latex/contrib/pdfmanagement-testphase/l3pdfannot.dtx
@@ -52,7 +52,7 @@
% }^^A
% }
%
-% \date{Version 0.95a, released 2021-02-21}
+% \date{Version 0.95b, released 2021-02-21}
%
% \maketitle
% \begin{documentation}
@@ -70,26 +70,15 @@
% \subsection{General annotation commands}
%
% \begin{function}[added = 2019-09-05, updated = 2020-04-14]
-% { \pdfannot_box:nnnn }
+% { \pdfannot_box:nnnn,\pdfannot_box:nnnx }
% \begin{syntax}
% \cs{pdfannot_box:nnnn} \Arg{width} \Arg{height} \Arg{depth} \Arg{annot spec}
% \end{syntax}
% This creates an \texttt{/Type/Annot} object with the given dimensions.
-% It doesn't use hooks or dictionaries.
-% \end{function}
-% \begin{function}[added = 2020-03-30]
-% { \pdfannot_box:nnnnn }
-% \begin{syntax}
-% \cs{pdfannot_box:nnnnn} \Arg{type} \Arg{width} \Arg{height} \Arg{depth} \Arg{annot spec}
-% \end{syntax}
-% This creates an \texttt{/Type/Annot} object with the given dimensions.
-% \meta{type} should be currently one of |link/URI|, |link/GoToR|,
-% |link/Launch|, |link/GoTo| or |link/Named| or
-% |widget|, it will then insert the attribute dictionary of this type
-% additionally to the manually given \meta{annot spec}.
-% The attribute dictionaries can be filled with commands described below.
-% Hooks are not used.
+% It doesn't use hooks or dictionaries. The annotation doesn't occupy space but
+% as it is a whatsit it can affect spacing.
% \end{function}
+%
% \begin{function}[added = 2019-09-05]
% { \pdfannot_box_ref_last: }
% \begin{syntax}
@@ -97,6 +86,32 @@
% \end{syntax}
% This retrieves the object reference of the last box annotation created.
% \end{function}
+% \subsection{Dictionary for the annotation spec}
+%
+% \meta{annot spec} in the above command can be given in two ways. One way is
+% to enter the needed dictionary keys and values directly:
+% \begin{verbatim}
+% \pdfannot_box:nnnn{1cm}{1cm}{0cm}{/Subtype/Link /Border[0~0~1]}
+% \end{verbatim}
+%
+% A second method is to make use of the dictionary commands provided by \pkg{l3pdfdict}:
+%
+% \begin{verbatim}
+% \pdfdict_new:n {l_my_annot}
+% \pdfdict_put:nnn{l_my_annot}{Subtype}{/Link}
+% \pdfdict_put:nnn{l_my_annot}{Border}{[0~0~1]}
+% \pdfannot_box:nnnx{1cm}{1cm}{0cm}{\pdfdict_use:n{l_my_annot}}
+% \end{verbatim}
+%
+% The second method is clearly slower and more to type. But it has the advantage
+% that using such a dictionary makes it easy to add, remove and change entries.
+% It also avoids the potential problem that a key is added twice with different
+% values. This allows to create user interfaces to change settings and
+% also makes it easy to extend the interfaces in case some new setting
+% should be included. For these reasons both the PDF management itself,
+% but also the specific annotation commands in the following sections
+% all make use of such dictionaries.
+%
% \subsection{Link annotations}
% Link annotations are special cases of annotations. In the PDF they are identified
% by an |/Subtype/Link| entry in the dictionary.
@@ -152,16 +167,22 @@
% \begin{syntax}
% \cs{pdfannot_link:nnn} \Arg{type} \Arg{user action spec} \Arg{link text}
% \end{syntax}
-% This creates a link around the \meta{link text} with the specified
+% This creates a link around the \meta{link text}.
+% \texttt{/Subtype/Link} is added automatically through the dictionary.
% \meta{user action spec}\footnote{The wording follows the pdftex documentation}.
-% \texttt{/Subtype/Link} is added automatically.
+% is provided as a fast method to add dictionary contents,
+% but it should be noted that no provision is taken to avoid clashes with
+% values added through the dictionary. If needed clashing entries should be
+% removed from the dictionary first. Normally the argument is not needed, all
+% entries can be added through the dictionary too.
% \meta{type} should be one of \texttt{URI}, \texttt{GoToR},
% \texttt{Launch}, \texttt{GoTo} or \texttt{Named}. The |GoTo| variant does
% \emph{not} complain if the destination name is not known like
% \cs{pdfannot_link_goto_begin:nw}.
% The attributes stored in the local dictionary
% \texttt{link/}\meta{type} are inserted as
-% \emph{attr spec} and the code in the begin and end hook
+% \emph{attr spec} before \meta{user action spec}.
+% The code in the begin and end hook
% \texttt{pdfannot/link/\meta{type}/before}
% and \texttt{pdfannot/link/\meta{type}/after}
% is executed before and after the link (outside the link command)
@@ -193,10 +214,14 @@
% \cs{pdfannot_link_begin:nnw} \Arg{type} \Arg{user action spec} \meta{content}
% \cs{pdfannot_link_end:n} \Arg{type}
% \end{syntax}
-% This creates a link around the \meta{content} with the specified
-% \meta{user action spec} (e.g. an /A dictionary with an URI) or
-% \meta{destination} (a name as defined with the
-% first argument of \cs{pdf_destination:nn}).
+% This creates a link like the previous command.
+% \texttt{/Subtype/Link} is added automatically through the dictionary.
+% \meta{user action spec}\footnote{The wording follows the pdftex documentation}.
+% is provided as a fast method to add dictionary contents,
+% but it should be noted that no provision is taken to avoid clashes with
+% values added through the dictionary. If needed clashing entries should be
+% removed from the dictionary first. Normally the argument is not needed, all
+% entries can be added through the dictionary too.
% \texttt{/Subtype/Link} is added automatically.
% In contrast to \cs{pdfannot_link:nnn} this function
% does not absorb the argument when finding the \meta{content}, and so can
@@ -278,6 +303,17 @@
% \texttt{link/GoTo}, \texttt{link/Named}.
% \end{function}
%
+% \begin{function}[EXP,added = 2021-03-03]
+% { \pdfannot_dict_use:n }
+% \begin{syntax}
+% \cs{pdfannot_dict_use:n} \Arg{dictionary name}
+% \end{syntax}
+% This outputs the property list of the dictionary as a list of
+% |/key value| pairs.
+% This can be used e.g. when writing a dictionary object with
+% \cs{pdf_object_write:nx}
+% \end{function}
+%
% \begin{variable}[added = 2020-12-28]{\l_pdfannot_F_bitset}
% This is a bitset variable, with the named index names suitable for the
% /F flag in an annotation.
@@ -291,6 +327,27 @@
% |Print|, |NoZoom|, |NoRotate|, |NoView|, |ReadOnly|, |Locked|, |ToggleNoView|,
% |LockedContents| which correspond to the names used in the PDF references.
% \end{variable}
+% \subsection{Widget annotations}
+% Widget annotations are quite important for form fields, as they are used
+% to build the actually instance of such fields.
+%
+% As they can contain meaningful content hooks are probably needed to allow tagging
+% and other manipulations, so like with link special commands are provided.
+% Widget are normally in a box and line and page breaks are not relevant, so
+% the command is offered as box command.
+%
+% \begin{function}[added = 2021-03-02]
+% { \pdfannot_widget_box:nnn }
+% \begin{syntax}
+% \cs{pdfannot_widget_box:nnn} \Arg{width} \Arg{height} \Arg{depth}
+% \end{syntax}
+% This creates an \texttt{/Type/Annot} object with the given dimensions.
+% The annotation doesn't occupy space.
+% It will insert the attribute dictionary of the widget type (which
+% is prefilled with \texttt{/Subtype/Widget}).
+% The hooks \texttt{pdfannot/widget/before} and \texttt{pdfannot/widget/after}
+% are executed before and after the widget.
+% \end{function}
% \end{documentation}
%
% \begin{implementation}
@@ -300,7 +357,7 @@
% \begin{macrocode}
%<@@=pdfannot>
%<*header>
-\ProvidesExplPackage {l3pdfannot} {2021-02-22} {0.95a}
+\ProvidesExplPackage {l3pdfannot} {2021-03-07} {0.95b}
{PDF-annotations}
\RequirePackage{l3pdfdict}
%</header>
@@ -349,41 +406,45 @@
% type or not type? Syntax for type?
% should there be a version without type?
% \end{NOTE}
-
+% \begin{macro}{\pdfannot_box:nnnn,\pdfannot_box:nnnx,\pdfannot_box_ref_last:}
% \begin{macrocode}
\cs_new_protected:Npn \pdfannot_box:nnnn #1 #2 #3 #4
{
\__pdf_backend_annotation:nnnn {#1}{#2}{#3}{#4}
\bool_gset_false:N\g_@@_use_lastlink_bool
}
-
+\cs_generate_variant:Nn \pdfannot_box:nnnn {nnnx}
\cs_new:Npn \pdfannot_box_ref_last:
{
\__pdf_backend_annotation_last:
}
-\cs_new_protected:Npn \pdfannot_box:nnnnn #1 #2 #3 #4 #5
- {
- \exp_args:Nx
- \__pdf_backend_annotation:nnnn {#2}{#3}{#4}
- {
- \pdfdict_if_exist:nT { l_@@/#1 }
- {
- \pdfdict_use:n { l_@@/#1}
- }
- #5
- }
- \bool_gset_false:N\g_@@_use_lastlink_bool
- }
% \end{macrocode}
+% \end{macro}
% \subsection{Annotations, subtype Widget}\label{pdf:annot:widget}
-% Currently no code is provided here.
-% The local dictionary \texttt{l_@@/Widget} is a skeleton
-% dictionary for this subtype. It currently contains as only entry
+% Widgets are typically boxes, so we provide a box command.
+% A local dictionary \texttt{l_@@/Widget} is used.
+% It contains like the other dictionaries
% the subtype setting (the /Type is added by the backend).
% \begin{macrocode}
- \pdfdict_new:n { l_@@/widget }
+ \pdfdict_new:n { l_@@/widget }
\pdfdict_put:nnn { l_@@/widget }{ Subtype }{ /Widget }
+ \hook_new_pair:nn
+ {pdfannot/widget/before}
+ {pdfannot/widget/after}
+ \hook_new_pair:nn
+ {pdfannot/widget/begin}
+ {pdfannot/widget/end}
+\cs_new_protected:Npn \pdfannot_widget_box:nnn #1 #2 #3
+ {
+ \hook_use:n { pdfannot/widget/before }
+ \pdfannot_box:nnnx {#1}{#2}{#3}
+ {
+ \pdfdict_use:n { l_@@/widget}
+ }
+ \hook_use:n { pdfannot/widget/after }
+ \bool_gset_false:N\g_@@_use_lastlink_bool
+ }
% \end{macrocode}
%
% \subsection{Annotations, subtype Link}\label{sec:links}
@@ -427,6 +488,7 @@
\seq_map_inline:Nn \c_pdfannot_link_types_seq
{
\pdfdict_new:n { l_@@/link/#1 }
+ \pdfdict_put:nnn { l_@@/link/#1 }{ Subtype }{ /Link }
\hook_new_pair:nn
{pdfannot/link/#1/before}
{pdfannot/link/#1/after}
@@ -454,7 +516,6 @@
}
}
{
- /Subtype/Link
#2 %exp_not?
}
\bool_gset_true:N \g_@@_use_lastlink_bool
@@ -504,7 +565,8 @@
% \begin{macrocode}
\cs_new_protected:Npn \pdfannot_link_goto_begin:nw #1 %#1 destination
{
- \hook_use:n { pdfannot/link/GoTo/before}
+ \pdfdict_remove:nn { l_@@/link/GoTo} {Subtype}
+ \hook_use:n { pdfannot/link/GoTo/before} %the backend add it too
\mode_leave_vertical:
\exp_args:Nxx %xetex needs expansion
\__pdf_backend_link_begin_goto:nnw
@@ -513,6 +575,7 @@
}
{ #1 }
\bool_gset_true:N \g_@@_use_lastlink_bool
+ \pdfdict_put:nnn { l_@@/link/GoTo} {Subtype}{GoTo}
\hook_use:n { pdfannot/link/GoTo/begin}
}
@@ -556,6 +619,7 @@
% \pdfannot_dict_put:nnx,
% \pdfannot_dict_remove:nn,
% \pdfannot_dict_show:n
+% \pdfannot_dict_use:n
% }
% \begin{macrocode}
\cs_new_protected:Npn \pdfannot_dict_put:nnn #1 #2 #3
@@ -575,6 +639,11 @@
{
\pdfdict_show:n { l_@@/#1 }
}
+
+\cs_new:Npn \pdfannot_dict_use:n #1
+ {
+ \pdfdict_use:n { l_@@/#1 }
+ }
%</package>
% \end{macrocode}
% \end{macro}