API Guide Home
(Online version only)

Header Files » Incs » 68k » system

PalmGoLCD.h File Reference

Detailed Description

Public include header file for the GoLCD Library.

Version:
1.1
You can use the functions in this API to enable or disable fullscreen writing, enable and disable the Graffiti 2 shift indicator (GSI) as a control for full-screen writing, enable and disable Graffiti 2 inking, and even change the colors of Graffiti 2 inking and the GSI.

You can check whether the GoLCD Manager is installed by examining its feature set. Call FtrGet as follows: 

 err = FtrGet (goLcdCreator, goLcdFtrNumVersion, &value);

Definition in file PalmGoLCD.h.

Include dependency graph for PalmGoLCD.h:

Go to the source code of this file.

Functions

Function Documentation

void GoLcdGetBounds ( UInt16  libRefNum,
RectangleType *  rectP 
)

Returns the current bounds defined for use with GoLCD.

Parameters:
libRefNum,: IN: Reference number of the GoLCD library.
rectP,: IN: Points to the returned rectangle.
Remarks:
GoLCD ignores any succession of pen events (a series of penDownEvents followed by a penUpEvent) if the initial penDownEvent occurs outside its bounds. By default, its bounds are the entire display and users can start drawing full-screen writing characters anywhere except for the right-most scroll bar and the menu bar area.
 RectangleType gCurrentBounds;
 GoLcdGetBounds(gGoLcdLibRefNum, &gCurrentBounds);

See also:
GoLcdSetBounds

void GoLcdGetGsiState ( UInt16  libRefNum,
GoLcdGsiStateType *  stateP,
GoLcdColorModeType *  colorModeP,
RGBColorType *  rgbP 
)

Returns the GSI state associated with GoLCD.

Parameters:
libRefNum,: IN: Reference number of the GoLCD library.
stateP,: IN: Points to the returned GoLCD GSI state.
colorModeP,: IN: Points to the returned GoLCD color mode for GSI.
rgbP,: IN: Valid only if colorMode is set to goLcdColorOverride. Points to an RGB color value corresponding to the current color used for inking. (The RGBColorType is defined in the header file Bitmap.h.)
Remarks:
In normal operation, the GSI is drawn in the lower-right portion of the screen when the user enters the shift keystroke. The functionality of the GSI can be changed into an enable and disable control for GoLCD. This function returns the current state of the GSI.
 GoLcdGsiStateType gCurrentGoLcdGsiState = goLcdGsiNormal;
 GoLcdColorModeType gCurrentGoLcdColorMode = goLcdColorDefault;
 RGBColorType gCurrentColor;
 GoLcdGetGsiState(gGoLcdLibRefNum, &gCurrentGoLcdGsiState, &gCurrentGoLcdColorMode, &gCurrentColor);

See also:
GoLcdSetGsiState

void GoLcdGetInkState ( UInt16  libRefNum,
GoLcdInkStateType *  stateP,
GoLcdColorModeType *  colorModeP,
RGBColorType *  rgbP 
)

Returns the current state of GoLCD inking.

Parameters:
libRefNum,: IN: Reference number of the GoLCD library.
stateP,: IN: Points to the returned GoLCD ink state.
colorModeP,: IN: Points to the returned GoLCD color mode for ink.
rgbP,: IN: Valid only if colorMode is set to goLcdColorOverride. Points to an RGB color value corresponding to the current color used for inking. (The RGBColorType is defined in the header file Bitmap.h.)
 GoLcdInkStateType gCurrentGoLcdInkState = goLcdInkDisabled;
 GoLcdColorModeType gCurrentGoLcdColorMode = goLcdColorDefault;
 RGBColorType gCurrentColor;
 GoLcdGetInkState(gGoLcdLibRefNum, &gCurrentGoLcdInkState, &gCurrentGoLcdColorMode, &gCurrentColor);

See also:
GoLcdSetInkState

GoLcdStatusType GoLcdGetStatus ( UInt16  libRefNum  ) 

Returns whether the GoLCD functionality is enabled, disabled, or not available on this device.

