
Documentation for PAL Extensions for Perl.


PalPerl is a standard Perl 4.0.36 with PAL extensions and 
SDBM functions. SDBM is from Perl 5 and works with dbmopen etc.


Not all PAL functions have been implemented.

Calling functions:

  $retval = &Function(<parameters...>);
or
  @retarray = &Function(<parameters...>);

All functions and constants have been defined in pal package.
Therefore you must call them as &pal'PalInit().


Initialization functions:

PalInit()
  Initializes PAL library and changes to the graphic mode.
  If there is a fatal error (die, etc.) Perl will change 
  display to text mode.
  Returns 1 for success.
  
PalDeInit()
  Un-initializes PAL library and changes to the text mode.
  Returns 1 for success.


Miscellaneous functions:
  
ShowTopTime("Title text" [, flag])
  Display title on the top row and if flag present and 
  non-zero displays also the current time on the right.
  Returns no return value.
  
ShowFKeys([ up to 10 function key labels ])
  Displays function key labels on the bottom row.
  No return value.
  
AskYesNo("Question text")
  Shows a dialog box with text and Yes and No buttons.
  Returns 0 if user presses No and 1 if user presses Yes.
  
MsgBox("Title text", "Message text", "Buttons")
  Display a dialog on the screen with title and text. If you
  want several rows of text, use | to delimit lines in the
  text. Buttons may contain up to 5 buttons, separate buttons
  with |. If you want buttons to be available on the function
  keys, append [Fn] to the label text: "Ok[F5]|Cancel[F6]".
  Optional text parameters will be substituted for %s's
  in the message text.
  Returns index of the buttons, starting from 0.

MsgBox("Title text", "Message text", "Buttons", "Prompt", "Initial value")
  First three parameters as above.
  Displays a text field with prompt "Prompt" and initial value.
  Returns index of button in scalar context, as above.
  In array context returns index of button and value of edit field.

FileSelect("Title", "Path", "Ext")
  Shows a file-select dialog.
  Returns 0 if user selects cancel, otherwise returns the selected file
  name.

OpenMeter(type, x, y, size, begin value, end value, "Title")
  Returns a handle to a meter. Type may be ProgressMeter or LevelMeter.
  Size may be 1 to 4, specifies the length of meter on the screen.

UpdateMeter(meter handle, value)
  Value must be between begin value and end value.
  No return value.

CloseMeter(meter handle)
  Closes a previously opened meter.
  No return value.

GetKey()
  Waits for key and returns it.

KeyWaiting()
  Return 0 if there is no key waiting.

WhichHp()
  Returns the model of HP:
  0 for PC, 95 for HP95, 100 for HP100, or 200 for HP200.


Graphics functions:
  
Line(x1, y1, x2, y2)
  Draws a line on the screen from (x1,y1) to (x2,y2)
  No return value.
  
RevBlock(x1, y1, x2, y2)
  Reverse the color of the block (x1,y1)-(x2,y2)
  No return value.
  
Rectangle(x1, y1, x2, y2, fillstyle)
  Draw rectangle at (x1,y1)-(x2,y2) with fillstyle.
  Fillstyle may be OutlineFill, SolidFill, or PatternFill.
  No return value.
  
ClrBlock(x1, y1, x2, y2, color)
  Clears rectangle (x1,y1)-(x2,y2) with color (Black or White).
  No return value.
  
WriteText(x, y, "Text")
  Display text on the screen at (x,y).
  No return value.
  
LoadFont("Font name")
  Load hfn font by name.
  Returns font id if succesfull, 0 otherwise.
  
DiscardFont(font id)
  Discard previously loaded hfn font.
  No return value.
  
FontHeight(font id)
  Returns height of the font.
  Id may be a previously loaded hfn font id or in-built font:
  SmallFont, MediumFont, LargeFont.
  
TextExt(font id, "Text")
  Returns length of the text with font.
  Id may be a previously loaded hfn font id or in-built font:
  SmallFont, MediumFont, LargeFont.
  
