forms

package
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 24, 2026 License: MIT Imports: 2 Imported by: 0

Documentation

Overview

Package forms provides interactive form field support for PDF documents.

This package implements AcroForm (Interactive Form) support, allowing creation of fillable PDF forms with text fields, checkboxes, radio buttons, and other interactive elements.

Thread Safety

Form field instances are NOT safe for concurrent use. Each goroutine should create and manipulate its own field instances. Fields should be created and configured before adding to a page.

Example 

c := creator.New()
page, _ := c.NewPage()

// Text field
nameField := forms.NewTextField("name", 100, 700, 200, 20)
nameField.SetValue("John Doe")
page.AddField(nameField)

c.WriteToFile("form.pdf")

Index

Constants

View Source 
const (
	// FlagReadOnly makes the field read-only (bit 1).
	FlagReadOnly = 1 << 0 // 1

	// FlagRequired marks the field as required (bit 2).
	FlagRequired = 1 << 1 // 2

	// FlagNoExport excludes the field from form data export (bit 3).
	FlagNoExport = 1 << 2 // 4
)

FieldFlags defines common field flags as constants.

View Source 
const (
	// FlagMultiline allows multiple lines in the text field (bit 13).
	FlagMultiline = 1 << 12 // 4096

	// FlagPassword masks text entry as password (bit 14).
	FlagPassword = 1 << 13 // 8192

	// FlagFileSelect treats the field as a file selection (bit 21).
	FlagFileSelect = 1 << 20 // 1048576

	// FlagDoNotSpellCheck disables spell checking (bit 23).
	FlagDoNotSpellCheck = 1 << 22 // 4194304

	// FlagDoNotScroll prevents scrolling in the field (bit 24).
	FlagDoNotScroll = 1 << 23 // 8388608

	// FlagComb creates a comb field (fixed character positions) (bit 25).
	FlagComb = 1 << 24 // 16777216

	// FlagRichText enables rich text formatting (bit 26).
	FlagRichText = 1 << 25 // 33554432
)

TextFieldFlags defines text field specific flags.

View Source 
const (
	// FlagNoToggleToOff prevents checkboxes/radio from toggling off (bit 15).
	FlagNoToggleToOff = 1 << 14 // 16384

	// FlagRadio makes the button a radio button (bit 16).
	FlagRadio = 1 << 15 // 32768

	// FlagPushbutton makes the button a pushbutton (bit 17).
	FlagPushbutton = 1 << 16 // 65536

	// FlagRadiosInUnison makes all radio buttons with same value toggle together (bit 26).
	FlagRadiosInUnison = 1 << 25 // 33554432
)

ButtonFieldFlags defines button field specific flags.

View Source 
const (
	// FlagCombo makes the choice field a combo box (editable) (bit 18).
	FlagCombo = 1 << 17 // 131072

	// FlagEdit allows editing in combo box (bit 19).
	FlagEdit = 1 << 18 // 262144

	// FlagSort sorts choice options (bit 20).
	FlagSort = 1 << 19 // 524288

	// FlagMultiSelect allows multiple selections in list (bit 22).
	FlagMultiSelect = 1 << 21 // 2097152

	// FlagCommitOnSelChange commits value on selection change (bit 27).
	FlagCommitOnSelChange = 1 << 26 // 67108864
)

ChoiceFieldFlags defines choice field specific flags.

Variables

This section is empty.

Functions

This section is empty.

Types

type Checkbox 

type Checkbox struct {
	// contains filtered or unexported fields
}

Checkbox represents a checkbox field in a PDF form.

Checkboxes allow users to select or deselect an option. They are button fields with /FT /Btn and no special flags (radio/pushbutton).

Example: 

// Create checkbox
agreeBox := forms.NewCheckbox("agree", 100, 650, 15, 15)
agreeBox.SetLabel("I agree to terms")
agreeBox.SetChecked(true)

// Styled checkbox
subscribeBox := forms.NewCheckbox("subscribe", 100, 600, 20, 20)
subscribeBox.SetLabel("Subscribe to newsletter")
subscribeBox.SetBorderColor(0, 0, 0) // Black border
subscribeBox.SetFillColor(1, 1, 1)   // White background

PDF Structure: 

<< /Type /Annot
   /Subtype /Widget
   /FT /Btn                  % Field Type: Button
   /T (agree)                % Field name
   /V /Yes                   % Value when checked (/Yes or /Off)
   /Rect [100 650 115 665]   % Position
   /F 4                      % Print flag
   /Ff 0                     % No flags = checkbox (not radio/pushbutton)
   /AS /Yes                  % Appearance state (current state)
   /AP <<                    % Appearance dictionary (optional)
       /N << /Yes 10 0 R /Off 11 0 R >>
   >>
>>

func NewCheckbox 

func NewCheckbox(name string, x, y, width, height float64) *Checkbox

