FindHack 4 for Software Developers

Important note: the FindHack API is still evolving. Please contact me before your start implementing FindHack support in your application!

Audience

This document is provided to allow software developers who have applications using more than one database to provide a better Find experience to the end-user by speeding up the results display refreshes when the user moves back and forth in the results list.

 

Introduction

FindHack 4 brings a new UI to the traditional Find function that usually ships with Palm OS handhelds. While this is very much praised by end users, it also highlight problems in the aging Find mechanism defined by Palm for applications to support.

The most prominent change is that FindHack supports scrolling back and forth within results of a Find operation. The traditional sysAppLaunchCmdFind command received by applications to perform a Find operation was not enough to suppport this feature, since Find operations where designed to be linear (starting from the first matches then only heading towards one direction).

To support scrolling, FindHack tricks the applications into redisplaying one or more matches by simulating the continuation of a Find operation restarting from a given point. While this works mostly OK with most applications, it is very costly in terms of required processing power and time. Additionally, scrolling back is more costly because the search operation often needs to be restarted from the beginning to ensure that the displayed match is the right one.

The main issue with scrolling back and forth is that applications with multiple databases (for example database management applications and word processing applications) need to keep more context than just the record that was current when the last Find command was interrupted. To properly resume a Find operation, the applications also need to know into which database the "last known current record" is located. Since there is no provision in the FindParamsType structure to store this information, applications use various solutions: some store their context information in a feature, others in a database, others in their preferences.

While FindHack can operate without explicit support from the application for scrolling back and forth, list refresh speed is much greater if applications (especially the ones containing the largest sets of data) do support the context save/restore mechanism that FindHack provides.

 

Context Save / Restore

FindHack is able to save arbitrary context data provided by an application for a given match displayed in the results list, and to restore it and make it available to the application when it needs to redisplay one or more lines of results.

This is being done through the use of Features and Feature Pointers. During the initial search phase, FindHack sets a feature indicating that the application can save a block of data of any size using FtrPtrNew. This data block will later be made available to the application which can get its search context from there instead of using other methods to save / restore the context.

Additionally, when redisplaying matches, FindHack sets another feature to tell the application how many lines of results it wants to redisplay. Although the application is free to ignore this and proceed as usual, it can use this information to come back from the sysAppLaunchCmdFind command as soon as possible instead of continuing the search until FindSaveMatch returns false.

Note that FindHack takes care of disposing any feature pointers your application creates.

Definitions of features provided by FindHack

All features set by FindHack have the creator 'FnHk'.

Feature #	Explanation
#define  kFindHackContextDataFeature  4	For applications to store their context data with FindSaveMatch, contains the feature# that apps should allocate with FtrPtrNew. Application should increment this value after saving each match and its associated context data. Therefore, if it saves 5 matches, it can create 5 context data blocks. Note that your application is free to not save context data for every match. FindHack handles this gracefully and will resume the search from the last match for which a context data block is available, when needed.
#define  kFindHackRestoredContextData 5	When we are restoring context data, it is being passed back as a feature pointer in this feature.
#define kFindHackRedisplayNumRows 6	When redisplaying one or more rows, tells the application how many row it should display before returning from the search.

 

Example of use

To help you add support for FindHack in your application, you can use the code below as an example implementation.

void Search(...)
{
    UInt32 numRowsToRedisplay = 0;
    UInt32 saveContextDataFtr = 0;
    ...
    // read information provided by FindHack
    FtrGet('FnHk', kFindHackContextDataFeature, &saveContextDataFtr);
    FtrGet('FnHk', kFindHackRedisplayNumRows, &numRowsToRedisplay);
    if (numRowsToRedisplay)
    {
        // restore application's private context passed back by Findhack
        void *myContextData;
        FtrGet('FnHk', kFindHackRestoredContextData, (UInt32*)&myContextData);
        ... // do what you need to do with the data here
    }
    else if (saveContextDataFtr == 0)
    {
        // FindHack not installed
        // use your traditional way of restoring your context data
        ...
    }

    // find loop
    while (searching)
    {
        ...
        if (matchFound)
        {
            if (FindSaveMatch(...) == true)
                break; // screen is full

            if (saveContextDataFtr)
            {
                // save the context data for this match
                // (only used during initial search phase)
                void *myContextData;
                if (FtrPtrNew('FnHk', saveContextDataFtr++, &myContextData, myContextDataSize))
                {
                    ... // write the contents of your context in myContextData
                }
            }
            ...
            // display match here
            ...
            // if FindHack is installed and we are redisplaying matches,
            // stop as soon as the number of matches to redisplay are on screen
            if (numRowsToRedisplay && --numRowsToRedisplay == 0)
                break;
        }
    }
}

FindHack is Copyright (c) 1997-2003 by Florent Pillet, All Rights Reserved.