Parameters:
libRefNum,: IN: Reference number of the GoLCD library.
Return values:
GoLcdStatusType Returns the current GoLCD status.
See also:
GoLcdStatusType
 GoLcdStatusType gCurrentGoLcdStatus = goLcdNotAvailable;
 gCurrentGoLcdStatus = GoLcdGetStatus(gGoLcdLibRefNum);
 switch(gCurrentGoLcdStatus) {
     case goLcdDisabled:
         // GoLcd is disabled
         break;
     case goLcdEnabled:
         // GoLcd is Enabled
         break;
     case goLcdNotAvailable:
     default:
         // Not available
         break;
 }

See also:
GoLcdSetStatus

UInt32 GoLcdGetTimeout ( UInt16  libRefNum,
GoLcdModeType  mode 
)

Returns the length, in system ticks, of the time-out value of GoLCD.

Parameters:
libRefNum,: IN: Reference number of the GoLCD library.
mode,: IN: Specifies the GoLCD mode.
Return values:
UInt32 Returns the length (in system ticks) of the time-out value.
Remarks:
GoLCD starts in goLcdPenTapMode. When a penDownEvent is received, a timer is started. If a penUpEvent is received before the timer reaches the time-out value for this mode, the pen events are passed on to the event handler for the application control. Otherwise, if the pen events exceed the time-out value and the x, y coordinates change significantly, GoLCD enters goLcdGraffitiMode and treats the pen events as a Graffiti 2 stroke.
The default time-out value for goLcdPenTapMode is 15 system ticks, or 150 milliseconds.
When it enters goLcdGraffitiMode, GoLCD continuously interprets all pen events as Graffiti 2 strokes. There is a time-out value associated with goLcdGraffitiMode, however. If it does not receive a new pen event within the allotted time, it returns to goLcdPenTapMode.
The default time-out value for goLcdGraffitiMode is 150 system ticks, or 1500 milliseconds.
 UInt32 gCurrentTimeout = GoLcdGetTimeout(gGoLcdLibRefNum, goLcdPenTapMode);

See also:
GoLcdSetTimeout

Err GoLcdLibClose ( UInt16  libRefNum  ) 

Closes the GoLCD library. This function should be called after your application has finished with the GoLCD library.

Parameters:
libRefNum,: IN: Reference number of the GoLCD library.
Return values:
Err The error code returned from the library. If this is errNone, the function was sucessful.
 err = GoLcdLibClose(gGoLcdLibRefNum);
 if( err == errNone )
     err = SysLibRemove(gGoLcdLibRefNum);

See also:
GoLcdLibOpen

Err GoLcdLibOpen ( UInt16  libRefNum  ) 

Opens the GoLCD library. This function should be called prior to calling the other GoLCD functions.

Parameters:
libRefNum,: IN: Reference number of the GoLCD library.
Return values:
Err The error code returned from the library. If this is errNone, the function was sucessful.
 UInt16 gGoLcdLibRefNum = 0;
 err = SysLibFind(goLcdLibName, &gGoLcdLibRefNum);
 if( err == sysErrLibNotFound )
 {
     err = SysLibLoad(goLcdLibType, goLcdLibCreator, &gGoLcdLibRefNum);
         if( !err ) {
             err = GoLcdLibOpen(gGoLcdLibRefNum);
         }
 }

See also:
GoLcdLibClose

void GoLcdSetBounds ( UInt16  libRefNum,
RectangleType *  rectP 
)

Sets the bounds defined for use with GoLCD.

Parameters:
libRefNum,: IN: Reference number of the GoLCD library.
rectP,: IN: Points to the rectangle value to set.
Remarks:
GoLCD ignores any succession of pen events (a series of penDownEvents followed by a penUpEvent) if the initial penDownEvent occurs outside its bounds. By default, its bounds are the entire display and users can start drawing full-screen writing characters anywhere except for the right-most scroll bar and the menu bar area.
 RectangleType gNewBounds = { { 0, 0 } , { 50, 50 } };
 GoLcdGetBounds(gGoLcdLibRefNum, &gNewBounds);

See also:
GoLcdGetBounds

void GoLcdSetGsiState ( UInt16  libRefNum,
GoLcdGsiStateType  state,
GoLcdColorModeType  colorMode,
RGBColorType *  rgbP 
)

Sets the GSI state associated with GoLCD.

