  ------------------------------------------------------------------------
  WinClip unit                              by Sebastian Groeneveld (2000)
  ------------------------------------------------------------------------

  Usage
  =====

  Add the following line to your program:

  $INCLUDE "WinClip.inc"


  Public routines
  ===============

  ------
    FUNCTION OpenClipboard () AS INTEGER

    Opens the clipboard for DOS access. You can only read from or write to
    the clipboard after opening it. Returns 0 on error.

  ------
    FUNCTION CloseClipboard () AS INTEGER

    Closes the clipboard. You should always close the clipboard when you
    don't need to access it (for a while), because Windows cannot use the
    clipboard while it's opened for DOS access. It will not automatically
    close when your program exits. Returns 0 on error.

  ------
    FUNCTION WriteClipboard ( BYVAL Tekst AS STRING) AS INTEGER

    Writes a string to (open) clipboard. Use CHR$(13, 10) to insert line
    breaks, or use the WriteClipBuffer routine (see below) to convert a
    string array to a single clipboard string. Returns 0 on error.

  ------
    FUNCTION ReadClipboard ( Tekst AS STRING ) AS INTEGER

    Reads a string from (open) clipboard. Lines are delimited with
    CHR$(13, 10), or use the ReadClipBuffer routine (see below) to convert
    the clipboard string to a string array. Returns 0 on error.

  ------
    FUNCTION ClipboardSize ( ) AS WORD

    Returns the size of the clipboard contents. This function is used in
    the ReadClipboard routine to check whether the clipboard data fits in
    a single string.

  ------
    SUB WriteClipBuffer ( Target AS STRING, StringArray() AS STRING, _
                          BYVAL First AS INTEGER, BYVAL Last AS INTEGER )

    Writes the elements of string array (from First to Last) to a single
    string, using CHR$(13, 10) between each element. The returned string
    Target is ready for writing to the clipboard. The routine will never
    read beyond the array bounds.

  ------
    SUB ReadClipBuffer ( BYVAL Source AS STRING, StringArray() AS STRING, _
                         BYVAL Lines AS INTEGER )

    Parses the Source string (read from clipboard) and writes the separate
    lines to the string array, starting at its lower bound. On return the
    variable Lines contains the number of parsed lines. The routine will
    never write beyond the array bounds.


  Example
  =======

  $INCLUDE "WinClip.inc"

  DIM SaveClip         AS STRING
  DIM Lines(1 TO 100)  AS STRING
  DIM NrLines          AS WORD

  CLS

  IF OpenClipboard() = 0 THEN
      PRINT "Clipboard not available."
      END
  END IF

  IF ReadClipboard( SaveClip ) THEN
      PRINT "Data successfully read from clipboard."
  END IF

  CALL ReadClipBuffer ( SaveClip, Lines(), NrLines )

  PRINT "   "; LEN(SaveClip); "bytes";
  PRINT "   "; NrLines; "lines"
  PRINT "-------------------"
  FOR i = 1 TO NrLines
      PRINT Lines(i)
  NEXT i
  PRINT "-------------------"

  IF WriteClipboard( "This text is written by a DOS unit." ) THEN
      PRINT "Data successfully written to clipboard."
      PRINT "Use Ctrl+V in Windows now to verify this, then press a key..."
  END IF

  'Close clipboard to allow Windows to use it
  CloseClipboard

  WHILE LEN(INKEY$) = 0: WEND

  'Open it again to restore old data
  IF OpenClipboard() THEN
	  IF WriteClipboard ( SaveClip ) THEN
          PRINT "Old clipboard data restored."
      END IF
	  CloseClipboard
  END IF

  PRINT "Ready"





