Article # 24, added by Geoworks, historical record
| first | previous | index | next | last |

Using the FilterListClass on the Nokia 9000.




Q. I need to set up a search box.  I found two classes in foam.goh
   that I thought I can use.  I created a search box using 
   FilterTextClass and I changed my GenDynamicList to FilterList. 
   Does the procedure begin like this?:

     I have to create a filter function that selects those business
     cards that match when user types in search box.

A. Correct. The function should retrieve the current text from
   the FilterText object, and perform the search.


Q. Continued...
   Then I have to send a message MSG_FILTER_LIST_INITIALIZE to my list in
   order to get update. Is the parameter "filter" a chunk array of items
   I want to display?

A. The "filter" is a simple (C-style) array of item ID's. For example:

    word searchResult[10];
    word searchResultLength;

    ... perform search, putting results in searchResult

    @call ListObj::MSG_FILTER_LIST_INITIALIZE(
        searchResultLength,
        searchResult );


Q. Continued...
   This causes my query message to be called. Here comes the problem:
   How can I find out the actual item number the list is going to show.

A. The item number passed to your method handler in the query message
   is the actual item number.

   If the filter has not been set, or has been removed (by passing NULL
   to MSG_FILTER_LIST_INITIALIZE), then the ID's passed & returned by
   filter list API are the physical item numbers, exactly like
   a normal GenDynamicList.


Q. Let's say I have five cards in the folder. Number two matches. My
   query message gives me parameters: item and list. Do I have to call
   MSG_FILTER_LIST_MAP_APP_TO_PHYSICAL?

A. You do not need to do this. The translation between the physical
   item number and the application's item number is automatic. If your
   application's ID for number two were '345', then the item number
   that the query message passes to your method handler will be '345'.

   This also applies to any of the other MSG_FILTER_LIST_* messages
   that have item ID parameters or return values - If
   MSG_FILTER_LIST_INITIALZE has been used to set a "filter", then the
   Item ID's that the application specified in that filter are used.

   The list's status and apply messages also do this automatically.

   It should never be necessary to use the MSG_FILTER_LIST_MAP_*
   messages to manually perform translations between physical and app
   ID's.

   Some other "tricks" you can employ when using FilterListClass:

   If an item matches more than once and you want to display
   it multiple times (once for each match), but be able to
   distinguish between instances of the item, when you build
   the filter array, store the actual item number in the lower bits
   of the ID word, and the character position of the match in the upper bits.
   Example:

    Search for 'Gr'
    Item #3: greg gray
    Match #0: GReg gray (position 0)
    Match #1: greg GRay (position 5)

    the filter list would contain:
       0 << 8 | 3,
       5 << 8 | 3

   The moniker query method could then fetch the actual item by looking
   at only the lower byte of the ID, and know which portion of the
   string to underline by looking at the upper byte (the length of the
   match would be stored in some global variable or instance data, and
   set at the time the search was performed).