PD_Layer.PDTextSelect (Acrobat)

	Define
	PDTextSelectCreatePageHilite
	PDTextSelectCreateRanges
	PDTextSelectCreateWordHilite
	PDTextSelectEnumQuads
	PDTextSelectEnumText
	PDTextSelectGetBoundingRect

	Typedef
	PDTextSelect A pointer to a PDTextSelect struct.
	PDTextSelectRange
	PDTextSelectRangeRec

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

	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
	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().
	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.
	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.
	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.
	void PDTextSelectEnumTextUCS(PDTextSelect textP, PDTextSelectEnumTextProc proc, void* procData) Same as PDTextSelectEnumText(), except the output is forced to UCS.
	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.
	ASInt32 PDTextSelectGetPage(PDTextSelect text) Gets the page number of a text selection's page.
	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.
	ASInt32 PDTextSelectGetRangeCount(PDTextSelect textP) 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.

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

PDTextSelectEnumQuads

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.

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.

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.

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.

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.

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.

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.

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.

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

PDDocCreateTextSelect

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

PDDocCreateTextSelect

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.

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.

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.

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.

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.

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 4602

Acrobat API Reference	All Layers \| All Objects \| Index \| Samples \| Frames No Frames
PDTextSelect	Defines \| Typedefs \| Structures \| Callbacks \| Methods

	ASInt32 start;

	ASInt32 end;

	ASInt32 ofsStart;

	ASInt32 ofsEnd;

Layer	PD_Layer
Object	PDTextSelect