LayerPD_Layer
ObjectPDTextSelect

PDTextSelect objects represent a selection of text on a single page, and may contain more than one disjointed group of words. A text selection contains one or more ranges of text, with each range containing the word numbers (in PDF order, as returned by PDWordFinderEnumWords() or PDWordFinderAcquireWordList()) of the selected words. Each range has a start word (the first word in the series) and an end word (the first word not in the series).

PDTextSelect methods are useful for:

You can manipulate text selections using the PDTextSelectRangeRec data structure. This structure contains two start/end pairs:

To create a selection, plug-ins can:

While character offsets are well-defined quantities in a PDF file, word numbers are calculated by the PDWordFinder algorithm and, therefore, may change as the word finder algorithm is improved in future versions. Because of this, long-term storage of selection information (for example, in custom annotations) is safer if done with page-relative character offsets and PDTextSelectCreatePageHilite().

Once a plug-in creates a text selection, it can make it the current selection using AVDocSetSelection().



Define Summary
 Define
 PDTextSelectCreatePageHilite
 PDTextSelectCreateRanges
 PDTextSelectCreateWordHilite
 PDTextSelectEnumQuads
 PDTextSelectEnumText
 PDTextSelectGetBoundingRect
Typedef Summary
 Typedef
 PDTextSelect
A pointer to a PDTextSelect struct.
 PDTextSelectRange
 PDTextSelectRangeRec
Structure Summary
 Structure
 _t_PDTextSelectRange
A data structure used to specify a range of text in a text selection.
Callback Summary
 Callback
 PDTextSelectEnumQuadProc
A callback for PDTextSelectEnumQuads(). It is called once for each quad in a text selection.
 PDTextSelectEnumRTFTextProc
 PDTextSelectEnumTextProc
A callback for PDTextSelectEnumText() and PDTextSelectEnumTextUCS(). It is called once for each text run (which is text in the same font, size, color, and on the same line) in a text selection.
Method Summary
 Method
 
PDTextSelect PDTextSelectCreatePageHilite(PDPage page, HiliteEntry* hList, ASInt32 listLen)
Creates a text selection from a page and a list of highlights specified as character offsets from the start of the page. Character offsets are a well-defined quantity in the PDF file, and are therefore stable against revisions of the word-finding algorithm, which makes them a good way to isolate yourself from changes in the algorithm.
 
PDTextSelect PDTextSelectCreatePageHiliteEx(PDPage page, HiliteEntry* hList, ASInt32 listLen, ASInt16 WFVersion)
Adds the WFVersion parameter to PDTextSelectCreatePageHilite(). It is the same as PDTextSelectCreatePageHilite(), but it creates a WordFinder using the specified version number. It is intended to be used by plug-ins that want to do text highlighting with previous versions of the word finder algorithm.
 
PDTextSelect PDTextSelectCreateRanges(PDPage page, PDTextSelectRange range, ASInt32 rangeCount)
Creates a text selection from one or more ranges.
 
PDTextSelect PDTextSelectCreateRangesEx(PDPage page, PDTextSelectRange range, ASInt32 rangeCount, ASInt16 WFVersion)
Adds the WFVersion parameter to PDTextSelectCreateRanges(). It is the same as PDTextSelectCreateRanges() but it creates a WordFinder using the specified version number. It is intended to be used by plug-ins that want to do text highlighting with previous versions of the word finder algorithm.
 
PDTextSelect PDTextSelectCreateWordHilite(PDPage page, HiliteEntry* hList, ASInt32 listLen)
Creates a text selection from a list of highlights specified as word offsets from the start of the page. Word offsets are not well-defined in PDF files, but are calculated by the word-finding algorithm. As a result, word offsets will, in general, differ in different versions of the word-finding algorithm. If you choose to store word offsets, you must also store the version of the word-finding algorithm from which they are obtained using PDWordFinderGetLatestAlgVersion().
 
PDTextSelect PDTextSelectCreateWordHiliteEx(PDPage page, HiliteEntry* hList, ASInt32 listLen, ASInt16 WFVersion)
Adds the WFVersion parameter to PDTextSelectCreateWordHilite().
 
