HomeAESGraphics libraryList boxes

8.13 Scrap library

This library makes functions available that permit a standardized interchange of data betweeen various applications. The following routines are present for this purpose:

scrp_clear Deletes files in the clipboard
scrp_read Obtains path of the clipboard
scrp_write Sets path of the clipboard

Note: Besides these functions, some other particulars have to be taken into account for exchanging data via the clipboard.

See also: Messages   SC_CHANGED   SH_WDRAW   Style guidelines

8.13.1 scrp_clear

Name: »Scrap clear« - Delete the contents of the clipboard.
Opcode: 82
Syntax: int16_t scrp_clear ( void );
Beschreibung_ The call scrp_clear deletes all files in the current clipboard.

Warning: Contrary to the usual conventions, really all files will be deleted, not just those matching the mask "scrap.*".
Return value: An error has arisen only if the value 0 is returned.
Availability: The function is available only under PC-GEM, KAOS 1.4.2 and MagiC. Not present in ViewMAX.
Group: Scrap library
See also: Binding   Data exchange via the GEM clipboard

8.13.1.1 Bindings for scrp_clear

C: int16_t scrp_clear ( void );
Binding:
int16_t scrp_clear (void)
{
   return ( crys_if(82) );
}
GEM-Arrays:

Address Element Contents
control control[0] 82 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 0 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_out int_out[0] Return value

8.13.2 scrp_read

Name: »Scrap read« - Obtain pathname of the clipboard.
Opcode: 80
Syntax: int16_t scrp_read ( int8_t *sc_rpscrap );
Description: The call scrp_read obtains the current directory which is being used for temporary storage (the clipboard).

Note: The clipboard directory path will lie in the parameter sc_rpscrap after the call. One must be sure that the receiving buffer is large enough for this.
Return value: An error has arisen only if the value 0 is returned.

To quote Mike Fulton, Atari Computer:
"The scrp_read function is defined as possibly returning an error-code of zero. However, this function currently always returns a value of 1. Since this may change in future versions of GEM AES, applications should handle the case of the error-code even if the programmer does not expect to see it."

As of PC-GEM Version 2.0 however the following values are returned: -1, if no path has been set yet; values >= 0 are to be taken as a bit-vector that is meant to provide information about the found file types. The following assignments apply:

SCRAP_CSV 0x0001 = scrap.csv
SCRAP_TXT 0x0002 = scrap.txt
SCRAP_GEM 0x0004 = scrap.gem
SCRAP_IMG 0x0008 = scrap.img
SCRAP_DCA 0x0010 = scrap.dca
  0x0020 = scrap.dif (see Note)
SCRAP_USR 0x8000 = scrap.usr


All other bits are reserved for future purposes.

Note: According to the docs for PC-GEM, scrap.usr is coded in bit 5, though the AES source text says bit 15.

The library from the book Vom Anfänger zum GEM-Profi allocates bit 5 to DIF files. The extension is unofficial and works only if that library is used for the build.
Availability: All AES versions, not present in ViewMAX.
Group: Scrap library
See also: Binding   scrp_write   Data exchange via the GEM clipboard

8.13.2.1 Bindings for scrp_read

C: int16_t scrp_read ( int8_t *sc_rpscrap );
Binding:
int16_t scrp_read (int8_t *sc_rpscrap)
{
   addr_in[0] = sc_rpscrap;
   return ( crys_if(80) );
}
GEM-Arrays:

Address Element Contents
control control[0] 80 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] sc_rpscrap
int_out int_out[0] Return value

8.13.3 scrp_write

Name: »Scrap write« - Set path of the clipboard.
Opcode: 81
Syntax: int16_t scrp_write ( int8_t *sc_wpscrap );
Description: The call scrp_write sets the directory that is to be used for temorary storage (the clipboard).

Note: The name of the new path is passed in the parameter sc_wpscrap. The clipboard should carry the name CLIPBRD, and should lie on the boot drive in each case.
Return value: An error has arisen only if the value 0 is returned.
Availability: All AES versions, not present in ViewMAX.
Group: Scrap library
See also: Binding   scrp_read   Data exchange via the GEM clipboard

8.13.3.1 Bindings for scrp_write

C: int16_t scrp_write ( int8_t *sc_wpscrap );
Binding:
int16_t scrp_write (int8_t *sc_wpscrap)
{
   addr_in[0] = sc_wpscrap;
   return ( crys_if(81) );
}
GEM-Arrays:

Address Element Contents
control control[0] 81 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] sc_wpscrap
int_out int_out[0] Return value

HomeAESGraphics libraryList boxes