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

4    Find

Text and Localization

Exploring Palm OS®

This chapter describes the Global Find facility API declared in the header file Find.h. It covers the following topics:

Find Structures and Types
Find Constants
Find Launch Codes
Find Functions and Macros

For more information on the Find Manager, see Chapter 2, "Implementing Global Find."

Find Structures and Types ^TOP^

FindMatchType Struct ^TOP^

Purpose

A structure that the Find Manager uses to save information about each matching record.

Declared In

Find.h

Prototype

typedef struct {
   DatabaseID appDbID;
   DatabaseID dbID;
   Boolean foundInCaller;
   uint8_t reserved;
   uint16_t reserved2;
   uint32_t recordNum;
   uint32_t recordID;
   uint32_t matchFieldNum;
   size_t matchPos;
   size_t matchLen;
   uint32_t matchCustom;
} FindMatchType;
typedef FindMatchType *FindMatchPtr

Fields

appDbID
Database ID of the application with the matching record.
dbID
Database ID of the record database in which the match was found.
foundInCaller
If true, the matching record was found in the application that was active when the user launched Find.
reserved
Reserved for future use.
reserved2
Reserved for future use.
recordNum
The index of the record containing the matching text.
recordID
The unique ID of the record containing the matching text.
matchFieldNum
The index of the text field that should display the matching text.
matchPos
Byte offset of the start of the matching text within the record.
matchLen
The number of bytes of matching text.
matchCustom
Application-specific information.

See Also

GoToParamsType, FindSaveMatch()

FindParamsType Struct ^TOP^

Purpose

Parameter block for sysAppLaunchCmdFind.

Declared In

Find.h

Prototype

typedef struct {
   uint32_t dbAccesMode;
   uint32_t recordNum;
   uint32_t recordID;
   Boolean more;
   char strAsTyped[maxFindStrLen+1];
   char strToFind[maxFindStrPrepLen+1];
   Boolean continuation;
   uint16_t lineNumber;
   RectangleType bounds;
   uint16_t numMatches;
   Boolean searchedCaller;
   uint8_t reserved1;
   uint8_t reserved2;
   uint8_t reserved3;
   DatabaseID callerAppDbID;
   DatabaseID appDbID;
   DmSearchStateType searchState;
} FindParamsType
typedef FindParamsType *FindParamsPtr

Fields

dbAccesMode
Mode in which to open the application's database. Pass this directly to DmOpenDatabase() as the mode parameter. Its value is either dmModeReadOnly or dmModeReadOnly | dmModeShowSecret. (See DmOpenModeType for more information.)
recordNum
Index of last record that contained a match. Start the search from this location. Do not set this value directly. Instead, call FindSaveMatch() when you have a matching record.
recordID
Unique ID of the last record that contained a match. Do not set this value directly. Instead, call FindSaveMatch() when you have a matching record.
more
No longer used.
strAsTyped
Search string as the user entered it.
strToFind
Normalized version of the search string. 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. You pass strToFind directly to the TxtFindString() search function.
continuation
No longer used.
lineNumber
Line number of the next line that displays the results. Do not set this field directly. It is incremented by a call to FindDrawHeader().
bounds
The current size of the form that the Find Manager is displaying. This field is used internally by the Find Manager.
numMatches
The current number of matches. Do not set this field directly. Instead, call FindSaveMatch(), which increments it for you.
searchedCaller
If true, the application that was active at the time the user tapped the Find icon has responded to this launch code. This application is always searched before any others.

NOTE: In Palm OS Cobalt version 6.0, the current application is always searched regardless of its APP_LAUNCH_PREFS_RESOURCE settings.
reserved1
Reserved for future use.
reserved2
Reserved for future use.
reserved3
Reserved for future use.
callerAppDbID
Database ID of the application that was active when the user tapped the Find button. Do not change the value of this field; the system sets it and uses it when searching for application databases.
appDbID
The ID of your application's resource database. Do not set this field directly; the system sets it and uses it when searching for application databases.
searchState
System use only.

Find Constants ^TOP^

Size Constants ^TOP^

Purpose

Specify the maximum sizes of search strings.

Declared In

Find.h

Constants

#define maxFindStrLen 48
The maximum length in bytes of the string the user can enter in the Find dialog. This is the maximum length of the strAsTyped field in FindParamsType.
#define maxFindStrPrepLen 64
The maximum length of a normalized string to be searched for using the Find facility. A normalized string has already had TxtPrepFindString() called on it.

Find Launch Codes ^TOP^

sysAppLaunchCmdFind ^TOP^

Purpose

Sent when the user has entered text in the Find dialog. The application should search for the string that the user entered and return any records matching the find request.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdFind 1


Parameters

