HomeUniDoc
...

Package annotator

Overview ▾

Package annotator provides an interface for creating annotations with appearance streams. It goes beyond the models package which includes definitions of basic annotation models, in that it can create the appearance streams which specify the exact appearance as needed by many pdf viewers for consistent appearance of the annotations. It also contains methods for generating appearance streams for fields via widget annotations.

Index ▾

func CreateCircleAnnotation(circDef CircleAnnotationDef) (*pdf.PdfAnnotation, error)
func CreateFileAttachmentAnnotation(fileDef FileAnnotationDef) (*model.PdfAnnotation, error)
func CreateInkAnnotation(inkDef InkAnnotationDef) (*model.PdfAnnotation, error)
func CreateLineAnnotation(lineDef LineAnnotationDef) (*pdf.PdfAnnotation, error)
func CreateRectangleAnnotation(rectDef RectangleAnnotationDef) (*pdf.PdfAnnotation, error)
func NewCheckboxField(page *model.PdfPage, name string, rect []float64, opt CheckboxFieldOptions) (*model.PdfFieldButton, error)
func NewComboboxField(page *model.PdfPage, name string, rect []float64, opt ComboboxFieldOptions) (*model.PdfFieldChoice, error)
func NewFormResetButtonField(page *model.PdfPage, opt FormResetActionOptions) (*model.PdfFieldButton, error)
func NewFormSubmitButtonField(page *model.PdfPage, opt FormSubmitActionOptions) (*model.PdfFieldButton, error)
func NewImageField(page *model.PdfPage, name string, rect []float64, opt ImageFieldOptions) (*model.PdfFieldButton, error)
func NewSignatureField(signature *model.PdfSignature, lines []*SignatureLine, opts *SignatureFieldOpts) (*model.PdfFieldSignature, error)
func NewTextField(page *model.PdfPage, name string, rect []float64, opt TextFieldOptions) (*model.PdfFieldText, error)
type AppearanceFont
type AppearanceFontStyle
type AppearanceStyle
type CheckboxFieldOptions
type CircleAnnotationDef
type ComboboxFieldOptions
type FieldAppearance
    func (fa FieldAppearance) GenerateAppearanceDict(form *model.PdfAcroForm, field *model.PdfField, wa *model.PdfAnnotationWidget) (*core.PdfObjectDictionary, error)
    func (fa *FieldAppearance) SetStyle(style AppearanceStyle)
    func (fa FieldAppearance) Style() AppearanceStyle
    func (fa FieldAppearance) WrapContentStream(page *model.PdfPage) error
type FileAnnotationDef
type FormResetActionOptions
type FormSubmitActionOptions
type ImageFieldAppearance
    func (fa ImageFieldAppearance) GenerateAppearanceDict(form *model.PdfAcroForm, field *model.PdfField, wa *model.PdfAnnotationWidget) (*core.PdfObjectDictionary, error)
    func (fa *ImageFieldAppearance) SetStyle(style AppearanceStyle)
    func (fa ImageFieldAppearance) Style() AppearanceStyle
    func (fa ImageFieldAppearance) WrapContentStream(page *model.PdfPage) error
type ImageFieldOptions
type InkAnnotationDef
type LineAnnotationDef
type RectangleAnnotationDef
type SignatureFieldOpts
    func NewSignatureFieldOpts() *SignatureFieldOpts
type SignatureImagePosition
type SignatureLine
    func NewSignatureLine(desc, text string) *SignatureLine
type TextFieldOptions

Package files

circle.go doc.go field_appearance.go file.go form_field.go image_field_appearance.go ink.go line.go rectangle.go signature.go

func CreateCircleAnnotation

func CreateCircleAnnotation(circDef CircleAnnotationDef) (*pdf.PdfAnnotation, error)

CreateCircleAnnotation creates a circle/ellipse annotation object with appearance stream that can be added to page PDF annotations.

func CreateFileAttachmentAnnotation

func CreateFileAttachmentAnnotation(fileDef FileAnnotationDef) (*model.PdfAnnotation, error)

CreateFileAttachmentAnnotation creates a file attachment annotation object that can be added to the annotation list of a PDF page.

func CreateInkAnnotation