TextOut(x1, y1, style, font iI, "Text")
  Print text at (x1,y1) with font and style. Style can be:
  ForceRule, AndRule, OrRule, XorRule, InvForceRule, 
  InvAndRule, InvOrRule, InvXorRule, TxtRule.
  Id may be a previously loaded hfn font id or in-built font:
  SmallFont, MediumFont, LargeFont.
  No return value.

SelectFont(font id)
  Selects font into context. Id can only be SmallFont, MediumFont, or
  LargeFont. This font will be used with only WriteText.
  No return value.

SetColor(color)
  Selects color into context. Color is either Black or White.
  No return value.

SetLineType(line type)
  Selects line type into context. 
  May be an 16 bit integer or SolidLine or DashedLine.
  No return value.

SetPos(x, y)
  Set position of cursor.
  No return value.

SetRule(rule)
  Sets graphics replacement rule. May be:  
  ForceRule, AndRule, OrRule, XorRule, InvForceRule, 
  InvAndRule, InvOrRule, InvXorRule, TxtRule.
  No return value.

SetMask("<8 bytes>" | b1, ... b8)
  Sets fill style. Fill style may be given with either a string of
  8 bytes or with individual 8 bytes.
  No return value.

PlotDot(x, y)
  Plots a dot at (x,y) with current color.
  No return value.

GetDot(x, y)
  Returns the current color of a dot at (x,y).

Scroll(x1, y1, x2, y2, direction, distance, color)
  Scrolls a rectangular region of screen (x1,y1) - (x2,y2).
  Direction may be ScrollLeft, ScrollRight, ScrollUp, or ScrollDown.
  Distance is a 16-bit value giving the number of pixels to scroll.
  Uses color to fill the scrolled area.
  No return value.


Image functions:

GetImage("bitmap name" | x1, y1, x2, y2)
  Returns a handle to a bitmap. Bitmap will be loaded from
  file or captured from screen.
  Returns 0 if some error.

PutImage(x, y, rule, bitmap handle)
  Displays a bitmap at (x,y) with specified replacement rule.
  See SetRule for description of the rules.

SaveImage(bitmap handle, "filename")
  Saves a bitmap in file.
  Returns 0 on error.

LoadPcx("pcx name" [, invert flag])
  Loads a pcx file and returns a handle to it or 0 if error.
  Inverts bitmap if flag present and != 0.

FreeImage(bitmap handle1 , ... bitmap handlen)
  Frees a bitmap(s) previously loaded with GetImage or LoadPcx.
  Returns number of bitmaps freed (not really useful...)


Window functions:

OpenWin(Style, x1, y1, x2, y2, "Title")
  Opens a new window at (x1,y1)-(x2,y2) with title. Style
  can be a combination of the following:
  WSBorder, WSDBorder, WSFrame, WSBMask,
  WSShadow, WSSmlFont, WSSaveBG, WSMenu,
  WSHP100, WSHP200, WSHelp.
  Returns window handle or 0 on error.

CloseWin(window handle)
  Closes previously opened window. Background is restored
  if window was opened with WSSaveBG style.
  No return value.

WinText(window handle, x, y, "text")
  Writes text inside window. Co-ordinates are relative to the window.
  No return value.

Dialog boxes:

NewDialog(width, depth, number of items)
  Creates a new dialog, size: (width, depth) with predefined max. number
  of items.
  No return value.

AddDialogItem(index, x, y, width, depth, label, type, ...)
  Index runs from 0 to <number of items>-1.
  X and y are relative to the dialog.
  Width and depth are normally pixels, some field types use different
  interpretation.
  Label is the label to show before field, if it contains '&' the character
  following that will be underlined.

  Field types            additional parameters:
    0 - static text
    1 - edit field       "initial text", max text length
    2 - button           flags (for example 0x20000 for default button)
    3 - listbox
    4 - group box
    5 - radio button     group number; 1 to 7
    6 - check box
    7 - combo box        "initial text", max text lenght, "choice1|choice2|..."
    8 - date select      format (mmddyy=0)/(ddmmyy=1) [, m/d, d/m, y]
    9 - image            image handle

