Index

  1. \SetaPDF
    1. FormFiller
    2. FormFiller
      1. Field
        1. Choice
        2. AbstractField
        3. AdditionalActions
        4. AppearanceValueCallbackInterface
        5. Button
        6. ButtonGroup
        7. Combo
        8. DefaultAppearanceData
        9. Exception
        10. FieldInterface
        11. Flags
        12. Formatter
        13. List
        14. PushButton
        15. Signature
        16. Text

SetaPDF_FormFiller_Field_Text A text field

File: /SetaPDF v2/FormFiller/Field/Text.php

Class hierarchy

Implements

Summary

Methods

Properties

Constants

Constants

OVERFLOWS_HORIZONTALLY

public const integer SetaPDF_FormFiller_Field_Text::OVERFLOWS_HORIZONTALLY = 2

Constant saying that text overflows horizontally

OVERFLOWS_NONE

public const integer SetaPDF_FormFiller_Field_Text::OVERFLOWS_NONE = 0

Constant saying that no text overflows the visible area

OVERFLOWS_VERTICALLY

public const integer SetaPDF_FormFiller_Field_Text::OVERFLOWS_VERTICALLY = 1

Constant saying that text overflows vertically


Properties

$_additionalActions

protected SetaPDF_FormFiller_Field_AdditionalActions SetaPDF_FormFiller_Field_Text::$_additionalActions

$_annotation

protected SetaPDF_Core_Document_Page_Annotation_Widget SetaPDF_FormFiller_Field_AbstractField::$_annotation

The annotation object of this form field

$_appearanceCanvas

protected SetaPDF_Core_Canvas SetaPDF_FormFiller_Field_AbstractField::$_appearanceCanvas

The canvas object of the appearance

$_appearanceCreated

protected bool SetaPDF_FormFiller_Field_AbstractField::$_appearanceCreated = false

$_appearanceValueCallback

protected callback SetaPDF_FormFiller_Field_Text::$_appearanceValueCallback = array(...)

A callback that may change the appearance value (e.g. format a number)

$_defaultAppearanceData

protected SetaPDF_FormFiller_Field_DefaultAppearanceData SetaPDF_FormFiller_Field_AbstractField::$_defaultAppearanceData

$_fieldDictionary

protected SetaPDF_Core_Type_Dictionary SetaPDF_FormFiller_Field_AbstractField::$_fieldDictionary

The main field dictionary

$_fieldObject

protected SetaPDF_Core_Type_IndirectObject SetaPDF_FormFiller_Field_AbstractField::$_fieldObject

The fields indirect object

$_fields

protected SetaPDF_FormFiller_Fields SetaPDF_FormFiller_Field_AbstractField::$_fields

A reference to the fields instance

$_font

protected SetaPDF_Core_Font_FontInterface SetaPDF_FormFiller_Field_AbstractField::$_font

The font object, which should be used to create the appearance

$_fontSize

protected float|null SetaPDF_FormFiller_Field_AbstractField::$_fontSize

The font size, which should be used to create the appearance

$_lineHeightFactor

protected float SetaPDF_FormFiller_Field_AbstractField::$_lineHeightFactor

The factor to calculate the line height based on the font size

$_observeTextOverflow

protected boolean SetaPDF_FormFiller_Field_Text::$_observeTextOverflow = false

Defines whether observing text overflow is enabled or not

$_originalQualifiedName

protected string SetaPDF_FormFiller_Field_AbstractField::$_originalQualifiedName

The name without the suffix

$_page

protected SetaPDF_Core_Document_Page SetaPDF_FormFiller_Field_AbstractField::$_page

The page instance on which the form field is placed

$_qualifiedName

protected string SetaPDF_FormFiller_Field_AbstractField::$_qualifiedName

The name including a suffix if needed ("Text#1")

$_textColor

protected SetaPDF_Core_DataStructure_Color|null SetaPDF_FormFiller_Field_AbstractField::$_textColor

An individual color object which should be used for drawing the text appearance

$_textColorSpace

protected SetaPDF_Core_ColorSpace|null SetaPDF_FormFiller_Field_AbstractField::$_textColorSpace

An individual color space object which should be used for setting the non-stroking color space

$_textOverflow

protected integer|null SetaPDF_FormFiller_Field_Text::$_textOverflow

Flag indicating that the text overflows the visible area of the field.

$_textTranslateData

protected array SetaPDF_FormFiller_Field_Text::$_textTranslateData = array(...)

