One field of a document. More...

#include <SignDocSDK-cpp.h>

Public Types
enum	Type { t_unknown, t_pushbutton, t_check_box, t_radio_button, t_text, t_list_box, t_signature_digsig, t_signature_signdoc, t_combo_box }
	Field types. More...
enum	Flag { f_ReadOnly = 1 << 0, f_Required = 1 << 1, f_NoExport = 1 << 2, f_NoToggleToOff = 1 << 3, f_Radio = 1 << 4, f_Pushbutton = 1 << 5, f_RadiosInUnison = 1 << 6, f_MultiLine = 1 << 7, f_Password = 1 << 8, f_FileSelect = 1 << 9, f_DoNotSpellCheck = 1 << 10, f_DoNotScroll = 1 << 11, f_Comb = 1 << 12, f_RichText = 1 << 13, f_Combo = 1 << 14, f_Edit = 1 << 15, f_Sort = 1 << 16, f_MultiSelect = 1 << 17, f_CommitOnSelChange = 1 << 18, f_SinglePage = 1 << 28, f_EnableAddAfterSigning = 1 << 29, f_Invisible = 1 << 30 }
	Field flags. More...
enum	WidgetFlag { wf_Invisible = 1 << (1 - 1), wf_Hidden = 1 << (2 - 1), wf_Print = 1 << (3 - 1), wf_NoZoom = 1 << (4 - 1), wf_NoRotate = 1 << (5 - 1), wf_NoView = 1 << (6 - 1), wf_ReadOnly = 1 << (7 - 1), wf_Locked = 1 << (8 - 1), wf_ToggleNoView = 1 << (9 - 1), wf_LockedContents = 1 << (10 - 1) }
	Annotation flags of a widget. More...
enum	Justification { j_none, j_left, j_center, j_right }
	Justification of text fields and list boxes. More...
enum	BorderStyle { bos_other, bos_solid, bos_dashed, bos_beveled, bos_inset, bos_underline }
	Border style. More...
enum	ButtonStyle { bus_default, bus_other, bus_check_mark, bus_cross, bus_star, bus_circle, bus_square, bus_diamond }
	Style used for check boxes and radio buttons. More...
enum	LockType { lt_na, lt_none, lt_all, lt_include, lt_exclude }
	Fields to be locked when signing this signature field. More...
enum	SignatureType { st_not_a_signature_field, st_not_signed, st_approval, st_certification, st_document_time_stamp }
	Signature type. More...
enum	CertSeedValueFlag { csvf_SubjectCert = 0x01, csvf_IssuerCert = 0x02, csvf_Policy = 0x04, csvf_SubjectDN = 0x08, csvf_KeyUsage = 0x20, csvf_URL = 0x40 }
	Bit masks for getCertSeedValueFlags() and setCertSeedValueFlags(). More...
Public Member Functions
	SignDocField ()
	Constructor.
	SignDocField (const SignDocField &aSource)
	Copy constructor.
	~SignDocField ()
	Destructor.
SignDocField &	operator= (const SignDocField &aSource)
	Assignment operator.
void	swap (SignDocField &aOther)
	Efficiently swap this object with another one.
std::string	getName (Encoding aEncoding) const
	Get the name of the field.
const char *	getNameUTF8 () const
	Get the name of the field as UTF-8-encoded C string.
void	setName (Encoding aEncoding, const std::string &aName)
	Set the name of the field.
void	setName (const wchar_t *aName)
	Set the name of the field.
std::string	getAlternateName (Encoding aEncoding) const
	Get the alternate name of the field.
void	setAlternateName (Encoding aEncoding, const std::string &aName)
	Set the alternate name of the field.
std::string	getMappingName (Encoding aEncoding) const
	Get the mapping name of the field.
void	setMappingName (Encoding aEncoding, const std::string &aName)
	Set the mapping name of the field.
int	getValueCount () const
	Get the number of values of the field.
std::string	getValue (Encoding aEncoding, int aIndex) const
	Get a value of the field.
const char *	getValueUTF8 (int aIndex) const
	Get a value of the field.
void	clearValues ()
	Clear the values.
void	addValue (Encoding aEncoding, const std::string &aValue)
	Add a value to the field.
bool	setValue (int aIndex, Encoding aEncoding, const std::string &aValue)
	Set a value of the field.
void	setValue (Encoding aEncoding, const std::string &aValue)
	Set the value of the field.
bool	removeValue (int aIndex)
	Remove a value from the field.
int	getValueIndex () const
	Get the current value index.
void	setValueIndex (int aIndex)
	Set the value index.
bool	clickButton (int aIndex)
	Click a check box or a radio button.
int	getChoiceCount () const
	Get the number of available choices for a list box or combo box.
std::string	getChoiceValue (Encoding aEncoding, int aIndex) const
	Get an available choice of a list box or combo box.
const char *	getChoiceValueUTF8 (int aIndex) const
	Get an available choice of a list box or combo box.
std::string	getChoiceExport (Encoding aEncoding, int aIndex) const
	Get the export value for an available choice of a list box or combo box.
const char *	getChoiceExportUTF8 (int aIndex) const
	Get the export value for an available choice of a list box or combo box.
void	clearChoices ()
	Clear the choices of a list box or combo box.
void	addChoice (Encoding aEncoding, const std::string &aValue)
	Add a choice to a list box or combo box.
void	addChoice (Encoding aEncoding, const std::string &aValue, const std::string &aExport)
	Add a choice to a list box or combo box.
bool	setChoice (int aIndex, Encoding aEncoding, const std::string &aValue)
	Set a choice value of a list box or combo box.
bool	setChoice (int aIndex, Encoding aEncoding, const std::string &aValue, const std::string &aExport)
	Set a choice value of a list box or combo box.
bool	removeChoice (int aIndex)
	Remove a choice from a list box or combo box.
Type	getType () const
	Get the type of the field.
void	setType (Type aType)
	Set the type of the field.
int	getFlags () const
	Get the flags of the field, see enum Flag.
void	setFlags (int aFlags)
	Set the flags of the field, see enum Flag.
SignatureType	getSignatureType () const
	Get the signature type of a signature field.
int	getDocMDP () const
	Get the DocMDP P value of a certification signature.
bool	isSigned () const
	Check if this field is a signed signature field.
bool	isCurrentlyClearable () const
	Check if this signature field is currently clearable.
int	getMaxLen () const
	Get maximum length of text field.
void	setMaxLen (int aMaxLen)
	Set maximum length of text fields.
int	getTopIndex () const
	Get the index of the choice to be displayed in the first line of a list box.
void	setTopIndex (int aTopIndex)
	Set the index of the choice to be displayed in the first line of a list box.
int	getWidget () const
	Get the index of the currently selected widget.
int	getWidgetCount () const
	Get the number of widgets.
bool	selectWidget (int aIndex)
	Select a widget.
bool	addWidget ()
	Add a widget to the field.
bool	insertWidget (int aIndex)
	Add a widget to the field in front of another widget.
bool	removeWidget (int aIndex)
	Remove a widget from the field.
int	getWidgetFlags () const
	Get the annotation flags of the widget, see enum WidgetFlag.
void	setWidgetFlags (int aFlags)
	Set the annotation flags of the widget, see enum WidgetFlag.
int	getPage () const
	Get the page number.
void	setPage (int aPage)
	Set the page number.
double	getLeft () const
	Get the left coordinate.
void	setLeft (double aLeft)
	Set the left coordinate.
double	getBottom () const
	Get the bottom coordinate.
void	setBottom (double aBottom)
	Set the bottom coordinate.
double	getRight () const
	Get the right coordinate.
void	setRight (double aRight)
	Set the right coordinate.
double	getTop () const
	Get the top coordinate.
void	setTop (double aTop)
	Set the top coordinate.
std::string	getButtonValue (Encoding aEncoding) const
	Get the button value of a widget of a radio button group or check box.
const char *	getButtonValueUTF8 () const
	Get the button value of a widget of a radio button group or check box.
void	setButtonValue (Encoding aEncoding, const std::string &aValue)
Justification	getJustification () const
	Get the justification of the widget.
void	setJustification (Justification aJustification)
	Set the justification of the widget.
int	getRotation () const
	Get the rotation of the widget contents.
void	setRotation (int aRotation)
	Set the rotation of the widget contents.
bool	getTextFieldAttributes (SignDocTextFieldAttributes &aOutput) const
	Get the text field attributes of the widget.
bool	setTextFieldAttributes (const SignDocTextFieldAttributes &aInput)
	Set the text field attributes of the widget.
SignDocColor *	getBackgroundColor () const
	Get the background color of the widget.
void	setBackgroundColor (const SignDocColor *aColor)
	Set the background color of the widget.
SignDocColor *	getBorderColor () const
	Get the border color of the widget.
void	setBorderColor (const SignDocColor *aColor)
	Set the border color of the widget.
double	getBorderWidth () const
	Get the border width of the widget.
void	setBorderWidth (double aWidth)
	Set the border width of the widget.
BorderStyle	getBorderStyle () const
	Get the border style.
void	setBorderStyle (BorderStyle aStyle)
	Set the border style.
ButtonStyle	getButtonStyle () const
	Get the button style of a check box or radio button field.
void	setButtonStyle (ButtonStyle aStyle)
	Set the button style of a check box or radio button field.
LockType	getLockType () const
	Get the lock type.
void	setLockType (LockType aLockType)
	Set the lock type.
int	getLockFieldCount () const
	Get the number of field names for lt_include and lt_exclude.
std::string	getLockField (Encoding aEncoding, int aIndex) const
	Get the name of a lock field.
const char *	getLockFieldUTF8 (int aIndex) const
	Get the name of a lock field.
void	clearLockFields ()
	Clear the lock fields.
void	addLockField (Encoding aEncoding, const std::string &aName)
	Add a lock field to the field.
bool	setLockField (int aIndex, Encoding aEncoding, const std::string &aName)
	Set a lock field.
void	setLockField (Encoding aEncoding, const std::string &aName)
	Set a lock field.
bool	removeLockField (int aIndex)
	Remove a lock field.
int	getLockMDP () const
	Get the lock MDP value.
void	setLockMDP (int aMDP)
	Set the lock MDP value.
unsigned	getCertSeedValueFlags () const
	Get the certificate seed value dictionary flags (/SV/Cert/Ff) of a signature field, see enum CertSeedValueFlag.
void	setCertSeedValueFlags (unsigned aFlags)
	Set the certificate seed value dictionary flags (/SV/Cert/Ff) of a signature field, see enum CertSeedValueFlag.
int	getCertSeedValueSubjectDNCount () const
	Get the number of subject distinguished names in the certificate seed value dictionary.
std::string	getCertSeedValueSubjectDN (Encoding aEncoding, int aIndex) const
	Get a subject distinguished name from the certificate seed value dictionary.
const char *	getCertSeedValueSubjectDNUTF8 (int aIndex) const
	Get a subject distinguished name from the certificate seed value dictionary.
void	clearCertSeedValueSubjectDNs ()
	Remove all subject distinguished names from the certificate seed value dictionary.
bool	addCertSeedValueSubjectDN (Encoding aEncoding, const std::string &aName)
	Add a subject distinguished name to the certificate seed value dictionary.
bool	setCertSeedValueSubjectDN (int aIndex, Encoding aEncoding, const std::string &aName)
	Set a subject distinguished name in the certificate seed value dictionary.
bool	setCertSeedValueSubjectDN (Encoding aEncoding, const std::string &aName)
	Set a subject distinguished name in the certificate seed value dictionary.
bool	removeCertSeedValueSubjectDN (int aIndex)
	Remove a subject distinguished name from the certificate seed value dictionary.
int	getCertSeedValueSubjectCertificateCount () const
	Get the number of subject certificates in the certificate seed value dictionary.
bool	getCertSeedValueSubjectCertificate (int aIndex, std::vector< unsigned char > &aOutput) const
	Get a subject certificate of the certificate seed value dictionary.
void	clearCertSeedValueSubjectCertificates ()
	Remove all subject certificates from the certificate seed value dictionary.
void	addCertSeedValueSubjectCertificate (const void *aPtr, size_t aSize)
	Add a subject certificate to the certificate seed value dictionary.
bool	setCertSeedValueSubjectCertificate (int aIndex, const void *aPtr, size_t aSize)
	Set a subject certificate in the certificate seed value dictionary.
void	setCertSeedValueSubjectCertificate (const void *aPtr, size_t aSize)
	Set a subject certificate in the certificate seed value dictionary.
bool	removeCertSeedValueSubjectCertificate (int aIndex)
	Remove a subject certificate from the certificate seed value dictionary.
int	getCertSeedValueIssuerCertificateCount () const
	Get the number of issuer certificates in the certificate seed value dictionary.
bool	getCertSeedValueIssuerCertificate (int aIndex, std::vector< unsigned char > &aOutput) const
	Get an issuer certificate of the certificate seed value dictionary.
void	clearCertSeedValueIssuerCertificates ()
	Remove all issuer certificates from the certificate seed value dictionary.
void	addCertSeedValueIssuerCertificate (const void *aPtr, size_t aSize)
	Add an issuer certificate to the certificate seed value dictionary.
bool	setCertSeedValueIssuerCertificate (int aIndex, const void *aPtr, size_t aSize)
	Set an issuer certificate in the certificate seed value dictionary.
void	setCertSeedValueIssuerCertificate (const void *aPtr, size_t aSize)
	Set an issuer certificate in the certificate seed value dictionary.
bool	removeCertSeedValueIssuerCertificate (int aIndex)
	Remove an issuer certificate from the certificate seed value dictionary.
int	getCertSeedValuePolicyCount () const
	Get the number of policy OIDs in the certificate seed value dictionary.
std::string	getCertSeedValuePolicy (Encoding aEncoding, int aIndex) const
	Get a policy OID from the certificate seed value dictionary.
const char *	getCertSeedValuePolicyUTF8 (int aIndex) const
	Get a policy OID from the certificate seed value dictionary.
void	clearCertSeedValuePolicies ()
	Remove all policy OIDs from the certificate seed value dictionary.
void	addCertSeedValuePolicy (Encoding aEncoding, const std::string &aOID)
	Add a policy OID to the certificate seed value dictionary.
bool	setCertSeedValuePolicy (int aIndex, Encoding aEncoding, const std::string &aOID)
	Set a policy OID in the certificate seed value dictionary.
void	setCertSeedValuePolicy (Encoding aEncoding, const std::string &aOID)
	Set a policy OID in the certificate seed value dictionary.
bool	removeCertSeedValuePolicy (int aIndex)
	Remove a policy OID from the certificate seed value dictionary.
std::string	getSeedValueTimeStampServerURL (Encoding aEncoding) const
	Get the URL of the RFC 3161 time-stamp server from the signature field seed value dictionary.
