API Guide Home (Online version only) |

# 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

- Err GoLcdLibOpen (UInt16 libRefNum)
    Opens the GoLCD library. This function should be called prior to calling the other GoLCD functions.
- Err GoLcdLibClose (UInt16 libRefNum)
    Closes the GoLCD library. This function should be called after your application has finished with the GoLCD library.
- GoLcdStatusType GoLcdGetStatus (UInt16 libRefNum)
    Returns whether the GoLCD functionality is enabled, disabled, or not available on this device.
- GoLcdStatusType GoLcdSetStatus (UInt16 libRefNum, GoLcdStatusType status)
    Enables or disables the GoLCD functionality.
- void GoLcdGetInkState (UInt16 libRefNum, GoLcdInkStateType *stateP, GoLcdColorModeType *colorModeP, RGBColorType *rgbP)
    Returns the current state of GoLCD inking.
- void GoLcdSetInkState (UInt16 libRefNum, GoLcdInkStateType state, GoLcdColorModeType colorMode, RGBColorType *rgbP)
    Sets the state of GoLCD inking.
- void GoLcdGetGsiState (UInt16 libRefNum, GoLcdGsiStateType *stateP, GoLcdColorModeType *colorModeP, RGBColorType *rgbP)
    Returns the GSI state associated with GoLCD.
- void GoLcdSetGsiState (UInt16 libRefNum, GoLcdGsiStateType state, GoLcdColorModeType colorMode, RGBColorType *rgbP)
    Sets the GSI state associated with GoLCD.
- UInt32 GoLcdGetTimeout (UInt16 libRefNum, GoLcdModeType mode)
    Returns the length, in system ticks, of the time-out value of GoLCD.
- UInt32 GoLcdSetTimeout (UInt16 libRefNum, GoLcdModeType mode, UInt32 ticks)
    Sets the length, in system ticks, of the time-out value of GoLCD.
- void GoLcdGetBounds (UInt16 libRefNum, RectangleType *rectP)
    Returns the current bounds defined for use with GoLCD.
- void GoLcdSetBounds (UInt16 libRefNum, RectangleType *rectP)
    Sets the bounds defined for use with GoLCD.

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