GetTextBlockCharContentLocation

Text, Extraction, Content streams, Diagnostics

Description

Returns the stable content-stream location and encoded source-byte range associated with one extracted character

Syntax

Delphi

Function TPDFlib.GetTextBlockCharContentLocation(TextBlockListID, Index,
  CharIndex: Integer; Out ContentLayer, StreamObjectNumber,
  StreamGeneration, InstructionIndex, OperandIndex, ArrayElementIndex,
  SourceByteOffset, SourceByteLength, Flags: Integer): Integer;

Parameters

TextBlockListID	Handle returned by `ExtractPageTextBlocks`
Index	1-based text block index
CharIndex	1-based UTF-16 code-unit position inside the block text
ContentLayer	1-based page `/Contents` layer, or 0 for nested content
StreamObjectNumber	Object number of the containing stream, or 0 for a direct stream
StreamGeneration	Generation number of the containing stream
InstructionIndex	0-based instruction index in the decoded content program
OperandIndex	0-based text-string operand index
ArrayElementIndex	0-based `TJ` array element, or -1 for a direct string operand
SourceByteOffset	0-based offset in the decoded string value, or -1 when no safely addressable range exists
SourceByteLength	Number of encoded source bytes for the source glyph, or 0 when no safely addressable range exists
Flags	Bitwise content-location flags described below

Return values

1	A location record was returned, including synthetic or read-only records
0	The handle, block index or character index is invalid

Flags

`PDF_TEXT_CHAR_CONTENT_LOCATION_VALID`	The byte range identifies a content string, subject to any read-only flags
`PDF_TEXT_CHAR_CONTENT_LOCATION_GENERATED`	The character was generated during layout and has no source bytes
`PDF_TEXT_CHAR_CONTENT_LOCATION_LIGATURE`	Multiple extracted UTF-16 positions share one source glyph range
`PDF_TEXT_CHAR_CONTENT_LOCATION_ACTUALTEXT`	The character came from an `/ActualText` replacement and is read-only
`PDF_TEXT_CHAR_CONTENT_LOCATION_NESTED`	The character came from nested Form content and is read-only
`PDF_TEXT_CHAR_CONTENT_LOCATION_CROSS_LAYER`	The operand and text-showing operator cross page content layers and are read-only
`PDF_TEXT_CHAR_CONTENT_LOCATION_TRANSCODED`	The source string was transcoded before font mapping, so decoded offsets cannot address its original bytes safely

Remarks

Offsets address decoded font-encoded string bytes rather than Unicode text

Supplementary characters and ligature expansions may return the same source range for more than one UTF-16 position

Use ReplaceTextBlockCharSourceBytes only when the valid flag is set and none of the read-only flags is present

Location lookup uses extraction-time spans and does not reparse page content