func CreateInkAnnotation(inkDef InkAnnotationDef) (*model.PdfAnnotation, error)

CreateInkAnnotation creates an ink annotation object that can be added to the annotation list of a PDF page.

func CreateLineAnnotation

func CreateLineAnnotation(lineDef LineAnnotationDef) (*pdf.PdfAnnotation, error)

CreateLineAnnotation creates a line annotation object that can be added to page PDF annotations.

func CreateRectangleAnnotation

func CreateRectangleAnnotation(rectDef RectangleAnnotationDef) (*pdf.PdfAnnotation, error)

CreateRectangleAnnotation creates a rectangle annotation object that can be added to page PDF annotations.

func NewCheckboxField

func NewCheckboxField(page *model.PdfPage, name string, rect []float64, opt CheckboxFieldOptions) (*model.PdfFieldButton, error)

NewCheckboxField generates a new checkbox field with partial name `name` at location `rect` on specified `page` and with field specific options `opt`.

func NewComboboxField

func NewComboboxField(page *model.PdfPage, name string, rect []float64, opt ComboboxFieldOptions) (*model.PdfFieldChoice, error)

NewComboboxField generates a new combobox form field with partial name `name` at location `rect` on specified `page` and with field specific options `opt`.

func NewFormResetButtonField

func NewFormResetButtonField(page *model.PdfPage, opt FormResetActionOptions) (*model.PdfFieldButton, error)

NewFormResetButtonField would create a reset button in specified page according to the parameter in `FormResetActionOptions`.

func NewFormSubmitButtonField

func NewFormSubmitButtonField(page *model.PdfPage, opt FormSubmitActionOptions) (*model.PdfFieldButton, error)

NewFormSubmitButtonField would create a submit button in specified page according to the parameter in `FormSubmitActionOptions`.

func NewImageField

func NewImageField(page *model.PdfPage, name string, rect []float64, opt ImageFieldOptions) (*model.PdfFieldButton, error)

NewImageField generates a new image field with partial name `name` at location `rect` on specified `page` and with field specific options `opt`.

func NewSignatureField

func NewSignatureField(signature *model.PdfSignature, lines []*SignatureLine, opts *SignatureFieldOpts) (*model.PdfFieldSignature, error)

NewSignatureField returns a new signature field with a visible appearance containing the specified signature lines and styled according to the specified options.

func NewTextField

func NewTextField(page *model.PdfPage, name string, rect []float64, opt TextFieldOptions) (*model.PdfFieldText, error)

NewTextField generates a new text field with partial name `name` at location specified by `rect` on given `page` and with field specific options `opt`.

type AppearanceFont

AppearanceFont represents a font used for generating the appearance of a field in the filling/flattening process.

type AppearanceFont struct {
    // Name represents the name of the font which will be added to the
    // AcroForm resources (DR).
    Name string

    // Font represents the actual font used for the field appearance.
    Font *model.PdfFont

    // Size represents the size of the font used for the field appearance.
    // If the font size is 0, the value of the FallbackSize field of the
    // AppearanceFontStyle is used, if set. Otherwise, the font size is
    // calculated based on the available annotation height and on the
    // AutoFontSizeFraction field of the AppearanceStyle.
    Size float64
}

type AppearanceFontStyle

AppearanceFontStyle defines font style characteristics for form fields, used in the filling/flattening process.

type AppearanceFontStyle struct {
    // Fallback represents a global font fallback, used for fields which do
    // not specify a font in their default appearance (DA). The fallback is
    // also used if there is a font specified in the DA, but it is not
    // found in the AcroForm resources (DR).
    Fallback *AppearanceFont

    // FallbackSize represents a global font size fallback used for fields
    // which do not specify a font size in their default appearance (DA).
    // The fallback size is applied only if its value is larger than zero.
    FallbackSize float64

    // FieldFallbacks defines font fallbacks for specific fields. The map keys
    // represent the names of the fields (which can be specified by their
    // partial or full names). Specific field fallback fonts take precedence
    // over the global font fallback.
    FieldFallbacks map[string]*AppearanceFont

    // ForceReplace forces the replacement of fonts in the filling/flattening
    // process, even if the default appearance (DA) specifies a valid font.
    // If no fallback font is provided, setting this field has no effect.
    ForceReplace bool
}

