A Detailed Look at PAL

PAL files come compressed in the .ZIP format. The files inside the ZIP are organized in 5 major subdirectories as described below.

1. General documentation

These files are kept in the PAL subdirectory \DOCS.

2. Library files

These will automatically be created by the PalMake utility, and reside in the \LIBS directory.

3. Useful utilities

The PAL utilities, located under \UTIL, simplify developing and compiling PAL programs, or accessing documentation:

PalMake (PM) is a make utility that simplifies both the building of the library and the compiling process of any application written with PAL. PM is aware of several popular compilers and will automatically use the correct commands and switches. If PM is run from the \SRC directory, the complete library will be created.

PAL Font Editor (PFE) The utility (written by Harry Konstas) supports character sets from 4x4 to 16x16 bits of size. It can load, edit, save and convert fonts in and between the native PAL format, the format used by Vertical Reader (VR ), and the FCL format that was used to create the popular HELV fonts.

PAL Dialog Editor (PDE) This utility permits on-screen visual development of user interface dialogues. Once a dialog has been drawn on the screen, PDE will create the required resource files in C-source format, ready to link. It can optionally generate a test application that is ready to compile.

HTML Viewer (HV) HV (courtesy of Andreas Garzotto) can display hypertext documents in the increasingly popular HTML format - the same that is being used on the World Wide Web. The PAL reference can be converted into HTML format and HV can be used to view it.

Conversion utilities A number of handy conversion utilities are part of PAL, including: PCX2IMG, which converts a black & white PCX file into the native 100/ 200LX IMG format; MKBIN, which converts a binary file into a C source - useful for built-in pictures and fonts; VFN2HFN, which converts any vertical reader 8/16 bit font (.VFN) to the PAL font format; NG2HTML, which creates a hypertext HTML file from the PAL .DOC files.

4. Sources directory

This directory contains the PAL C source codes, subdivided into 10 modules. There are functions for displaying windows, menus and dialogues, hardware related functions such as volume, serial port control and power management. Clipboard and sound support is included as well as multi-font output routines. Each function group has a .DOC file with the descriptions of all the functions in a standardized format. These descriptions can be read with any text editor (they are in ASCII format), but PAL also includes utilities to create Norton Guide and even HTML (the popular World Wide Web format) versions of the documentation, for easy and fast reference.

5. Samples directory

This contains a number of programming samples that illustrate programming in PAL.

PAL Source Code Directory; Function list and description

As mentioned in point 4 above, this subdirectory is divided into 10 modules. Below is a description of each module.

1. Low Level Graphics

The low-level graphics routines are interface functions to the palmtop-specific INT5Fh graphics calls. With these functions one can set graphics mode, pen color, pen position, select and display text using the built-in fonts, scroll, save and restore a rectangular area of the graphics screen, or define shape and blink rate of the graphics cursor. The routines include the following:

• GraphMode : Switch to 640x200 monochrome graphics mode.
• TextMode : Switch to text mode.
• SelectFont : Select one of the 3 built-in fonts.
• SetColor : Select the pen color, black or white.
• SetRule : Set the graphics replacement rule.
• SetPos : Set the graphics pen coordinates.
• SetMask : Set fill mask.
• SetLineType : Set the graphics line type.
• SetClip : Define a rectangular clipping region.
• Scroll : Scroll a rectangular area of the screen.
• PlotDot : Set a pixel to current color.
• WriteText : Write text on the graphics screen.
• GetImg : Get and store a rectangular bitmap from screen.
• PutImg : Output a bitmap at a given coordinate position, with a given output rule.
• DefineCursor: Define the shape of the graphics cursor.
• BlinkRate : Specify the graphics cursor blink rate.
• Cursor : Cursor control function: ( CURSOR_ON, CURSOR_OFF, CURSOR_BLINK, CURSOR_ NOBLINK, CURSOR_INIT ).
• MoveCursor : Move graphics cursor to the specified X:Y location of the screen.
• SaveState : save the current PAL graphics state into a structure
• RestoreState: restore the graphics state from the above structure.

The High-level graphics routines can be used to create lines, rectangles, and handle PCX and ICN images. Some of these functions are calling low-level graphics functions, and are used by higher-level routines in PAL such as windows and menus. The routines include the following:

• Line : Draw a line on the screen.
• Rectangle : Draw a rectangle on the screen.
• RevBlock : Reverse colors of an image block.
• ClrBlock : Fill an image block with WHITE or BLACK
• LoadImg : Load an image file (.ICN format) in memory.
• LoadPcx : Load an image file (.PCX format) in memory.
• SaveImg : Save an image (.ICN format) to a file.
• ShowKeys : Show function key definitions.
• ShowTopLine : Display title/ time strings on the top line.
• ShowTopTime : Display title & time on the top display line.
• FormatDate : Format a date string, in SysMgr format.
• FormatTime : Format a time string, in SysMgr format.

