The Portfolio Unit, version 1.0  (c) 1990 BJ Gleason

by BJ Gleason,  The American University


INTRODUCTION

          The Portfolio Unit will allow Turbo Pascal programmers
     to access many of the features of the Portfolio.

          Also included are some of the more important procedures
     and function from the CRT unit, which can not be used, since
     it expects full hard compatibility.


USING PORTFOLI.TPU

          Place the file PORTFOLI.TPU in a directory where Turbo
     Pascal can access it.

          In your program, include the name PORTFOLIO in the USES
     clause in you program.

     
FUNCTION AND PROCEDURES IN PORTFOLIO.TPU

Replacements functions and procedures for the CRT unit: Will work
on Portfolio or PC

PROCEDURE ClrScr;

          Clear the screen.


PROCEDURE GotoXY(X,Y : Integer);

          Move cursor to position X, Y.


FUNCTION  KeyPressed : Boolean;

          Return TRUE if a key has been pressed.


FUNCTION  ReadKey : Char;

          Wait for a key to be pressed, return the character.


FUNCTION  WhereX : Integer;

          Return the Horizontal Position of the cursor.

FUNCTION  WhereY : Integer;

          Return the Vertical position of the cursor.


This function will work on the Portfolio or the PC.

FUNCTION  IsPort : Boolean;

          This function will return TRUE if running on a
          Portfolio, FALSE if not.  Handy if you want to run
          program on both machines without locking up the PC. 
          WARNING: There is no positive way to identify the
          Portfolio.  This functions checks to see if the
          Interrupts 60h and 61h vectors are pointing to
          0000:0000.  These are not normally used on the PC, but
          is on the Portfolio.  If you are running a TSR that
          takes over these vectors, IsPort will return TRUE.


The rest of the procedures and function will only work on the
Portfolio, unless you are using the Portfolio Emulation Software
(I60, I61) on the PC.

PROCEDURE PortAlarm;

          This will beep the speaker, about once a second until
          the user presses a key.  The program will then continue
          with the next statement.


PROCEDURE PortBeep;

          This will cause a single beep from the speaker.


PROCEDURE PortBox(X1,Y1,X2,Y2,Border : Integer);

          This will draw a box.  X1 and Y1 specify the upper left
          corner position of the box, while X2 and Y2 specify the
          lower right corner.  Border is 0 for single line box,
          and 1 for a double line box.
 
          Trying to draw a box larger than the screen (8x40) has
          unpredictable results.


FUNCTION  PortBoxAreaCalculation(var X,Y : Integer; Title,
               MenuText, DefaultText : String) : Integer;

          This function will return the size of the menu in
          characters.  X and Y are the upper left hand corner. 
          The function will modify X and Y so they point to the
          bottom right corner of the box.  Title, MenuText and
          DefaultText are the texts you are going to use in the
          menu.  These function is designed to work with
          PortScreenSaveAndRestore to calculate the amount of
          memory required to save the screen under the menu.


PROCEDURE PortDial(Number : String);

          This will dial the "number" through the speaker.  Valid
          characters for tones are: 0 1 2 3 4 5 6 7 8 9 A B C D *
          #.  The letters must be in uppercase.


PROCEDURE PortErrorWindow(X,Y:Integer; Message : String);

          This will draw a box around the message and display it
          at the specified X,Y.  It will then beep and wait for a
          keypress.  The text underneath the message is left
          untouched.

          Trying to place the message outside the screen (8x40)
          has unpredictable results.


FUNCTION  PortGetCursorMode : Integer;

          Returns the current cursor mode.  You can not detect
          mode 3, Force mode.  See PortSetCursorMode for details.


FUNCTION  PortGetDisplayMode : Integer;

          This function will return the current display mode. 
          See PortSetDisplayMode for details.


FUNCTION  PortGetKeyboardLanguage : Integer;

          Returns the current keyboard language.  See
          PortSetKeyboardLanguage for details.

 
FUNCTION  PortGetLogicalScreenCols : Integer;

          This function will return the width of the Logical
          Screen.  Used in conjunction with
          PortGetLogicalScreenRows will allow you to determine
          the overall size of the Logical screen.