type AppearanceStyle

AppearanceStyle defines style parameters for appearance stream generation.

type AppearanceStyle struct {
    // How much of Rect height to fill when autosizing text.
    AutoFontSizeFraction float64

    // CheckmarkRune is a rune used for check mark in checkboxes (for ZapfDingbats font).
    CheckmarkRune rune

    BorderSize  float64
    BorderColor model.PdfColor
    FillColor   model.PdfColor

    // Multiplier for lineheight for multi line text.
    MultilineLineHeight   float64
    MultilineVAlignMiddle bool // Defaults to top.

    // Visual guide checking alignment of field contents (debugging).
    DrawAlignmentReticle bool

    // Allow field MK appearance characteristics to override style settings.
    AllowMK bool

    // Fonts holds appearance styles for fonts.
    Fonts *AppearanceFontStyle

    // MarginLeft represents the amount of space to leave on the left side of
    // the form field bounding box when generating appearances (default: 2.0).
    MarginLeft *float64
}

type CheckboxFieldOptions

CheckboxFieldOptions defines optional parameters for a checkbox field a form.

type CheckboxFieldOptions struct {
    Checked bool
}

type CircleAnnotationDef

CircleAnnotationDef defines a circle annotation or ellipse at position (X, Y) and Width and Height. The annotation has various style parameters including Fill and Border options and Opacity.

type CircleAnnotationDef struct {
    X             float64
    Y             float64
    Width         float64
    Height        float64
    FillEnabled   bool // Show fill?
    FillColor     *pdf.PdfColorDeviceRGB
    BorderEnabled bool // Show border?
    BorderWidth   float64
    BorderColor   *pdf.PdfColorDeviceRGB
    Opacity       float64 // Alpha value (0-1).
}

type ComboboxFieldOptions

ComboboxFieldOptions defines optional parameters for a combobox form field.

type ComboboxFieldOptions struct {
    // Choices is the list of string values that can be selected.
    Choices []string
}

type FieldAppearance

FieldAppearance implements interface model.FieldAppearanceGenerator and generates appearance streams for fields taking into account what value is in the field. A common use case is for generating the appearance stream prior to flattening fields.

If `OnlyIfMissing` is true, the field appearance is generated only for fields that do not have an appearance stream specified. If `RegenerateTextFields` is true, all text fields are regenerated (even if OnlyIfMissing is true).

type FieldAppearance struct {
    OnlyIfMissing        bool
    RegenerateTextFields bool
    // contains filtered or unexported fields
}

func (FieldAppearance) GenerateAppearanceDict

func (fa FieldAppearance) GenerateAppearanceDict(form *model.PdfAcroForm, field *model.PdfField,
    wa *model.PdfAnnotationWidget) (*core.PdfObjectDictionary, error)

GenerateAppearanceDict generates an appearance dictionary for widget annotation `wa` for the `field` in `form`. Implements interface model.FieldAppearanceGenerator.

func (*FieldAppearance) SetStyle

func (fa *FieldAppearance) SetStyle(style AppearanceStyle)

SetStyle applies appearance `style` to `fa`.

func (FieldAppearance) Style

func (fa FieldAppearance) Style() AppearanceStyle

Style returns the appearance style of `fa`. If not specified, returns default style.

func (FieldAppearance) WrapContentStream

func (fa FieldAppearance) WrapContentStream(page *model.PdfPage) error

WrapContentStream ensures that the entire content stream for a `page` is wrapped within q ... Q operands. Ensures that following operands that are added are not affected by additional operands that are added. Implements interface model.ContentStreamWrapper.

type FileAnnotationDef

FileAnnotationDef holds base information for constructing an file attachment annotation.

type FileAnnotationDef struct {
    // Bounding box of the annotation.
    X      float64
    Y      float64
    Width  float64
    Height float64

    // EmbeddedFile is the file information to be attached.
    EmbeddedFile *model.EmbeddedFile

    // Author is the author of the attachment file.
    Author string

    // Subject is the subject of the attachment file.
    Subject string

    // Description of the file attachment that will be displayed as a comment on the PDF reader.
    Description string

    // IconName is The name of an icon that shall be used in displaying the annotation.
    // Conforming readers shall provide predefined icon appearances for at least the following standard names:
    //
    // - Graph
    // - PushPin
    // - Paperclip
    // - Tag
    //
    // Additional names may be supported as well. Default value: "PushPin".
    IconName string

    // Color is the color of the annotation.
    Color *model.PdfColorDeviceRGB

    // CreationDate is the date and time when the file attachment was created.
    // If not set, the current time is used.
    CreationDate *time.Time
}