NewCheckbox creates a new checkbox field at the specified position.

Parameters:

  • name: Unique field name (used for form data)
  • x: Left edge position in points
  • y: Bottom edge position in points
  • width: Checkbox width in points (typically 12-20)
  • height: Checkbox height in points (typically 12-20)

Example: 

checkbox := forms.NewCheckbox("terms", 100, 650, 15, 15)

func (*Checkbox) BorderColor 

func (c *Checkbox) BorderColor() *[3]float64

BorderColor returns the border color (nil if no border).

func (*Checkbox) DefaultValue 

func (c *Checkbox) DefaultValue() interface{}

DefaultValue returns the field's default value.

func (*Checkbox) FillColor 

func (c *Checkbox) FillColor() *[3]float64

FillColor returns the fill color (nil if transparent).

func (*Checkbox) Flags 

func (c *Checkbox) Flags() int

Flags returns the field flags bitmask. For checkboxes, this is typically 0 (no special flags). Radio and pushbutton flags are NOT set.

func (*Checkbox) IsChecked 

func (c *Checkbox) IsChecked() bool

IsChecked returns true if the checkbox is checked.

func (*Checkbox) IsReadOnly 

func (c *Checkbox) IsReadOnly() bool

IsReadOnly returns true if the field is read-only.

func (*Checkbox) IsRequired 

func (c *Checkbox) IsRequired() bool

IsRequired returns true if the field is required.

func (*Checkbox) Label 

func (c *Checkbox) Label() string

Label returns the label text.

func (*Checkbox) Name 

func (c *Checkbox) Name() string

Name returns the field name.

func (*Checkbox) Rect 

func (c *Checkbox) Rect() [4]float64

Rect returns the field's bounding rectangle [x1, y1, x2, y2].

func (*Checkbox) SetBorderColor 

func (c *Checkbox) SetBorderColor(r, g, b *float64) error

SetBorderColor sets the border color (RGB, 0.0-1.0 range).

Set to nil to remove border.

Example: 

checkbox.SetBorderColor(0, 0, 0)  // Black border

func (*Checkbox) SetChecked 

func (c *Checkbox) SetChecked(checked bool) *Checkbox

SetChecked sets whether the checkbox is checked.

Example: 

checkbox.SetChecked(true)  // Check the box

func (*Checkbox) SetDefaultChecked 

func (c *Checkbox) SetDefaultChecked(checked bool) *Checkbox

SetDefaultChecked sets the default checked state.

This is used when the form is reset.

Example: 

checkbox.SetDefaultChecked(false)  // Unchecked by default

func (*Checkbox) SetFillColor 

func (c *Checkbox) SetFillColor(r, g, b *float64) error

SetFillColor sets the background fill color (RGB, 0.0-1.0 range).

Set to nil for transparent background.

Example: 

checkbox.SetFillColor(1, 1, 1)  // White background

func (*Checkbox) SetLabel 

func (c *Checkbox) SetLabel(label string) *Checkbox

SetLabel sets the label text displayed next to the checkbox.

Note: This is for documentation/accessibility purposes. The actual label rendering is handled by the application.

Example: 

checkbox.SetLabel("I agree to the terms and conditions")

func (*Checkbox) SetReadOnly 

func (c *Checkbox) SetReadOnly(readonly bool) *Checkbox

SetReadOnly sets whether the field is read-only.

Example: 

checkbox.SetReadOnly(true)  // Field cannot be changed

func (*Checkbox) SetRequired 

func (c *Checkbox) SetRequired(required bool) *Checkbox

SetRequired sets whether the field is required.

Example: 

checkbox.SetRequired(true)  // User must check this box

func (*Checkbox) Type 

func (c *Checkbox) Type() string

Type returns the PDF field type (/FT value). For checkboxes, this is always "Btn" (button).

func (*Checkbox) Validate 

func (c *Checkbox) Validate() error

Validate checks if the field configuration is valid.

Returns an error if:

  • Name is empty
  • Rectangle has invalid dimensions

func (*Checkbox) Value 

func (c *Checkbox) Value() interface{}

Value returns the field's current value. For checkboxes, this is either "Yes" (checked) or "Off" (unchecked). 

type Dropdown struct {
	// contains filtered or unexported fields
}

Dropdown represents a dropdown (combo box) field in a PDF form.

Dropdowns allow users to select a single option from a list. They can optionally be editable, allowing users to enter custom values.

Example: 

// Simple dropdown
country := forms.NewDropdown("country", 100, 550, 150, 20)
country.AddOption("us", "United States")
country.AddOption("ca", "Canada")
country.AddOption("uk", "United Kingdom")
country.SetSelected("us")

// Editable dropdown (user can type custom value)
customDropdown := forms.NewDropdown("custom", 100, 500, 150, 20)
customDropdown.SetEditable(true)
customDropdown.AddOptions("Option 1", "Option 2", "Option 3")