Deletes a text selection object (the text on the page remains unchanged). Do not use this method to destroy a text selection that was passed to AVDocSetSelection(); such text selections are automatically destroyed when a new selection is made or the selection is cleared.
 
Enumerates the bounding quads in a text selection. proc is called for each quad. If a word is on a curve it may have a quad for each character, but it may also have two characters per quad. An upright word will have only one quad for all the characters. An upright hyphenated word will have two quads.
 
Enumerates the strings of the specified text select object, calling a procedure for each string. A string, in this context, is the set of like-styled characters within a word. It is never larger than a single word. A word containing three styles is enumerated as three strings. There is no guaranteed correspondence between these strings and the actual show strings in the PDF file. Acrobat enumerates text in the order it appears in the PDF file, which is often not the same as the order in which a person would read the text.
 
Same as PDTextSelectEnumText(), except the output is forced to UCS.
 
Gets a text selection's bounding rectangle. This is the smallest rectangle that completely encloses all characters in the selection.
 
Gets the page number of a text selection's page.
 
Extracts the range specified by index from a text selection. Use PDTextSelectGetRangeCount() to determine the number of ranges in a text selection.
 
Gets the number of ranges in a text selection. Use PDTextSelectGetRange() to extract a single range from a text selection.
Defines Detail
PDTextSelectCreatePageHilite 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define PDTextSelectCreatePageHilite PDTextSelectCreatePageHiliteHost

File: PDCalls.h
Line: 161
PDTextSelectCreateRanges 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define PDTextSelectCreateRanges PDTextSelectCreateRangesHost

File: PDCalls.h
Line: 163
PDTextSelectCreateWordHilite 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define PDTextSelectCreateWordHilite PDTextSelectCreateWordHiliteHost

File: PDCalls.h
Line: 162
PDTextSelectEnumQuads 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define PDTextSelectEnumQuads PDTextSelectEnumQuadsHost

File: PDCalls.h
Line: 158
PDTextSelectEnumText 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define PDTextSelectEnumText PDTextSelectEnumTextHost

File: PDCalls.h
Line: 159
PDTextSelectGetBoundingRect 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

#define PDTextSelectGetBoundingRect PDTextSelectGetBoundingRectHost

File: PDCalls.h
Line: 160

Typedefs Detail
PDTextSelect 
Product availability: All
Platform availability: All

Syntax

typedef struct _t_PDTextSelect* PDTextSelect;

A pointer to a PDTextSelect struct.


File: PDBasicExpT.h
Line: 120
PDTextSelectRange 
Product availability: All
Platform availability: All

Syntax

typedef _t_PDTextSelectRange PDTextSelectRange;

File: PDExpT.h
Line: 3080
PDTextSelectRangeRec 
Product availability: All
Platform availability: All

Syntax

typedef _t_PDTextSelectRange PDTextSelectRangeRec;

File: PDExpT.h
Line: 3080


Structure Detail
_t_PDTextSelectRange
Product availability: All
Platform availability: All

Syntax

struct _t_PDTextSelectRange {
 ASInt32 start; 
 
 ASInt32 end; 
 
 ASInt32 ofsStart; 
 
 ASInt32 ofsEnd; 
}

A data structure used to specify a range of text in a text selection.

Use 0 for ofsStart and ofsEnd for whole-word selections. Nonzero values for ofsStart and ofsEnd are supported by PDText but are currently ignored by the Acrobat viewer's user interface code (which highlights only whole-word selections). If ofsEnd is 0, end is the first word not selected.

See Also


File: PDExpT.h
Line: 3071

Elements
start  

A word containing the start of the selection.

 
end  

A word containing the end of the selection.

 
ofsStart  

An offset into the word at the start of the selection.

 
ofsEnd  

An offset into the word at the end of the selection.

Callbacks Detail
PDTextSelectEnumQuadProc 
Product availability: All
Platform availability: All

Syntax

ASBool (*PDTextSelectEnumQuadProc)(void *procObj, ASInt32 page, ASFixedQuad *quad)

A callback for PDTextSelectEnumQuads(). It is called once for each quad in a text selection.

See Also