InitDialog()
  Initializes the dialog. Must be called after AddDialogItem's and
  before any other functions.
  No return value.

SetDialogItems(index1, value1, ... indexn, valuen)
  Sets data for dialog items. Indexed at the same order as they
  were initially defined.
  For Edit, Combo, and Date sets the text,
  for Listbox sets the selected item's index, and
  for Radio, and Check sets the checked state.
  Returns 0 if something went wrong.

SetDialogList(index, function, ...)
  Index is the item index, preferably a listbox!

  Function             parameters
    0 - add string     subfunction, string1, string2, ...
      0 - LBPOS_FIRST, position strings first
     -1 - LBPOS_LAST, position strings last
     -2 - LBPOS_SORT, add string to "right" position
    1 - set string     index1, string1, index2, string2, ...
    2 - del string     index1, index2, ...
  Returns 0 if something went wrong

HandleDialog(x, y [, "Title"])
  Shows dialog at (x,y) with an optional title and waits for
  user interaction.
  Returns DnOk, DnCancel or index of pushed button.

GetDialogItems()
  Returns a list of (index, value) pairs for all fields in the dialog.

ResetDialog()
  Resets a previously opened dialog. There can be only one 
  dialog active at any time.
  No return value.

Menu handling:

NewMenu(index, label1, value1, label2, value2, ...)
  Make a new menu. Main menu (horizontal top-level menu) is index 0.
  Drop-down menus are numbered from 1 to <max top-level menu>.
  If label is a single -, it will be horizontal line and the value
  won't matter.
  You can change menu items without calling ResetMenus first.
  No return value.

HandleMenu(x, y)
  Display menu at (x,y) and wait for user interaction.
  Returns the value of the selected item or -1 if user canceled.

ResetMenus()
  Frees menus allocated with NewMenu.
  No return value.

Choice(x, y, "choice 1", ... "choice n")
  Displays a pull-down menu at (x,y) and waits for user interaction.
  Returns the value of selected menu item.


Defined constants:

  Black, White,
  SmallFont, MediumFont, LargeFont,
  ForceRule, AndRule, OrRule, XorRule, InvForceRule,
  InvAndRule, InvOrRule, InvXorRule, TxtRule,
  OutlineFill, SolidFill, PatternFill,
  SolidLine, DashedLine, 
  ScrollLeft, ScrollRight, ScrollUp, ScrollDown,
  LevelMeter, ProgMeter,
  WSBorder, WSDBorder, WSFrame, WSBMask, WSShadow,WSSmlFont,
  WSSaveBG, WSMenu, WSHP100, WSHP200, WSHelp,
  MIGray, MISkip,
  DnOK, DnCancel

Key codes:

  NoKey,
  F1Key, F2Key, F3Key, F4Key, F5Key, F6Key, F7Key, F8Key, F9Key, F10Key, 
  F11Key, F12Key, 
  Sf1Key, Sf2Key, Sf3Key, Sf4Key, Sf5Key, Sf6Key, Sf7Key, Sf8Key, 
  Sf9Key, Sf10Key, Sf11Key, Sf12Key, 
  Af1Key, Af2Key, Af3Key, Af4Key, Af5Key, Af6Key, Af7Key, Af8Key, 
  Af9Key, Af10Key, Af11Key, Af12Key, 
  Cf1Key, Cf2Key, Cf3Key, Cf4Key, Cf5Key, Cf6Key, Cf7Key, Cf8Key, 
  Cf9Key, Cf11Key, Cf12Key, 
  ZoomKey, DelKey, 
  UpKey, DownKey, LeftKey, RightKey, PgupKey, PgdnKey, 
  HomeKey, EndKey, InsKey, MenuKey, 
  StabKey, 
  CutKey, CopyKey, PasteKey, 
  BackKey, 
  EnterKey, 
  SpaceKey, 
  EscKey, 
  AppmgrKey, SetupKey, FilerKey, DbaseKey, CalcKey, ApptKey, LotusKey, 
  PhoneKey, NoteKey, MemoKey, DatacommKey, QuickenKey, MacrosKey, 
  WorldKey, WatchKey, CcmailKey, DosKey, 
  

