9 Find

This chapter provides reference material for the global find facility. The API for the find facility is defined in the header file Find.h.

Find Functions

FindDrawHeader

Purpose

Draw the header line that separates, by database, the list of found items.

Prototype

Boolean FindDrawHeader (FindParamsPtr findParams, Char const* title)

Parameters

findParams

Handle of FindParamsPtr.

title

Description of the database (for example Memos).

Result

Returns true if Find screen is filled up. Applications should exit from the search if this occurs.

FindGetLineBounds

Purpose

Returns the bounds of the next available line for displaying a match in the Find Results dialog.

Prototype

void FindGetLineBounds (const FindParamsType *findParams, RectanglePtr r)

Parameters

findParams

Handle of FindParamsPtr.

r

Pointer to a structure to hold the bounds of the next results line.

Result

Returns nothing.

FindSaveMatch

Purpose

Saves the record and position within the record of a text search match. This information is saved so that it's possible to later navigate to the match.

Prototype

Boolean FindSaveMatch (FindParamsPtr findParams, UInt16 recordNum, UInt16 pos, UInt16 fieldNum, UInt32 appCustom, UInt16 cardNo, LocalID dbID)

Parameters

findParams

Handle of FindParamsPtr.

recordNum

Record index.

pos

Offset of the match string from start of record.

fieldNum

Field number the string was found in.

appCustom

Extra data the application can save with a match.

cardNo

Card number of the database that contains the match.

dbID

Local ID of the database that contains the match.

Result

Returns true if the maximum number of displayable items has been exceeded

Comments

Called by application code when it gets a match.

FindStrInStr

Purpose

Perform a case-blind partial word search for a string in another string. This function assumes that the string to find has already been normalized for searching.

Prototype

Boolean FindStrInStr (Char const *strToSearch, Char const *strToFind, UInt16 *posP)

Parameters

strToSearch

String to search.

strToFind

Normalized version of the text string to be found.

posP

Pointer to offset in search string of the match.

Result

Returns true if the string was found. FindStrInStr matches the beginnings of words only; that is, strToFind must be a prefix of one of the words in strToSearch for FindStrInStr to return true.

Comment

Don't use this function on systems that support the Text Manager. Instead, use TxtFindString, which performs searches on strings that contain multi-byte characters and returns the length of the matching text.

On systems that don't support the Text Manager, use TxtGlueFindString, found in the PalmOSGlue library. For more information, see Chapter 62, "PalmOSGlue Library."

The method by which a search string is normalized varies depending on the version of Palm OS^® and the character encoding supported by the device. The string passed to your application in the strToFind field of the sysAppLaunchCmdFind launch code parameter block has already been normalized. It can be passed directly to FindStrInStr, TxtFindString, or TxtGlueFindString. If you have to create your own normalized search string, use TxtGluePrepFindString, also in the PalmOSGlue library.