type FormResetActionOptions

FormResetActionOptions holds options for creating a form reset button.

type FormResetActionOptions struct {
    // Rectangle holds the button position, size, and color.
    Rectangle draw.Rectangle

    // Label specifies the text that would be displayed on the button.
    Label string

    // LabelColor specifies the button label color.
    LabelColor model.PdfColor

    // Font specifies a font used for rendering the button label.
    // When omitted it will fallback to use a Helvetica font.
    Font *model.PdfFont

    // FontSize specifies the font size used in rendering the button label.
    // The default font size is 12pt.
    FontSize *float64

    // Fields specifies list of fields that could be resetted.
    // This list may contain indirect object to fields or field names.
    Fields *core.PdfObjectArray

    // IsExclusionList specifies that the fields in the `Fields` array would be excluded form reset process.
    IsExclusionList bool
}

type FormSubmitActionOptions

FormSubmitActionOptions holds options for creating a form submit button.

type FormSubmitActionOptions struct {
    // Rectangle holds the button position, size, and color.
    Rectangle draw.Rectangle

    // Url specifies the URL where the fieds will be submitted.
    Url string

    // Label specifies the text that would be displayed on the button.
    Label string

    // LabelColor specifies the button label color.
    LabelColor model.PdfColor

    // Font specifies a font used for rendering the button label.
    // When omitted it will fallback to use a Helvetica font.
    Font *model.PdfFont

    // FontSize specifies the font size used in rendering the button label.
    // The default font size is 12pt.
    FontSize *float64

    // Fields specifies list of fields that could be submitted.
    // This list may contain indirect object to fields or field names.
    Fields *core.PdfObjectArray

    // IsExclusionList specifies that the fields contain in `Fields` array would not be submitted.
    IsExclusionList bool

    // IncludeEmptyFields specifies if all fields would be submitted even though it's value is empty.
    IncludeEmptyFields bool

    // SubmitAsPDF specifies that the document shall be submitted as PDF.
    // If set then all the other flags shall be ignored.
    SubmitAsPDF bool
}

type ImageFieldAppearance

ImageFieldAppearance implements interface model.FieldAppearanceGenerator and generates appearance streams for attaching an image to a button field.

type ImageFieldAppearance struct {
    OnlyIfMissing bool
    // contains filtered or unexported fields
}

func (ImageFieldAppearance) GenerateAppearanceDict

func (fa ImageFieldAppearance) GenerateAppearanceDict(form *model.PdfAcroForm,
    field *model.PdfField, wa *model.PdfAnnotationWidget) (*core.PdfObjectDictionary, error)

GenerateAppearanceDict generates an appearance dictionary for widget annotation `wa` for the `field` in `form`. Implements interface model.FieldAppearanceGenerator.

func (*ImageFieldAppearance) SetStyle

func (fa *ImageFieldAppearance) SetStyle(style AppearanceStyle)

SetStyle applies appearance `style` to `fa`.

func (ImageFieldAppearance) Style

func (fa ImageFieldAppearance) Style() AppearanceStyle

Style returns the appearance style of `fa`. If not specified, returns default style.

func (ImageFieldAppearance) WrapContentStream

func (fa ImageFieldAppearance) WrapContentStream(page *model.PdfPage) error

WrapContentStream ensures that the entire content stream for a `page` is wrapped within q ... Q operands. Ensures that following operands that are added are not affected by additional operands that are added. Implements interface model.ContentStreamWrapper.

type ImageFieldOptions

ImageFieldOptions defines optional parameters for a push button with image attach capability form field.

type ImageFieldOptions struct {
    Image *model.Image
    // contains filtered or unexported fields
}

type InkAnnotationDef

InkAnnotationDef holds base information for constructing an ink annotation.

