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-FileThe OriginatorWhen the user selects an object or group of objects, drags the mouse (and
objects), and releases the mouse button outside one of your application
window's work areas, the operation is a candidate for a drag and drop
operation.
When this action is initiated by the user, your application should call
wind_find() to determine the window handle of the window at the drop
location. From the window handle you can use wind_get() to determine the
owner's application identifier which will be needed to send an AES message
to the application.
At this point you should use Psignal() to cause SIGPIPE (13) signals to
be ignored and create a pipe named DRAGDROP.xx where 'xx' is a unique two
character combination. The pipe created should have its 'hidden' attribute
set. This causes reads to return EOF when the other end of the pipe is
closed. To ensure your value is unique, try using the ASCII representation
of your own application ID. If the Fcreate() fails, try a new combination
until you find one that is available.
Now use appl_write() to send an AES message to the application whose
window was targeted (the recipient) as follows:
WORD Content
0 AP_DRAGDROP (63)
1 Originator's application id.
2 0
3 Window handle of the target.
4 Mouse X position at time of drop.
5 Mouse Y position at time of drop.
6 Keyboard shift status at time of drop.
7 2 character pipe ID packed into a WORD (this is the file extension
of the created pipe).
The originator application should now use Fselect() to wait for either
a write to the pipe or a timeout (3 to 4 seconds should be sufficient). If
the call times out then the drag and drop operation failed and the pipe
should be closed, otherwise, read one byte from the pipe which should be
either DD_OK (0) or DD_NAK (1).
DD_OK means that the recipient wishes to continue the exchange. DD_NAK
means that the user dropped the data on a window not prepared to accept
data and that the pipe should be closed and the drag and drop operation
aborted.
On receipt of a DD_OK, the originator should then read an additional 32
BYTEs from the pipe. These 32 BYTEs consist of eight 4 BYTE data type
values that the recipient understands in order of preference. This list is
not necessarily complete and the originator should not abort simply
because it can't handle any of the listed data types. If less than eight
data types are listed by the recipient the 32 bytes will be padded with
zeros.
Data type values are four-byte ASCII values that represent data that
might be exchanged. When these values are prefixed with a period, they
represent data in a format that might be stored in a disk file. Examples
of these are '.IMG', '.TXT', and '.GEM'. Some data types such as 'ARGS' or
'PATH' are not prefixed with a period because they represent special
data.
The desktop sends an 'ARGS' drag and drop message to an application
window when the user drags a group of file icons to an application window.
The 'ARGS' data consists of a standard command line with the names of each
file. 'ARGS' data should be translated for non-TOS file systems.
Characters within single quotes should be interpreted as a single
filename. Two single quotes in a row should be interpreted as a single
quote.
After the originator has consulted the 32 byte list or preferred file
types, it should construct its own structure consisting of the following
data:
1. The type of data the originator has decided to send (4 ASCII bytes),
ex: '.IMG'.
2. The length of data in bytes (LONG).
3. The data's name in ASCII format terminated by a NULL (this is
a variable length field but should be brief as it will be used to
label an icon which represents the data chunk), ex: "ASCII Text".
4. The filename the data is associated with in ASCII format terminated
by a NULL (again, a variable length field), ex: "SAMPLE.TXT".
The originator should now write a WORD to the pipe signifying the length
of the header and then the header itself. After doing so, the recipient
will write a one byte reply indicating a return code from the following
list:
Name Val Meaning
DD_OK 0 Ready to receive data. After receiving this message you
should Fwrite() the actual data to the pipe and then
Fclose() it to complete the operation.
DD_NAK 1 Abort the drag and drop. After receiving this message,
close the pipe and abort the operation.
DD_EXT 2 The recipient cannot accept the format the data is in.
You may either construct a new header and send it as
before or close the pipe to abort the operation.
DD_LEN 3 The recipient cannot handle so much data. Either use
a format which would cause less data to be sent or close
the pipe to abort.
DD_TRASH 4 The data has been dropped on a trashcan. The pipe should
be Fclose()'d and the data should be deleted from the
originator application.
DD_PRINTER 5 The data has been dropped on a printer. The pipe should
be Fclose()'d and the data should be printed.
DD_CLIPBOARD 6 The data has been dropped on a clipboard. The pipe
should be Fclose()'d and the exchange should be treated
like a 'Copy' clipboard operation.
The one exception to the above procedure involves the 'PATH' data type.
If the recipient agrees to the 'PATH' data type by sending a DD_OK, the
originator should read a path string (terminated by a NULL byte). The path
string should be the complete pathname represented by the target window,
ex: "C:\WORDPRO\FILES\". The size of the data, as specified in the header,
specifies the maximum size of the string the recipient should write.