Data to be used for translation of the initial x/y coordinates of the field appearance.


Methods

__construct()

public SetaPDF_FormFiller_Field_AbstractField::__construct (
SetaPDF_FormFiller_Fields $fields, string $qualifiedName, SetaPDF_Core_Type_IndirectReference|SetaPDF_Core_Type_IndirectObject $fieldObject [, string $originalQualifiedName = null ]
)

The constructor.

Parameters
$fields : SetaPDF_FormFiller_Fields

The fields instance

$qualifiedName : string

The qualified name of the field

$fieldObject : SetaPDF_Core_Type_IndirectReference|SetaPDF_Core_Type_IndirectObject
 
$originalQualifiedName : string

The original qualified name of the field

_checkPermission()

protected SetaPDF_FormFiller_Field_AbstractField::_checkPermission (
[ integer $permission = SetaPDF_Core_SecHandler::PERM_FILL_FORM ]
): void

Checks for form-filling permissions.

Parameters
$permission : integer
 
Exceptions

Throws SetaPDF_Core_SecHandler_Exception

_getAppearanceReference()

protected SetaPDF_FormFiller_Field_AbstractField::_getAppearanceReference (
void
): SetaPDF_Core_Type_IndirectReference

Get the reference to the normal appearance stream object.

_getBorderWidthAndStyle()

protected SetaPDF_FormFiller_Field_AbstractField::_getBorderWidthAndStyle (
void
): array

Resolve the border width and style

_getFontRelation()

protected SetaPDF_FormFiller_Field_AbstractField::_getFontRelation (
SetaPDF_Core_Type_Dictionary $nDictionary, string &$fontName
): SetaPDF_Core_Type_Dictionary_Entry

Get the font relation and copy the resources to the Resources entry if needed.

Parameters
$nDictionary : SetaPDF_Core_Type_Dictionary
 
$fontName : string
 
Exceptions

Throws SetaPDF_FormFiller_Exception

_postDelete()

protected SetaPDF_FormFiller_Field_AbstractField::_postDelete (
void
): void

A method called after deleting a field.

This method forwards the deletion info to the fields instance.

_preDelete()

protected SetaPDF_FormFiller_Field_AbstractField::_preDelete (
void
): void

A method called before deleting a field.

This method forwards the deletion info to the fields instance.

_preFlatten()

protected SetaPDF_FormFiller_Field_AbstractField::_preFlatten (
void
): void

A method called before flattening a field.

This method forwards the flatten info to the fields instance.

_purgeValue()

protected SetaPDF_FormFiller_Field_Text::_purgeValue (
string $value
): string

Purges the value accoring to field properties like "multiline" or "max-length".

Parameters
$value : string

Value in UTF-16BE encoding

_recreateAppearance()

protected SetaPDF_FormFiller_Field_AbstractField::_recreateAppearance (
[ null|SetaPDF_Core_Canvas $circle = false [, $canvas = null ]]
): SetaPDF_Core_Canvas

Recreate or creates the background appearance of the form field.

Parameters
$circle : null|SetaPDF_Core_Canvas
 
$canvas
 

cleanUp()

public SetaPDF_FormFiller_Field_Text::cleanUp (
void
): void

Release cycled references and release memory.

delete()

public SetaPDF_FormFiller_Field_AbstractField::delete (
void
): void

Delete the field.

Exceptions

Throws SetaPDF_FormFiller_Field_Exception

flatten()

public SetaPDF_FormFiller_Field_AbstractField::flatten (
[ boolean $recreateAppearanceIfNeedAppearancesIsSet = false ]
): void

Flatten the field to the pages content stream.

Parameters
$recreateAppearanceIfNeedAppearancesIsSet : boolean

Defines whether the field appearance is re-created if the NeedAppearances flag is set.

Exceptions

Throws SetaPDF_Core_Type_Exception

Throws SetaPDF_Core_Type_IndirectReference_Exception

See

getAdditionalActions()

public SetaPDF_FormFiller_Field_Text::getAdditionalActions (
void
): SetaPDF_FormFiller_Field_AdditionalActions

Gets the additional actions object instance for this field.

getAnnotation()

public SetaPDF_FormFiller_Field_AbstractField::getAnnotation (
void
): SetaPDF_Core_Document_Page_Annotation_Widget

Get the widget annotation object from this field.

getAppearanceCanvas()

