Miscellaneous User Interface Functions
 

 < 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

-> fldPField 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

-> fldPField object in which the text to match is found.
<-> paramsA 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.
-> useClipboardIf 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

-> rscIDThe 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

-> rscIDThe 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

-> rscIDThe 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.