These are for special operations, such as control of the volume, serial port, light-sleep and timeout of the palmtop, reading scan and ASCII codes from a pressed key, and much more.

• PalInit : Initialize PAL library.
• PalDeInit : Shut down PAL library.
• FatalExit : Error exit from PAL and return code to DOS.
• Check5f : Check for presence of INT 5Fh services.
• CheckSysMgr : Check for presence of INT 7Eh (SysMgr) services.
• WhichHp : Returns the model number of the palmtop.
• AnnuncPos : Set the annunciator's position (Shift,Fn).
• GetKey : Get a key (with ASCII and Scan code).
• KeyWaiting : Check if a key is waiting
• PushKeys : Push a sequence of keys for GetKey to deliver.
• Volume : Set the volume level of the palmtop.
• SetSerialPort: Turn on/off the serial port COM1.
• SetLightSleep Enable/disable light-sleep (Power management).
• SetTimeOut : Set the timeout delay of the Auto-Power-Off.
• MsDelay : Wait a specific number of milliseconds.
• MsgBox : Display a message box with title, text and buttons.
• AskYesNo : Ask user Yes or No.

The window functions can be used to create or remove a graphical window that displays information. As many windows as memory allows can be opened. A number of window styles are supported. The functions available are as follows:

• OpenWin : Open a window with a given style.
• CloseWin : Closes a window.
• WinText : Output text in a window.

PAL menu functions support horizontal & vertical pull-down menus, hotkeys, line separators, bitmaps, and even scrollable menus. Menus are described in PAL using structures: a MENU structure that holds general information on the menu that PAL should display, and a MENUITEM structure (actually, an array of these), that describes a single item of a menu. Each MENU structure represents a pulldown, and has a pointer to its item array. The functions include:

• HandleMenu : Handles the complete menu process.
• MenuSelect : Show a menu and let user select from it. Comparable to HandleMenu, but easier to call for simple menus - just pass a string containing the menu items to be displayed, separated by vertical bar characters.

A dialog box is a special kind of window that handles user interaction. Inside of it, interface elements called controls or dialog items contain and handle the actual information. PAL currently has edit fields, check boxes, radio and control buttons, combo boxes, bitmaps, group frames, static labels, static line elements (separators), and the possibility to add your own custom-made items and handlers. (Comparable to Visual Basic custom controls that you can write yourself). The functions include:

• InitDialog : prepares a dialog to be used.
• SetDlgItem : used to set the value of a dialog item.
• ShowDialog : view dialog window and all its items.
• HandleDialog : will take care of user interaction.
• GetDlgItem : retrieve data from a dialog item.
• CloseDialog : close the dialog window, free all resources.

This is a subset of the HP System Manager functions that can be successfully called from non-SysMgr compliant DOS programs. The functions include:

• m_play : Play a sound string in HP alarm sound format.
• m_sound : Generate one of several sound patterns.
• m_soundoff : Turns off sounds generated by m_asound.
• m_open_cb : Claim access to the clipboard and lock it.
• m_cb_read : Read data from clipboard.
• m_cb_write : Write data to clipboard.
• m_fini_rep : Terminate writing to clipboard.
• m_close_cb : Releases the clipboard for access by other applications.
• m_new_rep : Prepare sending a new representation.
• m_rep_index : Get info about a representation.
• m_reset_cb : Clear clipboard, get ownership.
• m_get_cb_info : Get clipboard state info.

This set of functions allows easy retrieval of information from user-editable plain-text config files, much like the Windows WIN.INI files. The functions include:

• ReadConfig : Read config file given full name.
• ReadMyconfig : Read config, given program name (as in argv[0])
• GetConfigString : Retrieve a string from config data.
• GetConfigInt : Retrieve an integer from config data.
• GetFirstEntry : Used to scan sections: init scan.
• GetNextEntry : Used to scan sections: continue scan.
• GetCfgLine : Retrieve line number info during scan.

These functions support loading and discarding of proportional fonts - also see the unified font routines that provide a common interface to both internal (built-in) monospaced and external, proportional fonts.

• LoadHfn : Load a font in memory.
• InitHfn : Initialize a given font.
• WriteHfn : Writes a string using one of the loaded fonts.
• TextExtHfn : Compute text extent of a string in a given font.
• FontHeightHfn : Returns height of a given font.
• DiscardHfn : Discard a loaded font.

The unified font routines permit transparent usage of both the built-in fonts and the loadable fonts that the HFN module supports. A font is identified by a handle with the unified font routines - regardless whether it is a built-in or a loadable font. A collection of loadable fonts is provided with PAL. The routines include:

• TextOut : Output a string at a given screen position in a font you specify.
• TextExt : Compute the length (in pixels) of a string in a given font, without actually drawing the characters.
• FontHeight : Returns the height of a given font in pixels.
• LoadFont : Loads an external font in memory.
• DiscardFont : Discards a font loaded by LoadFont, and recovers the memory associated with it.