File: PDExpT.h
Line: 3095
PDTextSelectEnumRTFTextProc 
Product availability: All
Platform availability: All

Syntax

ASBool (*PDTextSelectEnumRTFTextProc)(void *procObj, PDFont font, ASFixed size, PDColorValue color, char *text, ASUns32 rtfCntFlag, ASInt32 textLen)

File: PDExpT.h
Line: 3120
PDTextSelectEnumTextProc 
Product availability: All
Platform availability: All

Syntax

ASBool (*PDTextSelectEnumTextProc)(void *procObj, PDFont font, ASFixed size, PDColorValue color, char *text, ASInt32 textLen)

A callback for PDTextSelectEnumText() and PDTextSelectEnumTextUCS(). It is called once for each text run (which is text in the same font, size, color, and on the same line) in a text selection.

See Also


File: PDExpT.h
Line: 3116

Method Detail
PDTextSelectCreatePageHilite()
Product availability: All
Platform availability: All

Syntax

PDTextSelect PDTextSelectCreatePageHilite(PDPage page, HiliteEntry* hList, ASInt32 listLen)

Creates a text selection from a page and a list of highlights specified as character offsets from the start of the page. Character offsets are a well-defined quantity in the PDF file, and are therefore stable against revisions of the word-finding algorithm, which makes them a good way to isolate yourself from changes in the algorithm.

This method does not highlight the text selection. That occurs when you pass the PDTextSelect returned by this method to AVDocSetSelection().

Parameters

page — 

The page on which the highlights appear.

 
hList — 

A pointer to an array of highlight entries. If the length field of a HiliteEntry is 0, the entire word is highlighted. hList should not contain multiple instances of the same highlight; the display appearance is undefined when it does.

 
listLen — 

The number of highlight entries in hList.

Returns

The newly created text selection.

See Also

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 4539
PDTextSelectCreatePageHiliteEx() 
Product availability: All
Platform availability: All

Syntax

PDTextSelect PDTextSelectCreatePageHiliteEx(PDPage page, HiliteEntry* hList, ASInt32 listLen, ASInt16 WFVersion)

Adds the WFVersion parameter to PDTextSelectCreatePageHilite(). It is the same as PDTextSelectCreatePageHilite(), but it creates a WordFinder using the specified version number. It is intended to be used by plug-ins that want to do text highlighting with previous versions of the word finder algorithm.

Parameters

page — 

The page on which the highlights appear.

 
hList — 

A pointer to an array of highlight entries. If the length field of a HiliteEntry is 0, the entire word is highlighted. hList should not contain multiple instances of the same highlight; the display appearance is undefined when it does.

 
listLen — 

The number of highlight entries in hList.

 
WFVersion — 

The WordFinder version:

Annotation

Use

WF_LATEST_VERSION

To obtain the latest available version.

WF_VERSION_2

Version used for Acrobat 3.x, 4.x.

WF_VERSION_3

Available in Acrobat 5.0 without Accessibility enabled. Includes some improved word-piecing algorithms.

WF_VERSION_4

For Acrobat 5.0 with Accessibility enabled. Includes advanced word-ordering algorithms in addition to improved word-piecing algorithms.

Returns

The newly created text selection.

See Also

Since

PI_PDMODEL_VERSION >= 0x00050000

File: PDProcs.h
Line: 8076
PDTextSelectCreateRanges() 
Product availability: All
Platform availability: All

Syntax

PDTextSelect PDTextSelectCreateRanges(PDPage page, PDTextSelectRange range, ASInt32 rangeCount)

Creates a text selection from one or more ranges.

This method does not highlight the text selection. That occurs when you pass the PDTextSelect returned by this method to AVDocSetSelection().

Parameters

page — 

IN/OUT The page on which the text appears.

 
range — 

IN/OUT A pointer to an array of ranges that are used to create a text selection. Each array element is a PDTextSelectRange structure.

 
rangeCount — 

IN/OUT The number of ranges in range.

Returns

A text selection created from the specified ranges.

See Also

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 4626
PDTextSelectCreateRangesEx() 
Product availability: All
Platform availability: All

Syntax

