This chapter provides descriptions of miscellaneous user interface functions. It covers the following topics:
You can find declarations for the functions described in this chapter in the header files AppLaunchCmd.h
,PhoneLookup.h
, and UIResources.h
.
Miscellaneous User Interface Data Structures
The PhoneNumberLookupCustom()
function uses these data structures to look up contact information based upon the current cursor position.
AddressLookupFields Enum
Purpose
The AddressLookupFields
enum 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
.
Prototype
typedef enum { 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 } AddressLookupFields;
AddrLookupParamsType Struct
Purpose
Pass this structure to PhoneNumberLookupCustom()
to precisely control the phone number lookup dialog and paste process.
Prototype
typedef struct { Char *title; Char *pasteButtonText; Char lookupString[addrLookupStringLength]; AddressLookupFields field1; AddressLookupFields field2; Boolean field2Optional; Boolean userShouldInteract; Char *formatStringP; MemHandle resultStringH; UInt32 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:
-
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.
Miscellaneous User Interface Functions
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
Nothing returned; it's locked.
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 that 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.
Compatibility
Implemented only if 2.0 New Feature Set is present.
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, Boolean useClipboard )
Parameters
-
→
fldP
- Field object 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 returned; it's locked.
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,
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.
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.
Compatibility
Implemented only if 4.0 New Feature Set is present.
ResLoadConstant Function
Purpose
Load a constant from a 'tint'
resource and return its value.
Declared In
UIResources.h
Prototype
UInt32 ResLoadConstant ( UInt16 rscID )
Parameters
Returns
The four-byte value of the constant in the resource, or 0 if the resource could not be found. The return value may be cast as necessary.
Comments
Use this function to load "soft constants"—constant values that are stored as 'tint'
resources. (All open resource databases are searched for the resource ID you specify.) You should store a constant value as a resource when its value changes depending on the locale.
As an example, consider the maximum length of the Alarm Sound trigger label in the Datebook application's preferences panel. The list displayed by this trigger uses the localized name for each sound stored in the system. Because localized names are used, the maximum length that the Datebook application allows for the label differs depending on the current locale. The maximum length is stored as a resource constant so that each overlay database can specify a different value for the constant.
Compatibility
Implemented only if 3.5 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS®, link with the PalmOSGlue library and call ResGlueLoadConstant
. For more information, see Chapter 80, "PalmOSGlue Library."
See Also
DmGetResource()
, DmGet1Resource()
ResLoadForm Function
Purpose
Copy and initialize a form resource. The structures are complete except pointers updating. Pointers are stored as offsets from the beginning of the form.
Declared In
UIResources.h
Prototype
void *ResLoadForm ( UInt16 rscID )
Parameters
Returns
The handle of the memory block that the form is in, since the form structure begins with the WindowType
, this is also a WinHandle
.
Compatibility
If either 5.0 New Feature Set or Palm OS Cobalt Feature Set is present this function is unimplemented.
ResLoadMenu Function
Purpose
Copy and initialize a menu resource. The structures are complete except pointers updating. Pointers are stored as offsets from the beginning of the menu.
Declared In
UIResources.h
Prototype
void *ResLoadMenu ( UInt16 rscID )
Parameters
Returns
The handle of the memory block that the form is in, since the form structure begins with the WindowType
this is also a WinHandle
.