public SetaPDF_FormFiller_Field_AbstractField::getAppearanceCanvas (
void
): SetaPDF_Core_Canvas

Get the appearance canvas of the "normal" appearance object.

getAppearanceFont()

public SetaPDF_FormFiller_Field_AbstractField::getAppearanceFont (
void
): null|SetaPDF_Core_Font_FontInterface

Get the appearance font object.

getAppearanceFontSize()

public SetaPDF_FormFiller_Field_AbstractField::getAppearanceFontSize (
void
): float|null

Get the appearance font size.

Exceptions

Throws SetaPDF_FormFiller_Field_Exception

getAppearanceTextColor()

public SetaPDF_FormFiller_Field_AbstractField::getAppearanceTextColor (
void
): null|SetaPDF_Core_DataStructure_Color

Get the individual appearance text color.

getAppearanceTextColorSpace()

public SetaPDF_FormFiller_Field_AbstractField::getAppearanceTextColorSpace (
void
): null|SetaPDF_Core_ColorSpace

Get the individual color space object which should be used for setting the non-stroking color space.

getAppearanceValue()

public SetaPDF_FormFiller_Field_Text::getAppearanceValue (
[ string $encoding = 'UTF-8' ]
): string

Get the appearance value.

Parameters
$encoding : string
 

getDefaultAppearanceData()

public SetaPDF_FormFiller_Field_AbstractField::getDefaultAppearanceData (
void
): SetaPDF_FormFiller_Field_DefaultAppearanceData

Get the default appearance data of the DA value.

Exceptions

Throws SetaPDF_FormFiller_Field_Exception

getDefaultValue()

public SetaPDF_FormFiller_Field_Text::getDefaultValue (
[ string $encoding = 'UTF-8' ]
): null|string

Returns the default value of the field.

This value is used if the form is reset.

Parameters
$encoding : string
 
See

getFieldDictionary()

public SetaPDF_FormFiller_Field_AbstractField::getFieldDictionary (
void
): SetaPDF_Core_Type_Dictionary

Get the field dictionary.

getFieldFlags()

public SetaPDF_FormFiller_Field_AbstractField::getFieldFlags (
void
): integer

Returns the current field flags.

getFieldObject()

public SetaPDF_FormFiller_Field_AbstractField::getFieldObject (
void
): SetaPDF_Core_Type_IndirectObject

Get the indirect object of the form field.

getFields()

public SetaPDF_FormFiller_Field_AbstractField::getFields (
void
): SetaPDF_FormFiller_Fields

Get the fields instance.

getLineHeightFactor()

public SetaPDF_FormFiller_Field_AbstractField::getLineHeightFactor (
void
): float

Get the line height factor

The line height is calculated by this factor in relation to the font size:

$lineHeight = $fontSize * $lineHeightFactor

By default this value is calculated by the font bounding box values "ury - lly / 1000".

See

getMaxLength()

public SetaPDF_FormFiller_Field_Text::getMaxLength (
void
): boolean|integer

Get the max length property if available.

getName()

public SetaPDF_FormFiller_Field_AbstractField::getName (
void
): string

Alias for getQualifiedName().

See

getNoExport()

public SetaPDF_FormFiller_Field_AbstractField::getNoExport (
void
): boolean

Checks if the no-export flag is set.

getNormalAppearanceObject()

public SetaPDF_FormFiller_Field_AbstractField::getNormalAppearanceObject (
[ boolean $createNew = false ]
): SetaPDF_Core_Type_IndirectObject

Get or create the normal appearance object (the object referenced in the N entry).

Parameters
$createNew : boolean

Pass true to force a recreation

getObserveTextOverflow()

public SetaPDF_FormFiller_Field_Text::getObserveTextOverflow (
void
): boolean

Get whether observing text overflow is enabled or not.

getOriginalQualifiedName()

public SetaPDF_FormFiller_Field_AbstractField::getOriginalQualifiedName (
void
): string

Get the original qualified name (without suffix).

getPage()

public SetaPDF_FormFiller_Field_AbstractField::getPage (
void
): SetaPDF_Core_Document_Page

Gets the page object on which the form field is placed.

Exceptions

Throws SetaPDF_FormFiller_Field_Exception

getPageNumber()

public SetaPDF_FormFiller_Field_AbstractField::getPageNumber (
void
): integer

Get the page number on which the field appears.

getQualifiedName()

public SetaPDF_FormFiller_Field_AbstractField::getQualifiedName (
void
): string