PDTextSelect PDTextSelectCreateRangesEx(PDPage page, PDTextSelectRange range, ASInt32 rangeCount, ASInt16 WFVersion)

Adds the WFVersion parameter to PDTextSelectCreateRanges(). It is the same as PDTextSelectCreateRanges() but it creates a WordFinder using the specified version number. It is intended to be used by plug-ins that want to do text highlighting with previous versions of the word finder algorithm.

Parameters

page — 

IN/OUT The page on which the text appears.

 
range — 

IN/OUT A pointer to an array of ranges that are used to create a text selection. Each array element is a PDTextSelectRange structure.

 
rangeCount — 

IN/OUT The number of ranges in range.

 
WFVersion — 

IN/OUT The WordFinder version:

Annotation

Use

WF_LATEST_VERSION

To obtain latest the available version.

WF_VERSION_2

Version used for Acrobat 3.x, 4.x.

WF_VERSION_3

Available in Acrobat 5.0 without Accessibility enabled. Includes some improved word-piecing algorithms.

WF_VERSION_4

For Acrobat 5.0 with Accessibility enabled. Includes advanced word-ordering algorithms in addition to improved word-piecing algorithms.

Returns

A text selection created from the specified ranges.

See Also

Since

PI_PDMODEL_VERSION >= 0x00050000

File: PDProcs.h
Line: 8143
PDTextSelectCreateWordHilite() 
Product availability: All
Platform availability: All

Syntax

PDTextSelect PDTextSelectCreateWordHilite(PDPage page, HiliteEntry* hList, ASInt32 listLen)

Creates a text selection from a list of highlights specified as word offsets from the start of the page. Word offsets are not well-defined in PDF files, but are calculated by the word-finding algorithm. As a result, word offsets will, in general, differ in different versions of the word-finding algorithm. If you choose to store word offsets, you must also store the version of the word-finding algorithm from which they are obtained using PDWordFinderGetLatestAlgVersion().

This method does not highlight the text selection. That occurs when you pass the PDTextSelect returned by this method to AVDocSetSelection().

Parameters

page — 

The page on which the highlights appear.

 
hList — 

A pointer to an array of highlight entries. hList should not contain multiple instances of the same highlight; the display appearance is undefined when it does.

 
listLen — 

The number of highlight entries in hList.

Returns

The newly created text selection.

See Also

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 4570
PDTextSelectCreateWordHiliteEx() 
Product availability: All
Platform availability: All

Syntax

PDTextSelect PDTextSelectCreateWordHiliteEx(PDPage page, HiliteEntry* hList, ASInt32 listLen, ASInt16 WFVersion)

Adds the WFVersion parameter to PDTextSelectCreateWordHilite().

Parameters

page — 

The page on which the highlights appear.

 
hList — 

A pointer to an array of highlight entries. hList should not contain multiple instances of the same highlight; the display appearance is undefined when it does.

 
listLen — 

The number of highlight entries in hList.

 
WFVersion — 

The WordFinder version:

Annotation

Use

WF_LATEST_VERSION

To obtain the latest available version.

WF_VERSION_2

Version used for Acrobat 3.x, 4.x.

WF_VERSION_3

Available in Acrobat 5.0 without Accessibility enabled. Includes some improved word-piecing algorithms.

WF_VERSION_4

For Acrobat 5.0 with Accessibility enabled. Includes advanced word-ordering algorithms in addition to improved word-piecing algorithms.

Returns

The newly created text selection.

See Also

Since

PI_PDMODEL_VERSION >= 0x00050000

File: PDProcs.h
Line: 8108
PDTextSelectDestroy() 
Product availability: All
Platform availability: All

Syntax

void PDTextSelectDestroy(PDTextSelect text)

Deletes a text selection object (the text on the page remains unchanged). Do not use this method to destroy a text selection that was passed to AVDocSetSelection(); such text selections are automatically destroyed when a new selection is made or the selection is cleared.

Parameters

text — 

IN/OUT The text selection to destroy.

See Also

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 4429
PDTextSelectEnumQuads() 
Product availability: All
Platform availability: All

Syntax

void PDTextSelectEnumQuads(PDTextSelect text, PDTextSelectEnumQuadProc proc, void* procObj)

