< Home < Developers < Development Support < Documentation

## 23 Miscellaneous User Interface Functions

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part I: User Interface 23 Miscellaneous User Interface Functions Miscellaneous User Interface Data Structures AddressLookupFields AddrLookupParamsType Miscellaneous User Interface Functions PhoneNumberLookup PhoneNumberLookupCustom ResLoadConstant ResLoadForm ResLoadMenu |  |  |  | This chapter provides descriptions of miscellaneous user interface functions. It covers the following topics: Miscellaneous User Interface Data Structures Miscellaneous User Interface Functions 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 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.
    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 Pass this structure to PhoneNumberLookupCustom to precisely control the phone number lookup dialog and paste process.
    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;
#### Value Descriptions #####
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.
## Miscellaneous User Interface Functions ## PhoneNumberLookup #### Purpose Calls the Address Book application to look up a phone number. #### Prototype void PhoneNumberLookup (FieldType *fldP) #### Parameters #####
-> fldP | Field object in which the text to match is found.
#### Result 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 ## New PhoneNumberLookupCustom #### Purpose Calls the Address Book application to look up a phone number. #### 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.
#### Result 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 #### Purpose Load a constant from a 'tint' resource and return its value. #### Prototype UInt32 ResLoadConstant (UInt16 rscID) #### Parameters #####
-> rscID | The ID of the 'tint' resource (symbolically named constantRscType) to load.
#### Result 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 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 76, "PalmOSGlue Library." #### See Also DmGetResource, DmGet1Resource ## ResLoadForm #### 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. #### Prototype void* ResLoadForm (UInt16 rscID) #### Parameters #####
-> rscID | The resource ID of the form.
#### Result The handle of the memory block that the form is in, since the form structure begins with the WindowType, this is also a WinHandle. ## ResLoadMenu #### 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. #### Prototype void* ResLoadMenu (UInt16 rscID) #### Parameters #####
-> rscID | The resource ID of the menu.
#### Result The handle of the memory block that the form is in, since the form structure begins with the WindowType this is also a WinHandle. |