Forms

A form is a self-contained description of any arbitrary geometric graphics, text, or raster graphics that are to be imaged multiple times, either on one page or on several pages.

Model for Forms

A form is defined at the structure level via a RESOURCE DEFINITION, and is bound to the value of an INTERNAL RESOURCE IDENTIFIER in a RESOURCE DECLARATION. The appearance of a form is described by a Procedure that executes imaging operators. The FindResource operator is used in content to obtain a form, which is represented in content by a Form Object, and is imaged by providing the Form Object as an operand to the ExecuteForm operator. There is no Form Object type in SPDL; rather the term is used as a convenient term to describe both references to the particular objects of type Dictionary which represent a form and its associated parameters (and are obtained via the FindResource operator) and to the Dictionaries themselves. That is, Form Object will be used both for the DictionaryReference and the Dictionary; which is intended will be clear from context.

The remainder of this clause specifies the contents of Form Dictionaries and the semantics of the ExecuteForm operator.

Form Dictionaries

A form is represented by a Form Object, which is a reference to a Form Dictionary with prescribed contents which fully describes the form to be imaged. The form is defined in its own coordinate system, the form coordinate system, which is defined by concatenating the value bound to the Matrix key in the Form Dictionary with the CurrentTransformation each time the Form Objects's PaintProc (the Procedure in the Form Dictionary that images the form) is executed. The BBox parameter in the Form Dictionary is interpreted in the form coordinate system; the PaintProc is executed in that coordinate system.

The following subclauses describe the contents of a Form Dictionary. In addition to the contents described below, the Form Dictionary can also contain other (constant) information that is required by the PaintProc (see ).

BBox