Enumerates the bounding quads in a text selection. proc is called for each quad. If a word is on a curve it may have a quad for each character, but it may also have two characters per quad. An upright word will have only one quad for all the characters. An upright hyphenated word will have two quads.

Parameters

text — 

IN/OUT The text selection whose bounding quads are enumerated.

 
proc — 

IN/OUT A user-supplied callback to call for each quad. Enumeration halts if proc returns false.

 
procObj — 

IN/OUT A user-supplied data to pass to proc each time it is called.

See Also

Exceptions

genErrBadParm

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 4449
PDTextSelectEnumText() 
Product availability: All
Platform availability: All

Syntax

void PDTextSelectEnumText(PDTextSelect text, PDTextSelectEnumTextProc proc, void* procObj)

Enumerates the strings of the specified text select object, calling a procedure for each string. A string, in this context, is the set of like-styled characters within a word. It is never larger than a single word. A word containing three styles is enumerated as three strings. There is no guaranteed correspondence between these strings and the actual show strings in the PDF file. Acrobat enumerates text in the order it appears in the PDF file, which is often not the same as the order in which a person would read the text.

Parameters

text — 

IN/OUT The text selection whose strings are enumerated.

 
proc — 

IN/OUT A user-supplied callback to call for each string in the text object. Enumeration ends if proc returns false.

 
procObj — 

IN/OUT User-supplied data to pass to proc each time it is called.

See Also

Exceptions

genErrBadParm
pdErrOpNotPermitted

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 4475
PDTextSelectEnumTextUCS() 
Product availability: All
Platform availability: All

Syntax

void PDTextSelectEnumTextUCS(PDTextSelect textP, PDTextSelectEnumTextProc proc, void* procData)

Same as PDTextSelectEnumText(), except the output is forced to UCS.

Parameters

textP — 

IN/OUT The text selection whose strings are enumerated.

 
proc — 

IN/OUT A user-supplied callback to call for each string in the text object. Enumeration ends if proc returns false.

 
procData — 

IN/OUT User-supplied data to pass to proc each time it is called.

See Also

Exceptions

genErrBadParm

Since

PI_PDMODEL_VERSION >= 0x00050000

File: PDProcs.h
Line: 7871
PDTextSelectGetBoundingRect() 
Product availability: All
Platform availability: All

Syntax

void PDTextSelectGetBoundingRect(PDTextSelect text, ASFixedRect* boundRectP)

Gets a text selection's bounding rectangle. This is the smallest rectangle that completely encloses all characters in the selection.

Parameters

text — 

IN/OUT The text selection whose bounding rectangle is determined.

 
boundRectP — 

IN/OUT (Filled by the method) A pointer to the text selection's bounding rectangle, specified in user space coordinates.

See Also

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 4505
PDTextSelectGetPage() 
Product availability: All
Platform availability: All

Syntax

ASInt32 PDTextSelectGetPage(PDTextSelect text)

Gets the page number of a text selection's page.

Parameters

text — 

IN/OUT The text selection whose page number is obtained.

Returns

The page number of the text selection's page.

See Also

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 4488
PDTextSelectGetRange() 
Product availability: All
Platform availability: All

Syntax

void PDTextSelectGetRange(PDTextSelect textP, ASInt32 index, PDTextSelectRange range)

Extracts the range specified by index from a text selection. Use PDTextSelectGetRangeCount() to determine the number of ranges in a text selection.

Parameters

textP — 

IN/OUT The text selection from which a range is extracted.

 
index — 

IN/OUT The index of the range to extract from textP.

 
range — 

IN/OUT (Filled by the method) A pointer to a structure that contains the specified range.

See Also

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 4588
PDTextSelectGetRangeCount() 
Product availability: All
Platform availability: All

Syntax

ASInt32 PDTextSelectGetRangeCount(PDTextSelect textP)

Gets the number of ranges in a text selection. Use PDTextSelectGetRange() to extract a single range from a text selection.

Parameters

textP — 

IN/OUT The text selection whose range count is obtained.

Returns

The number of ranges in the text selection.

See Also

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 4602