PDF Structure: 

<< /Type /Annot
   /Subtype /Widget
   /FT /Ch                          % Field Type: Choice
   /T (country)                     % Field name
   /V (us)                          % Selected value
   /Opt [                           % Options array
       [(us) (United States)]
       [(ca) (Canada)]
       [(uk) (United Kingdom)]
   ]
   /Rect [100 550 250 570]          % Position
   /F 4                             % Print flag
   /Ff 131072                       % Combo flag (bit 18)
>>

func NewDropdown 

func NewDropdown(name string, x, y, width, height float64) *Dropdown

NewDropdown creates a new dropdown field at the specified position.

Parameters:

  • name: Unique field name (used for form data)
  • x: Left edge position in points
  • y: Bottom edge position in points
  • width: Field width in points
  • height: Field height in points (typically 15-25 for single-line dropdown)

Example: 

dropdown := forms.NewDropdown("country", 100, 550, 150, 20)

func (d *Dropdown) AddOption(exportValue, displayValue string) *Dropdown

AddOption adds a single option to the dropdown.

Parameters:

  • exportValue: Value used in form data export
  • displayValue: Value shown to user in dropdown

Example: 

dropdown.AddOption("us", "United States")
dropdown.AddOption("ca", "Canada")

func (d *Dropdown) AddOptions(values ...string) *Dropdown

AddOptions adds multiple options where export value equals display value.

This is a convenience method for simple dropdowns where the internal value is the same as what's displayed.

Example: 

dropdown.AddOptions("Red", "Green", "Blue")

func (d *Dropdown) BorderColor() *[3]float64

BorderColor returns the border color (nil if no border). 

func (d *Dropdown) DefaultValue() interface{}

DefaultValue returns the field's default value. 

func (d *Dropdown) FillColor() *[3]float64

FillColor returns the fill color (nil if transparent). 

func (d *Dropdown) Flags() int

Flags returns the field flags bitmask. For dropdowns, this includes FlagCombo (bit 18). 

func (d *Dropdown) FontName() string

FontName returns the font name. 

func (d *Dropdown) FontSize() float64

FontSize returns the font size. 

func (d *Dropdown) IsEditable() bool

IsEditable returns true if users can enter custom values. 

func (d *Dropdown) IsReadOnly() bool

IsReadOnly returns true if the field is read-only. 

func (d *Dropdown) IsRequired() bool

IsRequired returns true if the field is required. 

func (d *Dropdown) IsSorted() bool

IsSorted returns true if options are sorted alphabetically. 

func (d *Dropdown) Name() string

Name returns the field name. 

func (d *Dropdown) Options() []Option

Options returns the list of available options. 

func (d *Dropdown) Rect() [4]float64

Rect returns the field's bounding rectangle [x1, y1, x2, y2]. 

func (d *Dropdown) SelectedValue() string

SelectedValue returns the currently selected value. 

func (d *Dropdown) SetBorderColor(r, g, b *float64) error

SetBorderColor sets the border color (RGB, 0.0-1.0 range).

Set to nil to remove border.

Example: 

dropdown.SetBorderColor(0, 0, 0)  // Black border

func (d *Dropdown) SetDefaultValue(exportValue string) error

SetDefaultValue sets the default selected value.

This is used when the form is reset.

Example: 

dropdown.SetDefaultValue("us")

func (d *Dropdown) SetEditable(editable bool) *Dropdown

SetEditable sets whether users can enter custom values.

When editable, the dropdown becomes a combo box where users can either select from the list or type a custom value.

Example: 

dropdown.SetEditable(true)  // Allow custom text entry

func (d *Dropdown) SetFillColor(r, g, b *float64) error

SetFillColor sets the background fill color (RGB, 0.0-1.0 range).

Set to nil for transparent background.

Example: 

dropdown.SetFillColor(1, 1, 1)  // White background

func (d *Dropdown) SetFontName(name string) *Dropdown

SetFontName sets the font name.

Common values: "Helvetica", "Courier", "Times-Roman"

Example: 

dropdown.SetFontName("Courier")

func (d *Dropdown) SetFontSize(size float64) error

SetFontSize sets the font size for the text.

Example: 

dropdown.SetFontSize(14)

func (d *Dropdown) SetReadOnly(readonly bool) *Dropdown

SetReadOnly sets whether the field is read-only.

Example: 

dropdown.SetReadOnly(true)  // Field cannot be changed

func (d *Dropdown) SetRequired(required bool) *Dropdown

SetRequired sets whether the field is required.

Example: 

dropdown.SetRequired(true)  // User must select an option

func (d *Dropdown) SetSelected(exportValue string) error

SetSelected sets the currently selected option by export value.

Example: 

dropdown.SetSelected("us")  // Select "United States"

