[latex3-commits] [git/LaTeX3-latex3-pdfresources] radiobuttons: first draft choice keys (b779fd1)
Ulrike Fischer
fischer at troubleshooting-tex.de
Tue Jun 1 18:13:53 CEST 2021
Repository : https://github.com/latex3/pdfresources
On branch : radiobuttons
Link : https://github.com/latex3/pdfresources/commit/b779fd1021ade39447dd840026fb90d17ad12196
>---------------------------------------------------------------
commit b779fd1021ade39447dd840026fb90d17ad12196
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date: Tue Jun 1 18:13:53 2021 +0200
first draft choice keys
>---------------------------------------------------------------
b779fd1021ade39447dd840026fb90d17ad12196
l3pdffield-choice.dtx | 588 ++++++++++++++++++++++++++++++++++++++++++++
l3pdffield.dtx | 10 +
pdfmanagement-testphase.ins | 1 +
3 files changed, 599 insertions(+)
diff --git a/l3pdffield-choice.dtx b/l3pdffield-choice.dtx
new file mode 100644
index 0000000..43523a5
--- /dev/null
+++ b/l3pdffield-choice.dtx
@@ -0,0 +1,588 @@
+% \iffalse meta-comment
+%
+%% File: l3pdfpdffield-choice.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{}
+\makeatletter
+\declare at file@substitution{doc.sty}{doc-v3beta.sty}
+\makeatother
+\documentclass[full]{l3doc}
+\usepackage{array,booktabs}
+\usepackage{l3pdffield-testphase}
+\hypersetup{pdfauthor=The LaTeX Project,
+ pdftitle=l3pdffield (LaTeX PDF management testphase bundle)}
+\begin{document}
+ \DocInput{\jobname.dtx}
+\end{document}
+%</driver>
+% \fi
+% \providecommand\hook[1]{\texttt{#1}}
+% \title{^^A
+% The \pkg{l3pdffield-choice} module\\ Commands to create choice fields ^^A
+% \\ \LaTeX{} PDF management testphase bundle
+% }
+%
+% \author{^^A
+% The \LaTeX{} Project\thanks
+% {^^A
+% E-mail:
+% \href{mailto:latex-team at latex-project.org}
+% {latex-team at latex-project.org}^^A
+% }^^A
+% }
+%
+% \date{Version 0.95c, released 2021-03-17}
+%
+% \maketitle
+% \begin{documentation}
+% \section{\pkg{l3pdffield-choice} Introduction}
+% This is the documentation for choice fields, for general information about form fields
+% check the documentation l3pdffield.
+%
+%
+% Please keep in mind
+% \begin{itemize}
+% \item Not every PDF viewer supports choice field.
+% \item The handling can depend on settings in the PDF viewer. In adobe reader for
+% example I had to disable an option to avoid that it tries to create an appearance
+% itself
+% \item Standards like pdf/A disable features of form fields too
+% (as you typically can't change the PDF).
+% \end{itemize}
+% \section{Choice fields}
+%
+% Choice fields are drop down menus or scrollable lists where
+% the user can select one or more entries. They can also contain a field where
+% users can insert a free text. The export value and the displayed value can differ.
+% Some values can be preselected.
+%
+% This means that various data will have to be set, and the sorting matters.
+% The module here will assume that the various values are stored in sequences:
+%
+% \ExplSyntaxOn
+% \seq_const_from_clist:Nn \c_my_values_seq {hippo,duck,bear}
+% \seq_const_from_clist:Nn \c_my_displayvalues_seq {Sieglinde,,Bär}
+% \seq_const_from_clist:Nn \c_my_defaultvalues_seq {duck,Bär} %check if export or altname ...
+% \ExplSyntaxOff
+%
+% Only the first sequence is required.
+% Empty values in the display sequence are possible, then the normal value is used.
+%
+% \subsection{Types}
+% Choice fields can be a drop down menu (called |Combo|), which can contain an editable
+% field.
+%
+% |setfieldflags={Combo,Edit}| or |setfieldflags={Combo}|
+%
+% If |Edit| is set, one can also set |DoNotSpellCheck|.
+%
+% Or they can be a list.
+%
+% |unsetfieldflags={Combo,Edit,DoNotSpellCheck}|
+%
+%
+% For both types it is possible to set or unset |MultiSelect| and |CommitOnSelChange|.
+%
+%
+% \subsection{Appearance}
+% hm ....
+%
+% \bigskip
+% \subsection{Commands}
+% \begin{function}{\pdffield_choice:n}
+% \begin{syntax}
+% \cs{pdffield_choice:n}\Arg{key val list}
+% \end{syntax}
+% This creates a choice field.
+% The list of allowed keys is described below.
+% The \meta{key val list} should at least set the name,
+% without it the default |choice| is used. Choice fields with the same
+% belong to the same field and if changed, the others are changed accordingly.
+% The default appearance ...
+%
+% The first choice field setups the field and so should setup values and field flags.
+% \end{function}
+%
+%
+% \subsection{Keys}
+%
+% The new choice command accept all field and annot keys from l3pdffield.
+% A few keys are disabled or are forced to specific values.
+% The |appearance| keys have a ...
+% behaviour, other keys have other defaults than with the basic commands.
+% Additionally there
+% are a small number of keys specific to a choice field.
+% |value| and |default| have a special meaning.
+%
+%
+% Disabled keys are
+% \begin{itemize}
+% \item |V|, |DV|, |AS|: they are set by the other keys.
+% \item |FT| is overwritten.
+% \item For fields only the field flags |ReadOnly|, |Required|, |NoExport|,
+% |Combo|, |Edit|, |MultiSelect|, |Sort|, |DoNotSpellCheck| and |CommitOnSelChange|
+% make sense. The code will force some values (e.g. disable |Edit| if |Combo| is false).
+% \end{itemize}
+%
+%
+% \begin{function}{preset-choice}
+% \begin{syntax}
+% |preset-choice| = \Arg{key-val-list}
+% \end{syntax}
+% This allows to set default keys for a choice field.
+% \end{function}
+%
+% \begin{function}{name,T}
+% \begin{syntax}
+% |name| = \meta{partial name}\\
+% |T| = \meta{partial name}
+% \end{syntax}
+% These keys set the partial name of the field. They both do the same
+% thing, use the one you are more comfortable with. The value
+% shouldn't contain a period, be not empty and sensibly consist of simple chars.
+% Additionally the value is used to create the field ID.
+% This means that choice field with the same partial name are annotations
+% with the same field as parent.
+% The field ID is then internal and can not be used to
+% attach another annotation.
+% For explicit control of the field ID use the |fieldID| key.
+% \end{function}
+%
+% \begin{function}{value}
+% \begin{syntax}
+% |value| = {\meta{seq var 1},\meta{seq var 2}
+% \end{syntax}
+% With this key you set the export value names. \meta{seq_var 1} should contain
+% the values in the order as wanted. The values are passed through |\pdf_string_from_unicode:nnN|
+% and can use unicode. \meta{seq var 2} is optional and should contain the
+% display values.
+% \end{function}
+%
+% \begin{function}{default}
+% \begin{syntax}
+% |default| = \meta{seq var}
+% \end{syntax}
+% With this key you set the values which are selected when the PDF is opened.
+% \meta{seq var} should contain a subset of the display values. (???)
+% \end{function}
+
+% \begin{function}{fieldID}
+% \begin{syntax}
+% |fieldID| = \meta{field ID}\\
+% \end{syntax}
+% \emph{For experts only!}
+% This allows to give the radio field a specific ID. This is only useful
+% in the context of a larger fieldset or if you want to attach another annotation
+% to the field with \cs{pdffield_annot:n}. If used wrongly you can
+% easily create invalid fieldset. It allows you to create to fields with the
+% same partial name, but if you want to see both
+% you need to ensure that their full names are
+% different---for example by adding some parent fields.
+% \end{function}
+%
+% \begin{function}{parent}
+% \begin{syntax}
+% |parent| = \meta{field ID}\\
+% \end{syntax}
+% This is only needed if the field should be part
+% of a larger fieldset. The value should be a field ID of a field created previously
+% with \cs{pdffield_field:nn}.
+% \end{function}
+%
+%
+% \begin{function}{width,height,depth}
+% \begin{syntax}
+% |width| = \meta{dim expression}\\
+% |height| = \meta{dim expression}\\
+% |depth| = \meta{dim expression}
+% \end{syntax}
+% These keys allow to set the dimensions of the choice field.
+% The value should be a dimension expression. By default
+% |width| and |height| and |depth| are ....
+% \end{function}
+%
+% \begin{function}{AP/N,appearance,AP/R,rollover-appearance,AP/D,down-appearance}
+% \begin{syntax}
+% |AP/N| = \meta{partial appearance name}\\
+% |appearance| = \meta{partial appearance name}\\
+% |AP/R| = \meta{partial appearance name}\\
+% |rollover-appearance| = \meta{partial appearance name}\\
+% |AP/D| = \meta{partial appearance name}\\
+% |down-appearance| = \meta{partial appearance name}
+% \end{syntax}
+% ???????????????
+% \end{function}
+%
+% \subsection{Using with hyperref}
+% ??????
+%
+%
+% \end{documentation}
+%
+% \begin{implementation}
+% % \DoNotIndex
+% {\\
+% ,\bitset_clear:N
+% ,\bitset_new:Nn
+% ,\bitset_set_false:Nn
+% ,\bitset_set_true:Nn
+% ,\bitset_to_arabic:N
+% ,\bitset_item:Nn
+% ,\bool_new:N
+% ,\box_dp:N
+% ,\box_ht:N
+% ,\clist_map_inline:nn
+% ,\color_export:nnN
+% ,\color_set:nn
+% ,\color_set:nnn
+% ,\color_select:n
+% ,\cs_new_protected:Npn
+% ,\cs_new_protected:cpn
+% ,\cs_set_eq:NN
+% ,\cs_gset_eq:cN
+% ,\cs_set_protected:Npn
+% ,\cs_generate_variant:Nn
+% ,\cs_gset_eq:NN
+% ,\c_space_tl
+% ,\csname
+% ,\dim_eval:n
+% ,\dim_new:N
+% ,\dim_to_decimal_in_bp:n
+% ,\endcsname
+% ,\exp_args:Ne
+% ,\exp_args:Nc
+% ,\fboxsep
+% ,\fp_eval:n
+% ,\f at size
+% ,\group_begin:
+% ,\group_end:
+% ,\hbox_to_wd:nn
+% ,\hfill
+% ,\hook_gput_code:nnn
+% ,\int_eval:n
+% ,\int_compare:nNnT
+% ,\int_compare:nNnTF
+% ,\int_incr:N
+% ,\int_new:N
+% ,\int_use:N
+% ,\int_zero:N
+% ,\l_keys_choice_int
+% ,\keys_define:nn
+% ,\keys_set:nn
+% ,\mode_leave_vertical:
+% ,\msg_error:nnn
+% ,\msg_error:nnnn
+% ,\msg_new:nnn
+% ,\msg_warning:nn
+% ,\msg_warning:nnn
+% ,\msg_warning:nnnnn
+% ,\NeedsTeXFormat
+% ,\normalsize
+% ,\paperheight
+% ,\paperwidth
+% ,\pdf_name_from_unicode_e:n
+% ,\pdf_object_if_exist:nTF
+% ,\pdf_object_if_exist:nF
+% ,\pdf_object_new:nn
+% ,\pdf_object_ref:n
+% ,\pdf_object_ref_last:
+% ,\pdf_object_unnamed_write:nn
+% ,\pdf_object_unnamed_write:nx
+% ,\pdf_object_write:nx
+% ,\pdf_object_write:nn
+% ,\pdf_string_from_unicode:nnN
+% ,\pdfannot_box_ref_last:
+% ,\pdfannot_dict_put:nnn
+% ,\pdfannot_dict_put:nnx
+% ,\pdfdict_put:nnx
+% ,\pdfannot_dict_remove:nn
+% ,\pdfannot_widget_box:nnn
+% ,\pdfdict_if_empty:nTF
+% ,\pdfdict_get:nnN
+% ,\pdfdict_new:n
+% ,\pdfdict_put:nnn
+% ,\pdfdict_remove:nn
+% ,\pdfdict_use:n
+% ,\pdfmanagement_add:nnn
+% ,\pdfmeta_standard_verify:nTF
+% ,\pdfxform_if_exist:nTF
+% ,\pdfxform_new:nnn
+% ,\pdfxform_ref:n
+% ,\phantom
+% ,\prg_do_nothing:
+% ,\ProvidesExplPackage
+% ,\quark_if_no_value:NT
+% ,\raisebox
+% ,\RequirePackage
+% ,\rule
+% ,\seq_gput_right:Nn
+% ,\seq_gput_right:cV
+% ,\seq_gput_left:cV
+% ,\seq_if_in:cVF
+% ,\seq_map_break:
+% ,\seq_map_inline:Nn
+% ,\seq_new:c
+% ,\seq_use:cn
+% ,\seq_if_exist:NTF
+% ,\seq_new:N
+% ,\seq_use:Nn
+% ,\smash
+% ,\str_if_empty:NTF
+% ,\str_if_in:NnTF
+% ,\str_if_eq:nVTF
+% ,\str_new:N
+% ,\strut
+% ,\strutbox
+% ,\tl_put_right:Nn
+% ,\tl_if_empty:NTF
+% ,\tl_if_empty:NT
+% ,\tl_if_empty:NF
+% ,\tl_put_left:Nn
+% ,\tl_if_eq:NnF
+% ,\tl_if_empty:nTF
+% ,\tl_if_head_eq_charcode:nNTF
+% ,\tl_new:N
+% ,\tl_set:Nn
+% ,\tl_to_str:n
+% ,\use:c
+% }
+% \section{\pkg{l3pdffield-radiobutton} Implementation}
+% \begin{macrocode}
+%<*package>
+%<@@=pdffield>
+\RequirePackage{l3draw}
+% \end{macrocode}
+% \subsection{Variables}
+% \begin{variable}
+% {
+% \l_@@_choice_values_seq
+% ,\l_@@_choice_defaults_seq
+% ,\l_@@_choice_displays_seq
+% ,\l_@@_choice_opt_seq
+% }
+% variables to hold the value, the default value, and display variants. The opt
+% set will be used to build the content of opt
+% \begin{macrocode}
+\seq_new:N \l_@@_choice_values_seq
+\seq_new:N \l_@@_choice_defaults_seq
+\seq_new:N \l_@@_choice_displayvalues_seq
+\seq_new:N \l_@@_choice_opt_seq
+% \end{macrocode}
+% \end{variable}
+%
+% \subsection{Appearances}
+% (probably take from textfield ...)
+%
+%\subsection{Creating the field}
+% A field should be created if the name doesn't exist yet
+% \begin{macro}{\@@_choice_field:n}
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_choice_field:n #1 %name
+ {
+ \pdf_object_if_exist:nF {@@/field/@@/choice/#1}
+ {
+% \end{macrocode}
+% We must at first build the Opt array.
+% \begin{macrocode}
+ \seq_clear:N \l_@@_choice_opt_seq
+ \seq_map_indexed_inline:Nn \l_@@_choice_values_seq
+ {
+ \pdf_string_from_unicode:nnN{utf16/hex}{##2}\l_@@_tmpa_str
+ \tl_set:Nx \l_@@_tmpa_tl {\seq_item:Nn \l_@@_choice_displayvalues_seq {##1} }
+ \tl_if_empty:NTF \l_@@_tmpa_tl
+ {
+ \seq_put_right:NV \l_@@_choice_opt_seq \l_@@_tmpa_str
+ }
+ {
+ \exp_args:NnV
+ \pdf_string_from_unicode:nnN{utf16/hex}\l_@@_tmpa_tl\l_@@_tmpb_str
+ \seq_put_right:Nx \l_@@_choice_opt_seq
+ { [ \l_@@_tmpa_str\c_space_tl\l_@@_tmpb_str] }
+ }
+ }
+ \pdf_object_unnamed_write:nx {array}{\seq_use:Nn\l_@@_choice_opt_seq {~}}
+ \pdfdict_put:nnx { l_@@/field }{Opt} { \pdf_object_ref_last: }
+% \end{macrocode}
+% Now we handle the V value. If MultiSelect is set, we use the full
+% displayvalues seq, if not only the first value.
+% \begin{macrocode}
+ \int_compare:nNnTF {\bitset_item:Nn \l_@@_Ff_bitset {MultiSelect}} = {1}
+ {
+
+ }
+ {
+ \tl_set:Nx \l_@@_tmpa_tl {\seq_item:Nn \l_@@_choice_defaults_seq {1} }
+ \exp_args:NnV
+ \pdf_string_from_unicode:nnN{utf16/hex}\l_@@_tmpa_tl\l_@@_tmpb_str
+ \pdfdict_put:nnx { l_@@/field }{V} { \l_@@_tmpb_str }
+ }
+% \end{macrocode}
+% now we create the field and set it as parent for the following annotation.
+% \begin{macrocode}
+ \@@_field:n { @@/choice/#1 }
+ }
+ \keys_set:nn {pdffield}{parent=@@/choice/#1}
+ }
+\cs_generate_variant:Nn \@@_choice_field:n {V}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Assembling the choice field}
+%
+% \begin{macro}{\@@_choice:n}
+% The argument are key-val settings.
+% At first we map the handlers. To setup the appearance we need the
+% Opt array, so the appearance handler only stores the code.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_choice:n #1
+ {
+ \group_begin:
+ % \cs_set_eq:NN\@@_appearance_handler:nnn \@@_radio_appearance_handler:nnn
+ \cs_set_eq:NN\@@_value_handler:n \@@_choice_value_handler:n
+ \cs_set_eq:NN\@@_default_handler:n \@@_choice_default_handler:n
+% \end{macrocode}
+% Setting up the defaults.
+% \begin{macrocode}
+ %\tl_set:Nn\l_@@_radio_appearance_code_tl{}
+ \keys_set:nn {pdffield}
+ {
+ fieldID=
+ ,name=choice
+ ,width = 3cm
+ ,height = \normalbaselineskip
+ ,type=combo-edit
+ ,@@/preset/choice
+ ,#1
+ ,FT= Ch
+ }
+ \@@_choice_set_type:
+% \end{macrocode}
+% If the fieldID has not been set explicitly, we use the name/T key
+% \begin{macrocode}
+ \tl_if_empty:NT\l_@@_fieldID_tl
+ {
+ \pdfdict_get:nnN {l_@@/field}{T}\l_@@_fieldID_tl
+ \tl_put_left:Nn \l_@@_fieldID_tl {@@/choice/}
+ }
+% \end{macrocode}
+% TODO Values, defaults ...
+% Now we build the field
+% \begin{macrocode}
+ \@@_choice_field:V\l_@@_fieldID_tl
+% \end{macrocode}
+%
+% Now we set the appearances, if no key has been use we take the default.
+% \begin{macrocode}
+ %missing yet.
+ \@@_annot:
+ \group_end:
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Keys and handlers}
+% Most keys are inherited simply the ones from the generic field and annot keys.
+% We define a group key, as the name is better.
+% The value key sets the export value. default the button which is checked on.
+% At first the two handlers
+% \begin{macro}{\@@_choice_value_handler:n,\@@_choice_default_handler:n,display-values}
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_choice_value_handler:n #1
+ {
+ \seq_set_eq:NN \l_@@_choice_values_seq #1
+ }
+\cs_new_protected:Npn \@@_choice_default_handler:n #1
+ {
+ \seq_set_eq:NN \l_@@_choice_defaultvalues_seq #1
+ }
+\keys_define:nn{pdffield}
+ {
+ display-values .code:n =
+ {
+ \seq_set_eq:NN \l_@@_choice_displayvalues_seq #1
+ }
+ ,top-value .code:n =
+ {
+ \pdfdict_put:nnx {l_@@/field}{TI}{\int_eval:n{#1-1}}
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{type}
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_choice_set_type: {}
+
+\keys_define:nn { pdffield }
+ {
+ type .choice:
+ ,type / combo .code:n =
+ {
+ \cs_set_protected:Npn\@@_choice_set_type:
+ {
+ \keys_set:nn{pdffield}{setFf={Combo},unsetFf={Edit,DoNotSpellCheck}}
+ }
+ }
+ ,type / combo-edit .code:n =
+ {
+ \cs_set_protected:Npn\@@_choice_set_type:
+ {
+ \keys_set:nn{pdffield}{setFf={Combo,Edit}}
+ }
+ }
+ ,type / list .code:n =
+ {
+ \cs_set_protected:Npn\@@_choice_set_type:
+ {
+ \keys_set:nn{pdffield}{unsetFf={Combo,Edit,},unsetFf={Edit,DoNotSpellCheck}}
+ }
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\@@_choice_appearance_handler:nnn}
+% The handler for the appearances stores only the code
+% as it must be executed rather late.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_choice_appearance_handler:nnn #1 #2 #3 %name, type, text
+ {
+ }
+
+% \end{macrocode}
+%
+% \end{macro}
+%
+% \subsection{User commands}
+% \begin{macro}{\pdffield_choice:n}
+% \begin{macrocode}
+\cs_set_eq:NN \pdffield_choice:n \@@_choice:n
+%</package>
+% \end{macrocode}
+% \end{macro}
+%\end{implementation}
+% \PrintIndex
diff --git a/l3pdffield.dtx b/l3pdffield.dtx
index c01c1e3..d9544e6 100644
--- a/l3pdffield.dtx
+++ b/l3pdffield.dtx
@@ -918,6 +918,7 @@
% \begin{variable}
% {
% \l_@@_tmpa_str
+% ,\l_@@_tmpb_str
% ,\l_@@_tmpa_tl
% ,\l_@@_tmpa_keys_tl
% ,\l_@@_currentparent_tl
@@ -930,6 +931,7 @@
% current fieldID.
% \begin{macrocode}
\str_new:N \l_@@_tmpa_str
+\str_new:N \l_@@_tmpb_str
\tl_new:N \l_@@_tmpa_tl
\tl_new:N \l_@@_tmpa_keys_tl
\tl_new:N \l_@@_currentparent_tl
@@ -1919,11 +1921,19 @@
@@/preset/pushbutton .meta:n = {#1},
}
}
+ ,preset-choice .code:n =
+ {
+ \keys_define:nn { pdffield }
+ {
+ @@/preset/choice .meta:n = {#1},
+ }
+ }
}
\keys_set:nn{ pdffield / setup }{preset-checkbox={}}
\keys_set:nn{ pdffield / setup }{preset-textfield={}}
\keys_set:nn{ pdffield / setup }{preset-radiobutton={}}
\keys_set:nn{ pdffield / setup }{preset-pushbutton={}}
+\keys_set:nn{ pdffield / setup }{preset-choice={}}
% \end{macrocode}
% \end{macro}
% \begin{macro}{\@@_style_create:nn}
diff --git a/pdfmanagement-testphase.ins b/pdfmanagement-testphase.ins
index 77d38e8..98b3153 100644
--- a/pdfmanagement-testphase.ins
+++ b/pdfmanagement-testphase.ins
@@ -132,6 +132,7 @@ and all files in that bundle must be distributed together.
\from{l3pdffield-radiobutton.dtx}{package}
\from{l3pdffield-textfield.dtx}{package}
\from{l3pdffield-pushbutton.dtx}{package}
+ \from{l3pdffield-choice.dtx}{package}
}%
}
More information about the latex3-commits
mailing list.