The launch code's parameter block pointer references a FindParamsType structure.

Comments

The system only send this launch code to applications that have an APP_LAUNCH_PREFS_RESOURCE of ID 0 with the flag ALPF_FLAG_NOTIFY_FIND set to true.


NOTE: In Palm OS Cobalt version 6.0, the current application is always searched regardless of its APP_LAUNCH_PREFS_RESOURCE settings.

Most applications that store text in a database should support this launch code. When they receive it, they should search all records for matches to the find string and return all matches. Chapter 2 describes how to respond to this launch code.

The system displays the results of the query in the Find Results dialog. The system continues the search with each application until all of the applications on the device have had a chance to respond.

An application can also integrate the find operation in its own user interface and send the launch code to a particular application.

Applications that support this launch code should also support sysAppLaunchCmdSaveData and sysAppLaunchCmdGoTo.

Find Functions and Macros ^TOP^

Find Function ^TOP^

Purpose

System use only function that handles the Global Find feature. Applications should not call this function.

Declared In

Find.h

Prototype

void Find (
   GoToParamsPtr goToP
)

Parameters

goToP
A pointer to a GoToParamsType structure. Usually NULL.

Returns

Nothing.

Comments

The system calls this function when it receives a keyDownEvent with the vchrFind virtual character. If you want to implement your own Find, the correct thing to do is to intercept this event before the call to SysHandleEvent() in your event loop.

FindDrawHeader Function ^TOP^

Purpose

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

Declared In

Find.h

Prototype

Boolean FindDrawHeader (
   FindParamsPtr findParams,
   char const *title
)

Parameters

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

Returns

Always returns false.

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.

The header is only drawn if your application successfully locates a matching result.

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 (
   const FindParamsType *findParams,
   RectanglePtr r
)

Parameters

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

Returns

Nothing.

Comments

Call this function when you've found a match that should be displayed in the Find Results dialog, and then call WinDrawChars(), passing it the location returned in r. WinDrawChars() does not draw directly to the Find Results dialog. The Find Manager traps all WinDrawChars() calls while a Find is in progress and copies the string to a buffer. The Find Manager displays the string at the appropriate location when it has a screen full of data to display.

FindSaveMatch Function ^TOP^

Purpose

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

Declared In

Find.h

Prototype

Boolean FindSaveMatch (
   FindParamsPtr findParams,
   uint32_t recordNum,
   uint32_t recordID,
   size_t matchPos,
   size_t matchLen,
   uint32_t fieldNum,
   uint32_t appCustom,
   DatabaseID dbID
)

Parameters

findParams
Pointer to the sysAppLaunchCmdFind launch code's parameter block (FindParamsType).
recordNum
Record index. This parameter sets the recordNum field in the sysAppLaunchCmdGoTo parameter block (GoToParamsType).
recordID
Unique ID of the record containing a match. This parameter sets the recordID field in the sysAppLaunchCmdGoTo parameter block.
matchPos
Byte offset of the start of the matching string in the record. This parameter sets the matchPos field in the sysAppLaunchCmdGoTo parameter block.
matchLen
The number of bytes of matched text found in the record. This parameter sets the matchLen field in the sysAppLaunchCmdGoTo parameter block.
fieldNum
Index of the text field in which the matching string should be displayed. This parameter sets the matchFieldNum field in the sysAppLaunchCmdGoTo parameter block.
If your application's database is a schema database, use this field to set the column ID in which the matching text was found.
appCustom
Extra data the application can save with a match. This parameter sets the matchCustom field in the sysAppLaunchCmdGoTo parameter block.
dbID
Database ID of the database that contains the match. This parameter sets the dbID field in the sysAppLaunchCmdGoTo parameter block.

Returns

true if the application should exit from the search.

Comments

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

FindSaveMatchV40 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 FindSaveMatchV40 (
   FindParamsPtr findParams,
   uint16_t recordNum,
   uint16_t pos,
   uint16_t fieldNum,
   uint32_t appCustom,
   uint16_t cardNo,
   LocalID dbID
)

Parameters

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

Returns

true if the application should exit from the search.

Compatibility

This function differs from FindSaveMatch() in that it does not have recordID or matchLen parameters and its matchNum, fieldNum, and matchPos parameters are all smaller. In earlier Palm OS releases, applications used the appCustom parameter to store the length of the matching string. These applications should now call FindSaveMatch() and pass the length of the matching string in matchLen.

FindStrInStrV50 Function ^TOP^

Purpose

Performs 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 FindStrInStrV50 (
   char const *strToSearch,
   char const *strToFind,
   uint16_t *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

true if the string was found.

Compatibility

Do not use this function. Instead use TxtFindString(), which can successfully search strings that containing multi-byte characters and can return the length of the matching text.