Returns the qualified name.

getTextOverflow()

public SetaPDF_FormFiller_Field_Text::getTextOverflow (
void
): null|integer

Check if the visible text overflows the visible area.

Return Values

If the annotation was not rendered null is returned. Otherwise 1 if the text overflows vertically or 2 if the text overflows horizontally. 3 for both.

getTooltip()

public SetaPDF_FormFiller_Field_AbstractField::getTooltip (
[ string $encoding = 'UTF-8' ]
): bool|string

Get the tooltip value.

Parameters
$encoding : string
 

getValue()

public SetaPDF_FormFiller_Field_Text::getValue (
[ string $encoding = 'UTF-8' ]
): string

Get the field value.

Parameters
$encoding : string

The output encoding

See

getVisibleValue()

public SetaPDF_FormFiller_Field_Text::getVisibleValue (
[ string $encoding = 'UTF-8' ]
): string

Returns the field specific visible value.

Parameters
$encoding : string
 

isCombField()

public SetaPDF_FormFiller_Field_Text::isCombField (
void
): boolean

Check if the comb field flag is set.

isDoNotScrollSet()

public SetaPDF_FormFiller_Field_Text::isDoNotScrollSet (
void
): boolean

Check if the "do not scroll" flag is set.

isDoNotSpellCheckSet()

public SetaPDF_FormFiller_Field_Text::isDoNotSpellCheckSet (
void
): boolean

Check if the "do not spell check" flag is set.

isFieldFlagSet()

public SetaPDF_FormFiller_Field_AbstractField::isFieldFlagSet (
integer $flag
): boolean

Checks if a specific field flag is set.

Parameters
$flag : integer
 

isMultiline()

public SetaPDF_FormFiller_Field_Text::isMultiline (
void
): boolean

Check if the multiline flag is set.

isPasswordField()

public SetaPDF_FormFiller_Field_Text::isPasswordField (
void
): boolean

Check if the password field flag is set.

isReadOnly()

public SetaPDF_FormFiller_Field_AbstractField::isReadOnly (
void
): boolean

Checks if the field is set to read-only.

isRequired()

public SetaPDF_FormFiller_Field_AbstractField::isRequired (
void
): boolean

Checks if the field is set to be required.

recreateAppearance()

public SetaPDF_FormFiller_Field_Text::recreateAppearance (
void
): void

Recreate or creates the Appearance of the form field.

setAppearanceFont()

public SetaPDF_FormFiller_Field_AbstractField::setAppearanceFont (
SetaPDF_Core_Font_FontInterface $font [, float $size = null ]
): void

Set the appearance font object.

Parameters
$font : SetaPDF_Core_Font_FontInterface
 
$size : float
 

setAppearanceFontSize()

public SetaPDF_FormFiller_Field_AbstractField::setAppearanceFontSize (
float|null $fontSize
): void

Set an individual font size.

Parameters
$fontSize : float|null
 

setAppearanceTextColor()

public SetaPDF_FormFiller_Field_AbstractField::setAppearanceTextColor (
[ SetaPDF_Core_DataStructure_Color $textColor = null ]
): void

Set an individual appearance text color.

Parameters
$textColor : SetaPDF_Core_DataStructure_Color
 

setAppearanceTextColorSpace()

public SetaPDF_FormFiller_Field_AbstractField::setAppearanceTextColorSpace (
[ SetaPDF_Core_ColorSpace|null $colorSpace = null ]
): void

Set the individual color space object which should be used for setting the non-stroking color space.

Parameters
$colorSpace : SetaPDF_Core_ColorSpace|null
 

setAppearanceValueCallback()

public SetaPDF_FormFiller_Field_Text::setAppearanceValueCallback (
callback $callback
): void

Set the appearance value callback (to e.g. format a number).

The callback will be called with 2 arguments:

  1. A reference to the field instance
  2. The requested encoding

It needs to return a value in the specified encoding (internal calls need UTF-16BE throughout).

Parameters
$callback : callback
 

setCombField()

public SetaPDF_FormFiller_Field_Text::setCombField (
[ boolean $comb = true ]
): void

Set the comb field flag.

Changing this flag will re-create the field appearance.

Parameters
$comb : boolean
 
Exceptions

Throws SetaPDF_FormFiller_Field_Exception

setDefaultValue()

public SetaPDF_FormFiller_Field_Text::setDefaultValue (
null|string $value [, string $encoding = 'UTF-8' ]
): void

