<TOC>
[>>]<INDEX>
Table of Contents
Table of Contents

This set of functions is for special operations, such
as control of the volume, serial port, light-sleep and
timeout of the palmtop, get scancode and ASCII code
from a pressed key, and much more.

[..AnnuncPos]<AnnuncPos> : 
Set the annunciators position (Shift,CAPS,Fn indicators).

[..Check5f]<Check5f> : 
Check for presence of INT 5Fh services.

[..CheckSysMgr]<CheckSysMgr> : 
Check for presence of INT 7Eh (SysMgr) services.

[..FatalExit]<FatalExit> : 
Fatal error exit from PAL and return error code to DOS.

[..PalInit]<PalInit> : 
Initialize PAL library (the first thing to do).

[..PalDeInit]<PalDeInit> : 
Shut down PAL library (just before exiting program).

[..WhichHp]<WhichHp> : 
Returns the model number of the palmtop we're running upon.

[..GetKey]<GetKey> : 
Get a key (with ASCII and Scan code).

[..PushKeys]<PushKeys> : 
Push a sequence of Keys which GetKey will deliver.

[..Volume]<Volume> : Set the volume level of the palmtop.

[..SetSerialPort]<SetSerialPort> : 
Turn on/off the serial port COM1 of the palmtop.

[..SetLightSleep]<SetLightSleep> : 
Enable/disable light-sleep (Power-management).

[..SetTimeOut]<SetTimeOut> : 
Set the timeout delay of the Auto-Power-Off feature.
;;;;;;;;;;;;;;;;;;;;;;;;;
<AnnuncPos>
[<<]<TOC>
[>>]<CheckSysMgr>
Set the annunciators position
AnnuncPos

   DESCRIPTION
This function places the annunciators (Shift,Caps,Fn
indicators) on the bottom left or right of the screen.
It is useful to place the annunciators to the left of
the screen in your programs, so they don't get over
the F1 label on the screen (like in the PIMs).

   SYNOPSIS
      #include "pal.h"
      void AnnuncPos(int position);

   INPUTS
      position - The position of the annunciators. You
                 can use one of the following values:

                 AN_LEFT : place annunciators to the bottom
                 left,
                 AN_RIGHT: place annunciators to the bottom
                 right.

   RETURN VALUE
      None

   NOTE
The annunciators are usually to the right side of the
screen while in DOS, and to the left when in the
System Manager PIMs.

   SAMPLE
      AnnuncPos(AN_LEFT);
      /* place annunciators to the left side */

See also: [..Graphics Modes]<Graphics Modes> and [..Text Modes]<Text Modes>

<Check5f>
[<<]<TOC>
[>>]<CheckSysMgr>
Check for INT 5Fh graphics services
Check5f

   DESCRIPTION
This function checks for the presence of INT 5Fh
services (Either running on palmtop or on PC with
emulator). Returns TRUE if services are present.

   SYNOPSIS
      #include "pal.h"
      int  Check5f(void);

   INPUTS
      None

   RETURN VALUE
      TRUE if INT 5Fh services are present.

   NOTE
