[latex3-commits] [git/LaTeX3-latex3-pdfresources] radiobuttons: starting pushbuttons (802152a)
Ulrike Fischer
fischer at troubleshooting-tex.de
Thu May 27 00:20:33 CEST 2021
Repository : https://github.com/latex3/pdfresources
On branch : radiobuttons
Link : https://github.com/latex3/pdfresources/commit/802152aa0d511a532a2bb17c3565b5e2f920fc04
>---------------------------------------------------------------
commit 802152aa0d511a532a2bb17c3565b5e2f920fc04
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date: Thu May 27 00:20:33 2021 +0200
starting pushbuttons
>---------------------------------------------------------------
802152aa0d511a532a2bb17c3565b5e2f920fc04
...field-checkbox.dtx => l3pdffield-pushbutton.dtx | 272 +++++++--------------
1 file changed, 92 insertions(+), 180 deletions(-)
diff --git a/l3pdffield-checkbox.dtx b/l3pdffield-pushbutton.dtx
similarity index 54%
copy from l3pdffield-checkbox.dtx
copy to l3pdffield-pushbutton.dtx
index ad026fa..388aa05 100644
--- a/l3pdffield-checkbox.dtx
+++ b/l3pdffield-pushbutton.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-%% File: l3pdfpdffield-checkbox.dtx
+%% File: l3pdfpdffield-pushbutton.dtx
%
% Copyright (C) 2021 The LaTeX Project
%
@@ -38,11 +38,6 @@
\end{document}
%</driver>
% \fi
-% \NewDocElement[
-% idxgroup=checkbox keys,
-% idxtype = {checkbox key},
-% printtype= \textit{checkbox key}
-% ]{Checkboxkey}{checkboxkey}
% \providecommand\hook[1]{\texttt{#1}}
% \ExplSyntaxOn
% \pdffield_appearance:nn {pdffield/bear/Yes}
@@ -55,7 +50,7 @@
% }
% \ExplSyntaxOff
% \title{^^A
-% The \pkg{l3pdffield-checkbox} module\\ Commands to create checkbox form fields ^^A
+% The \pkg{l3pdffield-pushbutton} module\\ Commands to create pushbutton form fields ^^A
% \\ \LaTeX{} PDF management testphase bundle
% }
%
@@ -72,70 +67,73 @@
%
% \maketitle
% \begin{documentation}
-% \section{\pkg{l3pdffield-checkbox} Introduction}
-% This is the documentation for checkbox fields, for general information about form fields
+% \section{\pkg{l3pdffield-pushbutton} Introduction}
+% This is the documentation for pushbutton fields, for general information about form fields
% check the documentation l3pdffield.
%
%
%
% Please keep in mind
% \begin{itemize}
-% \item Not every PDF viewer supports checkboxes.
+% \item Not every PDF viewer supports pushbuttons.
% \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{Checkboxes}
+% \section{Pushbuttons}
% Click me:
% \ExplSyntaxOn
-% \pdffield_checkbox:n{name=bear,appearance=pdffield/bear,width=23pt,height=30pt,depth=10pt}
+% \pdffield_push:n{name=bear,appearance=pdffield/bear,width=23pt,height=30pt,depth=10pt}
% \ExplSyntaxOff
%
% \bigskip
% \subsection{Commands}
-% \begin{function}{\pdffield_checkbox:n}
+% \begin{function}{\pdffield_push:n}
% \begin{syntax}
-% \cs{pdffield_checkbox:n}\Arg{key val list}
+% \cs{pdffield_push:n}\Arg{key val list}
% \end{syntax}
-% This creates a checkbox to check and uncheck. The list of allowed keys is described below.
+% This creates a pushbutton. Unlike radio buttons and checkboxes pushbuttons
+% don't change their state, instead the purpose is to trigger an action. Important
+% options are Submit and Reset. They will be setup in another module.
+% The list of allowed keys is described below.
% The \meta{key val list} should at least set the name, without it the default name
-% |checkbox| is used. Checkboxes with the same
-% name belong to the same field and are checked and unchecked together. The default appearance
-% is a quadratic frame with a \cs{texttimes} in it for the checked case.
+% |pushbutton| is used. The default appearance
+% is a rectangular frame with a text in it. Down and rollover use a different color.
% The default appearance is setup at the first use and will use the font family
-% active at that time.
+% active at that time for the text.
% \end{function}
%
%
% \subsection{Keys}
%
-% The new checkbox command accept all field and annot keys from l3pdffield.
+% The new pushbutton 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 more checkbox specific
+% The |appearance| keys have a more pushbutton specific
% behaviour, other keys have other defaults than with the basic commands.
% Additionally there
-% are a small number of keys specific to a checkbox.
+% are a small number of keys specific to a pushbutton.
% For convenience a number of important keys are documented here too, even if
% they are already in the document from l3pdffield.
%
%
% Disabled keys are
% \begin{itemize}
-% \item |V|, |DV|, |AS|: use |checked| instead.
+% \item |V|, |DV|. As a pushbutton has no permanent state,
+% the keys should not be used.
% \item |FT| is overwritten.
-% \item For checkboxes only the field flags |ReadOnly|, |Required| and |NoExport|
+% \item For pushbuttons 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.
+% |Pushbotton| are set automatically automatically by the code
+% as this is required for a pushbutton.
% \end{itemize}
%
-% \begin{function}{preset-checkbox}
+% \begin{function}{preset-push}
% \begin{syntax}
-% |preset-checkbox| = \Arg{key-val-list}
+% |preset-push| = \Arg{key-val-list}
% \end{syntax}
-% This allows to set default keys for a checkbox.
+% This allows to set default keys for a pushbutton.
% \end{function}
%
% \begin{function}{name,T}
@@ -146,9 +144,8 @@
% This sets 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 the same field as parent and are checked and unchecked together---this
-% what is typically expected.
+% This means that pushbuttons 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.
@@ -159,7 +156,7 @@
% |fieldID| = \meta{field ID}\\
% \end{syntax}
% \emph{For experts only!}
-% This allows to give the checkbox field a specific ID. This is only useful
+% This allows to give the pushbutton 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
@@ -183,7 +180,7 @@
% |TU| = \meta{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.
+% This name can only be set at the first pushbutton instance, when the field is initialized.
% \end{function}
%
% \begin{function}{mappingname,TM}
@@ -192,7 +189,7 @@
% |TM| = \meta{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.
+% This name can only be set at the first pushbutton instance, when the field is initialized.
% \end{function}
%
% \begin{function}{width,height,depth}
@@ -201,53 +198,45 @@
% |height| = \meta{dim expression}\\
% |depth| = \meta{dim expression}
% \end{syntax}
-% These keys allow to set the dimensions of checkbox instance.
+% These keys allow to set the dimensions of the pushbutton instance.
% The value should be a dimension expression. By default
% |width| and |height| use \cs{normalbaselineskip}, the |depth| is zero.
% \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}
+% |AP/N| = \meta{appearance name}\\
+% |appearance| = \meta{appearance name}\\
+% |AP/R| = \meta{appearance name}\\
+% |rollover-appearance| = \meta{appearance name}\\
+% |AP/D| = \meta{appearance name}\\
+% |down-appearance| = \meta{appearance 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 hovers over the pushbutton) and the down appearance (when the
% mouse clicks). They take as value a
-% \meta{partial appearance name} and expects that \emph{two} form Xobjects
-% \meta{partial appearance name}|/Yes| and \meta{partial appearance name}|/Off|
-% has been created. The initial value is |pdffield/checkbox/default|
-% for the normal appearance and shows a \cs{texttimes}.
-% The other appearances are not set by default.
+% \meta{appearance name} and expects that one form Xobjects
+% with this name has been created before. The initial value are
+% |pdffield/pushbutton/defaultN|, |pdffield/pushbutton/defaultD|,
+% |pdffield/pushbutton/defaultR|.
% \end{function}
%
-% \begin{function}{checked}
+% \begin{function}{value}
% \begin{syntax}
-% |checked| = |true|\verb"|"|false|
+% |value| = text???.....\\
% \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.
+% \ldots ...
% \end{function}
-%
-% \begin{function}{value,default}
+
+% \begin{function}{action}
% \begin{syntax}
-% |value| = |Yes|\verb"|"|Off|\\
-% |default| = |Yes|\verb"|"|Off|\\
+% |action| = .....\\
% \end{syntax}
-% With checkboxes this two key are simply an alternative input for |checked|.
+% \ldots ...
% \end{function}
%
% \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}
-% to use the commands of this module. Be aware that the behaviour will not be identical!
-% Not every setting and key from \pkg{hyperref} has been copied.
+% The \cs{Pushbutton} command from hyperref ?????
%
% \begin{verbatim}
% \ExplSyntaxOn\makeatletter
@@ -261,17 +250,10 @@
% checkboxes.
%
% A checkbox consist of a field along with one or more field annotations.
+% ??????
% The annotations can appear on more than one page or locations and if one instance
% is checked all other instances follows and are checked too.
%
-% A checkbox has two different looks: checked and unchecked. The hyperref
-% implementation uses symbolic names for the two states and adds some
-% values with the /MK key and lets the PDF viewer
-% create a look from them. But this doesn't work reliably and is one of the reasons
-% why a reimplementation is needed. Also newer PDF versions
-% deprecate the /NeedAppearances setting and require that such a look,
-% an \enquote{appearance}, is given as form XObjects.
-% So the code forces the use of two appearances.
%
% \end{documentation}
%
@@ -369,7 +351,7 @@
% ,\tl_to_str:n
% ,\use:c
% }
-% \section{\pkg{l3pdffield-checkbox} Implementation}
+% \section{\pkg{l3pdffield-pushbutton} Implementation}
% \begin{macrocode}
%<*package>
%<@@=pdffield>
@@ -379,22 +361,21 @@
% \subsection{Messages}
% There are no specific messages.
% \subsection{Appearances}
-% The default appearances are a quadratic frame with cross (\cs{texttimes}) if
-% checked.
-% User appearances should have two versions and follow the naming
-% module/\meta{name}/Yes and module/\meta{name}/Off.
+% The default appearances are a rectangular frame with some text.
+%
% \begin{macro}
% {
-% \@@_checkbox_default_appearances:,
-% pdffield/checkbox/default/Yes,
-% pdffield/checkbox/default/Off
+% @@/pushbutton/default_appearances:,
+% pdffield/pushbutton/defaultN,
+% pdffield/pushbutton/defaultR,
+% pdffield/pushbutton/defaultD,
% }
% This defines the standard appearance. It is setup at the first
-% use of a checkbox, and will adapt to the font family in use then.
+% use of a pushbutton, and will adapt to the font family in use then.
% \begin{macrocode}
-\cs_new_protected:Npn \@@_checkbox_default_appearances:
+\cs_new_protected:Npn \@@_pushbutton_default_appearances:n #1 % text
{
- \pdffield_appearance:nn {pdffield/checkbox/default/Yes}
+ \pdffield_appearance:nn {pdffield/pushbutton/defaultN}
{
\normalsize
\fboxsep 0pt
@@ -402,7 +383,7 @@
[ \dim_eval:n { \box_ht:N\strutbox+\box_dp:N\strutbox } ]
{ \texttimes \strut }
}
- \pdffield_appearance:nn {pdffield/checkbox/default/Off}
+ \pdffield_appearance:nn {pdffield/pushbutton/defaultR}
{
\normalsize
\fboxsep 0pt
@@ -410,67 +391,65 @@
[ \dim_eval:n { \box_ht:N\strutbox+\box_dp:N\strutbox } ]
{ \phantom{\texttimes} \strut }
}
- \cs_gset_eq:NN \@@_checkbox_default_appearances: \prg_do_nothing:
+
}
% \end{macrocode}
% \end{macro}
%
%\subsection{Creating the field}
% A field should be created if the name doesn't exist
-% \begin{macro}{ \@@_checkbox_field:n }
+% \begin{macro}{ \@@_pushbutton_field:n }
% \begin{macrocode}
-\cs_new_protected:Npn \@@_checkbox_field:n #1 %name
+\cs_new_protected:Npn \@@_pushbutton_field:n #1 %name
{
- \pdf_object_if_exist:nF {@@/field/@@/checkbox/#1}
+ \pdf_object_if_exist:nF {@@/field/@@/pushbutton/#1}
{
- \@@_field:n { @@/checkbox/#1 }
+ \@@_field:n { @@/pushbutton/#1 }
}
- \keys_set:nn {pdffield}{parent=@@/checkbox/#1}
+ \keys_set:nn {pdffield}{parent=@@/pushbutton/#1}
}
-\cs_generate_variant:Nn \@@_checkbox_field:n {V}
+\cs_generate_variant:Nn \@@_pushbutton_field:n {V}
% \end{macrocode}
% \end{macro}
-% \subsection{Assembling the checkbox}
+% \subsection{Assembling the Pushbutton}
%
-% \begin{macro}{\@@_checkbox:n}
+% \begin{macro}{\@@_pushbutton:n}
% \begin{macrocode}
-\cs_new_protected:Npn \@@_checkbox:n #1
+\cs_new_protected:Npn \@@_pushbutton:n #1
{
\group_begin:
- \@@_checkbox_default_appearances:
- \cs_set_eq:NN\@@_appearance_handler:nnn \@@_checkbox_appearance_handler:nnn
- \cs_set_eq:NN\@@_value_handler:n \@@_checkbox_value_handler:n
- \cs_set_eq:NN\@@_default_handler:n \@@_checkbox_default_handler:n
+ \@@_pushputton_default_appearances:n {TEXT}
+ % \cs_set_eq:NN\@@_appearance_handler:nnn \@@_checkbox_appearance_handler:nnn
+ % \cs_set_eq:NN\@@_value_handler:n \@@_checkbox_value_handler:n
+ % \cs_set_eq:NN\@@_default_handler:n \@@_checkbox_default_handler:n
% \end{macrocode}
% Setting up the defaults.
% \begin{macrocode}
\keys_set:nn {pdffield}
{
fieldID=,
- name=checkbox,
+ name=pushbutton,
appearance = pdffield/checkbox/default,
- checked=false,
- width = \normalbaselineskip,
+ width = 3cm,
height = \normalbaselineskip,
}
% \end{macrocode}
% Value keys should be undefined.
% \begin{macrocode}
- \@@_key_disable:nnn{checkbox}{V}{checked}
- \@@_key_disable:nnn{checkbox}{DV}{checked}
- \@@_key_disable:nnn{checkbox}{AS}{checked}
- \keys_set:nn { pdffield }{@@/preset/checkbox,#1}
+ \keys_set:nn { pdffield }{@@/preset/pushbutton,#1}
\keys_set:nn { pdffield }
{
- ,unsetFf={Radio,Pushbutton}
+ ,V=
+ ,DV=
+ ,setFf={Pushbutton}
,FT= Btn
}
\tl_if_empty:NT\l_@@_fieldID_tl
{
\pdfdict_get:nnN {l_@@/field}{T}\l_@@_fieldID_tl
- \tl_put_left:Nn \l_@@_fieldID_tl {@@/checkbox/}
+ \tl_put_left:Nn \l_@@_fieldID_tl {@@/pushbutton/}
}
- \@@_checkbox_field:V\l_@@_fieldID_tl
+ \@@_pushbutton_field:V\l_@@_fieldID_tl
\@@_annot:
\group_end:
}
@@ -481,92 +460,25 @@
% Most keys are inherited simply the ones from the generic field and annot keys.
% A key to decide if the box is initially checked or not.
% We stay in the same family so that we can build a style.
-% \begin{macro}{checked}
-% This is a key specific for checkbox, it sets both field and annotation keys.
+% \begin{macro}{}
% \begin{macrocode}
\keys_define:nn { pdffield }
{
- ,checked .choice:
- ,checked / false .code:n =
- {
- \pdfdict_put:nnx { l_@@/field }{V} { /Off }
- \pdfdict_put:nnx { l_@@/field }{DV}{ /Off }
- \pdfannot_dict_put:nnn {widget}{AS}{ /Off }
- }
- ,checked / true .code:n =
- {
- \pdfdict_put:nnx { l_@@/field }{V} { /Yes }
- \pdfdict_put:nnx { l_@@/field }{DV}{ /Yes }
- \pdfannot_dict_put:nnn {widget}{AS}{ /Yes }
- }
- ,checked .default:n = {true}
- ,checked .groups:n = {checkbox}
- }
-\keys_define:nn { pdffield }
- {
- ,__value .choice:
- ,__value / Off .code:n =
- {
- \pdfdict_put:nnx { l_@@/field }{V} { /Off }
- \pdfdict_put:nnx { l_@@/field }{DV}{ /Off }
- \pdfannot_dict_put:nnn {widget}{AS}{ /Off }
- }
- ,__value / Yes .code:n =
- {
- \pdfdict_put:nnx { l_@@/field }{V} { /Yes }
- \pdfdict_put:nnx { l_@@/field }{DV}{ /Yes }
- \pdfannot_dict_put:nnn {widget}{AS}{ /Yes }
- }
}
+
% \end{macrocode}
% \end{macro}
-% \begin{macro}{\@@_checkbox_value_handler:n,\@@_checkbox_default_handler:n}
+% \begin{macro}{\@@_pushbutton_value_handler:n,\@@_pushbutton_default_handler:n}
+% ??? probably unusuable
% |value| and |default| do the same as checked.
% \begin{macrocode}
-\cs_new_protected:Npn \@@_checkbox_value_handler:n #1
- {
- \keys_set:nn{pdffield}{__value={#1}}
- }
-\cs_new_protected:Npn \@@_checkbox_default_handler:n #1
- {
- \keys_set:nn{pdffield}{__value={#1}}
- }
-% \end{macrocode}
-% \end{macro}
-% \begin{macro}{\@@_checkbox_appearance_handler:nnn}
-% Appearances must create a dictionary, so we define a special handler.
-% \Arg{name} is the xform name without the /Yes, /Off, \Arg{type} is N, R, or D,
-% \Arg{text} is a word for the error message.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_checkbox_appearance_handler:nnn #1 #2 #3 %name, type, text
- {
- \pdfxform_if_exist:nTF { #1/Yes }
- {
- \pdf_object_if_exist:nF {@@/checkbox/AP/#1}
- {
- \pdf_object_new:nn {@@/checkbox/AP/#1}{dict}
- \pdf_object_write:nx
- {@@/checkbox/AP/#1}
- {
- /Yes ~ \pdfxform_ref:n { #1/Yes}
- /Off ~ \pdfxform_ref:n { #1/Off}
- }
- }
- \pdfannot_dict_put:nnx {widget/AP}{#2}{\pdf_object_ref:n{@@/checkbox/AP/#1}}
- }
- {
- \msg_error:nnnn{pdffield}{appearance-missing}{#1}{#3}
- }
- }
-
% \end{macrocode}
-%
% \end{macro}
%
% \subsection{user commands}
-% \begin{macro}{\pdffield_checkbox:n}
+% \begin{macro}{\pdffield_pushbutton:n}
% \begin{macrocode}
-\cs_set_eq:NN \pdffield_checkbox:n \@@_checkbox:n
+\cs_set_eq:NN \pdffield_pushbutton:n \@@_pushbutton:n
%</package>
% \end{macrocode}
% \end{macro}
More information about the latex3-commits
mailing list.