Set the default value of the field.

Parameters
$value : null|string
 
$encoding : string
 

setDoNotScroll()

public SetaPDF_FormFiller_Field_Text::setDoNotScroll (
[ boolean $doNotScroll = true ]
): void

Set the "do not scroll" flag.

Parameters
$doNotScroll : boolean
 

setDoNotSpellCheck()

public SetaPDF_FormFiller_Field_Text::setDoNotSpellCheck (
[ boolean $doNotSpellCheck = true ]
): void

Set the "do not spell check" flag.

Parameters
$doNotSpellCheck : boolean
 
Exceptions

Throws SetaPDF_FormFiller_Field_Exception

setFieldFlags()

public SetaPDF_FormFiller_Field_AbstractField::setFieldFlags (
integer $flags [, boolean|null $add = true ]
): void

Sets a field flag.

Parameters
$flags : integer
 
$add : boolean|null

Add = true, remove = false, set = null

setLineHeightFactor()

public SetaPDF_FormFiller_Field_AbstractField::setLineHeightFactor (
null|float $lineHeightFactor
): void

Set the line height factor

The line height is calculated by this factor in relation to the font size:

$lineHeight = $fontSize * $lineHeightFactor

By default this value is calculated by the font bounding box values "ury - lly / 1000".

Parameters
$lineHeightFactor : null|float
 
See

setMaxLength()

public SetaPDF_FormFiller_Field_Text::setMaxLength (
integer $maxLength
): void

Set the max length property.

Changing this flag will reset the value to a value that fits into the given maximal length.

Parameters
$maxLength : integer
 

setMultiline()

public SetaPDF_FormFiller_Field_Text::setMultiline (
[ bool|true $multiline = true ]
): void

Set the multiline flag.

Changing this flag will re-create the field appearance.

Parameters
$multiline : bool|true
 
Exceptions

Throws SetaPDF_FormFiller_Field_Exception

setNoExport()

public SetaPDF_FormFiller_Field_AbstractField::setNoExport (
[ boolean $noExport = true ]
): void

Set the no-export flag.

Parameters
$noExport : boolean
 

setObserveTextOverflow()

public SetaPDF_FormFiller_Field_Text::setObserveTextOverflow (
boolean $observeTextOverflow
): void

Set whether observing text overflow is enabled or not.

Parameters
$observeTextOverflow : boolean
 

setPasswordField()

public SetaPDF_FormFiller_Field_Text::setPasswordField (
[ boolean $password = true ]
): void

Set the password field flag.

Changing this flag will re-create the field appearance.

Parameters
$password : boolean
 
Exceptions

Throws SetaPDF_FormFiller_Field_Exception

setReadOnly()

public SetaPDF_FormFiller_Field_AbstractField::setReadOnly (
[ boolean $readOnly = true ]
): void

Sets the read-only flag.

Parameters
$readOnly : boolean
 

setRequired()

public SetaPDF_FormFiller_Field_AbstractField::setRequired (
[ boolean $required = true ]
): void

Sets the required flag.

Parameters
$required : boolean
 

setTextTranslate()

public SetaPDF_FormFiller_Field_Text::setTextTranslate (
[ integer $x = 0 [, integer $y = 0 ]]
): void

Set translate data for the text appearance.

Parameters
$x : integer

The value by which the text should be translated on the abscissa.

$y : integer

The value by which the text should be translated on the ordinate.

setTooltip()

public SetaPDF_FormFiller_Field_AbstractField::setTooltip (
string|false $value [, string $encoding = 'UTF-8' ]
): void

Set the tooltip value.

Parameters
$value : string|false
 
$encoding : string
 

setValue()

public SetaPDF_FormFiller_Field_Text::setValue (
string $value [, string $encoding = 'UTF-8' ]
): void

Set the field value.

If the fields multiline flag is set (see isMultiline()) the method accepts a string of several lines.

All common line delimiters are possible: \r\n, \n or \r

Internally they get normalized. So if you need to compare a value of the getValue() method keep this in mind.

Parameters
$value : string

The text field value

$encoding : string

The input encoding

unsetFieldFlags()

public SetaPDF_FormFiller_Field_AbstractField::unsetFieldFlags (
integer $flags
): void

Removes a field flag.

Parameters
$flags : integer
 

© 2023 Setasign GmbH & Co. KG · Contact / Imprint · Data Privacy Statement (German)