[latex3-commits] [git/LaTeX3-latex3-pdfresources] textfields: document font (211184e)
Ulrike Fischer
fischer at troubleshooting-tex.de
Tue May 11 13:04:02 CEST 2021
Repository : https://github.com/latex3/pdfresources
On branch : textfields
Link : https://github.com/latex3/pdfresources/commit/211184ec030059a095d3a027e0c2886c5a46607c
>---------------------------------------------------------------
commit 211184ec030059a095d3a027e0c2886c5a46607c
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date: Tue May 11 13:04:02 2021 +0200
document font
>---------------------------------------------------------------
211184ec030059a095d3a027e0c2886c5a46607c
l3pdffield-textfield.dtx | 161 +++++++++++++++++++++++++++++++++--------------
l3pdffield.dtx | 8 ++-
2 files changed, 121 insertions(+), 48 deletions(-)
diff --git a/l3pdffield-textfield.dtx b/l3pdffield-textfield.dtx
index 5d4bf8f..c011c58 100644
--- a/l3pdffield-textfield.dtx
+++ b/l3pdffield-textfield.dtx
@@ -64,32 +64,61 @@
% Textfields allows the user to input text which is then rendered by the PDF viewer and
% often can also be saved together with the PDF.
%
-% A typical wish here it that a font matching the document font is used
-% in textfields too. But how can be done?
+% Currently the package doesn't initialize the font |/Helv|
+% used by default in the fields (It works also without it, but this isn't fully compliant.)
+% I don't want to setup the same font twice and haven't yet decided how
+% to organize the collaboration with hyperref. So for now you should load hyperref
+% and issue the \cs{Form} command.
+%
+% Please keep in mind
+% \begin{itemize}
+% \item Not every PDF viewer supports textfields.
+% \item The font and the exact position of the chars depends on the PDF viewer.
+% \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}
+%
+% \subsection{About fonts}
+%
+% The font color and font size can be changed with the keys |fontcolor| and
+% |fontsize| described below. This works quite reliably (but e.g.
+% the PDF viewer of my browser insists to show the font in blue while editing).
+%
+% Much more difficult is the font family:
+% a typical wish for textfields is that a font matching the document font is used
+% in the fields. But how can that be done?
% Obviously it is not possible like with a checkbox to prepare and include appearances
% with the right look, the PDF reader has to render the text dynamically.
% The PDF reference mentions only one way to pass a font setting to the text field:
-% The |DA| key can contain a font operator. The name font used there should be added
-% to the form resources with the |DR| key. But clearly the main resources to render
-% the text is not an embedded font and a PDF font operator as both is not enough
-% to garanty a sensible text support: a font operator is normally used in
+% The |DA| key can contain a font operator and the fontname used should be added
+% along with a object reference of the font to the form resources
+% in the |AcroForm/DR/Font| dictionary. The question is: what does a PDF renderer
+% make with this data? Clearly the main resources to render
+% the text can not be to rely on an embedded font and a PDF font operator as both
+% is not enough
+% to guarantee a sensible text support: a font operator is normally used in
% the page stream along with glyph indices and positioning instructions, not
% with unicode input, and typically a font is only partially embedded.
-% This means the PDF viewers and editors actually use
-% system resources. Hyperref may add a reference
-% the type1 font helvetica to the DA key, but
-% PDF viewers use actually Arial.
-%
-% A number of test with the Adobe Reader and Pro show that
-% the DA/DR info isn't ignored but used to choose a fitting
-% system font:
+% This means the PDF viewers and editors actually have to use external
+% resources--system fonts, or fonts that come along with the viewer and libraries
+% to handle font shaping.
+%
+% Hyperref may add a reference the type1 font helvetica to the DA key, but
+% PDF viewers use actually Arial. And if one doesn't add a font with
+% |DA| and |DR/Font| the text field works nevertheless.
+%
+% This doesn't mean that the DA/DR info is ignored altogether.
+% Adobe Reader and Pro seems to use it to choose a fitting fallback font:
% \begin{itemize}
% \item One can change the font by simply using the font name (the examples use
-% the |font| key of this module). At least with
-% adobe one get courier with |font=courier|, times with |font=times|,
+% the |font| key of this module). One get courier with |font=courier|,
+% times with |font=times|,
% comic sans with |font=ComicSansMS|, DejaVu with |font=DejaVuSans|. The fonts
-% don't need to be used in the document or added as resources in the DR dictionary.
+% don't need to be used in the document or added as resources in the DR/Font dictionary.
% Some fonts work better than other: comic sans is quite unproblematic,
% but DejaVu seems to trigger a font search first and so is slower (perhaps the.
% \item If one fill and then save such a PDF at least adobe adds
@@ -97,28 +126,32 @@
% \end{itemize}
%
% This lazy font setting doesn't work with other PDF viewers.
-% In other test I had better results by actually embedding the font and adding it
+% In other test I had better results by actually embedding a few glyphs
+% of the font and then adding the font
% as resource to the DR/Font dictionary. Sadly this requires lualatex, only there is
% possible to retrieve the internal font name and font object number for a larger set
-% of fonts. With pdflatex it works only for font not using a virtual font, and xelatex
-% has no access at all. The code for lualatex looked like this
+% of fonts---with pdflatex it works only for fonts not using a virtual font, and xelatex
+% has no access at all. The code for lualatex looked like this (the font one wants
+% to use should be active)
% \begin{verbatim}
% \pdffield_textfield:n {name=text,font=F\pdffeedback~fontname\font}
% \pdfmanagement_add:nxx{Catalog/AcroForm/DR/Font}
-% {F\pdffeedback~fontname\font}{\pdffeedback~fontobjnum\font \c_space_tl0 \c_space_tl R}
+% {F\pdffeedback~fontname\font}
+% {\pdffeedback~fontobjnum\font \c_space_tl 0 \c_space_tl R}
% \end{verbatim}
%
+% \subsection{Vertical alignment}
+% There is no way to set a reference point for the baseline.
+% Alignment must achieved by
+% fiddling with the height and depth of the field. The defaults (which uses as
+% height the fontsize, and a bit depth) works okay in adobe reader with arial.
+% If the font is set to courier, the text jumps up and one has to decrease the height
+% by around 30\%. For a multiline field which should be top aligned you should
+% increase the depth by the wanted amount \emph{and} the height by around 2pt.
+%
+% The geometry of the fields is seen by TeX, and so can influence the line spacing.
+% If needed you should hide the height with \cs{raisebox} or \cs{smash}.
%
-% Please keep in mind
-% \begin{itemize}
-% \item Not every PDF viewer supports textfields.
-% \item The font and the exact position of the chars depends on the PDF viewer.
-% \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{Textfields}
% Input a value:
% \ExplSyntaxOn
@@ -142,16 +175,15 @@
%
% \subsection{Keys}
%
-% The new textfield command accept all field and annot keys from l3pdffield.
-% A few keys are disabled or are forced to specific values.
-% Some keys have a more textfield specific
-% behaviour or have other defaults than with the basic commands. Additionally there
-% are a small number of keys specific to a textfield.
-%
+% The new textfield command accept all field and annot keys from l3pdffield,
+% please check the documentation there. The list here mentions only a few
+% central keys, and the keys which are either specific for textfields, or have
+% changed functionality.
%
% Disabled keys are
% \begin{itemize}
% \item |FT| is overwritten.
+% \item |DA| is overwritten (use |fontcolor|, |fontsize| and |font| instead)
% \item For textfields only the field flags |ReadOnly|, |Required| |NoExport|
% |Multiline|, |Password|, |FileSelect|, |DoNotSpellCheck|, |DoNotScroll| and |Comb|
% make sense.
@@ -225,13 +257,14 @@
%
% \begin{function}{width,height,depth}
% \begin{syntax}
-% |width| = \meta{dim expression}\\
+% |width| = \meta{dim expression}\\
% |height| = \meta{dim expression}\\
-% |depth| = \meta{dim expression}
+% |depth| = \meta{dim expression}
% \end{syntax}
% These keys allow to set the dimensions of textfield instance.
% The value should be a dimension expression. By default
-% |width| is 3cm, the |height| use 0.7\cs{normalbaselineskip}, the |depth| is 0.3\cs{normalbaselineskip}.
+% |width| is 3cm, the |height| uses the fontsize (\cs{f at size} in pt),
+% the |depth| is 0.3\cs{f at size}.
% \end{function}
%
% \begin{function}{appearance,rollover-appearance,down-appearance}
@@ -249,6 +282,38 @@
% make sense for a textfield).
% \end{function}
%
+% \begin{function}{fontcolor}
+% \begin{syntax}
+% |fontcolor| = \meta{color expression} \verb"|" [\meta{model}]\Arg{values}\\
+% \end{syntax}
+% This is sets the color of font in the textfield. Internally currently RGB is used.
+% The colors used in
+% \meta{color expression} must be known to the \pkg{l3color} commands.
+% The initial color is black. It is a \emph{field} setting, that means instances
+% share the color.
+% \end{function}
+%
+% \begin{function}{fonsize}
+% \begin{syntax}
+% |fontsize| = \meta{dim expression}
+% \end{syntax}
+% This is sets the size of the font in the textfield.
+% The default value is the current font size (\cs{f at size} in pt).
+% It is a \emph{field} setting, that means instances
+% share the size.
+% \end{function}
+%
+% \begin{function}{font}
+% \begin{syntax}
+% |font| = \meta{symbolic font name}
+% \end{syntax}
+% This is sets the font in the textfield. See the discussion at the begin of
+% the documentation about some background. The default value is |Helv| and this
+% name is setup if you load hyperref and issue the \cs{Form} command.
+% The default value is the current font size (\cs{f at size} in pt).
+% It is a \emph{field} setting, that means instances
+% share the font.
+% \end{function}
%
% \subsection{Using with hyperref}
% The \cs{TextField} command from hyperref also prints a label, something that the
@@ -326,12 +391,13 @@
% \begin{macrocode}
\keys_set:nn {pdffield}
{
- fieldID=,
- name=textfield,
- appearance = pdffield/textfield/default,
- width = 3cm,
- height = 0.7\normalbaselineskip,
- depth = 0.3\normalbaselineskip,
+ ,fieldID=
+ ,name=textfield
+ ,appearance = pdffield/textfield/default
+ ,width = 3cm
+ ,fontsize= \f at size pt
+ ,height = \f at size pt,
+ depth = \fp_eval:n {0.3*\f at size} pt,
% font defaults!!
}
% \end{macrocode}
@@ -398,10 +464,13 @@
\tl_put_right:Nn \l_@@_DA_fontcolor_tl{~rg}
}
,fontcolor .initial:n = black,
+ ,fontcolor .groups:n = {textfield}
,font .tl_set:N = \l_@@_DA_fontname_tl
,font .initial:n = {Helv}
+ ,font .groups:n = {textfield}
,fontsize .dim_set:N = \l_@@_DA_fontsize_dim
,fontsize .initial:n = {10bp}
+ ,fontsize .groups:n = {textfield}
}
% \end{macrocode}
% And a key to set a dedicated field ID
diff --git a/l3pdffield.dtx b/l3pdffield.dtx
index 44cc0c3..a9cf8fe 100644
--- a/l3pdffield.dtx
+++ b/l3pdffield.dtx
@@ -693,7 +693,9 @@
% |MK/BC| = \meta{color expression} \verb"|" [\meta{model}]\Arg{values}\\
% |bordercolor| = \meta{color expression} \verb"|" [\meta{model}]\Arg{values}
% \end{syntax}
-% These colors the border. Internally currently RGB is used
+% These colors the border. Internally currently RGB is used.
+% The colors used in
+% \meta{color expression} must be known to the \pkg{l3color} commands.
% \end{function}
%
% \begin{function}{MK/BG,backgroundcolor}
@@ -701,7 +703,9 @@
% |MK/BG| = \meta{color expression} \verb"|" [\meta{model}]\Arg{values}\\
% |backgroundcolor| = \meta{color expression} \verb"|" [\meta{model}]\Arg{values}
% \end{syntax}
-% These colors the background. Internally currently RGB is used
+% These colors the background. Internally currently RGB is used.
+% The colors used in
+% \meta{color expression} must be known to the \pkg{l3color} commands.
% \end{function}
%
% The remaining key are useful for buttons only, currently no special syntax support
More information about the latex3-commits
mailing list.