The mandatory key/value pair <BBox: Vector> is a 4-element Vector of type Number specifying the bounding box of the form in the form coordinate system. This bounding box is used to clip the form. The four elements of the Vector specify the lower left x, lower left y, upper right x, and upper right y coordinates of the bounding box:

  • [ llx lly urx ury]

    Matrix

    The mandatory key/value pair <Matrix: Transformation> is the Transformation to be concatenated with the CurrentTransformation to produce the Transformation that defines the form coordinate system.

    PaintProc

    The mandatory key/value pair <PaintProc: Procedure> specifies the Procedure used to paint the form. PaintProc takes one operand

  • <FormDict: DictionaryReference> where FormDict is a reference to the Form Dictionary containing PaintProc, and returns no results. The effect of executing PaintProc is to image one instance of the form. The Context of Interpretation for PaintProc is described in .

    If PaintProc executes the ImageRasterElement or MaskBitMap imaging operators, none of the underlying Data Sources for the operator may be DataSource::Document. If any of the underlying Data Sources is a StreamObject derived from an external data source, the execution of the FindResource operator to obtain the StreamObject shall occur within PaintProc. Because it is expected that many implementations will optimize execution by maintaining a cache of recently used forms, PaintProc may be executed at unpredictable times and in unpredictable contexts. Therefore PaintProc should rely only on the operators in SystemDict, on the contents of its FormDict operand, and the Graphics State Variables not set to their default values according to . It should always produce the same results. It should have no side effects besides painting the form.

    UniqueID

    The optional key/value pair <UniqueID: Identifier> is designed to uniquely identify, for caching purposes, a form that is to be used by multiple documents. To avoid the possible waste of memory resources in caching implementations, a Form Dictionary for a form that is specified and used within a single document should not contain this key.

    Implementation

    The key/value pair <Implementation: Any> is added to the Form Dictionary by the ExecuteForm operator. It is intended to be used by implementations to store information to aid in the caching of the form. The type and value of this key are implementation-dependent. If an key/value pair whose key is Implementation is placed in a Form Dictionary by the TOKENSEQUENCE that defines the Dictionary, its value may be overwritten by the ExecuteForm operator.

    Obtaining a Form Dictionary for Use in Content

    A Form Object to be used as an operand to the ExecuteForm operator is obtained via execution of the FindResource operator. The FindResource operator takes as an operand an INTERNAL RESOURCE IDENTIFIER that has been previously bound to a Form resource in structure by a RESOURCE DECLARATION, and returns a Form Object. The FindResource operator does not examine the Form Dictionary referenced by the Form Object to ensure that the required keys are present and of the correct type; this function is performed by the ExecuteForm operator.

    Imaging a Form

    A form is imaged via execution of the ExecuteForm operator, which in turn executes the PaintProc in the Form Objects's Form Dictionary. Prior to executing the ExecuteForm operator, a document should set appropriate parameters in the graphics state; in particular, it should alter the CurrentTransformation in order to control the position, size, and orientation of the form in User Coordinate Space.

    Before execution of the PaintProc, the following Graphics State Variables are reset to their default values (see for the default value for each):

    • CurrentDashPattern
    • CurrentMiterLimit
    • CurrentPath
    • CurrentPosition
    • CurrentStrokeEnd
    • CurrentStrokeJoin
    • CurrentStrokeWidth
    If some other value than the default value of the above Graphics State Variables is desired, additional key/value pairs may be defined in the Form Dictionary to represent Graphics State Variable values or other information that can be used by the PaintProc in imaging the form.

    The rest of the Virtual Machine State in which the PaintProc executes is implementation-dependent. In some implementations, part or all of the remainder of the Virtual Machine State may be inherited from the Virtual Machine State at the time of execution of the ExecuteForm operator.

    ExecuteForm

    The specification of the ExecuteForm operator and its semantics includes the specification of conditions which may cause content exceptions to be raised as a result of interpretation of the operator. Content exceptions and exception handling are defined in . In addition to the operator-specific exceptions, there are generic exceptions which may be raised during the interpretation of almost any operator. These generic exceptions and their semantics are described in .

    The ExecuteForm operator accepts one operand

  • <FormObject: DictionaryReference> where Form Object is obtained via execution of the FindResource operator. The operator returns no results. The graphical output produced by ExecuteForm is defined by the PaintProc Procedure (see ) in the Form Object's Form Dictionary. If this is the first invocation of ExecuteForm for the form, ExecuteForm first verifies that the Form Dictionary contains the required keys. It then adds the Implementation key/value pair (see ) and reduces the access attribute of the Dictionary to at least ReadOnly. Because on some implementations the ExecuteForm operator may alter the contents of the Dictionary, the reduction of the access attribute of the Dictionary is performed to prevent subsequent content operators from modifying the contents of the Dictionary. Implementations which do not wish to allow any subsequent access to the contents of the Dictionary (except via executions of ExecuteForm) may reduce the access attribute of the Dictionary to ExecuteOnly.

    If any of the required key/value pairs are missing from the Form Dictionary operand of the ExecuteForm operator, RaiseError shall be invoked with UndefinedKey as its operand.

    ExecuteForm may call the PaintProc to image the form. It shall call the PaintProc the first time that ExecuteForm is called with a given Form Object and whenever changes to the Graphics State since the last time the PaintProc was called would effect how the form was imaged. Changes to the translation components of the CurrentTransformation Graphics State Variable do not effect how the form will be imaged. When ExecuteForm needs to call the PaintProc Procedure (rather than using a cached representation to image the form), it pushes the Form Object on the operand stack, then performs the equivalent of the following:

  • SaveGraphicsState
  • % The following procedure resets the Graphics State Variables specified in to their default values;
  • % the code for this Procedure is obvious. The values of all other Graphics State Variables are taken
  • % from the inherited Graphics State.
  • SetGStateVariables
  • % Concatenate Form Dictionary's Matrix with CurrentTransformation
  • Dup /Matrix Get Concat
  • % Stack has: Form-Dictionary llx lly urx ury (for BBox)
  • Dup /BBox Get VectorLoad Pop
  • % Stack has: Form-Dictionary llx lly width height
  • Exchange 3 Index Subtract
  • Exchange 2 Index Subtract
  • % Clip to form bounding box; ends with NewPath
  • RectClip
  • % Execute PaintProc
  • Dup /PaintProc Get Execute
  • RestoreGraphicsState The PaintProc Procedure is expected to consume the DictionaryReference operand and to execute a sequence of imaging operators to paint the form.The execution of PaintProc should depend only on the contents of the Form Dictionary and UserDict plus the Graphics State Variables not set to their default values according to ,. The PaintProc shall always produce the same output, given the same values for the Graphics State Variables not set to their default values according to , independent of the number of times it is called and independent, for example, of the contents of UserDict. The document should not expect any particular execution of ExecuteForm to cause execution of the specified PaintProc.

    If Form Object is not a reference to a Dictionary obtained via execution of the FindResource operator, RaiseError shall be invoked with UndefinedResource as its operand.