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

24    Phone Lookup Reference

User Interface

Exploring Palm OS®

This chapter provides descriptions of the phone lookup functions. It covers the following topics:

Phone Lookup Structures and Types
Phone Lookup Constants
Phone Lookup Functions and Macros

The header file PhoneLookup.h declares the API that this chapter describes.

Phone Lookup Structures and Types ^TOP^

AddrLookupParamsType Struct ^TOP^

Purpose

Structure to pass to PhoneNumberLookupCustom() to precisely control the phone number lookup dialog and paste process. The AddrLookupParamsPtr type defines a pointer to an AddrLookupParamsType structure.

Declared In

PhoneLookup.h

Prototype

typedef struct {
   char *title;
   char *pasteButtonText;
   char lookupString[addrLookupStringLength];
   AddressLookupFields field1;
   AddressLookupFields field2;
   Boolean field2Optional;
   Boolean userShouldInteract;
   char *formatStringP;
   MemHandle resultStringH;
   uint32_t uniqueID;
} AddrLookupParamsType;
typedef AddrLookupParamsType *AddrLookupParamsPtr

Fields

title
Title to appear in the title bar. Supply NULL to use the default title.
pasteButtonText
Text to appear in paste button. Supply NULL to use the default, "paste".
lookupString
Buffer containing the string to look up. If the string matches only one record, that record is used without presenting the lookup dialog to the user. PhoneNumberLookup() and PhoneNumberLookupCustom() both set this field based upon the current selection or cursor position.
field1
Field to search by. This field appears on the left side of the lookup dialog. If the field is the sort field, the search is performed using a binary search. If the field isn't the sort field, searching is performed by a linear search, which can be slow. Supply one of the values in the AddressLookupFields enum to specify the field to search by.
field2
Field to display on the right. Often displays some information about the person. If it is a phone field and a record has multiple instances of the phone type then the person appears once per instance of the phone type. Either field1 or field2 may be a phone field, but not both. Supply one of the values in the AddressLookupFields enum to specify the field to display.
field2Optional
A value of true means that the record need not have field2 in order to be listed. A value of false indicates that field2 is required in order for the record to be listed.
userShouldInteract
A value of true forces the user to resolve non-unique lookups. A false value means a non-unique and complete lookup causes resultStringH to be set to NULL and uniqueID to be set to 0.
formatStringP
Controls the format of the paste string. All characters in the format string are literal unless they identify a field (signified by a caret (^) followed by the field name). For example, the format string "^first - ^home" might result in "Roger - 123-4567". Allowable field names are:
    • name
    • first
    • company
    • address
    • city
    • state
    • zipcode
    • country
    • title
    • custom1
    • custom2
    • custom3
    • custom4
    • work
    • home
    • fax
    • other
    • email
    • main
    • pager
    • mobile
    • listname
resultStringH
If there is a format string, a result string is allocated on the dynamic heap and its handle is returned here.
uniqueID
The unique ID of the found record, or 0 if none was found, is returned here.

Phone Lookup Constants ^TOP^

AddressLookupFields Typedef ^TOP^

Purpose

Specifies the fields you can search by and the corresponding fields to return using the field1 and field2 elements of the AddrLookupParamsType structure. For both field1 and field2, pass one of the values up to but not including addrLookupFieldCount.

Declared In

PhoneLookup.h

Prototype

typedef Enum8 AddressLookupFields

Constants

addrLookupName
addrLookupFirstName
addrLookupCompany
addrLookupAddress
addrLookupCity
addrLookupState
addrLookupZipCode
addrLookupCountry
addrLookupTitle
addrLookupCustom1
addrLookupCustom2
addrLookupCustom3
addrLookupCustom4
addrLookupNote
addrLookupWork
addrLookupHome
addrLookupFax
addrLookupOther
addrLookupEmail
addrLookupMain
addrLookupPager
addrLookupMobile
addrLookupSortField
addrLookupListPhone
addrLookupFieldCount
addrLookupNoField = 0xff

Lookup String Length Constant ^TOP^

Purpose

Maximum size of the lookup string.

Declared In

PhoneLookup.h

Constants

#define addrLookupStringLength 20
Size of the string contained in the lookupString field of AddrLookupParamsType.

Phone Lookup Functions and Macros ^TOP^

PhoneNumberLookup Function ^TOP^

Purpose

Calls the Address Book application to look up a phone number.

Declared In

PhoneLookup.h

Prototype

void PhoneNumberLookup (
   FieldType *fldP
)

Parameters

fldP
Field in which the text to match is found.

Returns

Nothing.

Comments

This function displays the user's phone list and inserts the chosen name and number (or company name, name, and number, if that's how the user's Address Book preferences indicate that the phone list should be sorted) into the specified field. When displaying the phone list, PhoneNumberLookup() scrolls the list to the entry that best matches the supplied field. The match compares the field contents against the name or company name (depending on the user's preferences) as follows:

  • If the field contains selected text, PhoneNumberLookup() tries to match against the selected text. The selected text is then replaced with the text of the chosen address list entry.
  • If there is no selected text in the field, PhoneNumberLookup() matches against the word in which the cursor lies (the match will take place if the cursor is at the beginning, the end, or within a word). The matched word is replaced with the text of the chosen address list entry.
  • If the cursor does not lie within or adjoin a word, PhoneNumberLookup() displays the address list starting at the first entry, and the text of the chosen entry is inserted at the current position within the text field.

If the user chooses Cancel when the address list is displayed, the field contents are left unaltered. The paste operation takes place through the clipboard so that Undo can be used to restore the field to its previous state.

See Also

PhoneNumberLookupCustom()

PhoneNumberLookupCustom Function ^TOP^

Purpose

Calls the Address Book application to look up a phone number.

Declared In

PhoneLookup.h

Prototype

void PhoneNumberLookupCustom (
   FieldType *fldP,
   AddrLookupParamsType *params,
   Boolean useClipboard
)

Parameters

fldP
Field in which the text to match is found.
params
A structure that allows full control over the find dialog and the format of the resulting paste string. See AddrLookupParamsType for a description of the fields in this structure.
useClipboard
If true, PhoneNumberLookupCustom() pastes the result into the field through the clipboard, thereby enabling undo.

Returns

Nothing.

Comments

This function displays two fields from each record in the user's address list and inserts a formatted string based upon fields in the chosen record into the specified field. When displaying the address list, PhoneNumberLookupCustom() scrolls the list to that entry that best matches the supplied field. The match compares the field contents against the field specified in the params structure's field1 element as follows:

  • If the field contains selected text, PhoneNumberLookupCustom() tries to match against the selected text. The selected text is then replaced with the text of the chosen address list entry.
  • If there is no selected text in the field, PhoneNumberLookupCustom() matches against the word in which the cursor lies (the match will take place if the cursor is at the beginning, the end, or within a word). The matched word is replaced with the text of the chosen address list entry.
  • If the cursor does not lie within or adjoin a word, PhoneNumberLookupCustom() displays the address list starting at the first entry, and the text of the chosen entry is inserted at the current position within the text field.

PhoneNumberLookupCustom() copies the portion of the field used for the search—the selected text or the word in which the cursor lies—into the lookupString field in the params structure prior to replacing that part of the field with the user-selected entry.

If the user chooses Cancel when the address list is displayed, the field contents are left unaltered. Depending on the value of the useClipboard parameter, the paste operation can take place through the clipboard so that Undo can be used to restore the field to its previous state.