Parameters:
libRefNum,: IN: Reference number of the GoLCD library.
state,: IN: Sets the GoLCD GSI state.
colorMode,: IN: Sets the GoLCD color mode for GSI.
rgbP,: IN: Valid only if colorMode is set to goLcdColorOverride. Points to an RGB color value corresponding to the current color used for inking. (The RGBColorType is defined in the header file Bitmap.h.)
Remarks:
In normal operation, the GSI is drawn in the lower-right portion of the screen when the user enters the shift keystroke. The functionality of the GSI can be changed into an enable and disable control for GoLCD. This function determines whether the GSI is converted into a GoLCD control. This setting will apply to all GSIs in any active form.
 RGBColorType gNewColor = { 0, 255, 0, 0}; // Red
 GoLcdSetGsiState(gGoLcdLibRefNum, goLcdGsiOverride, goLcdColorOverride, &gNewColor);

See also:
GoLcdGetGsiState

void GoLcdSetInkState ( UInt16  libRefNum,
GoLcdInkStateType  state,
GoLcdColorModeType  colorMode,
RGBColorType *  rgbP 
)

Sets the state of GoLCD inking.

Parameters:
libRefNum,: IN: Reference number of the GoLCD library.
state,: IN: Sets the new GoLCD ink state.
colorMode,: IN: Sets the new GoLCD color mode for ink.
rgbP,: IN: Valid only if colorMode is set to goLcdColorOverride. Points to an RGB color value corresponding to the current color used for inking. (The RGBColorType is defined in the header file Bitmap.h.)
Remarks:
Inking, also known as echoing, refers to the drawing of Graffiti 2 strokes in the application area of the display.
 RGBColorType gNewColor = { 0, 255, 0, 0}; // Red
 GoLcdSetInkState(gGoLcdLibRefNum, goLcdInkEnabled, goLcdColorOverride, &gNewColor);

See also:
GoLcdGetInkState

GoLcdStatusType GoLcdSetStatus ( UInt16  libRefNum,
GoLcdStatusType  status 
)

Enables or disables the GoLCD functionality.

Parameters:
libRefNum,: IN: Reference number of the GoLCD library.
status IN: Sets the new GoLCD status.
Return values:
GoLcdStatusType Returns the previous GoLCD status.
 GoLcdStatusType gPreviousGoLcdStatus = goLcdNotAvailable;
 gPreviousGoLcdStatus = GoLcdSetStatus(gGoLcdLibRefNum, goLcdEnabled);

See also:
GoLcdGetStatus

UInt32 GoLcdSetTimeout ( UInt16  libRefNum,
GoLcdModeType  mode,
UInt32  ticks 
)

Sets the length, in system ticks, of the time-out value of GoLCD.

Parameters:
libRefNum,: IN: Reference number of the GoLCD library.
mode,: IN: Specifies the GoLCD mode.
ticks,: IN: The new time-out length in system ticks.
Return values:
UInt32 Returns the length (in system ticks) of the previous time-out value.
Remarks:
GoLCD starts in goLcdPenTapMode. When a penDownEvent is received, a timer is started. If a penUpEvent is received before the timer reaches the time-out value for this mode, the pen events are passed on to the event handler for the application control. Otherwise, if the pen events exceed the time-out value and the x, y coordinates change significantly, GoLCD enters goLcdGraffitiMode and treats the pen events as a Graffiti 2 stroke.
The default time-out value for goLcdPenTapMode is 15 system ticks, or 150 milliseconds.
When it enters goLcdGraffitiMode, GoLCD continuously interprets all pen events as Graffiti 2 strokes. There is a time-out value associated with goLcdGraffitiMode, however. If it does not receive a new pen event within the allotted time, it returns to goLcdPenTapMode.
The default time-out value for goLcdGraffitiMode is 150 system ticks, or 1500 milliseconds.
 UInt32 gPreviousTimeout = GoLcdSetTimeout(gGoLcdLibRefNum, goLcdPenTapMode, 100);

See also:
GoLcdGetTimeout

Top Palm Developer Network
© 2004-2008, Palm, Inc. All rights reserved.
Generated on Fri Jun 13 10:07:42 2008 for Palm API Guide