Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

12    Shift Indicator

Input Services

Exploring Palm OS®

This chapter describes the API for the shift indicator. It covers:

Shift Indicator Constants
Shift Indicator Events
Shift Indicator Functions and Macros

The header file GraffitiShift.h declares the API that this chapter describes.

Shift Indicator Constants ^TOP^

Dimension Constants ^TOP^

Purpose

Give the size requirements for the shift indicator.

Declared In

GraffitiShift.h

Constants

#define kMaxGsiHeight 10
The maximum height for a shift indicator.
#define kMaxGsiWidth 9
The maximum width for a shift indicator.

GsiShiftState Typedef ^TOP^

Purpose

Shift states. For system use only.

Declared In

GraffitiShift.h

Prototype

typedef Enum8 GsiShiftState

Constants

gsiShiftNone
The default mode. For the ISO-Latin character encoding, the normal mode translates strokes into lowercase letters.
gsiNumLock
The strokes will be interpreted as numeric characters.
gsiCapsLock
All of the characters will be uppercase until the mode is set to something else.
gsiShiftPunctuation
The next stroke will be interpreted as a punctuation mark or symbol, and then the mode is reset to normal.
gsiShiftExtended
The next stroke is a special symbol or part of the extended character set. The Graffiti® 2 handwriting recognition engine uses this mode for special symbols such as the trademark symbol.
gsiShiftUpper
The next stroke will be translated into an uppercase character rather than the normal lowercase characters.
gsiShiftLower
The next stroke will be translated into a lowercase character.

Lock Flag Constants ^TOP^

Purpose

Specifies what lock state, if any, the shift state is in.

Declared In

GraffitiShift.h

Constants

#define glfCapsLock 0x0001
Turn on the caps lock.
#define glfNumLock 0x0002
Turn on the numeric lock.
#define glfForceUpdate 0x8000
Forces the shift indicator to update. If this flag is not used, the indicator only updates if you are setting it to a new state.

Temporary Shift State Constants ^TOP^

Purpose

Define temporary shift states.

Declared In

GraffitiShift.h

Constants

#define gsiTempShiftNone 0
The default mode. For the ISO-Latin character encoding, the normal mode translates strokes into lowercase letters.
#define gsiTempShiftPunctuation 1
The next stroke will be interpreted as a punctuation mark or symbol, and then the mode is reset to normal.
#define gsiTempShiftExtended 2
The next stroke is a special symbol or part of the extended character set. The Graffiti 2 handwriting recognition engine uses this mode for special symbols such as the trademark symbol.
#define gsiTempShiftUpper 3
The next stroke will be translated into an uppercase character rather than the normal lowercase characters.
#define gsiTempShiftLower 4
The next stroke will be translated into a lowercase character.

Shift Indicator Events ^TOP^

gsiStateChangeEvent ^TOP^

Purpose

Sent when the shift indicator should change state.

Declared In

Event.h

Prototype

struct gsiStateChange {
   

   uint16_t lockFlags;
   

   uint16_t tempShift;
   

} gsiStateChange


Parameters

lockFlags
One of the Lock Flag Constants.
tempShift
One of the Temporary Shift State Constants.

Shift Indicator Functions and Macros ^TOP^

GsiEnable Function ^TOP^

Purpose

Enables or disables the shift indicator.

Declared In

GraffitiShift.h

Prototype

void GsiEnable (
   Boolean enableIt
)

Parameters

enableIt
true to enable, false to disable.

Returns

Nothing.

Comments

Enabling the indicator makes it visible, disabling it makes the insertion point invisible.

GsiEnabled Function ^TOP^

Purpose

Returns true if the shift indicator is enabled, or false if it's disabled.

Declared In

GraffitiShift.h

Prototype

Boolean GsiEnabled (
   void
)

Parameters

None.

Returns

true if enabled, false if not.

GsiInitialize Function ^TOP^

Purpose

Initializes the global variables used to manage the shift indicator.

Declared In

GraffitiShift.h

Prototype

void GsiInitialize (
   void
)

Parameters

None.

Returns

Nothing.

GsiSetLocation Function ^TOP^

Purpose

Sets the display-relative position of the shift indicator.

Declared In

GraffitiShift.h

Prototype

void GsiSetLocation (
   int16_t x,
   int16_t y
)

Parameters

x, y
Coordinate of left side and top of the indicator.

Returns

Nothing.

Comments

The indicator is not redrawn by this routine.

Do not use this function in application code. It is used internally by the Form Manager. If you need to change the shift indicator's location, do so using the automatic form layout facility described in the section "Laying Out a Form or Dialog" in the book Exploring Palm OS: User Interface.

GsiSetShiftState Function ^TOP^

Purpose

Sets the shift indicator.

Declared In

GraffitiShift.h

Prototype

void GsiSetShiftState (
   uint16_t lockFlags,
   uint16_t tempShift
)

Parameters

lockFlags
One of the Lock Flag Constants.
tempShift
One of the Temporary Shift State Constants.

Returns

Nothing.

Comments

This function affects only the state of the UI element, not the underlying handwriting recognition engine.