Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

10    Find

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

This chapter describes the global find facility API declared in the header file Find.h.

Find Functions ^TOP^

FindDrawHeader Function ^TOP^

Purpose

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

Declared In

Find.h

Prototype

Boolean FindDrawHeader (
   FindParamsPtrfindParams,
   Charconst *title
)

Parameters

findParams
Pointer to the sysAppLaunchCmdFind launch code's parameter block.
title
String to display as the title for the current application.

Returns

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

Comments

Call this function once at the beginning of your application's response to the sysAppLaunchCmdFind launch code. This function draws a header for your application's Find results. The header separates the search results from your application with the search results from another application.

If your application searches multiple databases, you may also use FindDrawHeader as a separator between databases.

FindGetLineBounds Function ^TOP^

Purpose

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

Declared In

Find.h

Prototype

void FindGetLineBounds(
   constFindParamsType*findParams,
   RectanglePtrr
)

Parameters

findParams
Pointer to the sysAppLaunchCmdFind launch code's parameter block.
r
The bounds of the area that should contain the next line of results.

Returns

Returns nothing.

FindSaveMatch Function ^TOP^

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.

Declared In

Find.h

Prototype

Boolean FindSaveMatch (
   FindParamsPtrfindParams,
   UInt16recordNum,
   UInt16pos,
   UInt16fieldNum,
   UInt32appCustom,
   UInt16cardNo,
   LocalIDdbID
)

Parameters

findParams
Pointer to the sysAppLaunchCmdFind launch code's parameter block.
recordNum
Record index. This parameter sets the recordNum field in the sysAppLaunchCmdGoTo's parameter block.
pos
Offset of the match string from start of record. This parameter sets the matchPos field in the sysAppLaunchCmdGoTo's parameter block.
fieldNum
Field number that the string was found in. This parameter sets the matchFieldNum field in the sysAppLaunchCmdGoTo's parameter block.
appCustom
Extra data the application can save with a match. This parameter sets the matchCustom field in the sysAppLaunchCmdGoTo's parameter block.
cardNo
Card number of the database that contains the match. This parameter sets the dbCardNo field in the sysAppLaunchCmdGoTo's parameter block.
dbID
Local ID of the database that contains the match. This parameter sets the dbID field in the sysAppLaunchCmdGoTo's parameter block.

Returns

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

Comments

Call this function when your application finds a record with a matching string (FindStrInStr() or TxtFindString() returns true). This function saves the information you pass. If the user clicks this selection in the Find results dialog, the information is retrieved and used to set up the sysAppLaunchCmdGoTo launch code's parameter block.

You can use the appCustom field for any application-specific data that might be needed to navigate to the record if the user selects it. It's common for localizable applications to set appCustom to the length of the matching string because the global find facility cannot correctly determine the length of the matching string on systems with multi-byte character sets. In some character encodings, one character may be accurately represented as either a single-byte character or a multi-byte character. The TxtFindString function accurately matches single-byte characters against their multi-byte equivalents and returns the length of the matching string. If you pass TxtFindString's return value as the appCustom parameter to FindSaveMatch, the matchCustom field of the sysAppLaunchCmdGoTo parameter block contains the length of the matching string.

If your application requires more custom information, you can store the information in a feature and store the feature number in the appCustom field. See the "Feature Manager" chapter for more information.

FindStrInStr Function ^TOP^

Purpose

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

Declared In

Find.h

Prototype

Boolean FindStrInStr (
   Charconst*strToSearch,
   Charconst*strToFind,
   UInt16*posP
)

Parameters

strToSearch
String to search.
strToFind
Normalized version of the text string to be found.
posP
If a match is found, contains the offset of the match within strToSearch.

Returns

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.

Comments

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.

For backward compatibility with systems that don't support the text manager, use TxtGlueFindString, found in the PalmOSGlue library. TxtGlueFindString calls TxtFindString if the text manager is present, or FindStrInStr if it is not present. For more information, see Chapter 80, "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 need to create your own normalized search string, use TxtGluePrepFindString, also in the PalmOSGlue library.