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
FindMatchType Struct
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
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 themode
parameter. Its value is eitherdmModeReadOnly
ordmModeReadOnly
|dmModeShowSecret
. (SeeDmOpenModeType
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 theTxtFindString()
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
Size Constants
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 inFindParamsType
. -
#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
sysAppLaunchCmdFind
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
Find Function
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. UsuallyNULL
.
Returns
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
Purpose
Draws the header line that separates, by application, the list of found items.
Declared In
Find.h
Prototype
Boolean FindDrawHeader ( FindParamsPtrfindParams
, char const*title
)
Parameters
-
→ findParams
- Pointer to the
sysAppLaunchCmdFind
launch code's parameter block. SeeFindParamsType
. -
→ title
- String to display as the title for the current application.
Returns
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
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
, RectanglePtrr
)
Parameters
-
→ findParams
- Pointer to the
sysAppLaunchCmdFind
launch code's parameter block. SeeFindParamsType
. -
← r
- The bounds of the area that should contain the next line of results.
Returns
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
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 ( FindParamsPtrfindParams
, uint32_trecordNum
, uint32_trecordID
, size_tmatchPos
, size_tmatchLen
, uint32_tfieldNum
, uint32_tappCustom
, DatabaseIDdbID
)
Parameters
-
→ findParams
- Pointer to the
sysAppLaunchCmdFind
launch code's parameter block (FindParamsType
). -
→ recordNum
- Record index. This parameter sets the
recordNum
field in thesysAppLaunchCmdGoTo
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 thesysAppLaunchCmdGoTo
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 thesysAppLaunchCmdGoTo
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 thesysAppLaunchCmdGoTo
parameter block. -
→ dbID
- Database ID of the database that contains the match. This parameter sets the
dbID
field in thesysAppLaunchCmdGoTo
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
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 ( FindParamsPtrfindParams
, uint16_trecordNum
, uint16_tpos
, uint16_tfieldNum
, uint32_tappCustom
, uint16_tcardNo
, LocalIDdbID
)
Parameters
-
→ findParams
- Pointer to the
sysAppLaunchCmdFind
launch code's parameter block. SeeFindParamsType
. -
→ recordNum
- Record index. This parameter sets the
recordNum
field in thesysAppLaunchCmdGoTo
parameter block. -
→ pos
- Offset of the match string from start of record. This parameter sets the
matchPos
field in thesysAppLaunchCmdGoTo
parameter block. -
→ fieldNum
- Field number that the string was found in. This parameter sets the
matchFieldNum
field in thesysAppLaunchCmdGoTo
parameter block. -
→ appCustom
- Extra data the application can save with a match. This parameter sets the
matchCustom
field in thesysAppLaunchCmdGoTo
parameter block. -
→ cardNo
- Card number of the database that contains the match. This parameter sets the
dbCardNo
field in thesysAppLaunchCmdGoTo
parameter block. -
→ dbID
- Local ID of the database that contains the match. This parameter sets the
dbID
field in thesysAppLaunchCmdGoTo
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
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
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.