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
AddrLookupParamsType Struct
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()
andPhoneNumberLookupCustom()
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
orfield2
may be a phone field, but not both. Supply one of the values in theAddressLookupFields
enum to specify the field to display. -
field2Optional
- A value of
true
means that the record need not havefield2
in order to be listed. A value offalse
indicates thatfield2
is required in order for the record to be listed. -
userShouldInteract
- A value of
true
forces the user to resolve non-unique lookups. Afalse
value means a non-unique and complete lookup causesresultStringH
to be set toNULL
anduniqueID
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:
-
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
AddressLookupFields Typedef
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
Purpose
Maximum size of the lookup string.
Declared In
PhoneLookup.h
Constants
-
#define addrLookupStringLength 20
- Size of the string contained in the
lookupString
field ofAddrLookupParamsType
.
Phone Lookup Functions and Macros
PhoneNumberLookup Function
Purpose
Calls the Address Book application to look up a phone number.
Declared In
PhoneLookup.h
Prototype
void PhoneNumberLookup (
FieldType *fldP
)
Parameters
Returns
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 Function
Purpose
Calls the Address Book application to look up a phone number.
Declared In
PhoneLookup.h
Prototype
void PhoneNumberLookupCustom ( FieldType*fldP
, AddrLookupParamsType*params
, BooleanuseClipboard
)
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
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.