Topic       : TOS - The Operating System
Author      : 
Version     : tos.hyp (December 19, 2008)
Subject     : Programmieren/Atari
Nodes       : 3010
Index Size  : 93790
HCP-Version : 5
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Title
@help       : 
@options    : +g -i -s +x +zz -t4
@width      : 70
View Ref-File13.11.4.2  Further communication                                   TOS

Once a file is displayed (in a window) and the viewer has returned a 
non-zero window identification in msg[7], both the application and the 
viewer may send each other messages refering to this file/window.

The 'msg[7]' variable will always contain the (non-zero) window 
identification as an identifier! As this is supposed to be unique, the 
'msg[3/4]' variable should not be used to identify the file (if the 
'msg[7]' variable is not zero).

If the viewer receives a wrong window identification, it replies by 
sending a VIEW_FAILED message:

retmsg[0]   = VIEW_FAILED
retmsg[3/4] = msg[3/4]
retmsg[5]   = VIEWERR_WID
retmsg[6]   = 0
retmsg[7]   = msg[7]    // The wrong window identification.

The application receiving this message must not use this window 
identification again, since the case may be that the viewer simply did 
not send VIEW_CLOSED(wid).

The application can perform some operations on the file being viewed:

   . The window should be closed (and the memory used by the file 
     freed):

     msg[0]   = VIEW_FILE
     msg[3/4] = NULL         // Remove File
     msg[5/6] = 0
     msg[7]   = wid          // This (obviously) cannot be 0.

   . If the application knows that the file has been changed, or wants 
     another file to be displayed in the same window, it can send the 
     following message:

     msg[0]   = VIEW_FILE
     msg[3/4] = filename     // This may be different.
     msg[5/6] = 0
     msg[7]   = wid          // The identification of the window.

     On the other side, the viewer should inform the application of 
     what is happening to its file:

   . If the window is closed (the user closed it or the viewer 
     received AC_CLOSE or VIEW_FILE(NULL, wid)), then the viewer 
     should send the following message:

     msg[0]   = VIEW_CLOSED
     msg[3/4] = filename     // This may be NULL and should be ignored!
     msg[5/6] = 0
     msg[7]   = wid

     The filename should be the one from the VIEW_FILE message, 
     otherwise it may be NULL, as no new global memory should be 
     allocated.

   . If the window was closed due to an error, the VIEW_FAILED message 
     may be sent instead:

     msg[0]   = VIEW_FAILED
     msg[3/4] = filename     // This may be NULL and should be ignored!
     msg[5]   = errcode      // See above.
     msg[6]   = 0
     msg[7]   = wid

     If the viewer does not have the ability to store the 
     identification of the application, it may not inform the 
     application when a window was closed without a message from the 
     application. This is very easy to implement, but may lead to 
     unexpected results. Please send your experiences to Peter Seitz 
     (the addresses he can be contacted at are shown above).