type InkAnnotationDef struct {
    // Paths is the array of stroked paths which compose the annotation.
    Paths []draw.Path

    // Color is the color of the line. Default to black.
    Color *model.PdfColorDeviceRGB

    // LineWidth is the width of the line.
    LineWidth float64
}

type LineAnnotationDef

LineAnnotationDef defines a line between point 1 (X1,Y1) and point 2 (X2,Y2). The line ending styles can be none (regular line), or arrows at either end. The line also has a specified width, color and opacity.

type LineAnnotationDef struct {
    X1               float64
    Y1               float64
    X2               float64
    Y2               float64
    LineColor        *pdf.PdfColorDeviceRGB
    Opacity          float64 // Alpha value (0-1).
    LineWidth        float64
    LineEndingStyle1 draw.LineEndingStyle // Line ending style of point 1.
    LineEndingStyle2 draw.LineEndingStyle // Line ending style of point 2.
}

type RectangleAnnotationDef

RectangleAnnotationDef is a rectangle defined with a specified Width and Height and a lower left corner at (X,Y). The rectangle can optionally have a border and a filling color. The Width/Height includes the border (if any specified).

type RectangleAnnotationDef struct {
    X             float64
    Y             float64
    Width         float64
    Height        float64
    FillEnabled   bool // Show fill?
    FillColor     *pdf.PdfColorDeviceRGB
    BorderEnabled bool // Show border?
    BorderWidth   float64
    BorderColor   *pdf.PdfColorDeviceRGB
    Opacity       float64 // Alpha value (0-1).
}

type SignatureFieldOpts

SignatureFieldOpts represents a set of options used to configure an appearance widget dictionary.

type SignatureFieldOpts struct {
    // Rect represents the area the signature annotation is displayed on.
    Rect []float64

    // AutoSize specifies if the content of the appearance should be
    // scaled to fit in the annotation rectangle.
    AutoSize bool

    // Font specifies the font of the text content.
    Font *model.PdfFont

    // FontSize specifies the size of the text content.
    FontSize float64

    // LineHeight specifies the height of a line of text in the appearance annotation.
    LineHeight float64

    // TextColor represents the color of the text content displayed.
    TextColor model.PdfColor

    // FillColor represents the background color of the appearance annotation area.
    FillColor model.PdfColor

    // BorderSize represents border size of the appearance annotation area.
    BorderSize float64

    // BorderColor represents the border color of the appearance annotation area.
    BorderColor model.PdfColor

    // WatermarkImage specifies the image used as a watermark that will be rendered
    // behind the signature.
    WatermarkImage image.Image

    // Image represents the image used for the signature appearance.
    Image image.Image

    // Encoder specifies the image encoder used for image signature. Defaults to flate encoder.
    Encoder core.StreamEncoder

    // ImagePosition specifies the image location relative to the text signature.
    ImagePosition SignatureImagePosition
}

func NewSignatureFieldOpts

func NewSignatureFieldOpts() *SignatureFieldOpts

NewSignatureFieldOpts returns a new initialized instance of options used to generate a signature appearance.

type SignatureImagePosition

SignatureImagePosition specifies the image signature location relative to the text signature. If text signature is not defined, this position will be ignored.

type SignatureImagePosition int
const (
    // SignatureImageLeft specifies that the image is rendered on the left of the text signature.
    SignatureImageLeft SignatureImagePosition = iota

    // SignatureImageRight specifies that the image is rendered on the right of the text signature.
    SignatureImageRight

    // SignatureImageTop specifies that the image is rendered on the top of the text signature.
    SignatureImageTop

    // SignatureImageBottom specifies that the image is rendered on the bottom of the text signature.
    SignatureImageBottom
)

type SignatureLine

SignatureLine represents a line of information in the signature field appearance.

type SignatureLine struct {
    Desc string
    Text string
}

func NewSignatureLine

func NewSignatureLine(desc, text string) *SignatureLine

NewSignatureLine returns a new signature line displayed as a part of the signature field appearance.

type TextFieldOptions

TextFieldOptions defines optional parameter for a text field in a form.

type TextFieldOptions struct {
    MaxLen int    // Ignored if <= 0.
    Value  string // Ignored if empty ("").
}