bool	getSeedValueTimeStampRequired () const
	This function gets a flag from the signature field seed value dictionary that indicates whether a time stamp is required or not for the signature.
bool	setSeedValueTimeStamp (Encoding aEncoding, const std::string &aURL, bool aRequired)
	Set the URL of an RFC 3161 time-stamp server in the signature field seed value dictionary.
std::string	getSeedValueFilter (Encoding aEncoding) const
	Get Filter entry (signature handler) from the signature field seed value dictionary.
bool	getSeedValueFilterRequired () const
	This function gets a flag from the signature field seed value dictionary that indicates whether the Filter entry (signature handler) is a required constraint or not.
bool	setSeedValueFilter (Encoding aEncoding, const std::string &aFilter, bool aRequired)
	Set the Filter entry (signature handler) in the signature field seed value dictionary.
int	getSeedValueSubFilterCount () const
	Get the number of SubFilter values in the seed value dictionary.
std::string	getSeedValueSubFilter (Encoding aEncoding, int aIndex) const
	Get a SubFilter value from the seed value dictionary.
bool	getSeedValueSubFilterRequired () const
	This function gets a flag from the signature field seed value dictionary that indicates whether the SubFilter values are a required constraint or not.
void	setSeedValueSubFilterRequired (bool aRequired) const
	Set a flag from the signature field seed value dictionary that indicates whether the SubFilter values are a required constraint or not.
const char *	getSeedValueSubFilterUTF8 (int aIndex) const
	Get a SubFilter value from the seed value dictionary.
void	clearSeedValueSubFilters ()
	Remove all SubFilter values from the seed value dictionary.
void	addSeedValueSubFilter (Encoding aEncoding, const std::string &aSubFilter)
	Add a SubFilter value to the seed value dictionary.
bool	setSeedValueSubFilter (int aIndex, Encoding aEncoding, const std::string &aSubFilter)
	Set a SubFilter value in the seed value dictionary.
void	setSeedValueSubFilter (Encoding aEncoding, const std::string &aSubFilter)
	Set a SubFilter value in the seed value dictionary.
bool	removeSeedValueSubFilter (int aIndex)
	Remove a SubFilter value from the seed value dictionary.
int	getSeedValueDigestMethodCount () const
	Get the number of DigestMethod values in the seed value dictionary.
std::string	getSeedValueDigestMethod (Encoding aEncoding, int aIndex) const
	Get a DigestMethod value from the seed value dictionary.
bool	getSeedValueDigestMethodRequired () const
	This function gets a flag from the signature field seed value dictionary that indicates whether the DigestMethod values are a required constraint or not.
void	setSeedValueDigestMethodRequired (bool aRequired) const
	Set a flag from the signature field seed value dictionary that indicates whether the DigestMethod values are a required constraint or not.
const char *	getSeedValueDigestMethodUTF8 (int aIndex) const
	Get a DigestMethod value from the seed value dictionary.
void	clearSeedValueDigestMethods ()
	Remove all DigestMethod values from the seed value dictionary.
void	addSeedValueDigestMethod (Encoding aEncoding, const std::string &aDigestMethod)
	Add a DigestMethod value to the seed value dictionary.
bool	setSeedValueDigestMethod (int aIndex, Encoding aEncoding, const std::string &aDigestMethod)
	Set a DigestMethod value in the seed value dictionary.
void	setSeedValueDigestMethod (Encoding aEncoding, const std::string &aDigestMethod)
	Set a DigestMethod value in the seed value dictionary.
bool	removeSeedValueDigestMethod (int aIndex)
	Remove a DigestMethod value from the seed value dictionary.
bool	getSeedValueAddRevInfo () const
	Get the AddRevInfo flag from the signature field seed value dictionary.
void	setSeedValueAddRevInfo (bool aAddRevInfo)
	Set the AddRevInfo flag in the signature field seed value dictionary.
int	getSeedValueMDP () const
	Get the MDP value from the signature field seed value dictionary.
bool	setSeedValueMDP (int aMDP)
	Set the MDP value in the signature field seed value dictionary.
SignDocColor *	getEmptyFieldColor () const
	Get the color used for empty signature field in TIFF document.
void	setEmptyFieldColor (const SignDocColor &aColor)
	Set color used for empty signature field in TIFF document.
	SignDocField (SIGNDOC_Field *aP)
	Internal function.
SIGNDOC_Field *	getImpl ()
	Internal function.
const SIGNDOC_Field *	getImpl () const
	Internal function.
void	setImpl (SIGNDOC_Field *aP)
	Internal function.

Detailed Description

One field of a document.

Calling member function of this class does not modify the document, use SignDocDocument::setField() to apply your changes to the document or SignDocDocument::addField() to add the field to the document.

In PDF documents, a field may have multiple visible "widgets". For instance, a radio button group (radio button field) usually has multiple visible buttons, ie, widgets.

A SignDocField object represents the logical field (containing the type, name, value, etc) as well as all its widgets. Each widget has a page number, a coordinate rectangle, and, for some field types, text field attributes.

Only one widget of the field is accessible at a time in a SignDocField object; use selectWidget() to select the widget to be operated on.

For radio button fields and check box fields, each widget also has a "button value". The button value should remain constant after the document has been created (but it can be changed if needed). The field proper has a value which is either "Off" or one of the button values of its widgets.

Each widget of a radio button field or a check box field is either off or on. If all widgets of a radio button field or a check box are off, the field's value is "Off". If at least one widget is on, the field's value is that widget's "button value". As the value of a field must be different for the on and off states of the field, the button values must not be "Off".

Check box fields usually have exactly one widget. If that widget's button value is, say, "On", the field's value is either "Off" (for the off state) or "On" (for the on state).

Check box fields can have multiple widgets. If all widgets have the same button value, say, "yes", the field's value is either "Off" (for the off state) or "yes" (for the on state). Clicking one widget of the check box field will toggle all widgets of that check box field.

Check box fields can have multiple widgets having different button values. If a check box field has two widgets with button values, say, "1" and "2", the field's value is either "Off" (for the off state), "1" (if the first widget is on) or "2" (if the second widget is on). The two widgets cannot be on at the same time.

If a check box field has three widgets with button values, say, "one, "two", and "two", respectively, the field's value is either "Off" (for the off state), "one" (if the first widget is on) or "two" (if the second and third widgets are on). The second and third widgets will always have the same state and that state will never be the same as the state of the first widget.

A radio button field usually has at least two widgets, having different button values. If a radio button field has two widgets with button values, say, "a" and "b", the field's value is either "Off" (for the off state), "a" (if the first widget is on), or "b" (if the second widget is on). Clicking the first widget puts the first widget into the on state and the second one into the off state (and vice versa).

Different widgets of a radio button field can have the same button value. The behavior for clicking a widget with non-unique button value depends on the f_RadiosInUnison field flag. If that flag is set (it usually is), widgets having the same button value always have the same on/off state. Clicking one of them will turn all of them on. If the f_RadiosInUnison is not set, clicking one widget will put all others (of the same radio button field) into the off state. See getValueIndex() for details.

Signature fields have exactly one widget. Fields of other types must have at least one widget.

Other fields such as text fields (except for signature fields) also can have multiple widgets, but all of them display the same value.

Signature fields in PDF documents are invisible if their width is zero or if their height is zero, that is, if the coordinates set by setLeft() and setRight() are equal or if the coordinates set by setBottom() and setTop()) are equal.

Constructors, destructors, assignment, swapping:

All fields have a type, a name, and flags:

Fields in PDF documents can have an alternate name which is used for displaying the field name in a user interface:

Moreover, fields in PDF documents can have a mapping name which is used for exporting field data:

Most fields in PDF documents can have one or more value:

List boxes and combo boxes can have multiple possible choices:

Fields have one or more widget annotation:

Each widget annotation has a couple of flags:

Each widget annotation has a position on a page:

Radio button widgets and check box widgets have a button value (see above):

Text in a widget is controlled by these functions:

The background color of a widget can be set:

The border of a widget is controlled by these functions:

Radio button widgets and Check box widgets can display various symbols:

The following functions can be used for signature fields only:

Signing signature fields in a PDF document can automatically lock other fields:

Signature fields in a PDF document can have a signature field seed value dictionary controlling various aspects of signing. It can restrict the certificates that can be used for signing:

The certificate can be restricted by subject distinguished name:

The certificate can be restricted by specifying acceptable signing certificates:

The certificate can be restricted by specifying acceptable issuer certificates:

And the certificate can be restricted by policy:

The signature field seed value dictionary can specify an RFC 3161 time-stamp server:

The signature field seed value dictionary can specify a signature handler (Filter):

The signature field seed value dictionary can specify signing methods (SubFilter):

The signature field seed value dictionary can specify a hash algorithms (DigestMethod):

The signature field seed value dictionary can specify whether adding revocation to the signature is mandatory:

The signature field seed value dictionary can specify what changes shall be allowed after signing the signature field:

The color of an empty signature field in a TIFF document can be specified:

Member Enumeration Documentation

enum de::softpro::doc::SignDocField::BorderStyle

Border style.

See also:: getBorderStyle(), setBorderStyle()

Enumerator:

bos_other	Unknown/unsupported border style.
bos_solid	Solid rectangle.
bos_dashed	Dashed rectangle.
bos_beveled	Rectangle looking embossed.
bos_inset	Rectangle looking engraved.
bos_underline	Single line at bottom.

enum de::softpro::doc::SignDocField::ButtonStyle

Style used for check boxes and radio buttons.

See also:: getButtonStyle(), setButtonStyle()

Enumerator:

bus_default	Default button style.
bus_other	Unknown/unsupported style.
bus_check_mark	Check mark.
bus_cross	Cross.
bus_star	Star.
bus_circle	Circle (default for radio buttons).
bus_square	Square.
bus_diamond	Diamond.

enum de::softpro::doc::SignDocField::CertSeedValueFlag

Bit masks for getCertSeedValueFlags() and setCertSeedValueFlags().

Please see the PDF specification (ISO 32000-1:2008) for details.

Enumerator:

csvf_SubjectCert	Adobe bit 1.
csvf_IssuerCert	Adobe bit 2.
csvf_Policy	Adobe bit 3.
csvf_SubjectDN	Adobe bit 4.
csvf_KeyUsage	Adobe bit 6.
csvf_URL	Adobe bit 7.

enum de::softpro::doc::SignDocField::Flag

Field flags.

See the PDF Reference for the meaning of these flags. Most field flags are supported for PDF documents only.

The f_NoToggleToOff flag should be set for all radio button groups. Adobe products seem to ignore this flag being not set.

The f_Invisible, f_EnableAddAfterSigning, and f_SinglePage flags cannot be modified.

Invisible signature fields (f_Invisible) are invisible (ie, they look as if not inserted) until signed. Warning: signing an invisible signature field in a TIFF file may increase the size of the file substantially.

By default, no fields can be inserted into a TIFF document after a signature field has been signed. The f_EnableAddAfterSigning flag changes this behavior. (f_EnableAddAfterSigning is ignored for PDF documents.)

If the f_EnableAddAfterSigning flag is set, document size increases more during signing this field than when this flaq is not set. Each signature will increase the document size by the initial size of the document (before the first signature was applied), approximately. That is, the first signature will approximately double the size of the document.

Inserting a signature field fails if there already are any signed signature fields that don't have this flag set.

By default, signing a signature field signs the complete document, that is, modifications to any page are detected. For TIFF documents, this behavior can be changed for signature fields that have the f_EnableAddAfterSigning flag set: If the f_SinglePage flag is set, the signature applies only to the page containing the signature field, modifications to other pages won't be detected. This flag can be used for speeding up verification of signatures.

A signature field for which f_EnableAddAfterSigning is not set (in a TIFF document) can only be cleared if no other signature fields that don't have f_EnableAddAfterSigning have been signed after the signature field to be cleared. Signature fields having f_EnableAddAfterSigning set can always be cleared.

See also:: getFlags(), setFlags(), SignDocDocument::clearSignature()

Enumerator:

f_ReadOnly	ReadOnly.
f_Required	Required.
f_NoExport	NoExport.
f_NoToggleToOff	NoToggleToOff.
f_Radio	Radio.
f_Pushbutton	Pushbutton.
f_RadiosInUnison	RadiosInUnison.
f_MultiLine	Multiline (for text fields). The value of a text field that has this flag set may contain hard line breaks encoded as "\r", "\n", or "\r\n". The contents of the text field are top-aligned if this flag is set and vertically centered if this flag is not set.
f_Password	Password.
f_FileSelect	FileSelect.
f_DoNotSpellCheck	DoNotSpellCheck.
f_DoNotScroll	DoNotScroll.
f_Comb	Comb.
f_RichText	RichText.
f_Combo	Combo (always set for combo boxes)
f_Edit	Edit (for combo boxes): If this flag is set, the user can enter an arbitrary value.
f_Sort	Sort (for list boxes and combo boxes)
f_MultiSelect	MultiSelect (for list boxes)
f_CommitOnSelChange	CommitOnSelChange (for list boxes and combo boxes)
f_SinglePage	Signature applies to the containing page only (TIFF only)
f_EnableAddAfterSigning	Signature fields can be inserted after signing this field (TIFF only)
f_Invisible	Invisible (TIFF only)

enum de::softpro::doc::SignDocField::Justification

Justification of text fields and list boxes.

See also:: getJustification(), setJustification()

Enumerator:

j_none	Justification does not apply (not a text field or a list box).
j_left	Left-justified.
j_center	Centered.
j_right	Right-justified.

enum de::softpro::doc::SignDocField::LockType

Fields to be locked when signing this signature field.

See also:: getLockType(), setLockType()

Enumerator:

lt_na	Not a signature field.
lt_none	Don't lock any fields.
lt_all	Lock all fields in the document.
lt_include	Lock all lock fields specified by addLockField() etc.
lt_exclude	Lock all fields except the lock fields specified by addLockField() etc.

enum de::softpro::doc::SignDocField::SignatureType

Signature type.

Enumerator:

