Part II: System Management

29 Character Attributes

Character Attribute Functions

ChrHorizEllipsis

ChrIsHardKey

ChrNumericSpace

GetCharAttr

GetCharCaselessValue

GetCharSortValue

This chapter provides reference material for character attributes functions defined in CharAttr.h.

Character Attribute Functions ^TOP^

ChrHorizEllipsis Macro ^TOP^

Purpose

Returns the appropriate character code for the horizontal ellipsis.

Declared In

Chars.h

Prototype

#define ChrHorizEllipsis (
   chP
)

Parameters

← chP

Pointer to a variable in which to return the horizontal ellipsis character code.

Returns

Returns nothing. Upon return, the variable pointed to by chP contains the horizontal ellipsis character.

Comments

Version 3.1 of the Palm OS^® uses different character codes for the horizontal ellipsis character and the numeric space character than earlier versions did. Use this macro to return the appropriate code for horizontal ellipsis regardless of which version of Palm OS your application is run on.

ChrIsHardKey Macro ^TOP^

Purpose

Returns true if the character is one of the hard keys on the device.

Declared In

Chars.h

Prototype

#define ChrIsHardKey (
   ch
)

Parameters

→ ch

The character from the keyDownEvent.

Returns

true if the character is one of the four built-in hard keys on the device, false otherwise.

Compatibility

This macro is obsolete and replaced by TxtCharIsHardKey() if the International Feature Set is present.

ChrNumericSpace Macro ^TOP^

Purpose

Returns the appropriate character code for the numeric space.

Declared In

Chars.h

Prototype

#define ChrNumericSpace (
   chP
)

Parameters

← chP

Pointer to a variable in which to return the numeric space character code.

Returns

Returns nothing. Upon return, the variable pointed to by chP contains the numeric space character.

Comments

Version 3.1 of the Palm OS uses different character codes for the horizontal ellipsis character and the numeric space character than earlier versions did. Use this macro to return the appropriate code for numeric space regardless of which version of Palm OS your application is run on.

GetCharAttr Function ^TOP^

Purpose

Return a pointer to the character attribute array. This array is used by the character classification and character conversion macros (such as isalpha).

Declared In

CharAttr.h

Prototype

UInt16 *GetCharAttr (
   void
)

Parameters

None

Returns

A pointer to the attributes array. This is an array of 256 UInt16 values, one for each possible character code. See CharAttr.h for an explanation of the attributes.

Compatibility

This function is not implemented if International Feature Set is present.

If 5.0 New Feature Set is present, this function is implemented in PACE. However, it only supports the Latin table, regardless of the localization.

See Also

TxtCharAttr(), TxtCharXAttr()

GetCharCaselessValue Function ^TOP^

Purpose

Return a pointer to an array that maps all characters to an assigned caseless and accentless value. Use this function for finding text.

Declared In

CharAttr.h

Prototype

UInt8 *GetCharCaselessValue (
   void
)

Parameters

None.

Returns

Returns a pointer to the sort array, which is an array of 256 bytes.

Comments

The GetCharCaselessValue conversion table converts each character into a numeric value that is caseless and sorted according to Microsoft Windows sorting rules:

• Punctuation characters have the lowest values,
• followed by numbers,
• followed by alpha characters.

  All forms of each alpha character have equivalent values, so that e = E = e-grave = e-circumflex, etc.

This conversion table is used by all the Palm OS sorting and comparison routines to yield caseless searches and caseless sorts in the almost same order as Windows-based programs, except that Palm OS routines produce the same sorting for all locales.

Compatibility

This function is not implemented if International Feature Set is present.

If 5.0 New Feature Set is present, this function is implemented in PACE. However, it only supports the Latin table, regardless of the localization.

GetCharSortValue Function ^TOP^

Purpose

Return a pointer to an array that maps all characters to an assigned sorting value. Use this function for ordering (sorting) text.

Declared In

CharAttr.h

Prototype

UInt8 *GetCharSortValue (
   void
)

Parameters

None.

Returns

Returns a pointer to the attributes array. This is an array of 256 UInt8 values, one for each possible character code.

Compatibility

This function is not implemented if International Feature Set is present.

If 5.0 New Feature Set is present, this function is implemented in PACE. However, it only supports the Latin table, regardless of the localization.