•  Back 
  •  Event library 
  •  Index 
  •  Tree View 
  •  Cross references 
  •  Help page 
  •  Show info about hypertext 
  •  View a new file 
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-File8.7.8  Messages                                                    TOS

Standard messages of the screen-manager are built up as follows:

 msg[0]  Message type

 msg[1]  Application ID of sender

 msg[2]  Length of additional data; if non-zero, use appl_read to read 
         the additional data. Always 0 in messages sent by the AES.

Types of standard messages:

 Message               Meaning



 AC_CLOSE (41)         This is sent to a desk accessory when the 
                       current application terminates, the screen is 
                       cleared and the window manager is reinitialized

                        msg[3]  Identifier of the desk accessory

                       Note: This message plays practically no role in 
                       multitasking systems any more, and is also no 
                       longer present in MagiC!

 AC_OPEN (40)          A desk accessory has been activated

                        msg[4]  Identifier of the desk accessory;
                                PC-GEM returns this information in 
                                msg[3]!, while KAOS 1.4.2 sets both 
                                entries

                       Geneva has the following extension:
                       If an application sends an AC_OPEN message to 
                       another application, it can optionally set WORD 
                       4 of the message to -1; in this case, Geneva 
                       will automatically substitute the correct menu 
                       identifier for the application in WORD 4. 
                       Example to open application with ID #5:

                       int buf[8]im { AC_OPEN, 5, 0, my_apid, -1 };
                       appl_write( 5, 16, buf );

                       Sending an AC_OPEN message to a desk accessory 
                       will cause it to open if it is not already 
                       open, or it will make its window topmost (by 
                       sending a WM_TOPPED message) if the desk 
                       accessory has a window open; an application 
                       will receive a WM_TOPPED message, if it has a 
                       window open.

 AP_DRAGDROP (63)      This is a part of the Drag&Drop protocol and is 
                       sent by the sender to the receiver

                        msg[3]  ID (handle) of the destination window
                        msg[4]  X-position of the mouse pointer
                        msg[5]  Y-position of the mouse pointer
                        msg[6]  Keyboard Shift status
                        msg[7]  2-byte ASCII packed pipe identifier

                       Note: If a value of -1 is passed instead of a 
                       valid window ID, then the destination of the 
                       Drag&Drop operation is no specific window, but 
                       the application itself; in that case normally 
                       one should open an additional window for the 
                       specified data.

 AP_RESCHG (57)        With this message, which is a sub-command only 
                       found as a possible value in AP_TERM (50), the 
                       relevant application is informed that a 
                       resolution change is to take place; the 
                       receiver of this message should then terminate 
                       itself as soon as possible

 AP_TERM (50)          The operating system requests the application 
                       to terminate itself; this may be necessary for 
                       a resolution change, for instance, or triggered 
                       by a general Shutdown utility

                        msg[5]  Reason for the shutdown, so e.g.
                                 AP_TERM    (General termination)
                                 AP_RESCHG  (Resolution change)

                       Warning: Contrary to the usual convention, the 
                       value -1 must be entered in msg[1], as 
                       according to MagiC documentation one can not 
                       guarantee otherwise that the desktop will react 
                       to an [Alternate]-[Control]-[Delete] Shutdown 
                       sequence

                       Note: Desk accesories will always be sent 
                       AC_CLOSE messages, not AP_TERM

 AP_TFAIL (51)         This is sent by the receiver of an AC_CLOSE or 
                       AP_TERM message if this does not wish to or 
                       cannot terminate itself

 CH_EXIT (90)          This is sent to the parent process when a child 
                       terminates

                        msg[3]  Child's application ID
                        msg[4]  Child's exit code

 CT_KEY (53)           This is sent by the modular control field 
                       XCONTROL to be able to evaluate key-presses 
                       that can have no efect on editable fields, such 
                       as [Help] or [Undo], for instance

                        msg[3]  High byte: Scancode of the pressed key
                                Low byte : ASCII-code of the key

 FNT_CHANGED (83)      This is sent if GDOS fonts were loaded or 
                       unloaded at run-time.
                       At the receipt of this message the reaction 
                       should be vst_unload_fonts, followed directly 
                       by vst_load_fonts; this ensures that the 
                       application can work with the current fonts

 MN_SELECTED (10)      This is sent when a menu option is chosen

                        msg[3]  The object index of the menu title 
                                selected
                        msg[4]  The object index of the menu item 
                                selected
                        msg[5]  Pointer to the OBJECT structure of the 
                                menu tree, as also passed in
                        msg[6]  menu_bar
                        msg[7]  Parent of the selected entry, i.e. the 
                                object index of the 'dropped down' box 
                                that contains the entry

                       Note: The presence of the extended message 
                       (msg[5] and following) is best inquired with 
                       appl_getinfo (opcode 9)

 PRN_CHANGED (82)      This message is sent by the GDOS configuration 
                       program to all reachable applications, to 
                       inform them about changes to device drivers; 
                       the following apply:

                        msg[3]  Device number
                        msg[4]  Action
                                 0  =  New 
                                 1  =  Changed 
                                 2  =  Removed 


                       After receipt of this message, an application 
                       can re-open the corresponding workstation, for 
                       instance, obtain the current settings, and 
                       perhaps offer a new preview

 RESCH_COMPLETED (61)  This message is sent to the application that 
                       initiated a resolution change; if no error has 
                       arisen, this must now terminate itself

                        msg[3]  Status (0 = error, 1 = OK)

 SC_CHANGED (80)       This message should be sent by a program to all 
                       other applications in the system when the 
                       contents of the GEM clipboard have been changed

                        msg[3]  Description of the file format:
                                 0x0000 =  No more exact specification
                                 0x0001 =  Data for a database
                                 0x0002 =  Text files
                                 0x0004 =  Vector graphics
                                 0x0008 =  Raster graphics
                                 0x0010 =  Spreadsheet data
                                 0x0020 =  Samples, MIDI files, Sound
                                 0x0040 =  Archive files (e.g. ".zip", 
                                           ".lzh")
                                 0x8000 =  System files (e.g. colour 
                                           palettes)
                                If possible the format 0x0000 should 
                                be avoided!
                        msg[4]  4 characters that describe the "best" 
                                and format (least loss of information) 
                                for
                        msg[5]  the data import; example ".RTF" rather 
                                than ".TXT"
                        msg[6]  Reserved, 0
                        msg[7]  Reserved, 0

 SH_WDRAW (72)         This message should be sent by an application 
                       to the system shell when the contents of a 
                       drive has been changed; following this the 
                       shell can update the corresponding window

                        msg[3]  Drive (0 = A:, 1 = B:, etc)

                       Note: A value of -1 means that the shell should 
                       update all windows

 SHUT_COMPLETED (60)   This is sent by the operating system to the 
                       initiator of a Shutdown when all other 
                       applications have already been informed about 
                       this and have reacted positively

 SM_M_SPECIAL (101)    This message is only available under MagiC (as 
                       of Version 2.0), and must be sent to the 
                       screen-manager

                        msg[3]  0
                        msg[4]  'MA'
                        msg[5]  'GX'
                        msg[6]  Desired action; the following apply:
                                 0 =  Perform a redraw
                                 1 =  Terminate an application
                                 2 =  Switch to an application
                                 3 =  Freeze an application
                                 4 =  Thaw out an application again
                                 5 =  No information known at present
                                 6 =  Unhide all applications
                                 7 =  Hide other applications
                                 8 =  Hide current application
                        msg[7]  0

                       Note: The codes 6..8 of msg[6] are available 
                       only as of MagiC Version 3.1. For "Perform a 
                       redraw" and "Unhide all applications" the ID to 
                       be passed must be that of the screen-manager 
                       (1).

 THR_EXIT (88)         This message is sent to the thread or the 
                       application that created the terminated thread; 
                       the following apply:

                        msg[3]  AES ID of the terminated thread
                        msg[4]  Return value or error-code as a
                        msg[5]  LONG value

 WM_ALLICONIFY (36)    All windows of the application should be 
                       collected up in one iconified window

                        msg[4]  X-coordinate, and
                        msg[5]  Y-coordinate of top left of the 
                                iconified window
                        msg[6]  Width, and
                        msg[7]  Height of the iconified window

 WM_ARROWED (24)       This message is sent to an application to tell 
                       it that one of its slider widgets (arrow or 
                       scroll bar) was clicked on; the following 
                       apply:

                        msg[3]  The handle (ID) of the window
                        msg[4]  One of the following values:
                                 WA_UPPAGE (0) = Page up
                                 WA_DNPAGE (1) = Page down
                                 WA_UPLINE (2) = Row up
                                 WA_DNLINE (3) = Row down
                                 WA_LFPAGE (4) = Page left
                                 WA_RTPAGE (5) = Page right
                                 WA_LFLINE (6) = Column left
                                 WA_RTLINE (7) = Column right
                                 WA_WHEEL  (8) = See below

                       As of XaAES v0.960 there is an extension of 
                       this message, since it has new drivers for a 
                       wheeled mouse:

                        msg[5] 'MW' (0x4d57) or 'Mw' (0x4d77)
                          'MW' (0x4d57) For the first mouse-wheel turn
                          'Mw' (0x4d77) For each further turn

                        msg[6] 0

                        msg[7] Current number of mouse-wheel turns; 
                          with this one can add together several 
                          turns, for instance for movement of the 
                          slider

                       But there is also the possibility of obtaining 
                       with WF_WHEEL real messages about mouse-wheel

                        msg[4] WA_WHEEL (8)

                        msg[6] Index of the wheel

                        msg[7] Number of mouse-wheel turns; with this 
                          one can add together several turns, for 
                          instance for movement of the slider

                       If WINX is installed one can get an extended 
                       WM_ARROWED message:

                        msg[5] Negates the speed factor for msg[4]

                        msg[6] Scroll type and direction, possible 
                          values as in msg[4]

                        msg[7] Negated speed factor for msg[6]

                       One should proceed as follows:
                       If [5] >=0, then we are dealing with a normal 
                       scroll message
                       If [5] < 0, then one negates the value and 
                       obtains the factor for [4]
                       If [7] < 0, then one negates the value and 
                       obtains the factor for [6]
                       Otherwise [6] will be ignored

                       Example:
                       If one receives [WM_ARROWED 1 0 win WA_DNLINE 
                       -2 WA_RTLINE -1] for instance, then one should 
                       scroll two lines downwards and one column to 
                       the right

 WM_BACKDROPPED (31)

                        msg[3]  Handle (ID) of the window in question

                       The application receives this message when 
                       operating the backdrop button of the window. 
                       This message is present only in KAOS 1.4.2 as 
                       well as MagiC 1 and 2; since MagiC Version 3, 
                       WM_BOTTOMED is sent.

 WM_BOTTOMED (33)      This is used by the screen-manager to request 
                       that the application should place a window in 
                       the background. In some TOS versions this is 
                       triggered by [Shift]-clicking on the window's 
                       mover bar; with MagiC (as of version 3) there 
                       is an extra widget for this (3rd from the right 
                       at the top).

                        msg[3]  Handle (ID) of the window in question

                       Note: The window can then be simply placed by 
                       the application in the background with wind_set 
                       (msg[3], WF_BOTTOM, 0, 0 ,0, 0). Under MagiC 
                       2.0 this message is still called WM_M_BDROPPED.

 WM_CLOSED (22)        This message is sent when the user clicks on a 
                       window's 'Closer' widget (top left corner), 
                       signalling that the topped window should be 
                       closed

                        msg[3]  The handle (ID) of the window

 WM_FULLED (23)        This message is sent when the user clicks on 
                       the top window's 'Fuller' widget (top right 
                       corner)

                        msg[3]  Handle (ID) of the window that is to 
                                be brought to its full size

 WM_HSLID (25)         This message is sent when the horizontal slider 
                       of the scroll bar has been moved

                        msg[3]  Handle (ID) of the window
                        msg[4]  The new slider position:
                                 0000  =  Far left 
                                 1000  =  Far right 


 WM_ICONIFY (34)       This message is sent when the user clicks on 
                       the 'Iconify' widget of a window (top, second 
                       rom the right), signifying that a window of the 
                       application is to be iconified

                        msg[3]  Handle (ID) of the window in question
                        msg[4]  X-coordinate, and
                        msg[5]  Y-coordinate of top left of the 
                                iconified window
                        msg[6]  Width, and
                        msg[7]  Height of the iconified window

 WM_M_BDROPPED (100)   This is used by the screen-manager to request 
                       that the application should place a window in 
                       the background (say when the 'Backdrop' button 
                       is activated). As of MagiC 3 this opcode is no 
                       longer sent, but WM_BOTTOMED is used instead.

                        msg[3]  Handle (ID) of the window in question

 WM_MOVED (28)         This message is sent when the user moves the 
                       whole window by dragging a window's title-bar

                        msg[3]  Handle (ID) of the window
                        msg[4]  New X-coordinate, and 
                        msg[5]  New Y-coordinate of top left of window
                        msg[6]  New window width (unchanged)
                        msg[7]  New window height (unchanged)

 WM_NEWTOP (29)        This message is sent when a window has been 
                       topped (brought to the front)

                        msg[3]  Handle (ID) of the window

 WM_ONTOP (31)         This message is sent when a window (after 
                       closing or deactivating another window) becomes 
                       the top (current or active) one

                        msg[3]  Handle (ID) of the window in question

                       Note: By the time the message arrives the 
                       window stack may have already changed again; 
                       the message is sent only when the application 
                       has not itself issued a call to place the 
                       window in the foreground

                       Messages of this type are coalesced in the AES 
                       message buffer. It follows from this that at 
                       all times the last message of this type will be 
                       received; thus there cannot be several of these 
                       messages in the buffer.

 WM_REDRAW (20)        This message warns an application that a part 
                       of the window area must be redrawn

                        msg[3]  Handle (ID) of the window
                        msg[4]  X-coordinate of the top left corner of 
                                the window area to redraw
                        msg[5]  Y-coordinate of the top left corner of 
                                the window area to redraw
                        msg[6]  Width of the portion of the window 
                                area to redraw
                        msg[7]  Height of the portion of the window 
                                area to redraw

 WM_SHADED (22360)     This message is sent when a window has been 
                       'shaded' (by double-clicking its title-bar so 
                       that only the title-bar remains visible

                        msg[3]  Handle (ID) of the window

 WM_SIZED (27)         This message occurs when the user alters the 
                       window's size (by dragging the window's 'Sizer' 
                       widget at the bottom right corner)

                        msg[3]  Handle (ID) of the window
                        msg[4]  New X-coordinate, and
                        msg[5]  New Y-coordinate of the window's top 
                                left corner (both unchanged)
                        msg[6]  New window width
                        msg[7]  New window height

 WM_TOOLBAR (37)       This message is sent when a toolbar object is 
                       clicked on; the following apply:

                        msg[3]  Handle (ID) of the window
                        msg[4]  Object clicked on
                        msg[5]  Number of mouse clicks
                        msg[6]  Keyboard state of [Shift], [Alternate] 
                                and [Control]

                       Note: All objects of the toolbox should have 
                       the TOUCHEXIT flag set. This does not apply for 
                       XaAES, for which there is an additional value:

                        msg[7]  Current object in which the text 
                                cursor is positioned

 WM_TOPPED (21)        This message is sent when an application window 
                       which is not currently topped is clicked on by 
                       the user to move it to the top (made active)

                        msg[3]  The handle (ID) of the window

 WM_UNICONIFY (35)     This message is sent when the user double- 
                       clicks one or more iconified windows of an 
                       application to uniconify it/them; if several 
                       windows are affected (WM_ALLICONIFY) then it is 
                       up to the application alone to process this, as 
                       the AES does not make available any information 
                       about the windows in question, including their 
                       positions or dimensions

                        msg[3]  Handle (ID) of the window in question
                        msg[4]  X-coordinate, and
                        msg[5]  Y-coordinate of top left corner of the 
                                uniconified window
                        msg[6]  Width, and
                        msg[7]  Height of the uniconified window

 WM_UNSHADED (22361)   This message is sent when a window has been 
                       'unshaded' (by again double-clicking its 
                       title-line) to make the whole window visible

                        msg[3]  Handle (ID) of the window

 WM_UNTOPPED (30)      This message is sent when the current window 
                       has been sent behind one or more windows due to 
                       another window becoming the active one

                        msg[3]  Handle (ID) of the window in question

                       Note: By the time the message arrives the 
                       window stack may have already changed again; 
                       the message is sent only when the application 
                       has not itself issued a call to place the 
                       window in the background

 WM_VSLID (26)         This message indicates that the vertical slider 
                       of the scroll bar has been moved

                        msg[3]  Handle (ID) of the window
                        msg[4]  The new slider position:
                                 0000  =  At the very top 
                                 1000  =  At the very bottom 


Support of the newer message types can be inquired with appl_getinfo 
(opcode 12). Incidentally, for user-defined messages Digital Research 
has suggested message numbers beyond 1024.

About the size of the message buffer:

An individual application should not use more than 16 windows under 
MagiC 2.0, as otherwise the message buffer of the system can overflow 
and possibly redraws can no longer be performed.

See also: evnt_multi   evnt_mesag   AV protocol   OLGA protocol 
Drag&Drop