func (d *Dropdown) SetSort(sort bool) *Dropdown

SetSort sets whether options are sorted alphabetically.

Example: 

dropdown.SetSort(true)  // Sort options A-Z

func (d *Dropdown) SetTextColor(r, g, b float64) error

SetTextColor sets the text color (RGB, 0.0-1.0 range).

Example: 

dropdown.SetTextColor(0, 0, 1)  // Blue text

func (d *Dropdown) TextColor() [3]float64

TextColor returns the text color. 

func (d *Dropdown) Type() string

Type returns the PDF field type (/FT value). For dropdowns, this is always "Ch" (choice). 

func (d *Dropdown) Validate() error

Validate checks if the field configuration is valid.

Returns an error if:

  • Name is empty
  • Rectangle has invalid dimensions
  • Selected value is not in options
func (d *Dropdown) Value() interface{}

Value returns the field's current selected value. For dropdowns, this is the export value of the selected option.

type FormField 

type FormField interface {
	// Name returns the field name (used for form data export).
	Name() string

	// Type returns the PDF field type (/FT value).
	// - "Tx" = Text field
	// - "Btn" = Button (checkbox, radio, pushbutton)
	// - "Ch" = Choice (list box, combo box)
	// - "Sig" = Signature field
	Type() string

	// Rect returns the field's position and size [x, y, width, height].
	Rect() [4]float64

	// Flags returns the field flags (Ff) as a bitmask.
	// Common flags:
	// - Bit 1 (1): ReadOnly
	// - Bit 2 (2): Required
	// - Bit 13 (4096): Multiline (for text fields)
	// - Bit 14 (8192): Password (for text fields)
	Flags() int

	// Value returns the field's current value.
	// For text fields, this is a string.
	// For buttons, this is the button state.
	// For choice fields, this is the selected option(s).
	Value() interface{}

	// DefaultValue returns the field's default value.
	// This is used when the form is reset.
	DefaultValue() interface{}

	// IsReadOnly returns true if the field is read-only.
	IsReadOnly() bool

	// IsRequired returns true if the field is required.
	IsRequired() bool
}

FormField represents an interactive form field in a PDF.

All form fields share common properties like name, value, flags, and position. Specific field types (TextField, CheckBox, etc.) implement this interface.

This follows the DDD pattern where FormField is a polymorphic entity within the Form aggregate.

type ListBox 

type ListBox struct {
	// contains filtered or unexported fields
}

ListBox represents a list box field in a PDF form.

List boxes display a scrollable list of options and can optionally allow multiple selections.

Example: 

// Single-select list
favColor := forms.NewListBox("favorite_color", 100, 450, 150, 80)
favColor.AddOptions("Red", "Green", "Blue", "Yellow", "Orange")
favColor.SetSelected("Blue")

// Multi-select list
interests := forms.NewListBox("interests", 100, 350, 150, 80)
interests.AddOptions("Sports", "Music", "Movies", "Reading", "Travel")
interests.SetMultiSelect(true)
interests.SetSelectedMultiple("Sports", "Music")

PDF Structure: 

<< /Type /Annot
   /Subtype /Widget
   /FT /Ch                          % Field Type: Choice
   /T (interests)                   % Field name
   /V [(Sports) (Music)]            % Selected values (array for multi-select)
   /Opt [(Sports) (Music) (Movies) (Reading) (Travel)]  % Options
   /Rect [100 350 250 430]          % Position
   /F 4                             % Print flag
   /Ff 2097152                      % MultiSelect flag (bit 22)
>>

func NewListBox 

func NewListBox(name string, x, y, width, height float64) *ListBox

NewListBox creates a new list box field at the specified position.

Parameters:

  • name: Unique field name (used for form data)
  • x: Left edge position in points
  • y: Bottom edge position in points
  • width: Field width in points
  • height: Field height in points (should be tall enough for multiple items)

Example: 

listbox := forms.NewListBox("colors", 100, 350, 150, 80)

func (*ListBox) AddOption 

func (l *ListBox) AddOption(exportValue, displayValue string) *ListBox

AddOption adds a single option to the list box.

Parameters:

  • exportValue: Value used in form data export
  • displayValue: Value shown to user in list

Example: 

listbox.AddOption("red", "Red Color")
listbox.AddOption("blue", "Blue Color")

func (*ListBox) AddOptions 

func (l *ListBox) AddOptions(values ...string) *ListBox

AddOptions adds multiple options where export value equals display value.

This is a convenience method for simple list boxes where the internal value is the same as what's displayed.

Example: 

listbox.AddOptions("Red", "Green", "Blue")

func (*ListBox) BorderColor 

func (l *ListBox) BorderColor() *[3]float64

BorderColor returns the border color (nil if no border).

func (*ListBox) DefaultValue 

func (l *ListBox) DefaultValue() interface{}

DefaultValue returns the field's default value(s).

func (*ListBox) FillColor 

func (l *ListBox) FillColor() *[3]float64

FillColor returns the fill color (nil if transparent).

func (*ListBox) Flags 

func (l *ListBox) Flags() int

Flags returns the field flags bitmask. For list boxes, Combo flag is NOT set (unlike dropdowns).

func (*ListBox) FontName 

func (l *ListBox) FontName() string

FontName returns the font name.

func (*ListBox) FontSize 

func (l *ListBox) FontSize() float64

FontSize returns the font size.

func (*ListBox) IsMultiSelect 

func (l *ListBox) IsMultiSelect() bool

IsMultiSelect returns true if multiple selections are allowed.

func (*ListBox) IsReadOnly 

func (l *ListBox) IsReadOnly() bool

IsReadOnly returns true if the field is read-only.

func (*ListBox) IsRequired 

func (l *ListBox) IsRequired() bool

IsRequired returns true if the field is required.

func (*ListBox) IsSorted 

func (l *ListBox) IsSorted() bool

IsSorted returns true if options are sorted alphabetically.

func (*ListBox) Name 

func (l *ListBox) Name() string

Name returns the field name.

func (*ListBox) Options 

func (l *ListBox) Options() []Option

Options returns the list of available options.

func (*ListBox) Rect 

func (l *ListBox) Rect() [4]float64

Rect returns the field's bounding rectangle [x1, y1, x2, y2].

func (*ListBox) SelectedValues 

func (l *ListBox) SelectedValues() []string

SelectedValues returns the currently selected values.

func (*ListBox) SetBorderColor 

func (l *ListBox) SetBorderColor(r, g, b *float64) error

SetBorderColor sets the border color (RGB, 0.0-1.0 range).

Set to nil to remove border.

Example: 

listbox.SetBorderColor(0, 0, 0)  // Black border

func (*ListBox) SetDefaultValue 

func (l *ListBox) SetDefaultValue(exportValue string) error

SetDefaultValue sets the default selected value (single selection).

This is used when the form is reset.

Example: 

listbox.SetDefaultValue("blue")

func (*ListBox) SetDefaultValueMultiple 

func (l *ListBox) SetDefaultValueMultiple(exportValues ...string) error

SetDefaultValueMultiple sets the default selected values (multi-select).

Example: 

listbox.SetDefaultValueMultiple("sports", "music")

func (*ListBox) SetFillColor 

func (l *ListBox) SetFillColor(r, g, b *float64) error

SetFillColor sets the background fill color (RGB, 0.0-1.0 range).

Set to nil for transparent background.

Example: 

listbox.SetFillColor(1, 1, 1)  // White background

func (*ListBox) SetFontName 

func (l *ListBox) SetFontName(name string) *ListBox

SetFontName sets the font name.

Common values: "Helvetica", "Courier", "Times-Roman"

Example: 

listbox.SetFontName("Courier")

func (*ListBox) SetFontSize 

func (l *ListBox) SetFontSize(size float64) error

SetFontSize sets the font size for the text.

Example: 

listbox.SetFontSize(14)

func (*ListBox) SetMultiSelect 

func (l *ListBox) SetMultiSelect(multiSelect bool) *ListBox

SetMultiSelect sets whether multiple selections are allowed.

When enabled, users can select multiple items from the list using Ctrl+Click or Shift+Click.

Example: 

listbox.SetMultiSelect(true)  // Allow multiple selections

func (*ListBox) SetReadOnly 

func (l *ListBox) SetReadOnly(readonly bool) *ListBox

SetReadOnly sets whether the field is read-only.

Example: 

listbox.SetReadOnly(true)  // Field cannot be changed

func (*ListBox) SetRequired 

func (l *ListBox) SetRequired(required bool) *ListBox

SetRequired sets whether the field is required.

Example: 

listbox.SetRequired(true)  // User must select at least one option

func (*ListBox) SetSelected 

func (l *ListBox) SetSelected(exportValue string) error

SetSelected sets a single selected option by export value.

This is for single-select list boxes (when MultiSelect is false).

Example: 

listbox.SetSelected("blue")

func (*ListBox) SetSelectedMultiple 

func (l *ListBox) SetSelectedMultiple(exportValues ...string) error

SetSelectedMultiple sets multiple selected options by export values.

This is for multi-select list boxes (when MultiSelect is true).

Example: 

listbox.SetMultiSelect(true)
listbox.SetSelectedMultiple("sports", "music", "movies")

func (*ListBox) SetSort 

func (l *ListBox) SetSort(sort bool) *ListBox

SetSort sets whether options are sorted alphabetically.

Example: 

listbox.SetSort(true)  // Sort options A-Z

func (*ListBox) SetTextColor 

func (l *ListBox) SetTextColor(r, g, b float64) error

SetTextColor sets the text color (RGB, 0.0-1.0 range).

Example: 

listbox.SetTextColor(0, 0, 1)  // Blue text

func (*ListBox) TextColor 

func (l *ListBox) TextColor() [3]float64

TextColor returns the text color.

func (*ListBox) Type 

func (l *ListBox) Type() string

Type returns the PDF field type (/FT value). For list boxes, this is always "Ch" (choice).

func (*ListBox) Validate 

func (l *ListBox) Validate() error

Validate checks if the field configuration is valid.

Returns an error if:

  • Name is empty
  • Rectangle has invalid dimensions
  • Selected values are not in options
  • Multiple selections when MultiSelect is false

func (*ListBox) Value 

func (l *ListBox) Value() interface{}

Value returns the field's current selected value(s). For single-select, returns a string. For multi-select, returns []string.

type Option 

type Option struct {
	ExportValue  string // Value exported in form data
	DisplayValue string // Value displayed to user
}

Option represents a single option in a dropdown or listbox. It consists of an export value (used in form data) and a display value (shown to user).

type RadioGroup 

type RadioGroup struct {
	// contains filtered or unexported fields
}

RadioGroup represents a group of radio buttons in a PDF form.

Radio buttons allow users to select exactly one option from a group. They are button fields with /FT /Btn and radio-specific flags.

Unlike checkboxes, radio buttons are represented as a parent field with multiple child widget annotations (one per option).

Example: 

// Create radio group
gender := forms.NewRadioGroup("gender")
gender.AddOption("male", 100, 600, "Male")
gender.AddOption("female", 200, 600, "Female")
gender.AddOption("other", 300, 600, "Other")
gender.SetSelected("male")

// Styled radio group
priority := forms.NewRadioGroup("priority")
priority.AddOption("low", 100, 550, "Low")
priority.AddOption("medium", 200, 550, "Medium")
priority.AddOption("high", 300, 550, "High")
priority.SetBorderColor(0, 0, 0) // Black border
priority.SetFillColor(1, 1, 1)   // White background

PDF Structure: 

% Parent radio group
<< /FT /Btn
   /T (gender)                % Field name
   /V /male                   % Selected value
   /Ff 49152                  % Flags: Radio (32768) + NoToggleToOff (16384)
   /Kids [101 0 R 102 0 R 103 0 R]
>>

% Child widget (one per option)
101 0 obj
<< /Type /Annot
   /Subtype /Widget
   /Parent 100 0 R
   /T (male)
   /Rect [100 600 115 615]
   /AS /male                  % Appearance state
   /AP << /N << /male 10 0 R /Off 11 0 R >> >>
>>

func NewRadioGroup 

func NewRadioGroup(name string) *RadioGroup

NewRadioGroup creates a new radio button group.

Parameters:

  • name: Unique field name (used for form data)

Example: 

radioGroup := forms.NewRadioGroup("payment_method")

func (*RadioGroup) AddOption 

func (r *RadioGroup) AddOption(value string, x, y float64, label string, dimensions ...float64) *RadioGroup

AddOption adds a radio button option to the group.

Parameters:

  • value: Option value (e.g., "male", "female")
  • x: Left edge position in points
  • y: Bottom edge position in points
  • label: Display label (e.g., "Male", "Female")
  • width: Button width in points (default: 15)
  • height: Button height in points (default: 15)

The width and height are optional. If not provided, default to 15x15.

Example: 

gender.AddOption("male", 100, 600, "Male")
gender.AddOption("female", 200, 600, "Female")

func (*RadioGroup) BorderColor 

func (r *RadioGroup) BorderColor() *[3]float64

BorderColor returns the border color (nil if no border).

func (*RadioGroup) DefaultValue 

func (r *RadioGroup) DefaultValue() interface{}

DefaultValue returns the field's default selected value.

func (*RadioGroup) FillColor 

func (r *RadioGroup) FillColor() *[3]float64

FillColor returns the fill color (nil if transparent).

func (*RadioGroup) Flags 

func (r *RadioGroup) Flags() int

Flags returns the field flags bitmask. For radio buttons, this includes FlagRadio and FlagNoToggleToOff.

func (*RadioGroup) IsReadOnly 

func (r *RadioGroup) IsReadOnly() bool

IsReadOnly returns true if the field is read-only.

func (*RadioGroup) IsRequired 

func (r *RadioGroup) IsRequired() bool

IsRequired returns true if the field is required.

func (*RadioGroup) Name 

func (r *RadioGroup) Name() string

Name returns the field name.

func (*RadioGroup) Options 

func (r *RadioGroup) Options() []*RadioOption

Options returns all radio button options.

func (*RadioGroup) Rect 

func (r *RadioGroup) Rect() [4]float64

Rect returns the bounding rectangle of the first option. For radio groups with multiple options, this returns the rect of the first option. PDF viewers typically ignore this for parent fields with /Kids.

func (*RadioGroup) Selected 

func (r *RadioGroup) Selected() string

Selected returns the currently selected option value.

func (*RadioGroup) SetAllowToggleOff 

func (r *RadioGroup) SetAllowToggleOff(allow bool) *RadioGroup

SetAllowToggleOff allows deselecting all radio buttons.

By default (NoToggleToOff flag), once a radio button is selected, the user cannot deselect all options. Setting this to true removes that restriction.

Example: 

radioGroup.SetAllowToggleOff(true)  // Allow deselecting all

func (*RadioGroup) SetBorderColor 

func (r *RadioGroup) SetBorderColor(rgbPtr ...*float64) error

SetBorderColor sets the border color for all radio buttons (RGB, 0.0-1.0 range).

Set to nil to remove border.

Example: 

r, g, b := 0.0, 0.0, 0.0
radioGroup.SetBorderColor(&r, &g, &b)  // Black border

func (*RadioGroup) SetDefaultSelected 

func (r *RadioGroup) SetDefaultSelected(value string) error

SetDefaultSelected sets the default selected option.

This is used when the form is reset.

Example: 

gender.SetDefaultSelected("male")

func (*RadioGroup) SetFillColor 

func (r *RadioGroup) SetFillColor(rgbPtr ...*float64) error

SetFillColor sets the background fill color for all radio buttons (RGB, 0.0-1.0 range).

Set to nil for transparent background.

Example: 

r, g, b := 1.0, 1.0, 1.0
radioGroup.SetFillColor(&r, &g, &b)  // White background

func (*RadioGroup) SetReadOnly 

func (r *RadioGroup) SetReadOnly(readonly bool) *RadioGroup

SetReadOnly sets whether the field is read-only.

Example: 

radioGroup.SetReadOnly(true)  // Field cannot be changed

func (*RadioGroup) SetRequired 

func (r *RadioGroup) SetRequired(required bool) *RadioGroup

SetRequired sets whether the field is required.

Example: 

radioGroup.SetRequired(true)  // User must select an option

func (*RadioGroup) SetSelected 

func (r *RadioGroup) SetSelected(value string) error

SetSelected sets the currently selected option.

The value must match one of the option values added via AddOption. If the value doesn't exist, this method does nothing.

Example: 

gender.SetSelected("male")

func (*RadioGroup) Type 

func (r *RadioGroup) Type() string

Type returns the PDF field type (/FT value). For radio buttons, this is always "Btn" (button).

func (*RadioGroup) Validate 

func (r *RadioGroup) Validate() error

Validate checks if the field configuration is valid.

Returns an error if:

  • Name is empty
  • No options have been added
  • Any option has an invalid rectangle
  • Selected value doesn't match any option

func (*RadioGroup) Value 

func (r *RadioGroup) Value() interface{}

Value returns the field's current selected value. For radio buttons, this is the value of the selected option (e.g., "male"). Returns empty string if no option is selected.

type RadioOption 

type RadioOption struct {
	// contains filtered or unexported fields
}

RadioOption represents a single radio button option.

func (*RadioOption) Label 

func (o *RadioOption) Label() string

Label returns the option label.

func (*RadioOption) Rect 

func (o *RadioOption) Rect() [4]float64

Rect returns the option rectangle [x1, y1, x2, y2].

func (*RadioOption) Value 

func (o *RadioOption) Value() string

Value returns the option value.

type TextField 

type TextField struct {
	// contains filtered or unexported fields
}

TextField represents a text input field in a PDF form.

Text fields allow users to enter single-line or multi-line text. They support various options like readonly, required, password masking, and multiline input.

Example: 

// Single-line text field
nameField := forms.NewTextField("name", 100, 700, 200, 20)
nameField.SetValue("John Doe")
nameField.SetPlaceholder("Enter your name")
nameField.SetRequired(true)

// Multi-line text area
commentField := forms.NewTextField("comment", 100, 600, 200, 80)
commentField.SetMultiline(true)
commentField.SetValue("Enter your comments here...")

PDF Structure: 

<< /Type /Annot
   /Subtype /Widget
   /FT /Tx                  % Field Type: Text
   /T (name)                % Field name
   /V (John Doe)            % Field value
   /DV (Enter your name)    % Default value (placeholder)
   /Rect [100 700 300 720]  % Position
   /F 4                     % Print flag
   /Ff 2                    % Field flags (required)
   /DA (/Helv 12 Tf 0 g)    % Default appearance
>>

func NewTextField 

func NewTextField(name string, x, y, width, height float64) *TextField

NewTextField creates a new text field at the specified position.

Parameters:

  • name: Unique field name (used for form data)
  • x: Left edge position in points
  • y: Bottom edge position in points
  • width: Field width in points
  • height: Field height in points

Example: 

field := forms.NewTextField("email", 100, 700, 200, 20)

