Topic       : The ATARI Compendium
Author      : Scott Sanders / JAY Software
Version     : 1.25 (20/6/2003)
Subject     : Documentation
Nodes       : 1117
Index Size  : 32614
HCP-Version : 6
Compiled on : Atari
@charset    : UTF-8
@lang       : en
@default    : 
@help       : %About
@options    : +g -i -t4 +y +z
@width      : 100
View Ref-File
                              The Scrap Library



The scrp_read() and scrp_write() calls are provided by the AES to return
and set the current clipboard path. The clipboard is a global resource in
which applications can share data. Applications supporting the clipboard
contain an 'Edit' menu title which has at least the following four items,
'Cut', 'Copy', 'Paste', and 'Delete'. An appropriate action for each is
listed below:

Implementing 'Cut' and 'Copy'

When the user selects 'Cut' or 'Copy' from the 'Edit' menu and an object
is selected ('Cut' and 'Copy' should only be enabled in the menu when an
object is selected which may be transferred to the clipboard) the
following steps may be used to transfer the data to the system clipboard:

1. Call scrp_read() to return the name of the current scrap directory. If
   the returned string is empty, no clipboard directory has been defined
   since the computer has been started. The directory string returned may
   need to be reformatted. A proper directory string ends in a backslash,
   however some applications incorrectly append a filename to this string.

2. If no clipboard directory was returned or the one specified is
   invalid, create a directory in the user's boot drive called '\CLIPBRD' and
   write the pathname back using scrp_write(). For example, if the user's
   boot drive was 'C:' then your parameter to scrp_write() would be
   'C:\CLIPBRD\'.

3. Search and delete files in the current clipboard directory with the
   mask 'SCRAP.*'.

4. Now write a disk file for the selected data to a file named SCRAP.???
   where '???' is the proper file extension for an object of its type. If the
   object can be represented in more than one format by your application,
   write as many formats as possible all named 'SCRAP' with the proper file
   extension.

5. If the menu choice was 'Cut' rather than 'Copy,' delete the object
   from your data structures and update your application as necessary.

Implementing 'Paste'

'Paste' is used to read a file and insert it appropriately into an
application that supports data of its type. To implement 'Paste' follow
the steps below:

1. Call scrp_read() to obtain the current system clipboard directory. If
   the returned string is empty, no data is in the clipboard.

2. Format the string returned by scrp_read() into a usable pathname and
   search for files called 'SCRAP' in that path having a file extension of
   data that your application supports. Remember, more than one SCRAP.???
   file may be present.

3. Load the data and insert it in your application as appropriate.

MultiTOS Notes

The AES, when running under MultiTOS, will create a MiNT semaphore named
'_SCP' which should be used to provide negotiated access to the scrap
directory. Access to this semaphore should be obtained from MiNT prior to
any clipboard operation and must be released as soon as it is complete.
Applications should not attempt to destroy this semaphore.