Carbon


TXNFind

Header: MacTextEditor.h Carbon status: Supported

Finds a piece of text or a graphics, sound, or movie object.

OSStatus TXNFind (
    TXNObject iTXNObject, 
    const TXNMatchTextRecord *iMatchTextDataPtr, 
    TXNDataType iDataType, 
    TXNMatchOptions iMatchOptions, 
    TXNOffset iStartSearchOffset, 
    TXNOffset iEndSearchOffset, 
    TXNFindUPP iFindProc, 
    SInt32 iRefCon, 
    TXNOffset *oStartMatchOffset, 
    TXNOffset *oEndMatchOffset
);
Parameter descriptions
iTXNObject

A variable of type TXNObject. Pass the text object o be searched.

iMatchTextDataPtr

A pointer to a MatchTextRecord structure containing the text to match, the length of that text, and the text’s encoding. Pass NULL if you are looking for a graphics, sound, or movie object.

iDataType

A “Supported Data Types” value of type TXNDataType. If the data type is ‘PICT’, ‘moov’, or ‘snd’ the default behavior is to match on any nontext object. If you want to find a specific data type, you can provide a custom find callback or ignore types that do not match what you want to find.

iMatchOptions

A “Search Criteria Masks” value of type TXNMatchOptions. This specifies the matching rules to use in the find operation.

iStartSearchOffset

A variable of type TXNOffset. This specifies the offset at which a search should begin. You can use kTXNStartOffset if you want to search from the start of the object’s data.

iEndSearchOffset

A variable of type TXNOffset. This specifies the offset at which the search should end. You can use kTXNEndOffset if you want to search to the end of the object’s data.

iFindProc

A variable of type TXNFindUPP. This specifies a custom callback you want used in place of the default matching behavior. You can pass NULL if you want the default matching behavior.

iRefCon

An unsigned 32-bit integer. You can use this for whatever your application needs. It is passed to the custom callback specified by iFindProc.

oStartMatchOffset

A pointer to a variable of type TXNOffset. On return, it specifies the absolute offset to the start of the match. It is set to 0xFFFFFFFF if there is no match.

oEndMatchOffset

A pointer to a variable of type TXNOffset. On return, it specifies the absolute offset to the end of the match. It is set to 0xFFFFFFFF if there is no match.

function result

A result code.

DISCUSSION

By default, text is matched on the basis of a binary comparison. If you set the iMatchOptions variable to ignore case, the characters you want searched are duplicated and case neutralized. If the amount of text you want searched is large, the binary comparison can fail due to insufficient memory. Binary comparison is also slow.

If you set the iMatchOptions variable to find an entire word, then once a match is found, the matched text is tested to see if it is a word. A word is defined as a match that has white space before and after it. If the kTXNUseEncodingWordRulesBit is set, then the Script Manager's FindWord function is called to make this determination. If the text being searched is Unicode text, then ATSUI’s word-determining functions are used to test for a word.

If the application is looking for a nontext type, then each nontext type in the document is returned. The iFindProc parameter lets you provide a more elaborate search engine (such as a regular expression processor) should you need one.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.


© 2000 Apple Computer, Inc. (Last Updated 7/17/2000)