Example:

&pal'PalInit() || die("Cannot init PAL!");

$s1 = &pal'AskYesNo("Hello?");

$s2 = &pal'MsgBox("Title",
  "This is a message|box which will|contain all this text",
  "  OK  |!Cancel");

@a1 = &pal'MsgBox("Title",
  "This is a message|box which will|contain all this text",
  "  OK  |!Cancel", "Prompt:", "init text");

@keys = ("Help", "","","","","","","","OK","Cancel");
&pal'ShowFKeys(@keys);
&pal'ShowTopTime("File: pal.perl", 1);

for($x = 0; $x < 200; $x+=20){
  &pal'Line($x,0,0,199);
}
&pal'Rectangle(100,50,400,150,0);

$line = <>;    # wait for user to press enter

$win = &pal'OpenWin($pal'WSDBorder|$pal'WSSaveBG, 20, 60, 550, 120, "Window title") 
  || die("Cannot open");
&pal'WinText($win, 20, 20, "Text...");

$line = <>;    # wait for user to press enter

&pal'CloseWin($win);

&pal'NewMenu(0,"&File", 1, "&Help", 2);
&pal'NewMenu(1,"&Open", 3, "E&xit", 4);
&pal'NewMenu(2,"&Help", 5, "-", 0, "&About", 6);
&pal'NewMenu(3,"Test", 5, "XXX", 6);

$s3 = &pal'HandleMenu(10, 80);

&pal'ResetMenus();

$s4 = &pal'Choice(20,20,"One", "Two", "Three");

$s5 = &pal'FileSelect("Title", "c:\\", "*.bat");

$meter = &pal'OpenMeter(pal'ProgressMeter, 100, 50, 3, 10, 250, "Progress level");
for($f = 10; $f <= 250; $f+=10){
  &pal'UpdateMeter($meter, $f);
  &pal'GetKey();   # press any key
}
&pal'CloseMeter($meter);

&pal'NewDialog(500, 130, 6);
$k = &pal'AddDialogItem(0, 10, 10, -10, 0, "Label1:", 1, "Init", 25);
$k = &pal'AddDialogItem(1, 10, 25, 174, 14, "Radio1", 5, 1);
$k = &pal'AddDialogItem(2, 10, 40, 174, 14, "Radio2", 5, 1);
$k = &pal'AddDialogItem(3, 10, 60, 100, 14, "&OK", 2, 0x20000);
$k = &pal'AddDialogItem(4, 200, 10, 100, 100, "List:", 3);
$k = &pal'AddDialogItem(5, 300, 10, -11, 0, "Date:", 8, 0, 0, 0, 0);
&pal'InitDialog();
$k = &pal'SetDialogList(4, 0, -1,"List1", "List2", "List3", "List4", List5, List6);
$k = &pal'SetDialogList(4, 1, 2, "Foo1", 0, "Article");
$k = &pal'SetDialogList(4, 2, 5,2,1);
&pal'SetDialogItems(5, "3/12/99");
&pal'HandleDialog(100,50,"Title");

@a2 = &pal'GetDialogItems();

#&pal'GetKey();

$s6 = &pal'WhichHp();

&pal'PalDeInit();

$s7 = &heapfree();
$s8 = &stkfree();


print "@a1\n";
print "@a2\n";
print "$s1 $s2 $s3 $s4 $s5 $s6 $s7 $s8\n"; 