You can use the CGAGRAPH.COM or CG.COM emulator to
have access of the INT 5Fh services on your desktop
(286+ only). You can also use the Palinit() function
which does the Check5f() automatically for you.

   SAMPLE
      if(!Check5f()) FatalExit("Init failed -
                     CGAGRAPH not loaded ?", 1);

See also: [..PalInit]<PalInit> [..FatalExit]<FatalExit>

<CheckSysMgr>
[<<]<TOC>
[>>]<FatalExit>
Check for SysMgr services
CheckSysMgr

   DESCRIPTION
      This function checks if the System manager is
      loaded.

   SYNOPSIS
      #include "pal.h"
      int CheckSysMgr(void);

   INPUTS
      None.

   RETURN VALUE
      Returns TRUE (1) if SysMgr is loaded, FALSE (0)
      otherwise.

   NOTE
Checking for SysMgr presence is mandatory for PAL
applications that use functions from the SM_SVC module
- these will not work and even crash without the
presence of SysMgr.

   SAMPLE
    if(!CheckSysMgr()) printf("SysMgr not loaded!\n");
    else printf("SysMgr is loaded...\n");

<FatalExit>
[<<]<TOC>
[>>]<PalInit>
Fatal error exit from PAL.
FatalExit

   DESCRIPTION
This function is used to exit the program when a fatal
error occurs. You can specify the error message to be
displayed and the error code to be returned to DOS.

   SYNOPSIS
      #include "pal.h"
      void FatalExit(char *Msg, int ExitCode);

   INPUTS
      Msg      - The error message you want to be
                 displayed.
      ExitCode - The error code (number) to be returned
                 to DOS.

   RETURN VALUE
      Returns the error code to DOS and quits program.

   NOTE
      This function automatically resets the screen
      mode to text upon exit.

   SAMPLE

   if(!(pFont = LoadFont("span0015.hfn")))
              FatalExit("Load Font failed", 1);

See also: [..TextMode]<TextMode>

<PalInit>
[<<]<TOC>
[>>]<Volume>
Initialize PAL library
PalInit

   DESCRIPTION
This function initializes the PAL library by setting
the default colors, graphics screen mode, font size
and graphics rule, it also checks for the presence of
the INT 5Fh services and Sets 'Palmtop' variable to
non-zero if running on HP palmtop. This is the first
function that is usually called in a program using the
PAL library.

   SYNOPSIS
      #include "pal.h"
      int  PalInit(void);

   INPUTS
      None.

   RETURN VALUE
      Returns TRUE if the INT 5Fh services are
      available.

   NOTE
      The color is set to black, the font size to
      small, and the replacement rule to FORCE. The
      opposite function of PalInit() is PalDeInit().

   SAMPLE
   if(!PalInit()) FatalExit("Init failed - CGAGRAPH
   not loaded ?", 1);

See also: [..FatalExit]<FatalExit>, [..SetRule]<SetRule>, [..SetColor]<SetColor>,
          [..SelectFont]<SelectFont>, [..PalDeInit]<PalDeInit>

<PalDeInit>
[<<]<TOC>
[>>]<INDEX>
Shut down PAL library
PalDeInit

   DESCRIPTION
      This function shuts down the PAL library and
      resets the screen mode to text. It is normally
      called just before exiting the program.

   SYNOPSIS
      #include "pal.h"
      void PalDeInit(void);

   INPUTS
      None

   RETURN VALUE
      None

   NOTE
      This function is the opposite of PalInit().

   SAMPLE
      PalDeInit();  /* shut down PAL services */

See also: [..PalInit]<PalInit>, [..TextMode]<TextMode>

<WhichHp>
[<<]<TOC>
[>>]<INDEX>
Return palmtop model number
WhichHp

   DESCRIPTION
      This function returns the HP model number of the
      palmtop we're running upon.

   SYNOPSIS
      #include "pal.h"
      int  WhichHp(void);

   INPUTS
      None

   RETURN VALUE
        0 --> no palmtop, PC
       95 --> HP95LX
      100 --> HP100LX

   SAMPLE
      if(WhichHp() == 0) printf("This is not an HP palmtop!");

See also: [..Check5f]<Check5f>

<GetKey>
[<<]<TOC>
[>>]<INDEX>
Get a key (with ASCII and Scan code)
GetKey

   DESCRIPTION
      This function will wait for a keystroke and
      return it in both ASCII and scancode. The upper
      byte of the result will hold the scancode, the
      lower byte the ASCII code. This function can
      also detect the palmtop-specific keys like MENU.

   SYNOPSIS
      #include "pal.h"
      WORD GetKey(void);

   INPUTS
      None

   RETURN VALUE
      A 16-bit value (WORD) with the most significant
      byte for the scancode, and the least significant
      byte for the ASCII code.

   NOTE
      This function can work in conjunction with the
      PushKeys() function which allows to push a
      sequence of Keys which GetKey will deliver.

   SAMPLE
      int key;

      /* Get scancode and ASCII code */
      key = GetKey();  /* wait for a key press */

See also: [..PushKeys]<PushKeys>

<PushKeys>
[<<]<TOC>
[>>]<INDEX>
Push a sequence of Keys
PushKeys

   DESCRIPTION
      This function is used in conjunction with
      GetKey() and pushes a sequence of keys that
      GetKey() can deliver.

   SYNOPSIS
      #include "pal.h"
      void PushKeys(WORD *pKeys);

   INPUTS
      pKeys - pointer to a 0-terminated array of
              WORDs, with the most significant byte as
              scancode and the least significant one
              as ASCII code.

   RETURN VALUE
      None

   NOTE
      This function is using a global int array called
      KStack[MAX_KEYSTACK] which can hold up to
      MAX_KEYSTACK entries. It is used in recursive
      calls to PushKeys - this way, pushed keystrokes
      that cause PushKeys to be called again when
      being retrieved by GetKey don't cause a problem.
      Note that the Menu module calls PushKeys itself.

   SAMPLE
      Not available at this moment.

See also: [..GetKey]<GetKey>

<Volume>
[<<]<TOC>
[>>]<INDEX>
Set speaker volume level
Volume

   DESCRIPTION
      This function sets the volume level of the palmtop.

   SYNOPSIS
      #include "pal.h"
      void Volume(int Level);

   INPUTS
      Level - The volume level, which can be one of the 4
              possible settings:

                VOL_OFF   : Set volume completely off.
                VOL_LOW   : Set volume to the lowest level.
                VOL_MEDIUM: Set volume to the middle level.
                VOL_HI    : Set volume to the maximum level.

   RETURN VALUE
      None

   NOTE
      The default setting is VOL_HI.

   SAMPLE
      Volume(VOL_HI);  /* set volume to maximum */

See also: [..m_play]<m_play>, [..m_asound]<m_asound>

<SetSerialPort>
[<<]<TOC>
[>>]<INDEX>
Turn serial port on/off
SetSerialPort

   DESCRIPTION
      This function turns on or off the serial port COM1
      (wire) of the palmtop.

   SYNOPSIS
      #include "pal.h"
      void SetSerialPort(int Mode);

   INPUTS
      Mode - Can be either SERIAL_ON, or SERIAL_OFF.

   RETURN VALUE
      None

   NOTE
      When the serial port is ON, the palmtop drains
      the batteries faster. Do not forget to turn it
      off when not in use. The baudrate settings are
      not affected when calling this function. The
      Infared (I.R.) port is not affected either.

   SAMPLE
      SetSerialPort(SERIAL_OFF); /* turn off serial port */

See also: [..SetLightSleep]<SetLightSleep>

<SetLightSleep>
[<<]<TOC>
[>>]<INDEX>
Enable/disable light-sleep
SetLightSleep

   DESCRIPTION
This function enables/disables the power-management
feature called 'light-sleep'. This does accelerate the
computer's speed somehow, but decreases battery life.
It is useful to turn it off while doing a search for
example, to speed-up the search process.

   SYNOPSIS
      #include "pal.h"
      void SetLightSleep(int Mode);

   INPUTS
      Mode - Can be either SLEEP_ON, or SLEEP_OFF.

   RETURN VALUE
      None

   NOTE
      When the light sleep feature is disabled, the
      battery life is reduced dramatically. It is
      important to remember to turn this feature back
      ON before exiting your program.

   SAMPLE
      SetLightSleep(SLEEP_ON); /* enable light-sleep */

See also: [..SetSerialPort]<SetSerialPort>, [..SetTimeOut]<SetTimeOut>

<SetTimeOut>
[<<]<TOC>
[>>]<INDEX>
Set power-off timeout delay
SetTimeOut

   DESCRIPTION
      This function will change the time-out delay of
      the Auto-Shut-Off feature of the palmtop.

   SYNOPSIS
      #include "pal.h"
      void SetTimeOut(WORD value);

   INPUTS
      value - A 16-bit value for the time-out delay.
              The value is actually the number of
              clock ticks (18.2 per second), so a
              time-out delay of ten seconds should be
              182.

   RETURN VALUE
      None

   NOTE
      WARNING!!! If the time-out value is too small
      the palmtop will turn off as soon as you turn it
      on, and only a CTL-ALT-DEL (warm boot) will
      bring it back to normal!

   SAMPLE
      SetTimeOut(2184); /* set timeout to 2 minutes */

See also: [..SetLightSleep]<SetLightSleep>
<INDEX>
[<<]<TOC>
Index
Index

[..AnnuncPos]<AnnuncPos> 
[..Check5f]<Check5f>     
[..CheckSysMgr]<CheckSysMgr>
[..FatalExit]<FatalExit> 
[..PalInit]<PalInit>     
[..PalDeInit]<PalDeInit> 
[..WhichHp]<WhichHp>     
[..GetKey]<GetKey>       
[..PushKeys]<PushKeys>   
[..Volume]<Volume>       
[..SetSerialPort]<SetSerialPort>
[..SetLightSleep]<SetLightSleep>
[..SetTimeOut]<SetTimeOut>  

<END>
