SP Mice implementation

Mice and SuperLib

 SuperLib contains a set of mouse and event functions.
 These functions are MOSTLY prefaced with 'RAT' for uniqueness.

 The basic functions are written in assembler (MASM
 5.10) and are in s_mouse.asm. These provide such things as
 testing for a mouse, turning the mouse cursor on, turning it off,
 positioning it.

 Also provided are two approaches to knowing where the
 mouse is and what it is doing. The first is a direct query of
 the mouse's status and position. This is basically, "where is the
 mouse right now, is the right button depressed right now, is the
 left button depressed right now". These are accomplished through
 service 3 of interrupt 33h.

 The second approach is to use service 5 of interrupt
 33h, which 'records' right and left mouse button depresses and
 where the mouse was when these occurred.

 These Clipper functions, contained in s_moose.prg,
 are included to provide a simple event manager to trap both keys
 and mouse events and store them for reference.

 The event manager RAT_EVENT() can be used in place of
 inkey(), and will detect a keypress, a mouse left button press,
 a mouse right button press, or a timeout. The 'event' returns a
 value similiar to inkey(), but adds values of 400 and 500 for
 mouse right and left presses. Functions are provided to find out
 the mouse row and column when the event occurred.

 Two additional functions RAT_READ() and RAT_MENU2()
 are provided which use the mouse and event functions to perform
 a read and a menu to emulation. These are also good examples for
 usage of the mouse and event functions.

 All SuperLib functions are mouse aware, as of version 3.5.


SP Printer Issues

 This is how printing is handled by the library
 functions. You need not follow this method except where it is
 imbedded in SuperLib metafunctions.

 The function SLS_PRN() is a SET/RETRIEVE function
 which sets and retrieves the default printer port as a string
 with the default as "LPT1". This function may be called with any
 valid printer port name as a parameter to set a new printer port
 for SuperLib usage.

 Valid values are "LPT1", "LPT2", "LPT3", "COM1",
 "COM2" - anything you could issue a SET PRINTER TO
 <cPort> with.

 Another SET/RETRIEVE function - SLS_PRNC() - points
 to the setting which determines if the printer port will be
 checked for readiness before printing. Passing it a False causes
 it to not check the printer before printing - handy in some
 network situations.

 At print time, LPT* ports are checked for readiness
 via the P_READY() function. (COM ports are not checked for
 readiness.) However, if SLS_PRNC() has been passed a .f., no
 check for readiness is done.

 P_READY() uses the .ASM function ISPRN() to check for

 If the port is not ready, the user is given
 the option to:       Try Again
                      Ignore the Warning
                      Select a Different Printer Port
                      Abort the print request

 If Abort is selected, P_READY() returns false.


SP Color functions

1. These are the functions that relate to entire color sets

  SATTCOLOR()         Sets up the the color set for color monitor
  SATTMONO()          Sets up the the color set for MONO
  SATTDIRECT()        Sets up the the color set directly
  SATTGET()           Sets up color set from COLORS.DBF
  SATTPICK()          Sets up color set by selecting from stored definitions
  SATTGETMEM()        Sets up color set from old colors.mem
  SATTPUT()           Stores current color set  to colors.dbf
  SATTPICKPUT()       Stores current SuperLib color set to
                      colors.dbf, with picklist selection of set
  SATTPICKDEL()       Picklist deletion of stored color sets
  SATTPUSH()          Pushes the current SuperLib color set
  SATTPOP()           Pops previously pushed color set
  SETCOLORS()         Interactive color setting -
                      save/restore/edit color sets
  COLPIK()            10 built in color sets to select
                      from a popup

 2. These are the functions that deal with individual color set items

  SLS_NORMCOL()       Normal screen output
  SLS_NORMMENU()      Normal MENU color
  SLS_POPCOL()        Popup screen output
  SLS_POPMENU()       Popup MENU color
  SLS_FRAME()         Box frames
  SLS_SHADATT()       Shadow attribute
  SLS_SHADPOS()       Shadow position
  SLS_XPLODE()        Explode/implode popups

 3. Other color related functions

  SLS_ISCOLOR( )      Is this a color monitor

