[latex3-commits] [git/LaTeX3-latex3-pdfresources] textfields: code + checkbox docu (26ddb22)
Ulrike Fischer
fischer at troubleshooting-tex.de
Sun May 9 23:19:38 CEST 2021
Repository : https://github.com/latex3/pdfresources
On branch : textfields
Link : https://github.com/latex3/pdfresources/commit/26ddb22e88975f05cd2e027e809dc3b3b3d773d6
>---------------------------------------------------------------
commit 26ddb22e88975f05cd2e027e809dc3b3b3d773d6
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date: Sun May 9 23:19:38 2021 +0200
code + checkbox docu
>---------------------------------------------------------------
26ddb22e88975f05cd2e027e809dc3b3b3d773d6
info/note-fields.tex | 1 +
l3pdffield-checkbox.dtx | 203 +++++++++++++++++-------------------------------
l3pdffield.dtx | 95 ++++++++++++++++++----
l3pdffield.pdf | Bin 514367 -> 607093 bytes
4 files changed, 150 insertions(+), 149 deletions(-)
diff --git a/info/note-fields.tex b/info/note-fields.tex
index 5667efb..00b4eb2 100644
--- a/info/note-fields.tex
+++ b/info/note-fields.tex
@@ -102,3 +102,4 @@
% EmbedForm = 12
% }
% source: %adapted from https://chat.stackexchange.com/transcript/message/54421537#54421537
+
diff --git a/l3pdffield-checkbox.dtx b/l3pdffield-checkbox.dtx
index 6587379..3b5affc 100644
--- a/l3pdffield-checkbox.dtx
+++ b/l3pdffield-checkbox.dtx
@@ -108,9 +108,10 @@
% active at that time.
% \end{function}
%
+%
% \subsection{Keys}
%
-% The new checkbox commands accept almost all field and annot keys from l3pdffield.
+% The new checkbox commands accept all field and annot keys from l3pdffield.
% A few keys are disabled or are forced to specific values.
% A number of keys have more user friendly alias names, which roughly follow the
% naming used in hyperref for the analog feature. Some keys have a more checkbox specific
@@ -124,91 +125,97 @@
% \item |AP/N|, |AP/R|, |AP/D|: checkboxes need special formated
% appearances, use |appearance|, |rollover-appearance| and |down-appearance| instead.
% \item |FT| is overwritten.
-% \item some flags are set as needed by a checkbox.
+% \item For checkboxes only the field flags |ReadOnly|, |Required| and |NoExport| make sense.
+% |Radio|, |Pushbotton| are set automatically automatically by the code
+% as this is required for a checkbox.
% \end{itemize}
%
+% \begin{function}{preset-checkbox}
+% \begin{syntax}
+% |preset-checkbox| = \Arg{key-val}
+% \end{syntax}
+% This allows to set default keys for a checkbox.
+% \end{function}
%
-% \DescribeCheckboxkey{name}\DescribeCheckboxkey{T}
+% \begin{function}{name,T}
+% \begin{syntax}
+% |name| = \Arg{partial name}\\
+% |T| = \Arg{partial name}
+% \end{syntax}
% This sets like the |T| key for fields the partial name of the field. 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 checkboxes with the same partial name are annotations
-% with all the same field as parent and are checked and unchecked together---this
+% with the same field as parent and are checked and unchecked together---this
% what is typically expected. There could be an option to change the behaviour
% but currently I can't see a sensible use case.
% The field ID is internal as the field has a field annotation and so
% is always a terminal field.
+% \end{function}
%
-% \DescribeCheckboxkey{parent} This is only needed if the field should be part
-% of a larger fieldset. The value should be a field ID of field created previously
+% \begin{function}{parent}
+% \begin{syntax}
+% |parent| = \Arg{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}
%
-% \DescribeCheckboxkey{altname} This is an alias for the |TU| key and sets
-% an alternative name for user interaction.
+% \begin{function}{altname,TU}
+% \begin{syntax}
+% |altname| = \Arg{string}\\
+% |TU| = \Arg{string}\\
+% \end{syntax}
+% This is sets an alternative name for user interaction.
% This name can only be set at the first checkbox instance, when the field is initialized.
+% \end{function}
%
-% \DescribeCheckboxkey{mappingname} This is an alias for the |TM| key and
-% sets an alternative name for export.
+% \begin{function}{mappingname,TM}
+% \begin{syntax}
+% |mappingname| = \Arg{string}\\
+% |TM| = \Arg{string}\\
+% \end{syntax}
+% This is sets an alternative name for export.
% This name can only be set at the first checkbox instance, when the field is initialized.
+% \end{function}
%
-% \DescribeCheckboxkey{width}
-% \DescribeCheckboxkey{height}
-% \DescribeCheckboxkey{depth} These keys allow to set the dimensions of checkbox instance.
+% \begin{function}{width,height,depth}
+% \begin{syntax}
+% |width| = \Arg{dim expression}\\
+% |height| = \Arg{dim expression}\\
+% |depth| = \Arg{dim expression}
+% \end{syntax}
+% These keys allow to set the dimensions of checkbox instance.
% The value should be a dimension expression. By default
% |width| and |height| use \cs{normalbaselineskip}, the |depth| is zero.
+% \end{function}
%
-% \DescribeCheckboxkey{appearance} This key sets the normal appearance. It takes as value a
+% \begin{function}{appearance,rollover-appearance,down-appearance}
+% \begin{syntax}
+% |appearance| = \Arg{name}\\
+% |rollover-appearance| = \Arg{name}\\
+% |down-appearance| = \Arg{name}
+% \end{syntax}
+% This keys sets the normal appearance, the rollover appearance (when the
+% mouse hovers over the checkbox) and the down appearance (when the
+% mouse clicks). They take as value a
% \meta{name} and expects that the two appearances \meta{name}|/Yes| and \meta{name}|/Off|
% has been created with the command described below. The initial value is |checkbox/default|
-% and shows a \cs{texttimes}.
-%
-% \DescribeCheckboxkey{rollover-appearance} This key sets the rollover appearance (when the
-% mouse hovers over the checkbox). It takes as value a
-% \meta{name} and expects that the two appearances \meta{name}|/Yes| and \meta{name}|/Off|
-% has been created with the command described below. Initially this is not set.
-% An empty value removes the entry.
-%
-% \DescribeCheckboxkey{down-appearance} This key sets the down appearance (when the
-% mouse clicks). It takes as value a
-% \meta{name} and expects that the two appearances \meta{name}|/Yes| and \meta{name}|/Off|
-% has been created with the command described below. Initially this is not set.
-% An empty value removes the entry.
-%
-% \DescribeCheckboxkey{checked} This is a boolean key which allows to set if the
+% for the normal appearance and shows a \cs{texttimes}. The other appearance are not set by default.
+% \end{function}
+
+% \begin{function}{checked}
+% \begin{syntax}
+% |checked| = |true|\verb"|"|false|
+% \end{syntax}
+% This is a boolean key which allows to set if the
% checkbox should be initially checked or not. It sets the |/V| and |/DV| key of the field
% and the |/AS| key of the annotation instance. It is possible to use different
% values for different instances, if one wants to confuse the user.
+% \end{function}
%
%
-% \DescribeCheckboxkey{setfieldflags}
-% \DescribeCheckboxkey{unsetfieldflags}
-% These keys allow to set or unset the field flags. This is are alias keys for
-% |setFf| and |unsetFf|. They expect a comma lists of
-% flag names. For checkboxes only |ReadOnly|, |Required| and |NoExport| make sense.
-% |Radio|, |Pushbotton| are set automatically automatically by the code
-% as this is required for a checkbox.
-%
-% \begin{checkboxkey}{keystroke,format,validate,calculate}
-% These keys are aliases for |AA/K|, |AA/F|, |AA/V|, |AA/C|.
-% They add the |/K, |/F, |/V|, |/C| key to the |/AA| dictionary of the field object.
-% Their value should be javascript code. The |/AA| dictionary is suppressed
-% if a pdf/A standard is set. These keys are probably not of much used with a checkbox.
-% \end{checkboxkey}
-%
-% \vspace{2\baselineskip}
-% \begin{checkboxkey}{onfocus,onblur,onmousedown,onmouseup,onenter,onexit}
-% These keys are aliases for the |AA/F, |AA/Bl, |AA/D|, |AA/U|, |AA/E| and |AA/X|
-% keys. They add the |/F, |/Bl, |/D|, |/U|, |E| and |X| key to the |/AA| dictionary
-% of the widget annotation (the checkbox instance) object.
-% Their value should be javascript code. The |/AA| dictionary
-% is suppressed if a pdf/A standard is set.
-%
-% For example
-% \begin{verbatim}
-% onenter={app.alert('Hello');}
-% \end{verbatim}
-% \end{checkboxkey}
-%
% \subsection{Using with hyperref}
% The \cs{CheckBox} command from hyperref also prints a label, something that the
% command here doesn't do. A redefinition like the following should allow \cs{CheckBox}
@@ -297,7 +304,6 @@
}
\cs_generate_variant:Nn \@@_checkbox_field:n {V}
% \end{macrocode}
-%
% \subsection{Assembling the checkbox}
% \begin{macro}{\@@_checkbox:n}
% \begin{macrocode}
@@ -309,12 +315,13 @@
% Setting up the defaults.
% \begin{macrocode}
\keys_set:nn {pdffield}
- {
+ {
name=checkbox,
appearance = pdffield/checkbox/default,
+ checked=false,
width = \normalbaselineskip,
height = \normalbaselineskip,
- }
+ }
% \end{macrocode}
% A number of keys should be undefined, to avoid that the value and
% appearances has the wrong format.
@@ -324,7 +331,7 @@
V .undefine: , DV .undefine: , AS .undefine:,
AP/N .undefine: , AP/R .undefine: , AP/D .undefine:,
}
- \keys_set:nn { pdffield }{#1}
+ \keys_set:nn { pdffield }{@@/preset/checkbox,#1}
\keys_set:nn { pdffield }
{
,unsetFf={Radio,Pushbutton}
@@ -364,7 +371,7 @@
,checked .groups:n = {checkbox}
}
% \end{macrocode}
-% The code
+% \begin{macro}{\@@_checkbox_appearance:nnn}
% \begin{macrocode}
\cs_new_protected:Npn \@@_checkbox_appearance:nnn #1 #2 #3 %name, type, text
{
@@ -426,73 +433,3 @@
%\end{implementation}
\endinput%
-%%%%
-%
-%Field dict
-%Ft : /Btn /Tx /Ch /Sig
-%Parent : OR
-%Kids: array, other fields or annot/widget
-%T: partial fieldname (test string)
-%TU: alternate description (test string)
-%TM: mapping name
-%Q integer (variable text field)
-%Ff: flags ->pdffield/checkbox/field
-%V: value % not pushbutton
-%DV: default value % not pushbutton
-%AA: Action dict ... -> see below
-%Opt: array of strings, connected to kids
-% or for choices, choices
-%TI integer (lists)
-%I array Ch (complicated ...)
-%
-%/DA ( 0 0 1 rg /Ti 12 Tf ) %text field
-%/MaxLen %text field
-%
-%Lock dict (Sig)
-%SV dict (Sig)
-%
-%
-%
-%
-%Connected widget:
-%/AS default appearance from AP ( here/Yes or /Off)
-%% Appearance
-%%checkbox
-%/AP <</N <</Yes 2 0 R /Off 3 0 R>>>>
-%/C / Border /BS
-%
-%/OC ?
-%/Structparens?
-%/F flags
-%
-%
-%AA: Submit:
-% /S /SubmitForm
-% /F file /URI (/F ( ftp : / / www . beatles . com / Movies / AbbeyRoad . mov )
-% /Fields array
-%
-% /S /ImportData
-% /F file
-%
-% /S /ResetData
-% /Fields array
-%
-% /S /JavaScript
-% /JS text string or stream
-% %\pdf_flag_new:nn {annot/field/submit} %name is wrong ...
-% {
-% Include/Exclude = 0,
-% IncludeNoValueFields = 1,
-% ExportFormat = 2,
-% GetMethod = 3, % if ExportFormat=0 -> =0 to
-% SubmitCoordinates = 4, % if ExportFormat=0 -> =0 to
-% XFDF = 5,
-% IncludeAppendSaves = 6,
-% IncludeAnnotations = 7,
-% SubmitPDF = 8,
-% CanonicalFormat = 9,
-% ExclNonUserAnnots = 10,
-% ExclFKey = 11,
-% EmbedForm = 12
-% }
-% source: %adapted from https://chat.stackexchange.com/transcript/message/54421537#54421537
diff --git a/l3pdffield.dtx b/l3pdffield.dtx
index bfeb4d9..abae0ba 100644
--- a/l3pdffield.dtx
+++ b/l3pdffield.dtx
@@ -28,7 +28,7 @@
\makeatletter
\declare at file@substitution{doc.sty}{doc-v3beta.sty}
\makeatother
-\documentclass[full]{l3doc}
+\documentclass{l3doc}
\usepackage{array,booktabs,caption}
\usepackage{l3pdffield-testphase,tikz}
\hypersetup{pdfauthor=The LaTeX Project,
@@ -49,6 +49,11 @@
% printtype= \textit{field key}
% ]{Fieldkey}{fieldkey}
% \NewDocElement[
+% idxgroup=setup keys,
+% idxtype = {setup key},
+% printtype= \textit{setup key}
+% ]{Fieldsetupkey}{fieldsetupkey}
+% \NewDocElement[
% idxgroup=annot keys,
% idxtype = {annot key},
% printtype= \textit{annot key}
@@ -277,6 +282,29 @@
% a module part, e.g. |mymodule/appearance/cross|.
% \end{function}
%
+% \begin{function}{\pdffield_setup:n}
+% \begin{syntax}
+% \cs{pdffield_setup:n}\Arg{key-val}
+% \end{syntax}
+% This command allows to preset some field settings.
+% \end{function}
+% It knows currently two keys:
+%
+% \begin{function}{create-style}
+% \begin{syntax}
+% |create-style| = \Arg{name}\Arg{key-val}
+% \end{syntax}
+% This defines a style which can then be used with the |style| key.
+% \Arg{key-val} can be an arbitrary collection of the keys of the module.
+% \end{function}
+%
+% \begin{function}{preset-checkbox}
+% \begin{syntax}
+% |preset-checkbox|=\Arg{key-val}
+% \end{syntax}
+% This allows to set default keys for a checkbox.
+% \end{function}
+
% \section{Field Keys}
%
% Table~\ref{tab:fieldkeys} summarize the keys which can be used.
@@ -290,6 +318,7 @@
% \toprule
% key & value & required & inheritable &remark\\\midrule
% parent & field ID & for non-root fields & \\
+% style & style name & & defined with |create-style| \\
% T, name & string & mostly & \\
% TU, altname & string & & \\
% TM, mappingname & string & & \\
@@ -339,9 +368,14 @@
% The value is of relevance only for terminal fields, but it can be set in a parent
% and then inherited.
%
-% \DescribeFieldkey{setFf}\DescribeFieldkey{setfieldflags}
-% \DescribeFieldkey{unsetFf}\DescribeFieldkey{unsetfieldflags}
-% This key accepts a list of flag names and then sets or unsets them, the resulting value
+% \begin{function}{setfieldflags,setFf,unsetfieldflags,unsetFf}
+% \begin{syntax}
+% |setfieldflags| = \meta{comma list of flags}\\
+% |setFf| = \meta{comma list of flags}\\
+% |unsetfieldflags| = |all| \verb"|" \meta{comma list of flags}\\
+% |unsetFf| = |all| \verb"|" \meta{comma list of flags}
+% \end{syntax}
+% These keys accept a list of flag names and then sets or unsets them, the resulting value
% is then used with the \texttt{/Ff} key. Depending
% on the field type some flags must be set or unset, other are optional or are ignored.
% The flag name can be given in PDF spelling (\texttt{RadiosInUnison}),
@@ -354,6 +388,8 @@
% |Combo|, |Edit|, |Sort|, |FileSelect|, |MultiSelect|, |DoNotSpellCheck|,
% |DoNotScroll|, |Comb|, |RadiosInUnison|, |RichText|, |CommitOnSelChange|.
%
+% \end{function}
+
% \DescribeFieldkey{V} This sets the value of the field. Its
% format varies depending on the field type, so typically
% commands for the various type will have to preprocess and sanitize it.
@@ -490,6 +526,12 @@
% of the field annotation object.
% Their value should be javascript code. The |/AA| dictionary
% is suppressed if a pdf/A standard is set.
+%
+% For example
+% \begin{verbatim}
+% onenter={app.alert('Hello');}
+% \end{verbatim}
+
% \end{annotkey}
%
% \medskip
@@ -542,12 +584,7 @@
}
\msg_new:nnn {pdffield}{appearance-missing}
{
- The~appearance~`#1`~is~missing~for~the~#2~appearance.
- }
-\msg_new:nnn {pdffield}{field-keys-ignored}
- {
- The~field~`#1`~is~already~initialized\\
- The~field~keys~`#2`~are~ignored.
+ The~appearance~definition~`#1`~is~missing~for~the~#2~appearance.
}
\msg_new:nnn {pdffield}{not-implemented}
{
@@ -798,6 +835,7 @@
}
\str_if_empty:NTF\l_@@_tmpa_str
{
+ \msg_warning:nn {pdffield}{empty-name}
\pdfdict_remove:nn { l_@@/field }{T}
}
{
@@ -1194,23 +1232,48 @@
{
\pdfxform_new:nnn {#1}{}{#2}
}
-%for compability ...
+
\cs_set_eq:NN \pdffield_store_appearance:nn\pdffield_appearance:nn
% \end{macrocode}
+% \end{macro}
% \subsection{Setup command}
%
+% \begin{macrocode}
\keys_define:nn { pdffield / setup }
- { create-style . code:n = { \@@_style_create:nn #1 } }
+ {
+ ,create-style .code:n = { \@@_style_create:nn #1 }
+ ,preset-checkbox .code:n =
+ {
+ \keys_define:nn { pdffield }
+ {
+ @@/preset/checkbox .meta:n = {#1},
+ }
+ }
+ }
+\keys_set:nn{ pdffield / setup }{preset-checkbox={}}
\cs_new_protected:Npn \@@_style_create:nn #1#2
- { \keys_define:nn { pdffield } { #1 .meta:n = {#2} } }
+ {
+ \keys_define:nn { pdffield }
+ {
+ @@/style/#1 .meta:n = {#2},
+ }
+ }
-\cs_new_protected:Npn \pdffield_setup:nn #1 #2
- {
- }
+\cs_new_protected:Npn \pdffield_setup:n #1
+ {
+ \keys_set:nn{pdffield/setup}{#1}
+ }
+\keys_define:nn { pdffield }
+ {
+ style .code:n = {\keys_set:nn {pdffield}{@@/style/#1={#1}}}
+ }
+% \end{macrocode}
% \begin{macrocode}
%</package>
% \end{macrocode}
%\end{implementation}
+%
+% \PrintIndex
diff --git a/l3pdffield.pdf b/l3pdffield.pdf
index d7e4e67..038addb 100644
Binary files a/l3pdffield.pdf and b/l3pdffield.pdf differ
More information about the latex3-commits
mailing list.