st_not_a_signature_field	The field is not a signature field.
st_not_signed	The signature field is not signed.
st_approval	Approval signature (that's the normal type of signature).
st_certification	Certification signature (signed by the author).
st_document_time_stamp	Document time stamp.

enum de::softpro::doc::SignDocField::Type

Field types.

Most field types are supported for PDF documents only.

Enumerator:

t_unknown	Unknown type.
t_pushbutton	Pushbutton (PDF).
t_check_box	Check box field (PDF).
t_radio_button	Radio button (radio button group) (PDF).
t_text	Text field (PDF).
t_list_box	List box (PDF).
t_signature_digsig	Digital signature field (Adobe DigSig in PDF, SOFTPRO signature in TIFF).
t_signature_signdoc	Digital signature field (traditional SignDoc, no longer supported) (PDF)
t_combo_box	Combo box (drop-down box) (PDF).

enum de::softpro::doc::SignDocField::WidgetFlag

Annotation flags of a widget.

See the PDF Reference for the meaning of these flags. All these flags are supported for PDF documents only, they are ignored for TIFF documents.

See also:: getWidgetFlags(), setWidgetFlags()

Enumerator:

wf_Invisible	do not display non-standard annotation
wf_Hidden	do not display or print or interact
wf_Print	print the annotation
wf_NoZoom	do not scale to match magnification
wf_NoRotate	do not rotate to match page's rotation
wf_NoView	do not display or interact
wf_ReadOnly	do not interact
wf_Locked	annotation cannot be deleted or modified, but its value can be changed
wf_ToggleNoView	toggle wf_no_view for certain events
wf_LockedContents	value cannot be changed

Constructor & Destructor Documentation

de::softpro::doc::SignDocField::SignDocField ( ) [inline]

Constructor.

The new SignDocField object will have one widget.

de::softpro::doc::SignDocField::SignDocField ( const SignDocField & aSource ) [inline]

Copy constructor.

Parameters:

[in] aSource The object to be copied.

de::softpro::doc::SignDocField::~SignDocField ( ) [inline]

Destructor.

de::softpro::doc::SignDocField::SignDocField ( SIGNDOC_Field * aP ) [inline]

Internal function.

Member Function Documentation

void de::softpro::doc::SignDocField::addCertSeedValueIssuerCertificate	(	const void *	aPtr,
		size_t	aSize
	)		`[inline]`

Add an issuer certificate to the certificate seed value dictionary.

See the PDF Reference for details.

Parameters:

[in]	aPtr	Pointer to the first octet of the DER-encoded certificate.
[in]	aSize	Size in octets of the DER-encoded certificate.

See also:: clearCertSeedValueIssuerCertificates(), getCertSeedValueIssuerCertificate(), getCertSeedValueIssuerCertificateUTF8(), setCertSeedValueIssuerCertificate()

void de::softpro::doc::SignDocField::addCertSeedValuePolicy	(	Encoding	aEncoding,
		const std::string &	aOID
	)		`[inline]`

Add a policy OID to the certificate seed value dictionary.

See the PDF Reference for details.

This function throws std::runtime_error if the value is not correctly encoded according to the specified encoding.

Note:: OIDs should be ASCII strings.

Parameters:

[in]	aEncoding	The encoding of aOID.
[in]	aOID	The policy OID.

See also:: clearCertSeedValuePolicies(), getCertSeedValuePolicy(), getCertSeedValuePolicyUTF8(), setCertSeedValuePolicy()

void de::softpro::doc::SignDocField::addCertSeedValueSubjectCertificate	(	const void *	aPtr,
		size_t	aSize
	)		`[inline]`

Add a subject certificate to the certificate seed value dictionary.

See the PDF Reference for details.

Parameters:

[in]	aPtr	Pointer to the first octet of the DER-encoded certificate.
[in]	aSize	Size in octets of the DER-encoded certificate.

See also:: clearCertSeedValueSubjectCertificates(), getCertSeedValueSubjectCertificate(), getCertSeedValueSubjectCertificateUTF8(), setCertSeedValueSubjectCertificate()

bool de::softpro::doc::SignDocField::addCertSeedValueSubjectDN	(	Encoding	aEncoding,
		const std::string &	aName
	)		`[inline]`

Add a subject distinguished name to the certificate seed value dictionary.

See the PDF Reference for details.

This function throws std::runtime_error if the name is not correctly encoded according to the specified encoding.

Note:: RFC 4514 requires UTF-8 encoding.

Parameters:

[in]	aEncoding	The encoding of aName.
[in]	aName	The subject distinguished name formatted according to RFC 4514.

Returns:: true if successful, false if aName cannot be parsed.

See also:: clearCertSeedValueSubjectDNs(), getCertSeedValueSubjectDN(), getCertSeedValueSubjectDNUTF8(), setCertSeedValueSubjectDN()

void de::softpro::doc::SignDocField::addChoice	(	Encoding	aEncoding,
		const std::string &	aValue
	)		`[inline]`

Add a choice to a list box or combo box.

This function uses the choice value as export value.

This function throws std::runtime_error if the value is not correctly encoded according to the specified encoding.

Note:: getValue() and setValue() use the export value.

Parameters:

[in]	aEncoding	The encoding of aValue.
[in]	aValue	The choice value and export value to be added. Complex scripts are supported, see Complex Scripts.

See also:: clearChoices(), getChoiceExport(), getChoiceValue(), setChoice(), setButtonValue()

void de::softpro::doc::SignDocField::addChoice	(	Encoding	aEncoding,
		const std::string &	aValue,
		const std::string &	aExport
	)		`[inline]`

Add a choice to a list box or combo box.

This function throws std::runtime_error if the value is not correctly encoded according to the specified encoding.

Note:: getValue() and setValue() use the export value.

Parameters:

[in]	aEncoding	The encoding of aValue and aExport.
[in]	aValue	The choice value to be added. Complex scripts are supported, see Complex Scripts.
[in]	aExport	The export value to be added.

See also:: clearChoices(), getChoiceExport(), getChoiceValue(), setChoice(), setButtonValue()

void de::softpro::doc::SignDocField::addLockField	(	Encoding	aEncoding,
		const std::string &	aName
	)		`[inline]`

Add a lock field to the field.

This function throws std::runtime_error if the name is not correctly encoded according to the specified encoding.

Parameters:

[in]	aEncoding	The encoding of aName.
[in]	aName	The name of the lock field to be added.

See also:: clearLockFields(), getLockField(), getLockFieldUTF8(), setLockField()

void de::softpro::doc::SignDocField::addSeedValueDigestMethod	(	Encoding	aEncoding,
		const std::string &	aDigestMethod
	)		`[inline]`

Add a DigestMethod value to the seed value dictionary.

See getSeedValueDigestMethod() for details.

This function throws std::runtime_error if the value is not correctly encoded according to the specified encoding.

Parameters:

[in]	aEncoding	The encoding of aDigestMethod.
[in]	aDigestMethod	The DigestMethod value.

See also:: clearSeedValueDigestMethods(), getSeedValueDigestMethod(), getSeedValueDigestMethodUTF8(), setSeedValueDigestMethod(), setSeedValueDigestMethodRequired()

void de::softpro::doc::SignDocField::addSeedValueSubFilter	(	Encoding	aEncoding,
		const std::string &	aSubFilter
	)		`[inline]`

Add a SubFilter value to the seed value dictionary.

See getSeedValueSubFilter() for details.

This function throws std::runtime_error if the value is not correctly encoded according to the specified encoding.

Parameters:

[in]	aEncoding	The encoding of aSubFilter.
[in]	aSubFilter	The SubFilter value.

See also:: clearSeedValueSubFilters(), getSeedValueSubFilter(), getSeedValueSubFilterUTF8(), setSeedValueSubFilter(), setSeedValueSubFilterRequired()

void de::softpro::doc::SignDocField::addValue	(	Encoding	aEncoding,
		const std::string &	aValue
	)		`[inline]`

Add a value to the field.

Pushbutton fields and signature fields don't have a value, list boxes can have multiple values selected if f_MultiSelect is set.

Hard line breaks for multiline text fields (ie, text fields with flag f_MultiLine set) are encoded as "\r", "\n", or "\r\n". The behavior for values containing line breaks is undefined if the f_MultiLine flag is not set.

After calling this function, getValueIndex() will return -1.

This function throws std::runtime_error if the value is not correctly encoded according to the specified encoding.

Parameters:

[in]	aEncoding	The encoding of aValue.
[in]	aValue	The value to be added. Complex scripts are supported, see Complex Scripts.

See also:: clearValues(), getValue(), getValueIndex(), getValueUTF8(), setValue()

bool de::softpro::doc::SignDocField::addWidget ( ) [inline]

Add a widget to the field.

The new widget will be added at the end, ie, calling getWidgetCount() before calling addWidget() yields the index of the widget that will be added.

After adding a widget, the new widget will be selected. You must set the page number and the coordinates in the new widget before calling SignDocDocument::addField() or SignDocDocument::setField().

Returns:: true iff successful.

See also:: addChoice(), getWidget(), getWidgetCount(), insertWidget(), removeWidget(), selectWidget()

void de::softpro::doc::SignDocField::clearCertSeedValueIssuerCertificates ( ) [inline]

Remove all issuer certificates from the certificate seed value dictionary.

See the PDF Reference for details.

After calling this function, getCertSeedValueIssuerCertificateCount() will return 0.

See also:: addCertSeedValueIssuerCertificate(), getCertSeedValueIssuerCertificateCount(), removeCertSeedValueIssuerCertificate()

void de::softpro::doc::SignDocField::clearCertSeedValuePolicies ( ) [inline]

Remove all policy OIDs from the certificate seed value dictionary.

See the PDF Reference for details.

After calling this function, getCertSeedValuePolicyCount() will return 0.

See also:: addCertSeedValuePolicy(), getCertSeedValuePolicyCount(), removeCertSeedValuePolicy()

void de::softpro::doc::SignDocField::clearCertSeedValueSubjectCertificates ( ) [inline]

Remove all subject certificates from the certificate seed value dictionary.

See the PDF Reference for details.

After calling this function, getCertSeedValueSubjectCertificateCount() will return 0.

See also:: addCertSeedValueSubjectCertificate(), getCertSeedValueSubjectCertificateCount(), removeCertSeedValueSubjectCertificate()

void de::softpro::doc::SignDocField::clearCertSeedValueSubjectDNs ( ) [inline]

Remove all subject distinguished names from the certificate seed value dictionary.

See the PDF Reference for details.

After calling this function, getCertSeedValueSubjectDNCount() will return 0.

See also:: addCertSeedValueSubjectDN(), getCertSeedValueSubjectDNCount(), removeCertSeedValueSubjectDN()

void de::softpro::doc::SignDocField::clearChoices ( ) [inline]

Clear the choices of a list box or combo box.

After calling this function, getChoiceCount() will return 0.

See also:: addChoice(), getChoiceCount(), removeChoice(), setButtonValue()

void de::softpro::doc::SignDocField::clearLockFields ( ) [inline]

Clear the lock fields.

After calling this function, getLockFieldCount() will return 0.

See also:: addLockField(), getLockFieldCount(), removeLockField()

void de::softpro::doc::SignDocField::clearSeedValueDigestMethods ( ) [inline]

Remove all DigestMethod values from the seed value dictionary.

See getSeedValueDigestMethod() for details.

After calling this function, getSeedValueDigestMethodCount() will return 0.

See also:: addSeedValueDigestMethod(), getSeedValueDigestMethodCount(), removeSeedValueDigestMethod(), setSeedValueDigestMethodRequired()

void de::softpro::doc::SignDocField::clearSeedValueSubFilters ( ) [inline]

Remove all SubFilter values from the seed value dictionary.

See getSeedValueSubFilter() for details.

After calling this function, getSeedValueSubFilterCount() will return 0.

See also:: addSeedValueSubFilter(), getSeedValueSubFilterCount(), removeSeedValueSubFilter(), setSeedValueSubFilterRequired()

void de::softpro::doc::SignDocField::clearValues ( ) [inline]

Clear the values.

After calling this function, getValueCount() will return 0 and getValueIndex() will return -1.

See also:: addValue(), getValueCount(), getValueIndex(), removeValue()

bool de::softpro::doc::SignDocField::clickButton ( int aIndex ) [inline]

Click a check box or a radio button.

This function updates both the value (see setValue()) and the value index (see setValueIndex()) based on the current (non-committed) state of the SignDocField object (not looking at the state of the field in the document). It does nothing for other field types.

Adobe products seem to ignore f_NoToggleToOff flag being not set, this function behaves the same way (ie, as if f_NoToggleToOff was set).

Note:: A return value of false does not indicate an error!

Parameters:

[in] aIndex The 0-based index of the widget being clicked.

Returns:: true if anything has been changed, false if nothing has been changed (wrong field type, aIndex out of range, radio button already active).

std::string de::softpro::doc::SignDocField::getAlternateName ( Encoding aEncoding ) const [inline]

Get the alternate name of the field.

The alternate name (if present) should be used for displaying the field name in a user interface. Currently, only PDF documents support alternate field names.

This function throws std::runtime_error if the name cannot be represented using the specified encoding.

Parameters:

[in] aEncoding The encoding to be used for the return value.

Returns:: The alternate name of the field, empty if the field does not have an alternate name. If flag SignDocDocument::f_keep_escape_sequences is set, the string may contain escape sequences for selecting natural languages.

See also:: getMappingName(), getName(), setAlternateName()

SignDocColor* de::softpro::doc::SignDocField::getBackgroundColor ( ) const [inline]

Get the background color of the widget.

This function is available for fields of PDF documents only.

Returns:: A pointer to an object describing the background color or NULL if the widget does not have a background color (transparent background). The caller is responsible for destroying the object.

See also:: getEmptyFieldColor(), selectWidget(), setBackgroundColor()

SignDocColor* de::softpro::doc::SignDocField::getBorderColor ( ) const [inline]

Get the border color of the widget.

This function is available for fields of PDF documents only.

The border color is used only if the border width is positive.

Returns:: A pointer to an object describing the border color or NULL if the widget does not have a border color. The caller is responsible for destroying the object.

See also:: getBorderWidth(), selectWidget(), setBorderColor()

BorderStyle de::softpro::doc::SignDocField::getBorderStyle ( ) const [inline]

Get the border style.

This function is available for fields of PDF documents only.

Returns:: The border style, see enum BorderStyle.

See also:: selectWidget(), setBorderStyle()

double de::softpro::doc::SignDocField::getBorderWidth ( ) const [inline]

Get the border width of the widget.

This function is available for fields of PDF documents only.

Returns:: The border width

See also:: getBorderColor(), getBorderStyle(), selectWidget(), setBorderWidth()

double de::softpro::doc::SignDocField::getBottom ( ) const [inline]

Get the bottom coordinate.

The origin is in the bottom left corner of the page, see Coordinate Systems.

Returns:: The bottom coordinate.

See also:: getLeft(), getRight(), getTop(), selectWidget(), setBottom()

ButtonStyle de::softpro::doc::SignDocField::getButtonStyle ( ) const [inline]

Get the button style of a check box or radio button field.

This function is available for fields of PDF documents only.

Returns:: The button style, see enum ButtonStyle (bus_default will never be returned).

See also:: selectWidget(), setButtonStyle()

std::string de::softpro::doc::SignDocField::getButtonValue ( Encoding aEncoding ) const [inline]

Get the button value of a widget of a radio button group or check box.

Usually, different radio buttons (widgets) of a radio button group (field) have different values. The radio button group has a value (returned by getValue()) which is either "Off" or one of those values. The individual buttons (widgets) of a check box field can also have different export values.

Different radio buttons (widgets) of a radio button group (field) can have the same value; in that case, the radio buttons are linked. The individual buttons of a check box field also can have the same value.

Parameters:

[in] aEncoding The encoding to be used for the return value.

Returns:: The button value an empty string (for field types that don't use button values). If flag SignDocDocument::f_keep_escape_sequences is set, the string may contain escape sequences for selecting natural languages.

See also:: getChoiceValue(), getValue(), selectWidget(), setButtonValue()

const char* de::softpro::doc::SignDocField::getButtonValueUTF8 ( ) const [inline]

Get the button value of a widget of a radio button group or check box.

See getButtonValue() for details.

Returns:: The button value an empty string (for field types that don't use button values). This pointer will become invalid when addWidget(), insertWidget(), removeWidget(), or setButtonValue() is called or this object is destroyed.

See also:: getButtonValue(), getChoiceValue(), getValue(), selectWidget(), setButtonValue()

unsigned de::softpro::doc::SignDocField::getCertSeedValueFlags ( ) const [inline]

Get the certificate seed value dictionary flags (/SV/Cert/Ff) of a signature field, see enum CertSeedValueFlag.

The default value is 0.

Returns:: The certificate seed value dictionary flags of the field.

See also:: setCertSeedValueFlags()

bool de::softpro::doc::SignDocField::getCertSeedValueIssuerCertificate	(	int	aIndex,
		std::vector< unsigned char > &	aOutput
	)		const `[inline]`

Get an issuer certificate of the certificate seed value dictionary.

See the PDF Reference for details.

Parameters:

[in]	aIndex	0-based index of the issuer certificate.
[out]	aOutput	The DER-encoded certificate will be stored here.

Returns:: true if successful, false if aIndex is out of range.

See also:: addCertSeedValueIssuerCertificate(), clearCertSeedValueIssuerCertificates(), getCertSeedValueIssuerCertificateCount(), getCertSeedValueIssuerCertificateUTF8(), removeCertSeedValueIssuerCertificate(), setCertSeedValueIssuerCertificate()

int de::softpro::doc::SignDocField::getCertSeedValueIssuerCertificateCount ( ) const [inline]

Get the number of issuer certificates in the certificate seed value dictionary.

See the PDF Reference for details.

Returns:: The number of issuer certificates.

See also:: addCertSeedValueIssuerCertificate(), clearCertSeedValueIssuerCertificates(), getCertSeedValueIssuerCertificate(), getCertSeedValueIssuerCertificateUTF8(), removeCertSeedValueIssuerCertificate()

std::string de::softpro::doc::SignDocField::getCertSeedValuePolicy	(	Encoding	aEncoding,
		int	aIndex
	)		const `[inline]`

Get a policy OID from the certificate seed value dictionary.

This function throws std::runtime_error if the value cannot be represented using the specified encoding.

See the PDF Reference for details.

Note:: OIDs should be ASCII strings.

Parameters:

[in]	aEncoding	The encoding to be used for the return value.
[in]	aIndex	0-based index of the policy OID.

Returns:: The selected policy OID or an empty string if the index is out of range.

See also:: addCertSeedValuePolicy(), clearCertSeedValuePolicies(), getCertSeedValuePolicyCount(), getCertSeedValuePolicyUTF8(), removeCertSeedValuePolicy(), setCertSeedValuePolicy()

int de::softpro::doc::SignDocField::getCertSeedValuePolicyCount ( ) const [inline]

Get the number of policy OIDs in the certificate seed value dictionary.

See the PDF Reference for details.

Returns:: The number of policy OIDs.

See also:: addCertSeedValuePolicy(), clearCertSeedValuePolicies(), getCertSeedValuePolicy(), getCertSeedValuePolicyUTF8(), removeCertSeedValuePolicy()

const char* de::softpro::doc::SignDocField::getCertSeedValuePolicyUTF8 ( int aIndex ) const [inline]

Get a policy OID from the certificate seed value dictionary.

See the PDF Reference for details.

Note:: OIDs should be ASCII strings.

Parameters:

[in] aIndex 0-based index of the policy OID.

Returns:: The selected policy OID or an empty string if the index is out of range. This pointer will become invalid when addCertSeedValuePolicy(), clearCertSeedValuePolicies(), removeCertSeedValuePolicy(), or setCertSeedValuePolicy() is called or this object is destroyed.

See also:: addCertSeedValuePolicy(), clearCertSeedValuePolicies(), getCertSeedValuePolicyCount(), getCertSeedValuePolicyUTF8(), setCertSeedValuePolicy()

bool de::softpro::doc::SignDocField::getCertSeedValueSubjectCertificate	(	int	aIndex,
		std::vector< unsigned char > &	aOutput
	)		const `[inline]`

Get a subject certificate of the certificate seed value dictionary.

See the PDF Reference for details.

Parameters:

[in]	aIndex	0-based index of the subject certificate.
[out]	aOutput	The DER-encoded certificate will be stored here.

Returns:: true if successful, false if aIndex is out of range.

See also:: addCertSeedValueSubjectCertificate(), clearCertSeedValueSubjectCertificates(), getCertSeedValueSubjectCertificateCount(), getCertSeedValueSubjectCertificateUTF8(), removeCertSeedValueSubjectCertificate(), setCertSeedValueSubjectCertificate()

int de::softpro::doc::SignDocField::getCertSeedValueSubjectCertificateCount ( ) const [inline]

Get the number of subject certificates in the certificate seed value dictionary.

See the PDF Reference for details.

Returns:: The number of subject certificates.

See also:: addCertSeedValueSubjectCertificate(), clearCertSeedValueSubjectCertificates(), getCertSeedValueSubjectCertificate(), getCertSeedValueSubjectCertificateUTF8(), removeCertSeedValueSubjectCertificate()

std::string de::softpro::doc::SignDocField::getCertSeedValueSubjectDN	(	Encoding	aEncoding,
		int	aIndex
	)		const `[inline]`

Get a subject distinguished name from the certificate seed value dictionary.

See the PDF Reference for details.

This function throws std::runtime_error if the name cannot be represented using the specified encoding.

Note:: RFC 4514 requires UTF-8 encoding.

Parameters:

[in]	aEncoding	The encoding to be used for the return value.
[in]	aIndex	0-based index of the subject distinguished name.

Returns:: The selected subject distinguished name (formatted according to RFC 4514) or an empty string if the index is out of range.

See also:: addCertSeedValueSubjectDN(), clearCertSeedValueSubjectDNs(), getCertSeedValueSubjectDNCount(), getCertSeedValueSubjectDNUTF8(), removeCertSeedValueSubjectDN(), setCertSeedValueSubjectDN()

int de::softpro::doc::SignDocField::getCertSeedValueSubjectDNCount ( ) const [inline]

Get the number of subject distinguished names in the certificate seed value dictionary.

See the PDF Reference for details.

Returns:: The number of subject distinguished names in the certificate seed value dictionary.

See also:: addCertSeedValueSubjectDN(), clearCertSeedValueSubjectDNs(), getCertSeedValueSubjectDN(), getCertSeedValueSubjectDNUTF8(), removeCertSeedValueSubjectDN()

const char* de::softpro::doc::SignDocField::getCertSeedValueSubjectDNUTF8 ( int aIndex ) const [inline]

Get a subject distinguished name from the certificate seed value dictionary.

See the PDF Reference for details.

Note:: RFC 4514 requires UTF-8 encoding.

Parameters:

[in] aIndex 0-based index of the subject distinguished name.

Returns:: The selected subject distinguished name (formatted according to RFC 4514) or an empty string if the index is out of range. This pointer will become invalid when addCertSeedValueSubjectDN(), clearCertSeedValueSubjectDNs(), removeCertSeedValueSubjectDN(), or setCertSeedValueSubjectDN() is called or this object is destroyed.

See also:: addCertSeedValueSubjectDN(), clearCertSeedValueSubjectDNs(), getCertSeedValueSubjectDNCount(), getCertSeedValueSubjectDNUTF8(), setCertSeedValueSubjectDN()

int de::softpro::doc::SignDocField::getChoiceCount ( ) const [inline]

Get the number of available choices for a list box or combo box.

List boxes and combo boxes can have multiple possible choices. For other field types, this function returns 0.

Returns:: The number of available choices or 0 if not supported for the type of this field.

See also:: getButtonValue(), getChoiceExport(), getChoiceValue(), getValueCount()

std::string de::softpro::doc::SignDocField::getChoiceExport	(	Encoding	aEncoding,
		int	aIndex
	)		const `[inline]`

Get the export value for an available choice of a list box or combo box.

List boxes and combo boxes can have multiple possible choices. Each choice has a value (which will be displayed) and an export value (which is used for exporting the value of the field). Usually, both values are identical. This function returns one export value, use getChoiceValue() to get the associated choice value.

This function throws std::runtime_error if the value cannot be represented using the specified encoding.

Note:: getValue() and setValue() use the export value.

Parameters:

[in]	aEncoding	The encoding to be used for the return value.
[in]	aIndex	0-based index of the export value.

Returns:: The selected export value of the field or an empty string if the index is out of range. If flag SignDocDocument::f_keep_escape_sequences is set, the string may contain escape sequences for selecting natural languages.

See also:: addChoice(), clearChoices(), getChoiceCount(), getChoiceExportUTF8(), getChoiceValue(), getButtonValue(), removeChoice(), setChoice()

const char* de::softpro::doc::SignDocField::getChoiceExportUTF8 ( int aIndex ) const [inline]

Get the export value for an available choice of a list box or combo box.

List boxes and combo boxes can have multiple possible choices. Each choice has a value (which will be displayed) and an export value (which is used for exporting the value of the field). Usually, both values are identical. This function returns one export value, use getChoiceValue() to get the associated choice value.

Note:: getValue() and setValue() use the export value.

Parameters:

[in] aIndex 0-based index of the choice value.

Returns:: The selected export value of the field or an empty string if the index is out of range. This pointer will become invalid when addChoice(), clearChoices(), removeChoice(), or setChoice() is called or this object is destroyed. If flag SignDocDocument::f_keep_escape_sequences is set, the string may contain escape sequences for selecting natural languages.

See also:: addChoice(), clearChoices(), getChoiceCount(), getChoiceExport(), getChoiceValueUTF8(), getButtonValueUTF8(), setChoice()

std::string de::softpro::doc::SignDocField::getChoiceValue	(	Encoding	aEncoding,
		int	aIndex
	)		const `[inline]`

Get an available choice of a list box or combo box.

List boxes and combo boxes can have multiple possible choices. Each choice has a value (which will be displayed) and an export value (which is used for exporting the value of the field). Usually, both values are identical. This function returns one choice value, use getChoiceExport() to get the associated export value.

This function throws std::runtime_error if the value cannot be represented using the specified encoding.

Note:: getValue() and setValue() use the export value.

Parameters:

[in]	aEncoding	The encoding to be used for the return value.
[in]	aIndex	0-based index of the choice value.

Returns:: The selected choice value of the field or an empty string if the index is out of range. If flag SignDocDocument::f_keep_escape_sequences is set, the string may contain escape sequences for selecting natural languages.

See also:: addChoice(), clearChoices(), getChoiceExport(), getChoiceValueUTF8(), getChoiceCount(), getButtonValue(), removeChoice(), setChoice()

const char* de::softpro::doc::SignDocField::getChoiceValueUTF8 ( int aIndex ) const [inline]

Get an available choice of a list box or combo box.

List boxes and combo boxes can have multiple possible choices. Each choice has a value (which will be displayed) and an export value (which is used for exporting the value of the field). Usually, both values are identical. This function returns one choice value, use getChoiceExportUTF8() to get the associated export value.

Note:: getValue() and setValue() use the export value.

Parameters:

[in] aIndex 0-based index of the choice value.

Returns:: The selected choice value of the field or an empty string if the index is out of range. This pointer will become invalid when addChoice(), clearChoices(), removeChoice(), or setChoice() is called or this object is destroyed. If flag SignDocDocument::f_keep_escape_sequences is set, the string may contain escape sequences for selecting natural languages.

See also:: addChoice(), clearChoices(), getChoiceCount(), getChoiceExportUTF8(), getChoiceValue(), getButtonValueUTF8(), setChoice()

int de::softpro::doc::SignDocField::getDocMDP ( ) const [inline]

Get the DocMDP P value of a certification signature.

The DocMDP P value specifies what modifications to the document are allowed by the certification signature.

This function does not verify the certification signature.

Returns:: -1 if this field is not a certification signature, 1 if no modifications are allowed, 2 if only filling in forms, instantiating page templates, and signing are permitted, 3 if only filling in forms, instantiating page templates, signing, creating annotations, deleting annotations, and modifying annotations are permitted. For TIFF documents, this function always returns -1.

See also:: getLockMDP(), getSignatureType(), SignDocDocument::getDocMDP(), SignDocDocument::setShootInFoot(), SignDocVerificationResult::getDocMDP()

SignDocColor* de::softpro::doc::SignDocField::getEmptyFieldColor ( ) const [inline]

Get the color used for empty signature field in TIFF document.

The default value is white.

Returns:: A pointer to a new SignDocColor object describing the color used for empty signature fields in a TIFF document. The caller is responsible for destroying the object. The return value is NULL for other types of documents.

See also:: getBackgroundColor(), setEmptyFieldColor()

int de::softpro::doc::SignDocField::getFlags ( ) const [inline]

Get the flags of the field, see enum Flag.

The default value is 0 (f_Radio and f_Pushbutton will be computed from the field type).

Do not set f_ReadOnly yourself to lock a field before or after signing. Instead, use setLockType() when adding the signature field.

Returns:: The flags of the field.

See also:: setFlags()

SIGNDOC_Field* de::softpro::doc::SignDocField::getImpl ( ) [inline]

Internal function.

const SIGNDOC_Field* de::softpro::doc::SignDocField::getImpl ( ) const [inline]

Internal function.

Justification de::softpro::doc::SignDocField::getJustification ( ) const [inline]

Get the justification of the widget.

The default value is j_none.

Returns:: The justification of the widget for text fields and list boxes, j_none for other fields.

See also:: selectWidget(), setJustification()

double de::softpro::doc::SignDocField::getLeft ( ) const [inline]

Get the left coordinate.

The origin is in the bottom left corner of the page, see Coordinate Systems.

Returns:: The left coordinate.

See also:: getBottom(), getRight(), getTop(), selectWidget(), setLeft()

std::string de::softpro::doc::SignDocField::getLockField	(	Encoding	aEncoding,
		int	aIndex
	)		const `[inline]`

Get the name of a lock field.

This function throws std::runtime_error if the name cannot be represented using the specified encoding.

Parameters:

[in]	aEncoding	The encoding to be used for the return value.
[in]	aIndex	0-based index of the lock field.

Returns:: The name of the selected lock field or an empty string if the index is out of range. If flag SignDocDocument::f_keep_escape_sequences is set, the string may contain escape sequences for selecting natural languages.

See also:: addLockField(), clearLockFields(), getLockFieldCount(), getLockFieldUTF8(), removeLockField(), setLockField()

int de::softpro::doc::SignDocField::getLockFieldCount ( ) const [inline]

Get the number of field names for lt_include and lt_exclude.

Returns:: The number of field names.

See also:: addLockField(), clearLockFields(), getLockField(), getLockFieldUTF8(), removeLockField()

const char* de::softpro::doc::SignDocField::getLockFieldUTF8 ( int aIndex ) const [inline]

Get the name of a lock field.

Parameters:

[in] aIndex 0-based index of the lock field.

Returns:: The name of the selected lock field or an empty string if the index is out of range. This pointer will become invalid when addLockField(), clearLockFields(), removeLockField(), or setLockField() is called or this object is destroyed. If flag SignDocDocument::f_keep_escape_sequences is set, the string may contain escape sequences for selecting natural languages.

See also:: addLockField(), clearLockFields(), getLockFieldCount(), getLockFieldUTF8(), setLockField()

int de::softpro::doc::SignDocField::getLockMDP ( ) const [inline]

Get the lock MDP value.

Returns:: The lock MDP value: -1 if there is no lock MDP value, 1 if no modifications are allowed, 2 if only filling in forms, instantiating page templates, and signing are permitted, 3 if only filling in forms, instantiating page templates, signing, creating annotations, deleting annotations, and modifying annotations are permitted.

See also:: getDocMDP(), setLockMDP()

LockType de::softpro::doc::SignDocField::getLockType ( ) const [inline]

Get the lock type.

The lock type defines the fields to be locked when signing this signature field.

Returns:: The lock type.

See also:: getLockField(), setLockType()

std::string de::softpro::doc::SignDocField::getMappingName ( Encoding aEncoding ) const [inline]

Get the mapping name of the field.

The mapping name (if present) should be used for exporting field data. Currently, only PDF documents support mapping field names.

This function throws std::runtime_error if the name cannot be represented using the specified encoding.

Parameters:

[in] aEncoding The encoding to be used for the return value.

Returns:: The mapping name of the field, empty if the field does not have an mapping name. If flag SignDocDocument::f_keep_escape_sequences is set, the string may contain escape sequences for selecting natural languages.

See also:: getAlternateName(), getName(), setMappingName()

int de::softpro::doc::SignDocField::getMaxLen ( ) const [inline]

Get maximum length of text field.

The default value is -1.

Returns:: The maximum length of text fields or -1 if the field is not a text field or if the text field does not have a maximum length.

See also:: setMaxLen()

std::string de::softpro::doc::SignDocField::getName ( Encoding aEncoding ) const [inline]

Get the name of the field.

This function throws std::runtime_error if the name cannot be represented using the specified encoding.

Parameters:

[in] aEncoding The encoding to be used for the return value.

Returns:: The name of the field. If flag SignDocDocument::f_keep_escape_sequences is set, the string may contain escape sequences for selecting natural languages.

See also:: getAlternateName(), getMappingName(), getNameUTF8(), setName()

const char* de::softpro::doc::SignDocField::getNameUTF8 ( ) const [inline]

Get the name of the field as UTF-8-encoded C string.

Returns:: The name of the field. This pointer will become invalid when setName() is called or this object is destroyed. If flag SignDocDocument::f_keep_escape_sequences is set, the string may contain escape sequences for selecting natural languages.

int de::softpro::doc::SignDocField::getPage ( ) const [inline]

Get the page number.

This function returns the index of the page on which this field occurs (1 for the first page), or 0 if the page number is unknown.

Returns:: The 1-based page number or 0 if the page number is unknown.

See also:: selectWidget(), setPage()

double de::softpro::doc::SignDocField::getRight ( ) const [inline]

Get the right coordinate.

The origin is in the bottom left corner of the page, see Coordinate Systems. If coordinates are given in pixels (this is true for TIFF documents), this coordinate is exclusive.

Returns:: The right coordinate.

See also:: getBottom(), getLeft(), getTop(), selectWidget(), setRight()

int de::softpro::doc::SignDocField::getRotation ( ) const [inline]

Get the rotation of the widget contents.

The rotation is specified in degrees (counter-clockwise). The default value is 0.

For instance, if the rotation is 270, left-to right text will display top down.

Returns:: The rotation of the widget: 0, 90, 180, or 270.

See also:: selectWidget(), setJustification()

bool de::softpro::doc::SignDocField::getSeedValueAddRevInfo ( ) const [inline]

Get the AddRevInfo flag from the signature field seed value dictionary.

If the AddRevInfo flag is set, revocation must be checked at signing time and revocation data must be included in the signature.

Returns:: true if the AddRevInfo flag is set and the Ff entry specifies that AddRevInfo is a mandatory constraint. false otherwise.

See also:: setSeedValueAddRevInfo()

std::string de::softpro::doc::SignDocField::getSeedValueDigestMethod	(	Encoding	aEncoding,
		int	aIndex
	)		const `[inline]`

Get a DigestMethod value from the seed value dictionary.

This function throws std::runtime_error if the value cannot be represented using the specified encoding.

DigestMethod values in the seed value dictionary restrict the hash algorithms available for signing with RSA.

Note that DigestMethod values are different from the message digest algorithms returned by SignDocVerificationResult::getDigestAlgorithm():

DigestMethod	getDigestAlgorithm()	DetachedHashAlgorithm
n/a	"MD5"	n/a
"RIPEMD160"	"RIPEMD-160"	SignDocSignatureParameters::dha_ripemd160
"SHA1"	"SHA-1"	SignDocSignatureParameters::dha_sha1
-	"SHA-224"	SignDocSignatureParameters::dha_sha224
"SHA256"	"SHA-256"	SignDocSignatureParameters::dha_sha256
"SHA384"	"SHA-384"	SignDocSignatureParameters::dha_sha384
"SHA512"	"SHA-512"	SignDocSignatureParameters::dha_sha512

Parameters:

[in]	aEncoding	The encoding to be used for the return value.
[in]	aIndex	0-based index of the DigestMethod value.

Returns:: The selected DigestMethod value or an empty string if the index is out of range.

See also:: addSeedValueDigestMethod(), clearSeedValueDigestMethods(), getSeedValueDigestMethodCount(), getSeedValueDigestMethodUTF8(), removeSeedValueDigestMethod(), setSeedValueDigestMethod()

int de::softpro::doc::SignDocField::getSeedValueDigestMethodCount ( ) const [inline]

Get the number of DigestMethod values in the seed value dictionary.

See getSeedValueDigestMethod() for details.

Returns:: The number of DigestMethod values.

See also:: addSeedValueDigestMethod(), clearSeedValueDigestMethods(), getSeedValueDigestMethod(), getSeedValueDigestMethodRequired(), getSeedValueDigestMethodUTF8(), removeSeedValueDigestMethod()

bool de::softpro::doc::SignDocField::getSeedValueDigestMethodRequired ( ) const [inline]

This function gets a flag from the signature field seed value dictionary that indicates whether the DigestMethod values are a required constraint or not.

If this function returns true, a signing method corresponding to one of the DigestMethod values returned by getSeedValueDigestMethod() must be used for signing.

Returns:: true iff one of the DigestMethod values returned by getSeedValueDigestMethod() must be used.

See also:: getSeedValueDigestMethodCount(), getSeedValueDigestMethod(), setSeedValueDigestMethodRequired()

const char* de::softpro::doc::SignDocField::getSeedValueDigestMethodUTF8 ( int aIndex ) const [inline]

Get a DigestMethod value from the seed value dictionary.

See getSeedValueDigestMethod() for details.

Parameters:

[in] aIndex 0-based index of the DigestMethod value.

Returns:: The selected DigestMethod value or an empty string if the index is out of range. This pointer will become invalid when addSeedValueDigestMethod(), clearSeedValueDigestMethods(), removeSeedValueDigestMethod(), or setSeedValueDigestMethod() is called or this object is destroyed.

See also:: addSeedValueDigestMethod(), clearSeedValueDigestMethods(), getSeedValueDigestMethodCount(), getSeedValueDigestMethodUTF8(), setSeedValueDigestMethod()

std::string de::softpro::doc::SignDocField::getSeedValueFilter ( Encoding aEncoding ) const [inline]

Get Filter entry (signature handler) from the signature field seed value dictionary.

This function throws std::runtime_error if the value cannot be represented using the specified encoding.

Note:: The Filter entry should be an ASCII string.

Parameters:

[in] aEncoding The encoding to be used for the return value.

Returns:: The Filter entry (signature handler) or an empty string if the signature field seed value dictionary does not have a Filter entry.

See also:: getSeedValueFilterRequired(), setSeedValueFilter()

bool de::softpro::doc::SignDocField::getSeedValueFilterRequired ( ) const [inline]

This function gets a flag from the signature field seed value dictionary that indicates whether the Filter entry (signature handler) is a required constraint or not.

If this function returns true, the signature handler returned by getSeedValueFilter() must be used for signing.

Note:: Adobe Reader seems to ignore this flag.

Returns:: true iff the signature handler returned by getSeedValueFilter() must be used.

See also:: getSeedValueFilter()

int de::softpro::doc::SignDocField::getSeedValueMDP ( ) const [inline]

Get the MDP value from the signature field seed value dictionary.

Returns:

-1 if the MDP value is not set, 0 for an approval signature, 1 through 3 for a certification signature:

1 no changes to the document shall be permitted
2 only filling in forms, instantiating page templates, and signing shall be permitted
3 only filling in forms, instantiating page templates, signing, creating annotations, deleting annotations, and modifying annotations shall be permitted.

See also:: setSeedValueMDP()

std::string de::softpro::doc::SignDocField::getSeedValueSubFilter	(	Encoding	aEncoding,
		int	aIndex
	)		const `[inline]`

Get a SubFilter value from the seed value dictionary.

This function throws std::runtime_error if the value cannot be represented using the specified encoding.

SubFilter values in the seed value dictionary restrict the signing methods available for signing. These values are currently defined:

"adbe.x509.rsa_sha1" (SignDocSignatureParameters::m_digsig_pkcs1)
"adbe.pkcs7.sha1" (SignDocSignatureParameters::m_digsig_pkcs7_sha1)
"adbe.pkcs7.detached" (SignDocSignatureParameters::m_digsig_pkcs7_detached)
"ETSI.CAdES.detached" (SignDocSignatureParameters::m_digsig_cades_detached)

Parameters:

[in]	aEncoding	The encoding to be used for the return value.
[in]	aIndex	0-based index of the SubFilter value.

Returns:: The selected SubFilter value or an empty string if the index is out of range.

See also:: addSeedValueSubFilter(), clearSeedValueSubFilters(), getSeedValueSubFilterCount(), getSeedValueSubFilterUTF8(), removeSeedValueSubFilter(), setSeedValueSubFilter()

int de::softpro::doc::SignDocField::getSeedValueSubFilterCount ( ) const [inline]

Get the number of SubFilter values in the seed value dictionary.

See getSeedValueSubFilter() for details.

Returns:: The number of SubFilter values.

See also:: addSeedValueSubFilter(), clearSeedValueSubFilters(), getSeedValueSubFilter(), getSeedValueSubFilterRequired(), getSeedValueSubFilterUTF8(), removeSeedValueSubFilter()

bool de::softpro::doc::SignDocField::getSeedValueSubFilterRequired ( ) const [inline]

This function gets a flag from the signature field seed value dictionary that indicates whether the SubFilter values are a required constraint or not.

If this function returns true, a signing method corresponding to one of the SubFilter values returned by getSeedValueSubFilter() must be used for signing.

Returns:: true iff one of the SubFilter values returned by getSeedValueSubFilter() must be used.

See also:: getSeedValueSubFilterCount(), getSeedValueSubFilter(), setSeedValueSubFilterRequired()

const char* de::softpro::doc::SignDocField::getSeedValueSubFilterUTF8 ( int aIndex ) const [inline]

Get a SubFilter value from the seed value dictionary.

See getSeedValueSubFilter() for details.

Parameters:

[in] aIndex 0-based index of the SubFilter value.

Returns:: The selected SubFilter value or an empty string if the index is out of range. This pointer will become invalid when addSeedValueSubFilter(), clearSeedValueSubFilters(), removeSeedValueSubFilter(), or setSeedValueSubFilter() is called or this object is destroyed.

See also:: addSeedValueSubFilter(), clearSeedValueSubFilters(), getSeedValueSubFilterCount(), getSeedValueSubFilterUTF8(), setSeedValueSubFilter()

bool de::softpro::doc::SignDocField::getSeedValueTimeStampRequired ( ) const [inline]

This function gets a flag from the signature field seed value dictionary that indicates whether a time stamp is required or not for the signature.

If this function returns true, the URL returned by getSeedValueTimeStampServerURL() will be used to add a time stamp to the signature when signing.

Returns:: false if a time stamp is not required, true if a time stamp is required.

See also:: getSeedValueTimeStampServerURL()

std::string de::softpro::doc::SignDocField::getSeedValueTimeStampServerURL ( Encoding aEncoding ) const [inline]

Get the URL of the RFC 3161 time-stamp server from the signature field seed value dictionary.

This function throws std::runtime_error if the value cannot be represented using the specified encoding.

Note:: The URL should be an ASCII string.

Parameters:

[in] aEncoding The encoding to be used for the return value.

Returns:: The URL of the time-stamp server or an empty string if no time-stamp server is defined.

See also:: getSeedValueTimeStampRequired(), setSeedValueTimeStamp()

SignatureType de::softpro::doc::SignDocField::getSignatureType ( ) const [inline]

Get the signature type of a signature field.

For TIFF documents, only approval signatures are available.

For st_certification, you should display "certified by ..." rather than "signed by ...".

Returns:: The signature type.

See also:: getDocMDP(), isSigned()

bool de::softpro::doc::SignDocField::getTextFieldAttributes ( SignDocTextFieldAttributes & aOutput ) const [inline]

Get the text field attributes of the widget.

This function returns false if the field uses the document's default font name for fields.

Text fields, signature fields, list boxes, and combo boxes can have text field attributes.

Parameters:

[in,out] aOutput This object will be updated.

Returns:: true iff successful.

See also:: selectWidget(), setTextFieldAttributes(), SignDocDocument::getTextFieldAttributes()

double de::softpro::doc::SignDocField::getTop ( ) const [inline]

Get the top coordinate.

The origin is in the bottom left corner of the page, see Coordinate Systems. If coordinates are given in pixels (this is true for TIFF documents), this coordinate is exclusive.

Returns:: The top coordinate.

See also:: getBottom(), getLeft(), getRight(), selectWidget(), setTop()

int de::softpro::doc::SignDocField::getTopIndex ( ) const [inline]

Get the index of the choice to be displayed in the first line of a list box.

The default value is 0.

Returns:: The index of the choice to be displayed in the first line of a list box or 0 for other field types.

See also:: getChoiceValue(), setTopIndex()

Type de::softpro::doc::SignDocField::getType ( ) const [inline]

Get the type of the field.

The default value is t_unknown.

Returns:: The type of the field.

See also:: setType()

std::string de::softpro::doc::SignDocField::getValue	(	Encoding	aEncoding,
		int	aIndex
	)		const `[inline]`

Get a value of the field.

Pushbutton fields and signature fields don't have a value, list boxes can have multiple values selected if f_MultiSelect is set.

Hard line breaks for multiline text fields (ie, text fields with flag f_MultiLine set) are encoded as "\r", "\n", or "\r\n".

This function throws std::runtime_error if the value cannot be represented using the specified encoding.

Parameters:

[in]	aEncoding	The encoding to be used for the return value.
[in]	aIndex	0-based index of the value.

Returns:: The selected value of the field or an empty string if the index is out of range. If flag SignDocDocument::f_keep_escape_sequences is set, the string may contain escape sequences for selecting natural languages.

See also:: addValue(), clearValues(), getChoiceExport(), getChoiceValue(), getValueCount(), getValueIndex(), getValueUTF8(), removeValue(), setValue()

int de::softpro::doc::SignDocField::getValueCount ( ) const [inline]

Get the number of values of the field.

Pushbutton fields and signature fields don't have a value, list boxes can have multiple values selected if f_MultiSelect is set.

Returns:: The number of values.

See also:: getChoiceCount(), getValue()

int de::softpro::doc::SignDocField::getValueIndex ( ) const [inline]

Get the current value index.

Radio button groups and check box fields can have multiple widgets having the same button value. For check box fields and radio buttons without f_RadiosInUnison set, specifying the selected button by value string is not possible in that case. A 0-based value index can be used to find out which button is selected or to select a button.

Radio button groups and check box fields need not use a value index; in fact, they usually don't.

SignDocDocument::addField() and SignDocDocument::setField() update the value index if the value of a radio button group or check box field is selected by string (ie, setValue()) and the field has ambiguous button names.

The "Off" value never has a value index.

Note:: addValue(), clearValues(), and setValue() make the value index unset (ie, getValueIndex() will return -1).

Returns:: the 0-based value index or -1 if the value index is not set.

See also:: clickButton(), getValue(), setValueIndex()

const char* de::softpro::doc::SignDocField::getValueUTF8 ( int aIndex ) const [inline]

Get a value of the field.

Pushbutton fields and signature fields don't have a value, list boxes can have multiple values selected if f_MultiSelect is set.

Hard line breaks for multiline text fields (ie, text fields with flag f_MultiLine set) are encoded as "\r", "\n", or "\r\n".

Parameters:

[in] aIndex 0-based index of the value.

Returns:: The selected value of the field or an empty string if the index is out of range. This pointer will become invalid when addValue(), clearValues(), removeValue(), or setValue() is called or this object is destroyed.

See also:: addValue(), clearValues(), getValue(), getValueCount(), getValueIndex(), setValue()

int de::softpro::doc::SignDocField::getWidget ( ) const [inline]

Get the index of the currently selected widget.

Initially, the first widget is selected (ie, this function returns 0). However, there is an exception to this rule: SignDocField objects created by SignDocDocument::getFieldsOfPage() can have a different widget selected initially for PDF documents.

Returns:: The 0-based index of the currently selected widget.

See also:: selectWidget()

int de::softpro::doc::SignDocField::getWidgetCount ( ) const [inline]

Get the number of widgets.

Signature fields always have exactly one widget. Radio button fields (radio button groups) usually have one widget per button (but can have more widgets than buttons by having multiple widgets for some or all buttons).

Returns:: The number of widgets for this field.

int de::softpro::doc::SignDocField::getWidgetFlags ( ) const [inline]

Get the annotation flags of the widget, see enum WidgetFlag.

The default value is wf_Print. The annotation flags are used for PDF documents only. Currently, the semantics of the annotation flags are ignored by this software (ie, the flags are stored in the document, but they don't have any meaning to this software).

Returns:: The annotation flags of the widget.

See also:: selectWidget(), setWidgetFlags()

bool de::softpro::doc::SignDocField::insertWidget ( int aIndex ) [inline]

Add a widget to the field in front of another widget.

The new widget will be inserted at the specified index, ie, the index of the new widget will be aIndex.

After adding a widget, the new widget will be selected. You must set the page number and the coordinates in the new widget before calling SignDocDocument::addField() or SignDocDocument::setField().

Parameters:

[in] aIndex 0-based index of the widget in front of which the new widget shall be inserted. You can pass the current number of widgets as returned by getWidgetCount() to add the new widget to the end as addWidget() does.

Returns:: true iff successful.

See also:: addWidget(), getWidget(), getWidgetCount(), removeWidget(), selectWidget(), setValueIndex

bool de::softpro::doc::SignDocField::isCurrentlyClearable ( ) const [inline]

Check if this signature field is currently clearable.

For some document formats (TIFF), signatures may only be cleared in the reverse order of signing (LIFO). Use this function to find out whether the signature field is currently clearable (as determined by SignDocDocument::getField() or SignDocDocument::getFields(),

Note:: The value returned by this function does not change over the lifetime of this object and therefore may not reflect the current state if signature fields have been signed or cleared since this object was created.

Returns:: true iff this is a signature field that can be cleared now.

See also:: SignDocDocument::getField(), SignDocDocument::getFields()

bool de::softpro::doc::SignDocField::isSigned ( ) const [inline]

Check if this field is a signed signature field.

This function is much more efficient than SignDocDocument::verifySignature() and SignDocDocument::verifySignature2().

Returns:: true if this field is a signed signature field, false if this field is not a signature field or if this field is a signature field that is not signed.

See also:: getSignatureType(), SignDocDocument::verifySignature()

SignDocField& de::softpro::doc::SignDocField::operator= ( const SignDocField & aSource ) [inline]

Assignment operator.

Parameters:

[in] aSource The source object.

bool de::softpro::doc::SignDocField::removeCertSeedValueIssuerCertificate ( int aIndex ) [inline]

Remove an issuer certificate from the certificate seed value dictionary.

See the PDF Reference for details.

Parameters:

[in] aIndex The 0-based index of the issuer certificate to be removed.

Returns:: true if successful, false if aIndex is out of range.

See also:: clearCertSeedValueIssuerCertificates(), getCertSeedValueIssuerCertificate(), getCertSeedValueIssuerCertificateUTF8()

bool de::softpro::doc::SignDocField::removeCertSeedValuePolicy ( int aIndex ) [inline]

Remove a policy OID from the certificate seed value dictionary.

See the PDF Reference for details.

Parameters:

[in] aIndex The 0-based index of the policy OID to be removed.

Returns:: true if successful, false if aIndex is out of range.

See also:: clearCertSeedValuePolicies(), getCertSeedValuePolicy(), getCertSeedValuePolicyUTF8()

bool de::softpro::doc::SignDocField::removeCertSeedValueSubjectCertificate ( int aIndex ) [inline]

Remove a subject certificate from the certificate seed value dictionary.

See the PDF Reference for details.

Parameters:

[in] aIndex The 0-based index of the subject certificate to be removed.

Returns:: true if successful, false if aIndex is out of range.

See also:: clearCertSeedValueSubjectCertificates(), getCertSeedValueSubjectCertificate(), getCertSeedValueSubjectCertificateUTF8()

bool de::softpro::doc::SignDocField::removeCertSeedValueSubjectDN ( int aIndex ) [inline]

Remove a subject distinguished name from the certificate seed value dictionary.

See the PDF Reference for details.

Parameters:

[in] aIndex The 0-based index of the subject distinguished name to be removed.

Returns:: true if successful, false if aIndex is out of range.

See also:: clearCertSeedValueSubjectDNs(), getCertSeedValueSubjectDN(), getCertSeedValueSubjectDNUTF8()

bool de::softpro::doc::SignDocField::removeChoice ( int aIndex ) [inline]

Remove a choice from a list box or combo box.

Parameters:

[in] aIndex The 0-based index of the choice to be removed.

Returns:: true if successful, false if aIndex is out of range.

See also:: addChoice(), clearChoices()

bool de::softpro::doc::SignDocField::removeLockField ( int aIndex ) [inline]

Remove a lock field.

Parameters:

[in] aIndex The 0-based index of the lock field to be removed.

Returns:: true if successful, false if aIndex is out of range.

See also:: clearLockFields(), getLockField(), getLockFieldUTF8()

bool de::softpro::doc::SignDocField::removeSeedValueDigestMethod ( int aIndex ) [inline]

Remove a DigestMethod value from the seed value dictionary.

See getSeedValueDigestMethod() for details.

Parameters:

[in] aIndex The 0-based index of the DigestMethod value to be removed.

Returns:: true if successful, false if aIndex is out of range.

See also:: clearSeedValueDigestMethods(), getSeedValueDigestMethod(), getSeedValueDigestMethodUTF8(), setSeedValueDigestMethodRequired()

bool de::softpro::doc::SignDocField::removeSeedValueSubFilter ( int aIndex ) [inline]

Remove a SubFilter value from the seed value dictionary.

See getSeedValueSubFilter() for details.

Parameters:

[in] aIndex The 0-based index of the SubFilter value to be removed.

Returns:: true if successful, false if aIndex is out of range.

See also:: clearSeedValueSubFilters(), getSeedValueSubFilter(), getSeedValueSubFilterUTF8(), setSeedValueSubFilterRequired()

bool de::softpro::doc::SignDocField::removeValue ( int aIndex ) [inline]

Remove a value from the field.

After calling this function, getValueIndex() will return -1.

Parameters:

[in] aIndex The 0-based index of the value to be removed.

Returns:: true if successful, false if aIndex is out of range.

See also:: clearValues(), getValue(), getValueIndex(), getValueUTF8()

bool de::softpro::doc::SignDocField::removeWidget ( int aIndex ) [inline]

Remove a widget from the field.

This function fails when there is only one widget. That is, a field always has at least one widget.

If the currently selected widget is removed, the following rules apply:

When removing the last widget (the one with index getWidgetCount()-1), the predecessor of the removed widget will be selected.
Otherwise, the index of the selected widget won't change, ie, the successor of the removed widget will be selected.

If the widget to be removed is not selected, the currently selected widget will remain selected.

All widgets having an index greater than aIndex will have their index decremented by one.

Parameters:

[in] aIndex 0-based index of the widget to remove.

Returns:: true iff successful.

See also:: addWidget(), getWidget(), getWidgetCount(), insertWidget(), selectWidget(), setValueIndex

bool de::softpro::doc::SignDocField::selectWidget ( int aIndex ) [inline]

Select a widget.

This function selects the widget to be used by getWidgetFlags(), getPage(), getLeft(), getBottom(), getRight(), getTop(), getButtonValue(), getJustification(), getRotation(), getTextFieldAttributes(), getBackgroundColor(), getBorderColor(), getBorderWidth(), getBorderStyle(), getButtonStyle(), setWidgetFlags(), setPage(), setLeft(), setBottom(), setRight(), setTop(), setButtonValue(), setJustification(), setRotation(), setTextFieldAttributes(), setBackgroundColor(), setBorderColor(), setBorderWidth(), setBorderStyle(), and setButtonStyle().

Parameters:

[in] aIndex 0-based index of the widget.

Returns:: true iff successful.

See also:: clickButton(), getWidgetCount()

void de::softpro::doc::SignDocField::setAlternateName	(	Encoding	aEncoding,
		const std::string &	aName
	)		`[inline]`

Set the alternate name of the field.

The alternate name (if present) should be used for displaying the field name in a user interface. Currently, only PDF documents support alternate field names.

This function throws std::runtime_error if the name is not correctly encoded according to the specified encoding.

Parameters:

[in]	aEncoding	The encoding of aName.
[in]	aName	The alternate name of the field, empty to remove any alternate field name. Use SignDocDocument::withEscapeSequence() to add a language code. See f_require_alternate_field_name for details.

See also:: getAlternateName(), getName(), setMappingName(), setName(), SignDocDocument::withEscapeSequence(), SignDocDocument::f_require_alternate_field_name

void de::softpro::doc::SignDocField::setBackgroundColor ( const SignDocColor * aColor ) [inline]

Set the background color of the widget.

This function is available for fields of PDF documents only.

The initial value is NULL (transparent).

Parameters:

[in] aColor NULL for transparent or a pointer to a SignDocColor object representing the new background color.

See also:: getBackgroundColor(), selectWidget(), setEmptyFieldColor()

void de::softpro::doc::SignDocField::setBorderColor ( const SignDocColor * aColor ) [inline]

Set the border color of the widget.

This function is available for fields of PDF documents only.

The border color is used only if the border width is positive.

For combo boxes, check boxes, and radio buttons, the initial value is black, for other field types, the initial value is transparent. After creation of a SignDocField object, calling setType() will set the border color accordingly. Once setBorderColor() has been called, setType() will no longer affect the border color.

Parameters:

[in] aColor NULL for transparent or a pointer to a SignDocColor object representing the new border color.

See also:: getBorderColor(), selectWidget(), setBorderStyle(), setBorderWidth(), setType()

void de::softpro::doc::SignDocField::setBorderStyle ( BorderStyle aStyle ) [inline]

Set the border style.

This function is available for fields of PDF documents only.

If aStyle is bos_other, SignDocDocument::setField() will keep the current border style and SignDocDocument::addField() will fail.

Parameters:

[in] aStyle The new border style, see enum BorderStyle.

See also:: selectWidget(), getBorderStyle()

void de::softpro::doc::SignDocField::setBorderWidth ( double aWidth ) [inline]

Set the border width of the widget.

This function is available for fields of PDF documents only.

The initial value is 1.

Parameters:

[in] aWidth The new border width.

See also:: getBorderWidth(), selectWidget(), setBorderColor(), setBorderStyle()

void de::softpro::doc::SignDocField::setBottom ( double aBottom ) [inline]

Set the bottom coordinate.

The origin is in the bottom left corner of the page, see Coordinate Systems.

Parameters:

[in] aBottom The bottom coordinate.

See also:: getBottom(), selectWidget(), setLeft(), setRight(), setTop(), SignDocDocument::sff_move

void de::softpro::doc::SignDocField::setButtonStyle ( ButtonStyle aStyle ) [inline]

Set the button style of a check box or radio button field.

This function is available for fields of PDF documents only.

If aStyle is bus_other, SignDocDocument::setField() will keep the current border style and SignDocDocument::addField() will fail.

Parameters:

[in] aStyle The new button style, see enum ButtonStyle.

See also:: getButtonStyle(), selectWidget()

void de::softpro::doc::SignDocField::setButtonValue	(	Encoding	aEncoding,
		const std::string &	aValue
	)		`[inline]`

Set the button value of a widget of a radio button group or a check box.

Usually, different radio buttons (widgets) of a radio button group (field) have different values. The radio button group has a value (returned by getValue()) which is either "Off" or one of those values. The individual buttons (widgets) of a check box field can also have different export values.

Different radio buttons (widgets) of a radio button group (field) can have the same value; in that case, the radio buttons are linked. The individual buttons of a check box field also can have the same value.

SignDocDocument::addField() and SignDocDocument::setField() ignore the value set by this function if the field is neither a radio button group nor a check box field.

Parameters:

[in]	aEncoding	The encoding of aValue.
[in]	aValue	The value to be set. Must not be empty, must not be "Off".

See also:: getButtonValue(), getChoiceValue(), getValue(), selectWidget()

void de::softpro::doc::SignDocField::setCertSeedValueFlags ( unsigned aFlags ) [inline]

Set the certificate seed value dictionary flags (/SV/Cert/Ff) of a signature field, see enum CertSeedValueFlag.

The default value is 0.

Parameters:

[in] aFlags The certificate seed value dicitionary flags of the field.

See also:: getCertSeedValueFlags()

bool de::softpro::doc::SignDocField::setCertSeedValueIssuerCertificate	(	int	aIndex,
		const void *	aPtr,
		size_t	aSize
	)		`[inline]`

Set an issuer certificate in the certificate seed value dictionary.

See the PDF Reference for details.

Parameters:

[in]	aIndex	0-based index of the issuer certificate to be set. If aIndex equals the current number of values, the certificate will be added.
[in]	aPtr	Pointer to the first octet of the DER-encoded certificate.
[in]	aSize	Size in octets of the DER-encoded certificate.

Returns:: true if successful, false if aIndex is out of range.

See also:: clearCertSeedValueIssuerCertificates(), getCertSeedValueIssuerCertificate(), getCertSeedValueIssuerCertificateUTF8()

void de::softpro::doc::SignDocField::setCertSeedValueIssuerCertificate	(	const void *	aPtr,
		size_t	aSize
	)		`[inline]`

Set an issuer certificate in the certificate seed value dictionary.

See the PDF Reference for details.

Calling this function is equivalent to calling clearCertSeedValueIssuerCertificates() and addCertSeedValueIssuerCertificate().

Parameters:

[in]	aPtr	Pointer to the first octet of the DER-encoded certificate.
[in]	aSize	Size in octets of the DER-encoded certificate.

See also:: clearCertSeedValueIssuerCertificates(), getCertSeedValueIssuerCertificate(), getCertSeedValueIssuerCertificateUTF8()

void de::softpro::doc::SignDocField::setCertSeedValuePolicy	(	Encoding	aEncoding,
		const std::string &	aOID
	)		`[inline]`

Set a policy OID in the certificate seed value dictionary.

See the PDF Reference for details.

Calling this function is equivalent to calling clearCertSeedValuePolicies() and addCertSeedValuePolicy(), but the encoding of aOID is checked before modifying this object.

This function throws std::runtime_error if the value is not correctly encoded according to the specified encoding.

Note:: OIDs should be ASCII strings.

Parameters:

[in]	aEncoding	The encoding of aOID.
[in]	aOID	The policy OID.

See also:: clearCertSeedValuePolicies(), getCertSeedValuePolicy(), getCertSeedValuePolicyUTF8()

bool de::softpro::doc::SignDocField::setCertSeedValuePolicy	(	int	aIndex,
		Encoding	aEncoding,
		const std::string &	aOID
	)		`[inline]`

Set a policy OID in the certificate seed value dictionary.

See the PDF Reference for details.

This function throws std::runtime_error if the value is not correctly encoded according to the specified encoding.

Note:: OIDs should be ASCII strings.

Parameters:

[in]	aIndex	The 0-based index of the value to be set. If aIndex equals the current number of values, the value will be added.
[in]	aEncoding	The encoding of aOID.
[in]	aOID	The policy OID.

Returns:: true if successful, false if aIndex is out of range.

See also:: clearCertSeedValuePolicies(), getCertSeedValuePolicy(), getCertSeedValuePolicyUTF8()

bool de::softpro::doc::SignDocField::setCertSeedValueSubjectCertificate	(	int	aIndex,
		const void *	aPtr,
		size_t	aSize
	)		`[inline]`

Set a subject certificate in the certificate seed value dictionary.

See the PDF Reference for details.

Parameters:

[in]	aIndex	0-based index of the subject certificate to be set. If aIndex equals the current number of values, the certificate will be added.
[in]	aPtr	Pointer to the first octet of the DER-encoded certificate.
[in]	aSize	Size in octets of the DER-encoded certificate.

Returns:: true if successful, false if aIndex is out of range.

See also:: clearCertSeedValueSubjectCertificates(), getCertSeedValueSubjectCertificate(), getCertSeedValueSubjectCertificateUTF8()

void de::softpro::doc::SignDocField::setCertSeedValueSubjectCertificate	(	const void *	aPtr,
		size_t	aSize
	)		`[inline]`

Set a subject certificate in the certificate seed value dictionary.

See the PDF Reference for details.

Calling this function is equivalent to calling clearCertSeedValueSubjectCertificates() and addCertSeedValueSubjectCertificate().

Parameters:

[in]	aPtr	Pointer to the first octet of the DER-encoded certificate.
[in]	aSize	Size in octets of the DER-encoded certificate.

See also:: clearCertSeedValueSubjectCertificates(), getCertSeedValueSubjectCertificate(), getCertSeedValueSubjectCertificateUTF8()

bool de::softpro::doc::SignDocField::setCertSeedValueSubjectDN	(	Encoding	aEncoding,
		const std::string &	aName
	)		`[inline]`

Set a subject distinguished name in the certificate seed value dictionary.

See the PDF Reference for details.

Calling this function is equivalent to calling clearCertSeedValueSubjectDNs() and addCertSeedValueSubjectDN(), but the encoding of aName is checked before modifying this object.

This function throws std::runtime_error if the name is not correctly encoded according to the specified encoding.

Note:: RFC 4514 requires UTF-8 encoding.

Parameters:

[in]	aEncoding	The encoding of aName.
[in]	aName	The subject distinguished name formatted according to RFC 4514.

Returns:: true if successful, false if aName cannot be parsed.

See also:: clearCertSeedValueSubjectDNs(), getCertSeedValueSubjectDN(), getCertSeedValueSubjectDNUTF8()

bool de::softpro::doc::SignDocField::setCertSeedValueSubjectDN	(	int	aIndex,
		Encoding	aEncoding,
		const std::string &	aName
	)		`[inline]`

Set a subject distinguished name in the certificate seed value dictionary.

See the PDF Reference for details.

This function throws std::runtime_error if the name is not correctly encoded according to the specified encoding.

Note:: RFC 4514 requires UTF-8 encoding.

Parameters:

[in]	aIndex	The 0-based index of the value to be set. If aIndex equals the current number of values, the value will be added.
[in]	aEncoding	The encoding of aName.
[in]	aName	The subject distinguished name formatted according to RFC 4514.

Returns:: true if successful, false if aIndex is out of range or if aName cannot be parsed.

See also:: clearCertSeedValueSubjectDNs(), getCertSeedValueSubjectDN(), getCertSeedValueSubjectDNUTF8()

bool de::softpro::doc::SignDocField::setChoice	(	int	aIndex,
		Encoding	aEncoding,
		const std::string &	aValue
	)		`[inline]`

Set a choice value of a list box or combo box.

This function uses the choice value as export value.

This function throws std::runtime_error if the value is not correctly encoded according to the specified encoding.

Note:: getValue() and setValue() use the export value.

Parameters:

[in]	aIndex	The 0-based index of the choice to be set. If aIndex equals the current number of choice, the value will be added.
[in]	aEncoding	The encoding of aValue.
[in]	aValue	The choice value and export value to be set. Complex scripts are supported, see Complex Scripts.

Returns:: true if successful, false if aIndex is out of range.

See also:: clearChoices(), getChoiceExport(), getChoiceValue(), setButtonValue()

bool de::softpro::doc::SignDocField::setChoice	(	int	aIndex,
		Encoding	aEncoding,
		const std::string &	aValue,
		const std::string &	aExport
	)		`[inline]`

Set a choice value of a list box or combo box.

This function throws std::runtime_error if the value is not correctly encoded according to the specified encoding.

Note:: getValue() and setValue() use the export value.

Parameters:

[in]	aIndex	The 0-based index of the choice to be set. If aIndex equals the current number of choice, the value will be added.
[in]	aEncoding	The encoding of aValue and aExport.
[in]	aValue	The choice value to be set. Complex scripts are supported, see Complex Scripts.
[in]	aExport	The export value to be set.

Returns:: true if successful, false if aIndex is out of range.

See also:: clearChoices(), getChoiceExport(), getChoiceValue(), setButtonValue()

void de::softpro::doc::SignDocField::setEmptyFieldColor ( const SignDocColor & aColor ) [inline]

Set color used for empty signature field in TIFF document.

The default value is white. For non-TIFF documents, the value set by this function is ignored. The value is also ignored if compatibility with version 1.12 and earlier is requested.

Parameters:

[in] aColor The new color.

See also:: getEmptyFieldColor(), setBackgroundColor(), SignDocDocument::setCompatibility()

void de::softpro::doc::SignDocField::setFlags ( int aFlags ) [inline]

Set the flags of the field, see enum Flag.

The default value is 0 (f_Radio and f_Pushbutton will be computed from the field type).

Parameters:

[in] aFlags The flags of the field.

See also:: getFlags()

void de::softpro::doc::SignDocField::setImpl ( SIGNDOC_Field * aP ) [inline]

Internal function.

void de::softpro::doc::SignDocField::setJustification ( Justification aJustification ) [inline]

Set the justification of the widget.

The default value is j_none.

For text fields and list boxes, the justification must be j_left, j_center, or j_right. For other fields, the justification must be j_none.

Parameters:

[in] aJustification The justification.

See also:: getJustification(), selectWidget()

void de::softpro::doc::SignDocField::setLeft ( double aLeft ) [inline]

Set the left coordinate.

The origin is in the bottom left corner of the page, see Coordinate Systems.

Parameters:

[in] aLeft The left coordinate.

See also:: getLeft(), selectWidget(), setBottom(), setRight(), setTop(), SignDocDocument::sff_move

void de::softpro::doc::SignDocField::setLockField	(	Encoding	aEncoding,
		const std::string &	aName
	)		`[inline]`

Set a lock field.

Calling this function is equivalent to calling clearLockFields() and addLockField(), but the encoding of aName is checked before modifying this object.

This function throws std::runtime_error if the name is not correctly encoded according to the specified encoding.

Parameters:

[in]	aEncoding	The encoding of aName.
[in]	aName	The name of the lock field to be set.

See also:: clearLockFields(), getLockField(), getLockFieldUTF8()

bool de::softpro::doc::SignDocField::setLockField	(	int	aIndex,
		Encoding	aEncoding,
		const std::string &	aName
	)		`[inline]`

Set a lock field.

This function throws std::runtime_error if the name is not correctly encoded according to the specified encoding.

Parameters:

[in]	aIndex	The 0-based index of the value to be set. If aIndex equals the current number of values, the value will be added.
[in]	aEncoding	The encoding of aName.
[in]	aName	The name of the lock field to be set.

Returns:: true if successful, false if aIndex is out of range.

See also:: clearLockFields(), getLockField(), getLockFieldUTF8()

void de::softpro::doc::SignDocField::setLockMDP ( int aMDP ) [inline]

Set the lock MDP value.

Parameters:

[in]

aMDP

The new lock MDP value:

1 no changes to the document shall be permitted
2 only filling in forms, instantiating page templates, and signing shall be permitted
3 only filling in forms, instantiating page templates, signing, creating annotations, deleting annotations, and modifying annotations shall be permitted.

See also:: getDocMDP(), getLockMDP()

void de::softpro::doc::SignDocField::setLockType ( LockType aLockType ) [inline]

Set the lock type.

The lock type defines the fields to be locked when signing this signature field.

Parameters:

[in] aLockType The new lock type.

See also:: addLockField(), getLockType()

void de::softpro::doc::SignDocField::setMappingName	(	Encoding	aEncoding,
		const std::string &	aName
	)		`[inline]`

Set the mapping name of the field.

The mapping name (if present) should be used for exporting field data. Currently, only PDF documents support mapping field names.

This function throws std::runtime_error if the name is not correctly encoded according to the specified encoding.

Parameters:

[in]	aEncoding	The encoding of aName.
[in]	aName	The mapping name of the field, empty to remove any mapping name.

See also:: getMappingName(), getName(), setAlternateName(), setName()

void de::softpro::doc::SignDocField::setMaxLen ( int aMaxLen ) [inline]

Set maximum length of text fields.

Parameters:

[in] aMaxLen The maximum length (in characters) of the text field or -1 for no maximum length.

See also:: getMaxLen()

void de::softpro::doc::SignDocField::setName ( const wchar_t * aName ) [inline]

Set the name of the field.

Different document types impose different restrictions on field names. PDF fields have hierarchical field names with components separated by dots.

SignDocDocument::setField() operates on the field having a fully-qualified name which equals the name set by this function. In consequence, SignDocDocument::setField() cannot change the name of a field.

Parameters:

[in] aName The name of the field.

See also:: getName(), getNameUTF8(), setAlternateName(), setMappingName()

void de::softpro::doc::SignDocField::setName	(	Encoding	aEncoding,
		const std::string &	aName
	)		`[inline]`

Set the name of the field.

Different document types impose different restrictions on field names. PDF fields have hierarchical field names with components separated by dots.

SignDocDocument::setField() operates on the field having a fully-qualified name which equals the name set by this function. In consequence, SignDocDocument::setField() cannot change the name of a field.

This function throws std::runtime_error if the name is not correctly encoded according to the specified encoding.

Parameters:

[in]	aEncoding	The encoding of aName.
[in]	aName	The name of the field.

See also:: getName(), getNameUTF8(), setAlternateName(), setMappingName()

void de::softpro::doc::SignDocField::setPage ( int aPage ) [inline]

Set the page number.

This function sets the index of the page on which this field occurs (1 for the first page).

By calling SignDocDocument::getField(), setPage(), and SignDocDocument::setField(), you can move a field's widget to another page but be careful because the two pages may have different conversion factors, see SignDocDocument::getConversionFactors().

Parameters:

[in] aPage The 1-based page number of the field.

See also:: getPage(), selectWidget()

void de::softpro::doc::SignDocField::setRight ( double aRight ) [inline]

Set the right coordinate.

The origin is in the bottom left corner of the page, see Coordinate Systems. If coordinates are given in pixels (this is true for TIFF documents), this coordinate is exclusive.

Parameters:

[in] aRight The right coordinate.

See also:: getRight(), selectWidget(), setBottom(), setLeft(), setTop(), SignDocDocument::sff_move

void de::softpro::doc::SignDocField::setRotation ( int aRotation ) [inline]

Set the rotation of the widget contents.

The rotation is specified in degrees (counter-clockwise). The default value is 0.

For instance, if the rotation is 270, left-to right text will display top down.

Currently, the rotation must always be 0 for TIFF documents.

Parameters:

[in] aRotation The rotation: 0, 90, 180, or 270.

See also:: getRotation(), selectWidget()

void de::softpro::doc::SignDocField::setSeedValueAddRevInfo ( bool aAddRevInfo ) [inline]

Set the AddRevInfo flag in the signature field seed value dictionary.

This function sets both the AddRevInfo flag and the flag specifying that AddRevInfo is mandatory. (Both flags are set to the same value, that is, you cannot set AddRevInfo as optional constraint.)

If the AddRevInfo flag is set, revocation must be checked at signing time and revocation data must be included in the signature.

Parameters:

[in] aAddRevInfo The new AddRevInfo flag value.

See also:: getSeedValueAddRevInfo()

void de::softpro::doc::SignDocField::setSeedValueDigestMethod	(	Encoding	aEncoding,
		const std::string &	aDigestMethod
	)		`[inline]`

Set a DigestMethod value in the seed value dictionary.

See getSeedValueDigestMethod() for details.

Calling this function is equivalent to calling clearSeedValueDigestMethods() and addSeedValueDigestMethod(), but the encoding of aDigestMethod is checked before modifying this object.

This function throws std::runtime_error if the value is not correctly encoded according to the specified encoding.

Parameters:

[in]	aEncoding	The encoding of aDigestMethod.
[in]	aDigestMethod	The DigestMethod value.

See also:: clearSeedValueDigestMethods(), getSeedValueDigestMethod(), getSeedValueDigestMethodUTF8(), setSeedValueDigestMethodRequired()

bool de::softpro::doc::SignDocField::setSeedValueDigestMethod	(	int	aIndex,
		Encoding	aEncoding,
		const std::string &	aDigestMethod
	)		`[inline]`

Set a DigestMethod value in the seed value dictionary.

See getSeedValueDigestMethod() for details.

This function throws std::runtime_error if the value is not correctly encoded according to the specified encoding.

Parameters:

[in]	aIndex	The 0-based index of the value to be set. If aIndex equals the current number of values, the value will be added.
[in]	aEncoding	The encoding of aDigestMethod.
[in]	aDigestMethod	The DigestMethod value.

Returns:: true if successful, false if aIndex is out of range.

See also:: clearSeedValueDigestMethods(), getSeedValueDigestMethod(), getSeedValueDigestMethodUTF8(), setSeedValueDigestMethodRequired()

void de::softpro::doc::SignDocField::setSeedValueDigestMethodRequired ( bool aRequired ) const [inline]

Set a flag from the signature field seed value dictionary that indicates whether the DigestMethod values are a required constraint or not.

Parameters:

[in] aRequired true if the DigestMethod values are a required constraint, false if the DigestMethod values are an optional constraint. If aRequired is true, there should be at least one DigestMethod value.

See also:: getSeedValueDigestMethod(), getSeedValueDigestMethodRequired()

bool de::softpro::doc::SignDocField::setSeedValueFilter	(	Encoding	aEncoding,
		const std::string &	aFilter,
		bool	aRequired
	)		`[inline]`

Set the Filter entry (signature handler) in the signature field seed value dictionary.

This function throws std::runtime_error if the value is not correctly encoded according to the specified encoding.

Parameters:

[in]	aEncoding	The encoding of aFilter.
[in]	aFilter	The name of the signature handler to be used for signing, e.g., "Adobe.PPKLite". An empty value will cause the Filter entry (constraint) to be removed. This should be an ASCII string.
[in]	aRequired	true if aFilter is a required constraint, false if aFilter is an optional constraint. Adobe Reader seems to ignore this flag.

Returns:: true if successful, false if aFilter is invalid.

See also:: getSeedValueFilter(), getSeedValueFilterRequired()

bool de::softpro::doc::SignDocField::setSeedValueMDP ( int aMDP ) [inline]

Set the MDP value in the signature field seed value dictionary.

Parameters:

[in]

aMDP

The new MDP value:

-1 to remove the MDP value
0 for an approval signature
1 for a certification signature, no changes to the document shall be permitted
2 for a certification signature, only filling in forms, instantiating page templates, and signing shall be permitted
3 for a certification signature, only filling in forms, instantiating page templates, signing, creating annotations, deleting annotations, and modifying annotations shall be permitted.

Returns:: true if successful, false if aMDP is invalid.

See also:: getSeedValueMDP()

void de::softpro::doc::SignDocField::setSeedValueSubFilter	(	Encoding	aEncoding,
		const std::string &	aSubFilter
	)		`[inline]`

Set a SubFilter value in the seed value dictionary.

See getSeedValueSubFilter() for details.

Calling this function is equivalent to calling clearSeedValueSubFilters() and addSeedValueSubFilter(), but the encoding of aSubFilter is checked before modifying this object.

This function throws std::runtime_error if the value is not correctly encoded according to the specified encoding.

Parameters:

[in]	aEncoding	The encoding of aSubFilter.
[in]	aSubFilter	The SubFilter value.

See also:: clearSeedValueSubFilters(), getSeedValueSubFilter(), getSeedValueSubFilterUTF8(), setSeedValueSubFilterRequired()

bool de::softpro::doc::SignDocField::setSeedValueSubFilter	(	int	aIndex,
		Encoding	aEncoding,
		const std::string &	aSubFilter
	)		`[inline]`

Set a SubFilter value in the seed value dictionary.

See getSeedValueSubFilter() for details.

This function throws std::runtime_error if the value is not correctly encoded according to the specified encoding.

Parameters:

[in]	aIndex	The 0-based index of the value to be set. If aIndex equals the current number of values, the value will be added.
[in]	aEncoding	The encoding of aSubFilter.
[in]	aSubFilter	The SubFilter value.

Returns:: true if successful, false if aIndex is out of range.

See also:: clearSeedValueSubFilters(), getSeedValueSubFilter(), getSeedValueSubFilterUTF8(), setSeedValueSubFilterRequired()

void de::softpro::doc::SignDocField::setSeedValueSubFilterRequired ( bool aRequired ) const [inline]

Set a flag from the signature field seed value dictionary that indicates whether the SubFilter values are a required constraint or not.

Parameters:

[in] aRequired true if the SubFilter values are a required constraint, false if the SubFilter values are an optional constraint. If aRequired is true, there should be at least one SubFilter value.

See also:: getSeedValueSubFilter(), getSeedValueSubFilterRequired()

bool de::softpro::doc::SignDocField::setSeedValueTimeStamp	(	Encoding	aEncoding,
		const std::string &	aURL,
		bool	aRequired
	)		`[inline]`

Set the URL of an RFC 3161 time-stamp server in the signature field seed value dictionary.

This function throws std::runtime_error if the value is not correctly encoded according to the specified encoding.

Note:: URLs must be ASCII strings.

Parameters:

[in]	aEncoding	The encoding of aURL.
[in]	aURL	The URL (must be ASCII), empty for no time-stamp server. Must be non-empty if aRequired is true. The scheme must be http or https.
[in]	aRequired	true if a time stamp is required, false if a time stamp is not required.

Returns:: true if successful, false if aURL is invalid.

See also:: getSeedValueTimeStampRequired(), getSeedValueTimeStampServerURL()

bool de::softpro::doc::SignDocField::setTextFieldAttributes ( const SignDocTextFieldAttributes & aInput ) [inline]

Set the text field attributes of the widget.

Font name and font size must be specified. The text color is optional. This function fails if any of the attributes of aInput are invalid.

Text field attributes can be specified for text fields, signature fields, list boxes, and combo boxes.

If SignDocTextFieldAttributes::isSet() returns false for aInput, the text field attributes of the field will be removed by SignDocDocument::setField().

The following rules apply if the field does not have text field attributes:

If the field inherits text field attributes from a ancestor field, those will be used by PDF processing software.
Otherwise, if the document has specifies text field attributes (see SignDocDocument::getTextFieldAttributes()), those will be used by PDF processing software.
Otherwise, the field is not valid.

To avoid having invalid fields, SignDocDocument::addField() and SignDocDocument::setField() will use text field attributes specifying Helvetica as the font and black for the text color if the field does not inherit text field attributes from an ancestor field or from the document.

This function always fails for TIFF documents.

Parameters:

[in] aInput The new default text field attributes.

Returns:: true iff successful.

See also:: getTextFieldAttributes(), selectWidget()

void de::softpro::doc::SignDocField::setTop ( double aTop ) [inline]

Set the top coordinate.

The origin is in the bottom left corner of the page, see Coordinate Systems. If coordinates are given in pixels (this is true for TIFF documents), this coordinate is exclusive.

Parameters:

[in] aTop The top coordinate.

See also:: getTop(), selectWidget(), setBottom(), setLeft(), setRight(), SignDocDocument::sff_move

void de::softpro::doc::SignDocField::setTopIndex ( int aTopIndex ) [inline]

Set the index of the choice to be displayed in the first line of a list box.

This value is ignored for other field types.

Parameters:

[in] aTopIndex The index of the choice to be displayed in the first line of a list box.

See also:: getChoiceValue(), getTopIndex()

void de::softpro::doc::SignDocField::setType ( Type aType ) [inline]

Set the type of the field.

The default value is t_unknown.

Calling this function may affect the border color, see setBorderColor().

Parameters:

[in] aType The type of the field.

See also:: getType(), setBorderColor()

void de::softpro::doc::SignDocField::setValue	(	Encoding	aEncoding,
		const std::string &	aValue
	)		`[inline]`

Set the value of the field.

Pushbutton fields and signature fields don't have a value, list boxes can have multiple values selected if f_MultiSelect is set.

Hard line breaks for multiline text fields (ie, text fields with flag f_MultiLine set) are encoded as "\r", "\n", or "\r\n". The behavior for values containing line breaks is undefined if the f_MultiLine flag is not set.

Calling this function is equivalent to calling clearValues() and addValue(), but the encoding of aValue is checked before modifying this object.

After calling this function, getValueIndex() will return -1.

This function throws std::runtime_error if the value is not correctly encoded according to the specified encoding.

Parameters:

[in]	aEncoding	The encoding of aValue.
[in]	aValue	The value to be set. Complex scripts are supported, see Complex Scripts.

See also:: clearValues(), clickButton(), getValue(), getValueIndex(), getValueUTF8(), setValueIndex()

bool de::softpro::doc::SignDocField::setValue	(	int	aIndex,
		Encoding	aEncoding,
		const std::string &	aValue
	)		`[inline]`

Set a value of the field.

Pushbutton fields and signature fields don't have a value, list boxes can have multiple values selected if f_MultiSelect is set.

Hard line breaks for multiline text fields (ie, text fields with flag f_MultiLine set) are encoded as "\r", "\n", or "\r\n". The behavior for values containing line breaks is undefined if the f_MultiLine flag is not set.

After calling this function, getValueIndex() will return -1.

This function throws std::runtime_error if the value is not correctly encoded according to the specified encoding.

Parameters:

[in]	aIndex	The 0-based index of the value to be set. If aIndex equals the current number of values, the value will be added.
[in]	aEncoding	The encoding of aValue.
[in]	aValue	The value to be set. Complex scripts are supported, see Complex Scripts.

Returns:: true if successful, false if aIndex is out of range.

See also:: clearValues(), clickButton(), getValue(), getValueIndex(), getValueUTF8(), setValueIndex()

void de::softpro::doc::SignDocField::setValueIndex ( int aIndex ) [inline]

Set the value index.

Radio button groups and check box fields can have multiple widgets having the same button value. For check box fields and radio buttons without f_RadiosInUnison set, specifying the selected button by value string is ambiguous in that case. A 0-based value index can be used to find out which button is selected or to select a button.

Radio button groups and check box fields need not use a value index; in fact, they usually don't. However, you can always set a value index for radio button groups and check box fields.

If the value index is non-negative, SignDocDocument::addField() and SignDocDocument::setField() will use the value index instead of the string value set by setValue().

Calling setValueIndex() doesn't affect the return value of getValue() as the value index is used by SignDocDocument::addField() and SignDocDocument::setField() only. However, successful calls to SignDocDocument::addField() and SignDocDocument::setField() will make getValue() return the selected value.

For radio button groups with f_RadiosInUnison set and non-unique button values and for check box fields with non-unique button values, for each button value, the lowest index having that button value is the canonical one. After calling SignDocDocument::addField() or SignDocDocument::setField(), getValueIndex() will return the canonical value index.

Don't forget to update the value index when adding or removing widgets!

SignDocDocument::addField() and SignDocDocument::setField() will fail if the value index is non-negative for fields other than radio button groups and check box fields.

The "Off" value never has a value index.

Note:: addValue(), clearValues(), and setValue() make the value index unset (ie, getValueIndex() will return -1). Therefore, you don't have to call setValueIndex(-1) to make setValue() take effect on SignDocDocument::addField() and SignDocDocument::setField().

Parameters:

[in] aIndex the 0-based value index or -1 to make the value index unset.

See also:: clickButton(), getValue(), getValueIndex(), setValue()

void de::softpro::doc::SignDocField::setWidgetFlags ( int aFlags ) [inline]

Set the annotation flags of the widget, see enum WidgetFlag.

The default value is wf_Print. The annotation flags are used for PDF documents only. Currently, the semantics of the annotation flags are ignored by this software (ie, the flags are stored in the document, but they don't have any meaning to this software).

Parameters:

[in] aFlags The annotation flags of the widget.

See also:: getWidgetFlags(), selectWidget()

void de::softpro::doc::SignDocField::swap ( SignDocField & aOther ) [inline]

Efficiently swap this object with another one.

Parameters:

[in] aOther The other object.

The documentation for this class was generated from the following file:

SignDocSDK-cpp.h

de::softpro::doc::SignDocField Class Reference

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation