oc

package
v0.7.1 Latest Latest
Warning

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

 Go to latest Published: Mar 31, 2026 License: GPL-3.0 Imports: 7 Imported by: 0

Documentation

Overview

Package oc implements optional content (PDF 1.5, section 8.11), the mechanism behind layers in PDF documents. Optional content allows parts of a document to be selectively viewed or hidden.

The main types are:

  • Group is a named toggle that controls visibility of associated content.
  • Membership computes visibility from a boolean combination of groups.
  • Configuration defines initial group states and UI presentation.
  • Properties is the top-level container stored in the document catalog.

A Group or Membership (both implement Conditional) is associated with content via marked content sequences (BDC/EMC) in content streams.

Group visibility is tracked as a GroupStates value. Use Configuration.DefaultState to compute initial states from a configuration. Groups whose intent does not match the configuration are excluded from the state, so they have no effect on visibility.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BaseState added in v0.7.1 

type BaseState pdf.Name

BaseState controls the initial group states when a configuration is applied. 

const (
	// BaseStateON sets all groups to ON.
	BaseStateON BaseState = "ON"

	// BaseStateOFF sets all groups to OFF.
	BaseStateOFF BaseState = "OFF"

	// BaseStateUnchanged leaves all group states unchanged.
	BaseStateUnchanged BaseState = "Unchanged"
)

type Category added in v0.7.1 

type Category pdf.Name

Category specifies which usage dictionary entry to consult. 

const (
	// CategoryCreatorInfo specifies the CreatorInfo usage dictionary entry.
	CategoryCreatorInfo Category = "CreatorInfo"

	// CategoryLanguage specifies the Language usage dictionary entry.
	CategoryLanguage Category = "Language"

	// CategoryExport specifies the Export usage dictionary entry.
	CategoryExport Category = "Export"

	// CategoryZoom specifies the Zoom usage dictionary entry.
	CategoryZoom Category = "Zoom"

	// CategoryPrint specifies the Print usage dictionary entry.
	CategoryPrint Category = "Print"

	// CategoryView specifies the View usage dictionary entry.
	CategoryView Category = "View"

	// CategoryUser specifies the User usage dictionary entry.
	CategoryUser Category = "User"

	// CategoryPageElement specifies the PageElement usage dictionary entry.
	CategoryPageElement Category = "PageElement"
)

type Conditional 

type Conditional interface {
	property.List
	IsVisible(*GroupStates) bool
}

Conditional represents an optional content element that controls visibility based on conditions. This must be either a Group or a Membership object.

func ExtractConditional 

func ExtractConditional(x *pdf.Extractor, path *pdf.CycleCheck, obj pdf.Object, _ bool) (Conditional, error)

ExtractConditional extracts an optional content element from a PDF object. The object can be either a Group (OCG) or a Membership (OCMD) dictionary.

type Configuration 

type Configuration struct {
	// Name (optional) is a name for the configuration, suitable for
	// presentation in a user interface.
	Name string

	// Creator (optional) is the name of the application or feature that
	// created this configuration dictionary.
	Creator string

	// BaseState (optional) controls initial group states when this
	// configuration is applied.
	// When encoding, an empty value is treated as BaseStateON.
	BaseState BaseState

	// ON (optional) lists groups forced ON after BaseState is applied.
	ON []*Group

	// OFF (optional) lists groups forced OFF after BaseState is applied.
	OFF []*Group

	// Intent (optional) lists intents to consider when determining visibility.
	// Content controlled by groups with no matching intent is always shown.
	// The special value "All" matches every group intent.
	//
	// On write, nil can be used as a shorthand for "View".
	Intent []pdf.Name

	// AS (optional) lists usage application dictionaries for automatic
	// state management.
	AS []*UsageApplication

	// Order (optional) specifies the presentation hierarchy for a user interface.
	Order []OrderItem

	// ListMode (optional) controls which groups are displayed.
	// When encoding, an empty value is treated as ListModeAllPages.
	ListMode ListMode

	// RBGroups (optional) lists collections of groups that follow a
	// radio-button paradigm.
	RBGroups [][]*Group

	// Locked (optional, PDF 1.6) lists groups locked in the user interface.
	Locked []*Group

	// SingleUse determines if Embed returns a dictionary (true) or
	// a reference (false).
	SingleUse bool
}

Configuration represents an optional content configuration dictionary that specifies initial states and display settings for optional content groups. This corresponds to Table 99 in the PDF specification.

func ExtractConfiguration added in v0.7.1 

func ExtractConfiguration(x *pdf.Extractor, path *pdf.CycleCheck, obj pdf.Object, isDirect bool) (*Configuration, error)

ExtractConfiguration extracts an optional content configuration dictionary from a PDF object.

func (*Configuration) ApplyViewUsage added in v0.7.1 

func (c *Configuration) ApplyViewUsage(state *GroupStates, ctx *ViewerContext)

ApplyViewUsage re-evaluates all View-event AS dicts with runtime context and updates the state accordingly. Groups with manual overrides are not affected.

If ctx is nil, this is a no-op.

func (*Configuration) DefaultState added in v0.7.1 

func (c *Configuration) DefaultState(allGroups []*Group, event Event, prior *GroupStates) *GroupStates

DefaultState computes the initial group visibility from this configuration. It applies BaseState to allGroups, then ON/OFF overrides, then AS usage applications for the given event. Groups whose intent does not match the configuration's intent are removed so they have no effect on visibility. If allGroups is nil, BaseState has no effect and only groups explicitly listed in ON, OFF, or AS are included.

The prior parameter provides the group states from the previously active configuration. It is used when BaseState is Unchanged (alternate configs only). If prior is nil, Unchanged is treated as ON.

func (*Configuration) Embed added in v0.7.1 

func (c *Configuration) Embed(rm *pdf.EmbedHelper) (pdf.Native, error)

Embed adds the configuration dictionary to a PDF file.

type Event added in v0.7.1 

type Event pdf.Name

Event specifies when usage application settings should be applied. 

const (
	// EventView applies when the document is being viewed interactively.
	EventView Event = "View"

	// EventPrint applies when the document is being printed.
	EventPrint Event = "Print"

	// EventExport applies when the document is being exported.
	EventExport Event = "Export"
)

type Group 

type Group struct {
	// Name specifies the name of the optional content group, suitable for
	// presentation in an interactive PDF processor's user interface.
	Name string

	// Intent (optional) represents the intended use of the graphics in the group.
	// Common values include "View" and "Design". Default is ["View"].
	Intent []pdf.Name

	// Usage (optional) describes the nature of the content controlled by the group.
	// It may be used by features that automatically control the group state.
	Usage *Usage
}

Group represents an optional content group dictionary that defines a collection of graphics that can be made visible or invisible dynamically by PDF processors. This corresponds to Table 96 in the PDF specification.

func ExtractGroup 

func ExtractGroup(x *pdf.Extractor, path *pdf.CycleCheck, obj pdf.Object, _ bool) (*Group, error)

ExtractGroup extracts an optional content group from a PDF object.

func (*Group) AsDirectDict added in v0.7.1 

func (g *Group) AsDirectDict() pdf.Dict

AsDirectDict returns nil since optional content groups are always indirect.

func (*Group) Embed 

func (g *Group) Embed(rm *pdf.EmbedHelper) (pdf.Native, error)

Embed adds the optional content group to a PDF file.

func (*Group) Equal added in v0.7.1 

func (g *Group) Equal(other property.List) bool

Equal reports whether two property lists are semantically equal.

func (*Group) IsVisible 

func (g *Group) IsVisible(s *GroupStates) bool

IsVisible returns whether the group is visible given a state.

type GroupStates added in v0.7.1 

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

GroupStates tracks the visibility state of optional content groups. Groups present in the map participate in visibility decisions; groups absent from the map have no effect on visibility (always shown).

func (*GroupStates) Clone added in v0.7.1 

func (s *GroupStates) Clone() *GroupStates

Clone returns a deep copy of the state.

func (*GroupStates) IsManual added in v0.7.1 

func (s *GroupStates) IsManual(g *Group) bool

IsManual reports whether the group was set manually by the user.

func (*GroupStates) IsOn added in v0.7.1 

func (s *GroupStates) IsOn(g *Group) bool

IsOn returns whether the group is visible. Groups not participating in this state (absent from the map) are treated as visible.

func (*GroupStates) Participates added in v0.7.1 

func (s *GroupStates) Participates(g *Group) bool

Participates reports whether the group takes part in visibility decisions.

func (*GroupStates) SetManualState added in v0.7.1 

func (s *GroupStates) SetManualState(g *Group, on bool)

SetManualState sets the visibility of a group and marks it as manually overridden by the user. Groups with manual overrides are not affected by Configuration.ApplyViewUsage.

func (*GroupStates) SetState added in v0.7.1 

func (s *GroupStates) SetState(g *Group, on bool)

SetState sets the visibility of a group, making it participate.

type ListMode added in v0.7.1 

type ListMode pdf.Name

ListMode controls which groups in the Order array are displayed to the user. 

const (
	// ListModeAllPages displays all groups in the Order array.
	ListModeAllPages ListMode = "AllPages"

	// ListModeVisiblePages displays only groups referenced by visible pages.
	ListModeVisiblePages ListMode = "VisiblePages"
)

type Membership 

type Membership struct {
	// OCGs (optional) specifies the optional content groups whose states
	// determine the visibility of content controlled by this membership dictionary.
	//
	// If VE is present, this entry is ignored.
	OCGs []*Group

	// Policy specifies the visibility policy for content belonging to this
	// membership dictionary. Valid values are [PolicyAllOn], [PolicyAnyOn],
	// [PolicyAnyOff], [PolicyAllOff].
	//
	// If VE is present, this entry is ignored.
	Policy MembershipPolicy

	// VE (optional) specifies a visibility expression for computing
	// visibility based on a set of optional content groups.
	//
	// If present, this takes precedence over OCGs and Policy.
	VE VisibilityExpression

	// SingleUse determines if Embed returns a dictionary (true) or
	// a reference (false).
	SingleUse bool
}

Membership represents an optional content membership dictionary that expresses complex visibility policies for content based on optional content groups. This corresponds to Table 97 in the PDF specification.

func ExtractMembership 

func ExtractMembership(x *pdf.Extractor, path *pdf.CycleCheck, obj pdf.Object, isDirect bool) (*Membership, error)

ExtractMembership extracts an optional content membership dictionary from a PDF object.

func (*Membership) AsDirectDict added in v0.7.1 

func (m *Membership) AsDirectDict() pdf.Dict

AsDirectDict returns nil since membership dictionaries are always indirect.

func (*Membership) Embed 

func (m *Membership) Embed(rm *pdf.EmbedHelper) (pdf.Native, error)

Embed converts the Membership to a PDF object.

func (*Membership) Equal added in v0.7.1 

func (m *Membership) Equal(other property.List) bool

Equal reports whether two property lists are semantically equal.

func (*Membership) IsVisible 

func (m *Membership) IsVisible(s *GroupStates) bool

IsVisible evaluates the visibility of content controlled by this membership dictionary based on the current state of optional content groups. Groups that do not participate in the state are filtered out before evaluating the policy; if no groups remain, the content is visible.

type MembershipPolicy added in v0.7.1 

type MembershipPolicy pdf.Name

MembershipPolicy represents the visibility policy for an optional content membership dictionary. 

const (
	// PolicyAllOn means visible only if all OCGs are ON.
	PolicyAllOn MembershipPolicy = "AllOn"

	// PolicyAnyOn means visible if any of the OCGs are ON (default).
	PolicyAnyOn MembershipPolicy = "AnyOn"

	// PolicyAnyOff means visible if any of the OCGs are OFF.
	PolicyAnyOff MembershipPolicy = "AnyOff"

	// PolicyAllOff means visible only if all OCGs are OFF.
	PolicyAllOff MembershipPolicy = "AllOff"
)

type OrderGroup added in v0.7.1 

type OrderGroup struct {
	// Label (optional) is a non-selectable text label for this sub-group.
	Label string

	// Children contains the nested groups and sub-groups.
	Children []OrderItem
}

OrderGroup represents a labeled nested array in the Order hierarchy.

type OrderItem added in v0.7.1 

type OrderItem interface {
	// contains filtered or unexported methods
}

OrderItem represents an item in the Order array of an optional content configuration dictionary. It is either a *Group or an *OrderGroup.

type PageElement 

type PageElement string

PageElement represents the subtype of a page element. 

const (
	// PageElementHeaderFooter represents header/footer content.
	PageElementHeaderFooter PageElement = "HF"

	// PageElementForeground represents foreground image or graphics.
	PageElementForeground PageElement = "FG"

	// PageElementBackground represents background image or graphics.
	PageElementBackground PageElement = "BG"

	PageElementLogo PageElement = "L"
)

type PrintSubtype 

type PrintSubtype string

PrintSubtype represents the kind of content controlled by a print usage dictionary. 

const (
	// PrintSubtypeTrapping represents trapping content.
	PrintSubtypeTrapping PrintSubtype = "Trapping"

	// PrintSubtypePrintersMarks represents printer's marks.
	PrintSubtypePrintersMarks PrintSubtype = "PrintersMarks"

	// PrintSubtypeWatermark represents watermark content.
	PrintSubtypeWatermark PrintSubtype = "Watermark"
)

type Properties 

type Properties struct {
	// OCGs lists all optional content groups in the document.
	OCGs []*Group

	// D is the default configuration, defining initial group states
	// and UI presentation.
	D *Configuration

	// Configs (optional) lists alternate configurations.
	Configs []*Configuration
}

Properties represents the optional content properties dictionary that contains all optional content groups and their configurations. This corresponds to Table 98 in the PDF specification.

func ExtractProperties added in v0.7.1 

func ExtractProperties(x *pdf.Extractor, path *pdf.CycleCheck, obj pdf.Object, _ bool) (*Properties, error)

ExtractProperties extracts an optional content properties dictionary from a PDF object.

func (*Properties) Embed added in v0.7.1 

func (p *Properties) Embed(rm *pdf.EmbedHelper) (pdf.Native, error)

Embed adds the properties dictionary to a PDF file.

type StateRec added in v0.7.1 

type StateRec int

StateRec represents an optional ON/OFF state recommendation. The zero value means no recommendation. 

const (
	// StateUnset indicates no state recommendation (leave unchanged).
	StateUnset StateRec = iota

	// StateON recommends that the group be ON.
	StateON

	// StateOFF recommends that the group be OFF.
	StateOFF
)

func (StateRec) IsOn added in v0.7.1 

func (s StateRec) IsOn() bool

IsOn reports whether the recommendation is ON. Returns false for StateOFF and StateUnset.

type Usage 

type Usage struct {
	// Creator (optional) contains application-specific data associated with this group.
	Creator *UsageCreator

	// Language (optional) specifies the language of the content controlled by this group.
	Language *UsageLanguage

	// Export (optional) contains export state configuration.
	Export *UsageExport

	// Zoom (optional) specifies a range of magnifications at which content is best viewed.
	Zoom *UsageZoom

	// Print (optional) specifies content to be used when printing.
	Print *UsagePrint

	// View (optional) contains view state information.
	View *UsageView

	// User (optional) specifies users for whom this group is primarily intended.
	User *UsageUser

	// PageElement (optional) declares that the group contains a pagination artifact.
	PageElement *UsagePageElement

	// SingleUse determines if Embed returns a dictionary (true) or
	// a reference (false).
	SingleUse bool
}

Usage represents an optional content usage dictionary that contains information describing the nature of the content controlled by an optional content group. This corresponds to Table 100 in the PDF specification.

func ExtractUsage 

func ExtractUsage(x *pdf.Extractor, path *pdf.CycleCheck, obj pdf.Object, isDirect bool) (*Usage, error)

ExtractUsage extracts a usage dictionary from a PDF object.

func (*Usage) Embed 

func (u *Usage) Embed(rm *pdf.EmbedHelper) (pdf.Native, error)

Embed adds the usage dictionary to a PDF file.

type UsageApplication 

type UsageApplication struct {
	// Event specifies when to apply: View, Print, or Export.
	Event Event

	// OCGs (optional) lists the optional content groups to manage.
	OCGs []*Group

	// Category lists which usage dictionary entries to consult.
	Category []Category

	// SingleUse determines if Embed returns a dictionary (true) or
	// a reference (false). Typically this should be true since usage
	// application dictionaries are usually embedded directly in the AS array.
	SingleUse bool
}

UsageApplication specifies rules for automatically managing optional content group states based on external factors such as zoom level, language, or whether the document is being viewed, printed, or exported. This corresponds to Table 101 in the PDF specification.

func ExtractUsageApplication added in v0.7.1 

func ExtractUsageApplication(x *pdf.Extractor, path *pdf.CycleCheck, obj pdf.Object, isDirect bool) (*UsageApplication, error)

ExtractUsageApplication extracts a usage application dictionary from a PDF object.

func (*UsageApplication) Embed added in v0.7.1 

func (ua *UsageApplication) Embed(rm *pdf.EmbedHelper) (pdf.Native, error)

Embed adds the usage application dictionary to a PDF file.

type UsageCreator 

type UsageCreator struct {
	// Creator specifies the application that created the group.
	Creator string

	// Subtype defines the type of content controlled by the group.
	// Suggested values include "Artwork" for graphic-design or publishing applications,
	// and "Technical" for technical designs such as building plans or schematics.
	Subtype pdf.Name

	// AdditionalInfo may contain additional entries relevant to the creating application.
	AdditionalInfo pdf.Dict
}

UsageCreator contains information about the application that created an optional content group.

type UsageExport 

type UsageExport struct {
	// ExportState indicates the recommended state for content when the document
	// is saved to a format that does not support optional content.
	ExportState StateRec
}

UsageExport contains export state information.

type UsageLanguage 

