API Guide Home (Online version only) |

# PalmGoLCD.h

Go to the documentation of this file.

    00001 /******************************************************************************
    00002  * Copyright (c) 2005 palmOne, Inc. or its subsidiaries.
    00003  * All rights reserved.
    00004  *****************************************************************************/
    00005 /**
    00006  * @ingroup GoLCD
    00007  *
    00008  */
    00009
    00010 /**
    00011  * @file    PalmGoLCD.h
    00012  * @version 1.1
    00013  *
    00014  * @brief Public include header file for the GoLCD Library.
    00015  *
    00016  *    You can use the functions in this API to enable or disable fullscreen
    00017  *    writing, enable and disable the Graffiti 2 shift indicator (GSI) as a control for
    00018  *    full-screen writing, enable and disable Graffiti 2 inking, and even change the colors
    00019  *    of Graffiti 2 inking and the GSI.
    00020  *
    00021  *    You can check whether the GoLCD Manager is installed by examining its feature set.
    00022  *    Call FtrGet as follows:
    00023  * @code err = FtrGet (goLcdCreator, goLcdFtrNumVersion, &value); @endcode
    00024  *
    00025  *
    00026  * <hr>
    00027  */
    00028
    00029
    00030 #ifndef __PALMGOLCD_H__
    00031 #define __PALMGOLCD_H__
    00032
    00033 #include <PalmTypes.h>
    00034 #include <LibTraps.h>
    00035
    00036 #include <Common/System/PalmGoLCDCommon.h>
    00037
    00038
    00039 /********************************************************************
    00040  * Prototypes
    00041  ********************************************************************/
    00042 #ifdef __cplusplus
    00043 extern "C" {
    00044 #endif
    00045
    00046 /**
    00047  * @brief Opens the GoLCD library.
    00048  *        This function should be called prior to calling the other GoLCD functions.
    00049  *
    00050  * @param libRefNum:    IN:  Reference number of the GoLCD library.
    00051  * @retval Err The error code returned from the library. If this is errNone, the
    00052  *     function was sucessful.
    00053  *
    00054  * @code
    00055  * UInt16 gGoLcdLibRefNum = 0;
    00056  * err = SysLibFind(goLcdLibName, &gGoLcdLibRefNum);
    00057  * if( err == sysErrLibNotFound )
    00058  * {
    00059  *     err = SysLibLoad(goLcdLibType, goLcdLibCreator, &gGoLcdLibRefNum);
    00060  *         if( !err ) {
    00061  *             err = GoLcdLibOpen(gGoLcdLibRefNum);
    00062  *         }
    00063  * } @endcode
    00064  *
    00065  * @see GoLcdLibClose
    00066  */
    00067 Err GoLcdLibOpen(UInt16 libRefNum)
    00068                 SYS_TRAP(kGoLcdLibTrapOpen);
    00069
    00070 /**
    00071  * @brief Closes the GoLCD library.
    00072  *    This function should be called after your application has finished with the GoLCD
    00073  *    library.
    00074  *
    00075  * @param libRefNum:    IN:  Reference number of the GoLCD library.
    00076  * @retval Err The error code returned from the library. If this is errNone, the
    00077  *     function was sucessful.
    00078  *
    00079  * @code
    00080  * err = GoLcdLibClose(gGoLcdLibRefNum);
    00081  * if( err == errNone )
    00082  *     err = SysLibRemove(gGoLcdLibRefNum); @endcode
    00083  *
    00084  * @see GoLcdLibOpen
    00085  */
    00086 Err GoLcdLibClose(UInt16 libRefNum)
    00087                 SYS_TRAP(kGoLcdLibTrapClose);
    00088
    00089 /**
    00090  * @brief Returns whether the GoLCD functionality is enabled, disabled, or not available on
    00091  *    this device.
    00092  *
    00093  * @param libRefNum:    IN:  Reference number of the GoLCD library.
    00094  * @retval GoLcdStatusType Returns the current GoLCD status.
    00095  *
    00096  * @see GoLcdStatusType
    00097  *
    00098  * @code
    00099  * GoLcdStatusType gCurrentGoLcdStatus = goLcdNotAvailable;
    00100  * gCurrentGoLcdStatus = GoLcdGetStatus(gGoLcdLibRefNum);
    00101  * switch(gCurrentGoLcdStatus) {
    00102  *     case goLcdDisabled:
    00103  *         // GoLcd is disabled
    00104  *         break;
    00105  *     case goLcdEnabled:
    00106  *         // GoLcd is Enabled
    00107  *         break;
    00108  *     case goLcdNotAvailable:
    00109  *     default:
    00110  *         // Not available
    00111  *         break;
    00112  * } @endcode
    00113  *
    00114  * @see GoLcdSetStatus
    00115  */
    00116 GoLcdStatusType GoLcdGetStatus(UInt16 libRefNum)
    00117                 SYS_TRAP(kGoLcdLibTrapGetStatus);
    00118
    00119 /**
    00120  * @brief Enables or disables the GoLCD functionality.
    00121  *
    00122  * @param libRefNum:    IN:  Reference number of the GoLCD library.
    00123  * @param status    IN:  Sets the new GoLCD status.
    00124  * @retval GoLcdStatusType Returns the previous GoLCD status.
    00125  *
    00126  * @code
    00127  * GoLcdStatusType gPreviousGoLcdStatus = goLcdNotAvailable;
    00128  * gPreviousGoLcdStatus = GoLcdSetStatus(gGoLcdLibRefNum, goLcdEnabled); @endcode
    00129  *
    00130  * @see GoLcdGetStatus
    00131  */
    00132 GoLcdStatusType GoLcdSetStatus(UInt16 libRefNum, GoLcdStatusType status)
    00133                 SYS_TRAP(kGoLcdLibTrapSetStatus);
    00134
    00135 /**
    00136  * @brief Returns the current state of GoLCD inking.
    00137  *
    00138  * @param libRefNum:    IN:  Reference number of the GoLCD library.
    00139  * @param stateP:   IN:  Points to the returned GoLCD ink state.
    00140  * @param colorModeP:   IN:  Points to the returned GoLCD color mode for ink.
    00141  * @param rgbP:     IN:  Valid only if colorMode is set to goLcdColorOverride. Points to an RGB color
    00142  *               value corresponding to the current color used for inking. (The RGBColorType is
    00143  *               defined in the header file Bitmap.h.)
    00144  *
    00145  * @code
    00146  * GoLcdInkStateType gCurrentGoLcdInkState = goLcdInkDisabled;
    00147  * GoLcdColorModeType gCurrentGoLcdColorMode = goLcdColorDefault;
    00148  * RGBColorType gCurrentColor;
    00149  * GoLcdGetInkState(gGoLcdLibRefNum, &gCurrentGoLcdInkState, &gCurrentGoLcdColorMode, &gCurrentColor); @endcode
    00150  *
    00151  * @see GoLcdSetInkState
    00152  */
    00153 void GoLcdGetInkState(UInt16 libRefNum, GoLcdInkStateType *stateP, GoLcdColorModeType *colorModeP, RGBColorType *rgbP)
    00154                 SYS_TRAP(kGoLcdLibTrapGetInkState);
    00155
    00156 /**
    00157  * @brief Sets the state of GoLCD inking.
    00158  *
    00159  * @param libRefNum:    IN:  Reference number of the GoLCD library.
    00160  * @param state:    IN:  Sets the new GoLCD ink state.
    00161  * @param colorMode:    IN:  Sets the new GoLCD color mode for ink.
    00162  * @param rgbP:     IN:  Valid only if colorMode is set to goLcdColorOverride. Points to an RGB color
    00163  *               value corresponding to the current color used for inking. (The RGBColorType is
    00164  *               defined in the header file Bitmap.h.)
    00165  *
    00166  * @remarks <em>Inking</em>, also known as <em>echoing</em>, refers to the drawing of Graffiti 2 strokes in the
    00167  *          application area of the display.
    00168  *
    00169  * @code
    00170  * RGBColorType gNewColor = { 0, 255, 0, 0}; // Red
    00171  * GoLcdSetInkState(gGoLcdLibRefNum, goLcdInkEnabled, goLcdColorOverride, &gNewColor); @endcode
    00172  *
    00173  * @see GoLcdGetInkState
    00174  */
    00175 void GoLcdSetInkState(UInt16 libRefNum, GoLcdInkStateType state, GoLcdColorModeType colorMode, RGBColorType *rgbP)
    00176                 SYS_TRAP(kGoLcdLibTrapSetInkState);
    00177
    00178 /**
    00179  * @brief Returns the GSI state associated with GoLCD.
    00180  *
    00181  * @param libRefNum:    IN:  Reference number of the GoLCD library.
    00182  * @param stateP:   IN:  Points to the returned GoLCD GSI state.
    00183  * @param colorModeP:   IN:  Points to the returned GoLCD color mode for GSI.
    00184  * @param rgbP:     IN:  Valid only if colorMode is set to goLcdColorOverride. Points to an RGB color
    00185  *               value corresponding to the current color used for inking. (The RGBColorType is
    00186  *               defined in the header file Bitmap.h.)
    00187  *
    00188  * @remarks In normal operation, the GSI is drawn in the lower-right portion of the screen when
    00189  *          the user enters the shift keystroke. The functionality of the GSI can be changed into
    00190  *          an enable and disable control for GoLCD. This function returns the current state of
    00191  *          the GSI.
    00192  *
    00193  * @code
    00194  * GoLcdGsiStateType gCurrentGoLcdGsiState = goLcdGsiNormal;
    00195  * GoLcdColorModeType gCurrentGoLcdColorMode = goLcdColorDefault;
    00196  * RGBColorType gCurrentColor;
    00197  * GoLcdGetGsiState(gGoLcdLibRefNum, &gCurrentGoLcdGsiState, &gCurrentGoLcdColorMode, &gCurrentColor); @endcode
    00198  *
    00199  * @see GoLcdSetGsiState
    00200  */
    00201 void GoLcdGetGsiState(UInt16 libRefNum, GoLcdGsiStateType *stateP, GoLcdColorModeType *colorModeP, RGBColorType *rgbP)
    00202                 SYS_TRAP(kGoLcdLibTrapGetGsiState);
    00203
    00204 /**
    00205  * @brief Sets the GSI state associated with GoLCD.
    00206  *
    00207  * @param libRefNum:    IN:  Reference number of the GoLCD library.
    00208  * @param state:    IN:  Sets the GoLCD GSI state.
    00209  * @param colorMode:    IN:  Sets the GoLCD color mode for GSI.
    00210  * @param rgbP:     IN:  Valid only if colorMode is set to goLcdColorOverride. Points to an RGB color
    00211  *               value corresponding to the current color used for inking. (The RGBColorType is
    00212  *               defined in the header file Bitmap.h.)
    00213  *
    00214  * @remarks In normal operation, the GSI is drawn in the lower-right portion of the screen when
    00215  *          the user enters the shift keystroke. The functionality of the GSI can be changed into
    00216  *          an enable and disable control for GoLCD. This function determines whether the
    00217  *          GSI is converted into a GoLCD control. This setting will apply to all GSIs in any
    00218  *          active form.
    00219  *
    00220  * @code
    00221  * RGBColorType gNewColor = { 0, 255, 0, 0}; // Red
    00222  * GoLcdSetGsiState(gGoLcdLibRefNum, goLcdGsiOverride, goLcdColorOverride, &gNewColor); @endcode
    00223  *
    00224  * @see GoLcdGetGsiState
    00225  */
    00226 void GoLcdSetGsiState(UInt16 libRefNum, GoLcdGsiStateType state, GoLcdColorModeType colorMode, RGBColorType *rgbP)
    00227                 SYS_TRAP(kGoLcdLibTrapSetGsiState);
    00228
    00229 /**
    00230  * @brief Returns the length, in system ticks, of the time-out value of GoLCD.
    00231  *
    00232  * @param libRefNum:    IN:  Reference number of the GoLCD library.
    00233  * @param mode:     IN:  Specifies the GoLCD mode.
    00234  * @retval UInt32 Returns the length (in system ticks) of the time-out value.
    00235  *
    00236  * @remarks GoLCD starts in goLcdPenTapMode. When a penDownEvent is received, a timer is
    00237  *          started. If a penUpEvent is received before the timer reaches the time-out value for
    00238  *          this mode, the pen events are passed on to the event handler for the application
    00239  *          control. Otherwise, if the pen events exceed the time-out value and the x, y
    00240  *          coordinates change significantly, GoLCD enters goLcdGraffitiMode and treats the
    00241  *          pen events as a Graffiti 2 stroke.
    00242  *          <br> The default time-out value for goLcdPenTapMode is 15 system ticks, or
    00243  *          150 milliseconds.
    00244  *          <br> When it enters goLcdGraffitiMode, GoLCD continuously interprets all pen events
    00245  *          as Graffiti 2 strokes. There is a time-out value associated with goLcdGraffitiMode,
    00246  *          however. If it does not receive a new pen event within the allotted time, it returns
    00247  *          to goLcdPenTapMode.
    00248  *          <br> The default time-out value for goLcdGraffitiMode is 150 system ticks, or
    00249  *          1500 milliseconds.
    00250  *
    00251  * @code
    00252  * UInt32 gCurrentTimeout = GoLcdGetTimeout(gGoLcdLibRefNum, goLcdPenTapMode); @endcode
    00253  *
    00254  * @see GoLcdSetTimeout
    00255  */
    00256 UInt32 GoLcdGetTimeout(UInt16 libRefNum, GoLcdModeType mode)
    00257                 SYS_TRAP(kGoLcdLibTrapGetTimeout);
    00258
    00259 /**
    00260  * @brief Sets the length, in system ticks, of the time-out value of GoLCD.
    00261  *
    00262  * @param libRefNum:    IN:  Reference number of the GoLCD library.
    00263  * @param mode:     IN:  Specifies the GoLCD mode.
    00264  * @param ticks:    IN:  The new time-out length in system ticks.
    00265  *
    00266  * @retval UInt32 Returns the length (in system ticks) of the previous time-out value.
    00267  *
    00268  * @remarks GoLCD starts in goLcdPenTapMode. When a penDownEvent is received, a timer is
    00269  *          started. If a penUpEvent is received before the timer reaches the time-out value for
    00270  *          this mode, the pen events are passed on to the event handler for the application
    00271  *          control. Otherwise, if the pen events exceed the time-out value and the x, y
    00272  *          coordinates change significantly, GoLCD enters goLcdGraffitiMode and treats the
    00273  *          pen events as a Graffiti 2 stroke.
    00274  *          <br> The default time-out value for goLcdPenTapMode is 15 system ticks, or
    00275  *          150 milliseconds.
    00276  *          <br> When it enters goLcdGraffitiMode, GoLCD continuously interprets all pen events
    00277  *          as Graffiti 2 strokes. There is a time-out value associated with goLcdGraffitiMode,
    00278  *          however. If it does not receive a new pen event within the allotted time, it returns
    00279  *          to goLcdPenTapMode.
    00280  *          <br> The default time-out value for goLcdGraffitiMode is 150 system ticks, or
    00281  *          1500 milliseconds.
    00282  *
    00283  * @code
    00284  * UInt32 gPreviousTimeout = GoLcdSetTimeout(gGoLcdLibRefNum, goLcdPenTapMode, 100); @endcode
    00285  *
    00286  * @see GoLcdGetTimeout
    00287  */
    00288 UInt32 GoLcdSetTimeout(UInt16 libRefNum, GoLcdModeType mode, UInt32 ticks)
    00289                 SYS_TRAP(kGoLcdLibTrapSetTimeout);
    00290
    00291 /**
    00292  * @brief Returns the current bounds defined for use with GoLCD.
    00293  *
    00294  * @param libRefNum:    IN:  Reference number of the GoLCD library.
    00295  * @param rectP:    IN:  Points to the returned rectangle.
    00296  *
    00297  * @remarks GoLCD ignores any succession of pen events (a series of penDownEvents followed
    00298  *          by a penUpEvent) if the initial penDownEvent occurs outside its bounds. By default,
    00299  *          its bounds are the entire display and users can start drawing full-screen writing
    00300  *          characters anywhere except for the right-most scroll bar and the menu bar area.
    00301  *
    00302  * @code
    00303  * RectangleType gCurrentBounds;
    00304  * GoLcdGetBounds(gGoLcdLibRefNum, &gCurrentBounds); @endcode
    00305  *
    00306  * @see GoLcdSetBounds
    00307  */
    00308 void GoLcdGetBounds(UInt16 libRefNum, RectangleType *rectP)
    00309                 SYS_TRAP(kGoLcdLibTrapGetBounds);
    00310
    00311 /**
    00312  * @brief Sets the bounds defined for use with GoLCD.
    00313  *
    00314  * @param libRefNum:    IN:  Reference number of the GoLCD library.
    00315  * @param rectP:    IN:  Points to the rectangle value to set.
    00316  *
    00317  *
    00318  * @remarks GoLCD ignores any succession of pen events (a series of penDownEvents followed
    00319  *          by a penUpEvent) if the initial penDownEvent occurs outside its bounds. By default,
    00320  *          its bounds are the entire display and users can start drawing full-screen writing
    00321  *          characters anywhere except for the right-most scroll bar and the menu bar area.
    00322  *
    00323  * @code
    00324  * RectangleType gNewBounds = { { 0, 0 } , { 50, 50 } };
    00325  * GoLcdGetBounds(gGoLcdLibRefNum, &gNewBounds); @endcode
    00326  *
    00327  * @see GoLcdGetBounds
    00328  */
    00329 void GoLcdSetBounds(UInt16 libRefNum, RectangleType *rectP)
    00330                 SYS_TRAP(kGoLcdLibTrapSetBounds);
    00331
    00332 #ifdef __cplusplus
    00333 }
    00334 #endif
    00335
    00336 #endif  //__PALMGOLCD_H__

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