FUNCTION  PortGetLogicalScreenRows : Integer;

          This function will return the number of rows of the
          logical screen.


FUNCTION  PortGetPhysicalScreenCols : Integer;

          This function will return the width of the Physical
          Screen.  Used conjunction with
          PortGetPhysicalScreenRows will allow you to determine
          the overall size of the Physical screen.


FUNCTION  PortGetPhysicalScreenRows : Integer;

          This function will return the number of rows of the
          Physical screen.


FUNCTION  PortGetSizeInternalDisk : Integer;

          Returns the size of the internal disk in Ks.


FUNCTION  PortGetTextLanguage : Integer;

          Returns the current text language.  See
          PortSetTextLanguage for details.

 
FUNCTION  PortGetTickSpeed : Integer;

          Returns the Tick speed of the Portfolio.  See
          PortSetTickSpeed for details.


FUNCTION  PortGetVirtualScreenX : Integer;

          Returns the current virtual cursor line.


FUNCTION  PortGetVirtualScreenY : Integer;

          Returns the current virtual cursor column.


PROCEDURE PortInitialization;

          Initialize the internal Interrupts.  Should be used
          before using any of the other routines.

PROCEDURE PortKeyClick;

          Make the key click sound.


FUNCTION  PortMenu(X, Y, Border, Depth, TopLine, SelectLine :
               Integer; Title, MenuText, DefaultText : String) :
               Integer;

          This will display and allow the user to choose from a
          menu.  X and Y specify the position of the top left
          corner of the screen.  Border is 0 for a single line, 1
          for a double line.  If a single line is selected, the
          border and title are only drawn.  The Depth variable is
          a placeholder, and has no effect in version 1.0. 
          Topline is the menu entry that should be at the top. 
          SelectLine is the line the cursor will be set on.  The
          Title will be display on the Border of the menu.  The
          each entry in the MenuText has to be separated by an
          ASCII 0.  DefaultText values for each line will be
          displayed on the right hand side of the menu.  Each
          entry needs to be separated by an ASCII 0.  See
          TEST.PAS for an example.


PROCEDURE PortMessageWindow(X,Y : Integer; Title, Message :
               String);

          The text of Message will be displayed in a double line
          box.  Each line of the Message needs to be separated by
          an ASCII 0.  The box will be placed at X, Y.


PROCEDURE PortMoveVirtualScreen(Direction, Distance : Integer);

          Move the screen in direction for distance number of
          character.  Works only in Static and Tracked modes. 
          Same as using the ALT arrow keys.  Values for direction
          are 1=Up,2=Down,3=Left,4=Right.


PROCEDURE PortOff;

          This will turn the Portfolio off until the user presses
          a key.  The program will then continue execution.


PROCEDURE PortRefresh;

          Copy video memory to the LCD controller.  Needed for
          when you are doing direct write to screen memory.

FUNCTION  PortRomVersion : Real;

          This function will return the version number of the
          Portfolio rom's.


PROCEDURE PortScreenSaveAndRestore(X1, Y1, X2, Y2, Command :
               Integer; Buffer : String);

          This will save and restore screen images under a menu. 
          X1, Y1 indicated the upper left corner, while X2, Y2
          indicate the lower left.  Buffer points a string in
          which to save or restore the screen image from.  The
          Command can be 0=Save Character only, 1=Save Characters
          and Attribute, 2=Restore Characters only, 3=Restore
          Characters and Attributes.
 

PROCEDURE PortSetCursorMode (Mode : Integer);

          Sets the cursor mode.  Modes are 0=Cursor Off,
          1=Underline, 2=Block and 3=Force.  Force modes sets the
          cursor size according to the keyboard Numlock state.


PROCEDURE PortSetDisplayMode(Mode : Integer);

          Set the Portfolio screen to Normal, Static or Tracked. 
          0=Static, 1=Normal, 2=Tracked.  The mode is only
          effective while in the program.  Using this statement
          might clear the screen depending on the position of the
          cursor.


