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