type UsageLanguage struct {
	// Lang specifies a language and possibly a locale.
	Lang language.Tag

	// Preferred indicates whether this language should be used when there is a partial
	// match but no exact match between the system language and available languages.
	Preferred bool
}

UsageLanguage specifies the language of the content controlled by an optional content group.

type UsagePageElement 

type UsagePageElement struct {
	// Subtype specifies the type of pagination artifact.
	Subtype PageElement
}

UsagePageElement declares that a group contains a pagination artifact.

type UsagePrint 

type UsagePrint struct {
	// Subtype specifies the kind of content controlled by the group.
	Subtype PrintSubtype

	// PrintState indicates whether the group shall be ON or OFF when printing.
	// StateUnset means leave unchanged.
	PrintState StateRec
}

UsagePrint specifies content to be used when printing.

type UsageUser 

type UsageUser struct {
	// Type specifies whether Name refers to an individual, title/position, or organisation.
	Type UserType

	// Name represents the name(s) of the individual, position or organisation.
	Name []string
}

UsageUser specifies users for whom an optional content group is primarily intended.

type UsageView 

type UsageView struct {
	// ViewState indicates the state of the group when the document is first opened.
	// StateUnset means leave unchanged.
	ViewState StateRec
}

UsageView contains view state information.

type UsageZoom 

type UsageZoom struct {
	// Min is the minimum recommended magnification factor at which the group shall be ON.
	Min float64

	// Max is the magnification factor below which the group shall be ON.
	Max float64
}

UsageZoom specifies a range of magnifications at which content is best viewed.

type UserType 

type UserType string

UserType represents the type of user in a usage dictionary. 

const (
	// UserTypeIndividual represents an individual user.
	UserTypeIndividual UserType = "Ind"

	// UserTypeTitle represents a title or position.
	UserTypeTitle UserType = "Ttl"

	// UserTypeOrganisation represents an organisation.
	UserTypeOrganisation UserType = "Org"
)

type ViewerContext added in v0.7.1 

type ViewerContext struct {
	// Zoom is the user-facing magnification factor.
	// Zero means skip zoom evaluation.
	Zoom float64

	// Lang is the system locale. language.Und means skip language evaluation.
	Lang language.Tag

	// UserName is the current user's name. Empty means skip user evaluation.
	UserName string

	// UserType filters the user match to a specific type.
	// Empty means match any type.
	UserType UserType
}

ViewerContext provides runtime information needed to evaluate Zoom, Language, and User usage categories.

type VisibilityExpression 

type VisibilityExpression interface {
	pdf.Embedder
	// contains filtered or unexported methods
}

VisibilityExpression represents a PDF visibility expression for optional content. This must be one of:

func ExtractVisibilityExpression 

func ExtractVisibilityExpression(x *pdf.Extractor, path *pdf.CycleCheck, obj pdf.Object, _ bool) (VisibilityExpression, error)

ExtractVisibilityExpression reads a visibility expression from a PDF object. The object can be either an array (for And/Or/Not expressions) or a dictionary (for a single optional content group reference).

type VisibilityExpressionAnd 

type VisibilityExpressionAnd struct {
	Args []VisibilityExpression
}

VisibilityExpressionAnd represents a logical AND of multiple visibility expressions.

func (*VisibilityExpressionAnd) Embed 

func (a *VisibilityExpressionAnd) Embed(e *pdf.EmbedHelper) (pdf.Native, error)

Embed converts the AND expression to a PDF array.

type VisibilityExpressionGroup 

type VisibilityExpressionGroup struct {
	Group *Group
}

VisibilityExpressionGroup represents a visibility expression that references a single group.

func (*VisibilityExpressionGroup) Embed 

func (g *VisibilityExpressionGroup) Embed(e *pdf.EmbedHelper) (pdf.Native, error)

Embed converts the group reference to a PDF object reference.

type VisibilityExpressionNot 

type VisibilityExpressionNot struct {
	Arg VisibilityExpression
}

VisibilityExpressionNot represents a logical NOT of a single visibility expression.

func (*VisibilityExpressionNot) Embed 

func (n *VisibilityExpressionNot) Embed(e *pdf.EmbedHelper) (pdf.Native, error)

Embed converts the NOT expression to a PDF array.

type VisibilityExpressionOr 

type VisibilityExpressionOr struct {
	Args []VisibilityExpression
}

VisibilityExpressionOr represents a logical OR of multiple visibility expressions.

func (*VisibilityExpressionOr) Embed 

func (o *VisibilityExpressionOr) Embed(e *pdf.EmbedHelper) (pdf.Native, error)

Embed converts the OR expression to a PDF array.

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.