summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/pdfmanagement-testphase/l3pdfannot.dtx
blob: 256e3e6dc9b9ce60ba358201394a8132d7cd2855 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
% \iffalse meta-comment
%
%% File: l3pdfannot.dtx
%
% Copyright (C) 2021 The LaTeX 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 "LaTeX PDF management testphase bundle" (The Work in LPPL)
% and all files in that bundle must be distributed together.
%
% -----------------------------------------------------------------------
%
% The development version of the bundle can be found at
%
%    https://github.com/latex3/pdfresources
%
% for those people who are interested.
%
%<*driver>
\RequirePackage{pdfmanagement-testphase}
\DeclareDocumentMetadata{pdfstandard=A-2b}
\makeatletter
\declare@file@substitution{doc.sty}{doc-v3beta.sty}
\makeatother
\documentclass[full]{l3doc}
\usepackage{array,booktabs,hyperxmp}
\hypersetup{pdfauthor=The LaTeX Project,
 pdftitle=l3pdfannot (LaTeX PDF management testphase bundle)}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
% \providecommand\hook[1]{\texttt{#1}}
% \title{^^A
%   The \pkg{l3pdfannot} module\\ Commands for PDF annotations   ^^A
%   \\ \LaTeX{} PDF management testphase bundle
% }
%
% \author{^^A
%  The \LaTeX{} Project\thanks
%    {^^A
%      E-mail:
%        \href{mailto:latex-team@latex-project.org}
%          {latex-team@latex-project.org}^^A
%    }^^A
% }
%
% \date{Version 0.95c, released 2021-03-17}
%
% \maketitle
% \begin{documentation}
%
% \section{\pkg{l3pdfannot} documentation}
% This module contains a number of commands to create PDF annotations.
% The commands are \emph{not} always simple wrappers around primitive commands.
% To allow external packages to configure links and other annotations,
% some of the commands have hooks and use shared attribute dictionaries.
% For these commands the hooks and dictionaries are selected depending on the \meta{type}
% of the annotation. Currently the module only supports some general commands
% and link annotations. Commands for other annotations like widgets will be added
% later.
%
% \subsection{General annotation commands}
%
% \begin{function}[added = 2019-09-05, updated = 2020-04-14]
%   { \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. 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}
%     \cs{pdfannot_box_ref_last:}
%   \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.
% Link annotations are quite important as many documents contain links,
% both internal and external. They need a set of special commands for two reasons:
%
% At first the content of links are not only boxes. Links can contain line
% and page breaks (this is normally implemented by the primitive command by
% creating a set of annotations).
%
% At second link annotations are objects that need some
% \enquote{management} as more than one
% package wants to configure their look and behaviour.
% For example \pkg{hyperref}, \pkg{ocgx2} and the code for tagged PDF (currently
% in \pkg{tagpdf}) all want to add keys and values to the dictionaries of
% link annotation and code around links.
% So commands to create link annotations should offer suitable hooks.
% There are three standard places in a link where such hooks are needed:
% At the begin (for example for a structure command or color),
% in the \emph{attr spec} dictionary of the link (for example for the border), and
% at the end of the link (to close a structure or the color group).
% For the begin and end hooks of the LaTeX hook management are predefined and used.
% To add and remove values from the \emph{attr spec} dictionary special
% commands described below are provided. The link commands switch to horizontal mode
% as the commands of pdftex and luatex can't be used in vertical mode.
%
% \begin{variable}{\c_pdfannot_link_types_seq}
% There are currently five link types, \texttt{URI}, \texttt{GoToR},
%  \texttt{Launch}, \texttt{GoTo} or \texttt{Named}, and there are store in this
%  constant.
% \end{variable}
% \begin{variable}
%  {
%   pdfannot/link/TYPE/before,
%   pdfannot/link/TYPE/begin,
%   pdfannot/link/TYPE/end,
%   pdfannot/link/TYPE/after
%  }
%  These are the hooks used by the following commands. TYPE can be one of
%  \texttt{URI}, \texttt{GoToR},
%  \texttt{Launch}, \texttt{GoTo} or \texttt{Named}
% \end{variable}
% \begin{variable}
%  {
%    link/TYPE
%  }
%  These is the name of the dictionary used by the following commands. TYPE can be one of
%  \texttt{URI}, \texttt{GoToR},
%  \texttt{Launch}, \texttt{GoTo} or \texttt{Named}. The dictionary can be changed
%  by the commands \cs{pdfannot_dict_put:nnn} and friends described below.
% \end{variable}
% \begin{function}[added = 2020-03-12, updated = 2020-12-06]
%    { \pdfannot_link:nnn,\pdfannot_link:nxn }
%   \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}.
%  \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.
%  \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} 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)
%  while \texttt{pdfannot/link/\meta{type}/begin}
%  and \texttt{pdfannot/link/\meta{type}/end} are directly around the link
%  text. None of the hooks introduce a group.
%  \meta{type} should normally be identical to the value of the |/S| key
%  in the action dictionary.
%  As example either with a direct action
%  \begin{verbatim}
%  \pdfannot_link:nnn { URI }
%     {
%       /A<<
%         /Type/Action
%         /S/URI
%         /URI(https://www.latex-project.org)
%       >>
%     }
%    { link text}
%  \end{verbatim}
%  Or through  a dictionary:
%  \begin{verbatim}
%    \pdfdict_new:n   {l_my_action_dict}
%    \pdfdict_put:nnn {l_my_action_dict}{Type}{/Action}
%    \pdfdict_put:nnn {l_my_action_dict}{S}{/URI}
%    \pdfdict_put:nnn {l_my_action_dict}{URI}{(https://www.latex-project.org)}
%
%    \pdfannot_dict_put:nnn
%      {link/URI} { C } {[1~0~0]} %red border
%
%    \pdfannot_link:nxn { URI }
%     {
%       /A <<\pdfdict_use:n{l_my_action_dict}>>
%     }
%     { link text }
%    \end{verbatim}
%
% Or if you want to exclude the possibility of a duplicated /A entry
% (if the action is already in the link/GoTo dictionary e.g. if you can expect
% other packages to add a dictionary). An alternative is to ensure that
% no /A is there by removing it explicitly.
%
%  \begin{verbatim}
%    \pdfdict_new:n   {l_my_action_dict}
%    \pdfdict_put:nnn {l_my_action_dict}{Type}{/Action}
%    \pdfdict_put:nnn {l_my_action_dict}{S}{/URI}
%    \pdfdict_put:nnn {l_my_action_dict}{URI}{(https://www.latex-project.org)}
%
%
%    \pdfannot_dict_put:nnn
%      {link/URI} { C } {[1~0~0]} %red border
%
%    \group_begin:
%    \pdfannot_dict_put:nnx {link/GoTo}{A}{<<\pdfdict_use:n{l_my_action_dict}>>}
%    \pdfannot_link:nnn { URI }{}{ link text }
%    \group_end:
%    \end{verbatim}
%
%
% \end{function}
% \begin{function}[updated = 2020-12-06]{ \pdfannot_link_begin:nnw, \pdfannot_link_end:n }
%   \begin{syntax}
%     \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 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
%  be used in circumstances where the \meta{content} may not be a simple
%  argument. But beside this, it works similar and use the same hooks.
%  As example
%  \begin{verbatim}
%    \pdfannot_link_begin:nnw { URI }
%     {
%       /A<<
%         /Type/Action
%         /S/URI
%         /URI(https://www.latex-project.org)
%       >>
%     }
%     link text
%    \pdfannot_link_end:n { URI }
%    \end{verbatim}
% \end{function}
% \begin{function}[updated = 2020-12-06]{ \pdfannot_link_goto_begin:nw, \pdfannot_link_goto_end: }
%   \begin{syntax}
%     \cs{pdfannot_link_goto_begin:nw} \Arg{destination} \meta{content}
%     \cs{pdfannot_link_goto_end:}
%   \end{syntax}
% This is a special, shorter version for links to internal destinations. It always
% uses the hooks and dictionary of the |GoTo| link type. \meta{destination} is a
% destination name. In difference to |\pdfannot_link:nnn { GoTo }| it will complain if
% \meta{destination} is an unknown destination and give the message
%
% |name{ZZZZ} has been referenced but does not exist, replaced by a fixed one|
%
% \end{function}
% \begin{function}[added = 2021-02-14]{  \pdfannot_link_ref_last: }
%   This retrieves the object reference a link created previously with the commands
%   above. This doesn't work currently with xelatex but a feature request has
%   been made. see https://tug.org/pipermail/dvipdfmx/2020-December/000134.html
% \end{function}
% \begin{function}[added = 2021-02-14]{  \pdfannot_ref_last: }
%   This retrieves the object reference a previously annotation
%   created either with a link or a general box command. When the last was a link
%   it won't work with xelatex.
%   see https://tug.org/pipermail/dvipdfmx/2020-December/000134.html
% \end{function}
% \begin{NOTE}{UF}
% only annot link or also annot?
% \end{NOTE}
% \begin{function}[added = 2020-03-12]{  \pdfannot_link_margin:n }
%  \begin{syntax}
%    \cs{pdfannot_link_margin:n} \Arg{dimen}
%  \end{syntax}
%   This sets the dimension of the link margin.
% \end{function}
% \begin{function}[added = 2020-12-04]{ \pdfannot_dict_put:nnn }
%  \begin{syntax}
%    \cs{pdfannot_dict_put:nnn} \Arg{dictionary name} \Arg{key} \Arg{value}
%  \end{syntax}
%   This adds (locally) a key-value to the internal annot dictionaries used
%   by the link commands above.
%   \meta{dictionary name} should be currently one of \texttt{link/URI},
%   \texttt{link/URI},\texttt{link/GoToR}, \texttt{link/Launch},
%   \texttt{link/GoTo}, \texttt{link/Named}.
% \end{function}
% \begin{function}[added = 2020-12-04]{ \pdfannot_dict_remove:nn }
%  \begin{syntax}
%    \cs{pdfannot_dict_remove:nn} \Arg{dictionary name} \Arg{key}
%  \end{syntax}
%   This removes a key-value from the internal annot dictionary
%   \meta{dictionary name} should be currently one of
%   \texttt{link/URI}, \texttt{link/GoToR}, \texttt{link/Launch},
%   \texttt{link/GoTo}, \texttt{link/Named}.
% \end{function}
% \begin{function}[added = 2020-12-04]{ \pdfannot_dict_show:n }
%  \begin{syntax}
%    \cs{pdfannot_dict_show:n} \Arg{dictionary name}
%  \end{syntax}
%   This shows the content of the internal annot dictionary.
%  \meta{dictionary name} should be currently one of \texttt{link/URI},
%   \texttt{link/URI}, \texttt{link/GoToR}, \texttt{link/Launch},
%   \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.
%  It can be used for example like this:
%  \begin{verbatim}
%  \pdfannot_dict_put:nnn {link/URI} {F}
%     { \bitset_to_arabic:N \l_pdfannot_F_bitset }
%  \bitset_set_true:Nn \l_pdfannot_F_bitset {Print}
%  \end{verbatim}
%  The known keys for the bitset are |Invisible|, |Hidden|,
%  |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}
%
% \section{\pkg{l3pdfannot} implementation}
%
%    \begin{macrocode}
%<@@=pdfannot>
%<*header>
\ProvidesExplPackage{l3pdfannot}{2021-03-17}{0.95c}
  {PDF-annotations}
\RequirePackage{l3pdfdict}
%</header>
%    \end{macrocode}
% Annotations have a /F flag, we provide a public
% bitset for it.
%    \begin{macrocode}
%<*package>
\RequirePackage{l3bitset}
\bitset_new:Nn \l_pdfannot_F_bitset
  {
    Invisible      = 1,
    Hidden         = 2,
    Print          = 3,
    NoZoom         = 4,
    NoRotate       = 5,
    NoView         = 6,
    ReadOnly       = 7,
    Locked         = 8,
    ToggleNoView   = 9,
    LockedContents = 10
  }
%    \end{macrocode}
% \begin{NOTE}{UF}
% The code/naming tries to unify general annotations and the special type of
% link under a common name.
% regarding naming and relation of annotation commands see
% https://github.com/FrankMittelbach/AccessiblePDF/issues/73
% \subsection{Annotations / backend}
% The backend commands are in l3backend:
% \cs{__pdf_backend_annotation:nnnn} and \cs{__pdf_backend_annotation_last:}
% \cs{__pdf_backend_link_begin_user:nnw}, etc
% \end{NOTE}
%
% \subsection{ General Annotations }
% \begin{variable}
%  { \g_@@_use_lastlink_bool }
% The pdf engines have two different primitive commands to refer to the last created
% annotation: one for links, one for boxed annotation. We use a boolean to decide
% which one should be used, so that only one user command is needed.
%    \begin{macrocode}
\bool_new:N \g_@@_use_lastlink_bool
%    \end{macrocode}
% \end{variable}
% \begin{NOTE}{UF}
%  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:
  }

%    \end{macrocode}
% \end{macro}
% \subsection{Annotations, subtype Widget}\label{pdf:annot:widget}
% 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_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}
% The code assumes that there will be different link types
% (currently URI, GoToR, Launch, GoTo, Named, hyperref uses the names
% url,file,run,link,menu) and that links of the same type share
% the \emph{attr spec} and also the same begin/end
% code. The list of link types need to stay restricted and well documented so that
% all packages know which types they have to handle. It is stored in a constant
% seq.
% \begin{NOTE}{UF}
% Perhaps a |cite| type will be useful at some time. -- Thinking more about it,
% a |cite| type is not sensible. hyperref supports it, but it doesn't fit in.
% Commands like cite, gls, acro, footnote and so on should locally change
% linkcolor and linkbordercolor.
% Probably we will need some commands to add an attribute to all link types
% at once.
% hyperref commands for the various type:
% url  |\hyper@linkurl|,
% file |\hyper@linkfile|,
% run  |\@hyper@launch run|,
% link |\hyper@link|, |\find@pdflink|
% menu |\Acrobatmenu|
% \end{NOTE}
% \begin{variable}[added = 2020-03-12]{ \c_pdfannot_link_types_seq }
% This constant sequence contains the list of currently supported link types
% for which hooks and dictionaries exist.
% \end{variable}
%
% \begin{variable}
%   {
%     link/TYPE,
%     pdfannot/link/TYPE/before,
%     pdfannot/link/TYPE/begin,
%     pdfannot/link/TYPE/end,
%     pdfannot/link/TYPE/after
%   }
% These setup the dictionary and the hook pairs.
%    \begin{macrocode}
\seq_const_from_clist:Nn \c_pdfannot_link_types_seq { URI , GoToR , Launch , GoTo, Named }
\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}
    \hook_new_pair:nn
      {pdfannot/link/#1/begin}
      {pdfannot/link/#1/end}
   }
%    \end{macrocode}
% \end{variable}
% \subsubsection{Annotations, subtype Link /management}
%
% \begin{macro}{\pdfannot_link:nnn,\pdfannot_link:nxn}
%    \begin{macrocode}
\cs_new_protected:Nn \pdfannot_link:nnn %#1 type (URI, GoTo etc),
                                        %#2 action spec, #3 link text
  {
    \hook_use:n { pdfannot/link/#1/before}
    \mode_leave_vertical:
    \exp_args:Nxx %xetex needs expansion
    \__pdf_backend_link_begin_user:nnw
      {
         \pdfdict_if_exist:nT { l_@@/link/#1 }
          {
            \pdfdict_use:n { l_@@/link/#1}
          }
      }
      {
        #2 %exp_not?
      }
    \bool_gset_true:N \g_@@_use_lastlink_bool
    \hook_use:n { pdfannot/link/#1/begin}
    #3
    \hook_use:n { pdfannot/link/#1/end}
    \__pdf_backend_link_end:
    \bool_gset_true:N \g_@@_use_lastlink_bool
    \hook_use:n { pdfannot/link/#1/after}
  }
\cs_generate_variant:Nn \pdfannot_link:nnn {nxn}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{
%   \pdfannot_link_begin:nnw,
%   \pdfannot_link_begin:nxw,
%   \pdfannot_link_end:n }
%    \begin{macrocode}
\cs_new_protected:Npn \pdfannot_link_begin:nnw #1 #2 %#1 type, #2 action spec
  {
    \hook_use:n { pdfannot/link/#1/before}
    \mode_leave_vertical:
    \exp_args:Nxx %xetex needs expansion
      \__pdf_backend_link_begin_user:nnw
        {
           \pdfdict_if_exist:nT { l_@@/link/#1 }
            {
              \pdfdict_use:n { l_@@/link/#1}
            }
        }
        { #2 }
      \bool_gset_true:N \g_@@_use_lastlink_bool
      \hook_use:n { pdfannot/link/#1/begin}
  }

\cs_new_protected:Nn \pdfannot_link_end:n %#1 type, e.g. url
  {
    \hook_use:n { pdfannot/link/#1/end}
    \__pdf_backend_link_end:
    \bool_gset_true:N \g_@@_use_lastlink_bool
    \hook_use:n { pdfannot/link/#1/after}
  }
\cs_generate_variant:Nn \pdfannot_link_begin:nnw {nxw}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\pdfannot_link_goto_begin:nw, \pdfannot_link_goto_end:}
%     \begin{macrocode}
\cs_new_protected:Npn \pdfannot_link_goto_begin:nw #1 %#1 destination
  {
    \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
      {
        \pdfdict_use:n { l_@@/link/GoTo}
      }
      { #1 }
     \bool_gset_true:N \g_@@_use_lastlink_bool
    \pdfdict_put:nnn { l_@@/link/GoTo} {Subtype}{GoTo}
     \hook_use:n { pdfannot/link/GoTo/begin}
  }

\cs_new_protected:Nn \pdfannot_link_goto_end:
  {
    \hook_use:n { pdfannot/link/GoTo/end}
    \__pdf_backend_link_end:
    \bool_gset_true:N \g_@@_use_lastlink_bool
     \hook_use:n { pdfannot/link/GoTo/after}
  }
%    \end{macrocode}
% \end{macro}
% \begin{macro}[EXP]{\pdfannot_link_ref_last:, \pdfannot_ref_last:}
%    \begin{macrocode}
\cs_new:Nn \pdfannot_link_ref_last: { \__pdf_backend_link_last: }
%    \end{macrocode}
%    \begin{macrocode}
\cs_new:Npn \pdfannot_ref_last:
  {
    \bool_if:NTF \g_@@_use_lastlink_bool
      {
        \__pdf_backend_link_last:
      }
      {
        \__pdf_backend_annotation_last:
      }
  }
%    \end{macrocode}
% \end{macro}
% \begin{macro}{ \pdfannot_link_margin:n}
%    \begin{macrocode}
\cs_new_protected:Npn \pdfannot_link_margin:n #1
  {
    \__pdf_backend_link_margin:n { #1 }
  }
%    \end{macrocode}
% \end{macro}
% \begin{macro}
%   {
%     \pdfannot_dict_put:nnn,
%     \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
  {
    \pdfdict_put:nnn { l_@@/#1 } { #2 }{ #3 }
  }
\cs_generate_variant:Nn \pdfannot_dict_put:nnn {nnx}
%    \end{macrocode}
%    \begin{macrocode}
\cs_new_protected:Npn \pdfannot_dict_remove:nn #1 #2
  {
    \pdfdict_remove:nn { l_@@/#1 } { #2 }
  }
%    \end{macrocode}
%    \begin{macrocode}
\cs_new_protected:Npn \pdfannot_dict_show:n #1
  {
    \pdfdict_show:n { l_@@/#1 }
  }

\cs_new:Npn \pdfannot_dict_use:n #1
  {
    \pdfdict_use:n { l_@@/#1 }
  }
%</package>
%    \end{macrocode}
% \end{macro}
% \end{implementation}
%
% \PrintIndex