PROCEDURE PortSetKeyboardLanguage(Language : Integer);

          Sets the language to be used for the keyboard.  The
          built in languages are 0=English, 1=French, and
          2=German.


PROCEDURE PortSetTextLanguage(Language : Integer);

          Sets the language to be used for text and menus.  The
          built in languages are 0=English, 1=French, and
          2=German.


PROCEDURE PortSetTickSpeed(Speed : Integer);

          Sets the Clock tick speed.  0 is Normal, 1 tick every
          128 seconds.  1 is Fast, 1 tick every second.  1 uses
          much more power.


PROCEDURE PortSetVirtualScreenLocation(X,Y : Integer);

          Move the virtual cursor to row, col.  This location
          will be at position 0,0 on the physical screen.


PROCEDURE PortSound(Tone, Length : Integer);

          This will activate the tone generator.  Length is the
          duration of the tone in 10 msec intervals.  Tone codes
          are displayed below.  These codes are taken from the
          Atari Portfolio Technical Reference Manual, copyrighted
          by the Atari Corporation.

               CODE      NOTE      Frequency (Hz)

               48        D#5       622.3
               49        E5        659.3
               50        F5        698.5
               51        F#5       740.0
               52        G5        784.0
               53        G#5       830.6
               54        A5        880.0
               55        A#5       932.3
               56        B5        987.8
               57        C6        1046.5
               58        C#6       1108.7
               41        D6        1174.7
               59        D#6       1244.5
               60        E6        1318.5
               61        F6        1396.9
               14        F#6       1480.0
               62        G6        1568.0
               44        G#6       1661.2
               63        A6        1760.0
                4        A#6       1864.7
                5        B6        1975.5
               37        C7        2093.0
               47        C#7       2217.5
                6        D7        2349.3
                7        D#7       2489.0

          Aside from these codes, other values will produce
          sounds as well.


PROCEDURE PortStatusLine(X,Y,OnOff : Integer);

          This will enable or disable the Status line and display
          it at X, Y.  This is the line that you see when you use
          the <LOCK> key on the Portfolio.  0 for off, 1 for on.




UPGRADE HISTORY


     Version 1.0    August 4, 1990

          Initial release.


TECHNICAL NOTES

          PORTFOLIO.TPU is about 500 lines of code was written in
     Turbo Pascal, version 5.5, and was compiled to a Turbo
     Pascal Unit just a tad over 10k in size.

          Many of the functions and procedures in PORTFOLIO.TPU
     will lock up a normal PC.  You should use the function
     ISPORT to determine if it is safe to the Portfolio routines. 
     If you have the Portfolio Emulation software (I60, I61), you
     can use all the features while on the PC.

          PORTFOLIO.TPU was developed on a Packard Bell 286 PC
     with 640k of memory.  It was tested on the Atari Portfolio,
     ROM version 1.052.



THE FILES

     PORTFOLI.TPU        The Portfolio Turbo Pascal Unit.
     PORTTPU.TXT         This file.
     TEST.EXE
     TEST.PAS            A program to exercise the Unit.  Take a
                              look at it, it demos many of the
                              features of the Portfolio routines.


ABOUT THE AUTHOR

     Mr. BJ Gleason is an Instructor at The American University
     in the Computer Science and Information Systems Department. 
     He has been programming for over a decade now.


COMMENTS, BUGS AND IDEAS

     If you find any bugs, or would like to see some new
     features, contact me and I will try to accommodate you and
     release a new version.


ADDRESS

     If you have an comments, suggestions or bug reports, you can
     write to the author at:


          BJ Gleason
          The American University
          CSIS  (Thin Air Labs)
          4400 Massachusetts Avenue, N.W.
          Washington, DC  20016

          Compuserve : 73337,2011
          Genie      : BJGLEASON

     
     This program and documentation is being placed into the
     public domain by the author.  It can be copied and
     distributed freely.  It can not be sold or used for
     commercial purposes without permission.

     The Portfolio Unit, version 1.0, Copyright 1990
                                         by BJ Gleason.

     Portfolio, Atari, Borland, and Turbo Pascal are trademarks
     of their respective companies.