SP Color Implementation

 This is not the perfect color scheme. It is the one
 this library runs on. The color scheme relates to SuperLib functions,
 and will not affect your other color usage.

 Basically, when a SuperLib metafunction is called, it
 will usually have a main screen, a menu, and a number of popups
 and other attached screens. Rather than have a burned-in color
 set, or use SETCOLOR() as the default, SuperLib has a dynamic
 color scheme, which may be changed and stored by both the
 programmer and the end-user.

 Several global color settings are used by SuperLib
 functions. The settings are accessed and set via a set of
 functions calls, which themselves access a set of STATIC
 variables. The functions are:

   <cSetting> := sls_normcol([cNew])      For normal output
   <cSetting> := sls_normmenu([cNew])     For normal 'menu to'
   <cSetting> := sls_popcol([cNew])       For popup  box colors
   <cSetting> := sls_popmenu([cNew])      For popup box menus
   <cSetting> := sls_frame([cNew])        Frame string
   <nSetting> := sls_shadatt([nNew])      Shadow color attribute
   <nSetting> := sls_shadpos([nNew])      Shadow  position
                 (0,1,3,7,9) to match the numeric keypad
   <lSetting> := sls_xplode([lNew])       Logical - explode

 All colors are of the format "fg/bg,fg/bg,,,fg/bg"

 (fg-foreground bg-background) except for shadow
 attribute, which is numeric.

 By default, a monochrome set of colors is used. You
 may call the function SATTCOLOR() to make the 'color' colors the

 The function SETCOLORS() allows interactive setting
 of these colors. The variables are stored in COLORS.DBF, which
 contains multiple sets of colors.

 You may override the Clipper ISCOLOR() by
 initializing another setting accessed via the function
 SLS_ISCOLOR(), and setting it to True or False. This is helpful
 in instances where ISCOLOR() sees a color card with a monochrome
 monitor, or some such combination.

 If you are upgrading from 2.50 or previous, see
 "Upgrading" in the appendix.


SP Examples

  (in the examples.zip file)

  The sample files are broken down into 1 .PRG file per

  PRG Files

  S3SCREEN.PRG      Fancy screen handling
  S3META.PRG        Metafunctions
  S3META2.PRG       Metafunctions - using new BUNGEE() menu
  S3POPUP.PRG       Popups
  S3MENU.PRG        Menus (including PULLDN(), BUNGEE() )
  S3GET.PRG         Get system enhancements
  S3MOUSE.PRG       Mouse and event function usage
  S3LOOKUP.PRG      Lookup functions
  S3LASER.PRG       LaserJet functions
  S3HELP.PRG        Online help
  S3PROG.PRG        Progress bars
  S3FILE.PRG        File and directory functions
  S3COLORS.PRG      SuperLib Color set handling
  S3BROWSE.PRG      Browses (tbrowse)
  S3OLD.PRG         OLD() on Line Doc sample


  S3SAMPLE.DBF      Sample Names type DBF file
  S3SAMPLE.DBT      Sample Names type DBT file

  S3SAMPLE.SDF      Sample Names type SDF file for

  S3SAMPLE.ASC      Sample Names type ASCII delim file
                    for S3BROWSE.PRG

  S3HELP.DBF        Online help samples DBF
  S3HELP.DBT        Online help samples DBT
  S3HELP.NTX        Online help samples NTX

  S3STATES.DBF      Lookup table used in S3LOOKUP.PRG
  S3PROD.DBF        Lookup table used in S3LOOKUP.PRG

  S3COLORS.DBF      Color set file


  To create an executable for any of the given .PRGs, where
  <prgfile> refers to the prg and <objfile> refers to the compiled
  object file: (add paths to Clipper and Extend and SUPERxx
  libraries as needed)

  A. COMPILE      NOTE: the -n switch is very important!

    Clipper <prgfile> -n -w


    1   blinker

        blinker fi <objfile> alloc super35

    2   rtlink (clipper 5.0 version)

        rtlink fi <objfile> lib super35

SP Documentation Key

    1. Parameter names are prefaced with their type:

       c        character             i.e.  cString, cFileName
       n        numeric               i.e.  nCount, nSize
       l        logical               i.e.  lSuccess, lStarted
       d        date                  i.e.  dToday, dTarget
       a        array                 i.e.  aNames, aFiles
       b        code block            i.e.  bBlock, bEvaluate
       o        object                i.e.  oTbrowse, oGet
       exp      any or multiple type  i.e. expWhatever

    2. A parameter prefaced with @ means pass by reference

    3. Parameters enclosed in:

       <> or none     indicates required parameter
       []             indicates optional parameter or set of params
       |              indicates mutually exclusive params

    4. => refers to the function return value