func (*TextField) BorderColor 

func (t *TextField) BorderColor() *[3]float64

BorderColor returns the border color (nil if no border).

func (*TextField) DefaultValue 

func (t *TextField) DefaultValue() interface{}

DefaultValue returns the field's default value.

func (*TextField) FillColor 

func (t *TextField) FillColor() *[3]float64

FillColor returns the fill color (nil if transparent).

func (*TextField) Flags 

func (t *TextField) Flags() int

Flags returns the field flags bitmask.

func (*TextField) FontName 

func (t *TextField) FontName() string

FontName returns the font name.

func (*TextField) FontSize 

func (t *TextField) FontSize() float64

FontSize returns the font size.

func (*TextField) IsMultiline 

func (t *TextField) IsMultiline() bool

IsMultiline returns true if the field allows multiple lines.

func (*TextField) IsPassword 

func (t *TextField) IsPassword() bool

IsPassword returns true if the field masks text as password.

func (*TextField) IsReadOnly 

func (t *TextField) IsReadOnly() bool

IsReadOnly returns true if the field is read-only.

func (*TextField) IsRequired 

func (t *TextField) IsRequired() bool

IsRequired returns true if the field is required.

func (*TextField) MaxLength 

func (t *TextField) MaxLength() int

MaxLength returns the maximum character length (0 = unlimited).

func (*TextField) Name 

func (t *TextField) Name() string

Name returns the field name.

func (*TextField) Rect 

func (t *TextField) Rect() [4]float64

Rect returns the field's bounding rectangle [x1, y1, x2, y2].

func (*TextField) SetBorderColor 

func (t *TextField) SetBorderColor(r, g, b *float64) error

SetBorderColor sets the border color (RGB, 0.0-1.0 range).

Set to nil to remove border.

Example: 

field.SetBorderColor(0, 0, 0)  // Black border

func (*TextField) SetFillColor 

func (t *TextField) SetFillColor(r, g, b *float64) error

SetFillColor sets the background fill color (RGB, 0.0-1.0 range).

Set to nil for transparent background.

Example: 

field.SetFillColor(1, 1, 1)  // White background

func (*TextField) SetFontName 

func (t *TextField) SetFontName(name string) *TextField

SetFontName sets the font name.

Common values: "Helvetica", "Courier", "Times-Roman"

Example: 

field.SetFontName("Courier")

func (*TextField) SetFontSize 

func (t *TextField) SetFontSize(size float64) error

SetFontSize sets the font size for the text.

Example: 

field.SetFontSize(14)

func (*TextField) SetMaxLength 

func (t *TextField) SetMaxLength(length int) error

SetMaxLength sets the maximum character length for the field.

Set to 0 for unlimited length.

Example: 

field.SetMaxLength(50)  // Max 50 characters

func (*TextField) SetMultiline 

func (t *TextField) SetMultiline(multiline bool) *TextField

SetMultiline sets whether the field allows multiple lines.

Example: 

field.SetMultiline(true)  // Text area (multiple lines)

func (*TextField) SetPassword 

func (t *TextField) SetPassword(password bool) *TextField

SetPassword sets whether the field masks text as password.

Example: 

field.SetPassword(true)  // Show *** instead of text

func (*TextField) SetPlaceholder 

func (t *TextField) SetPlaceholder(placeholder string) *TextField

SetPlaceholder sets the field's placeholder (default value).

The placeholder is shown when the field is empty.

Example: 

field.SetPlaceholder("Enter your name")

func (*TextField) SetReadOnly 

func (t *TextField) SetReadOnly(readonly bool) *TextField

SetReadOnly sets whether the field is read-only.

Example: 

field.SetReadOnly(true)  // Field cannot be edited

func (*TextField) SetRequired 

func (t *TextField) SetRequired(required bool) *TextField

SetRequired sets whether the field is required.

Example: 

field.SetRequired(true)  // Field must be filled

func (*TextField) SetTextColor 

func (t *TextField) SetTextColor(r, g, b float64) error

SetTextColor sets the text color (RGB, 0.0-1.0 range).

Example: 

field.SetTextColor(0, 0, 1)  // Blue text

func (*TextField) SetValue 

func (t *TextField) SetValue(value string) *TextField

SetValue sets the field's current value.

Example: 

field.SetValue("John Doe")

func (*TextField) TextColor 

func (t *TextField) TextColor() [3]float64

TextColor returns the text color.

func (*TextField) Type 

func (t *TextField) Type() string

Type returns the PDF field type (/FT value). For text fields, this is always "Tx".

func (*TextField) Validate 

func (t *TextField) Validate() error

Validate checks if the field configuration is valid.

Returns an error if:

  • Name is empty
  • Rectangle has invalid dimensions
  • Value exceeds max length

func (*TextField) Value 

func (t *TextField) Value() interface{}

Value returns the field's current value.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.