^event^
        
        This function waits for one or more event; an event is a user
        action as far as GEM is concerned. This may be a key press, or
        a click on a mouse button, the selection of a menu item, or
        a window action (moving it, change its size, clicking an arrow
        or a slide box, etc).
        
        The event function waits for the user to make one or several of the
        actions described above. Which elements to wait for are specified by
        the call. The function returns to the main program details of which 
        event has occurred.
         
        
^SYNTAX :^
        
        int menu_title;
        int menu_item;
        int key_press;
        int clickx;
        int clicky;
        short window[6];
        int event_type;
        event_type = event(&menu_title, &menu_item, window,
                                            &key_press, &clickx, &clicky);        
        
^PARAMETERS :^
        
        Function parameters : 
        
        - ^&menu_title^ and ^&menu_item^
                If you don't want to wait for events caused by menu selection
                then these two values must be zero. In place of &menu_title
                and &menu_item, you put the value 0. Otherwise, the event
                function returns the numbers of the title and item of the
                menu entry that was selected with the mouse. 
                Remember that these numbers are identical to the values 
                returned by the title_menu and item_menu toolbox 
                function when you create the menu. These two function give 
                unique numbers specifying the menu item. The same values 
                are returned in the menu_title and menu_item items to 
                inform you which item has been selected and the title of the 
                sub-menu.
                
        - ^window^
                This parameterlets you wait for an event applied to a window.
                It is an array of six short integers.
                
                The full list of GEM window events is as follows:
                        - Clicking in the close box
                        - Clicking in the full box
                        - Clicking on the arrows
                        - Moving a slider
                        - Changing the size of a window
                        - Moving a window without changing the size
                        - Re-displaying the inside of a window
                        - Making a window the top one
                
                If you haven't opened a window, or you don't wish to deal
                with events that can happen to your window then pass zero  
                for this parameter.
                
                Otherwise when a window event occurs, the event function
                modifies the array called window. The first (number 0)
                element of the array indicates which event has taken place.
                The significance of the other elements depends on the type
                of event; all the elements are never used at once. 
                There now follows a list of all the window events together
                with the appropriate values:
                                
                        - Clicking in the close box
                         element 0: 22
                         element 1: the number of the window to be closed.
                        
                        - Clicking in the full box. 
                         element 0: 23
                         element 1: the number of the window to make full size.
 
                        - Clicking on the arrows or in the grey part of a slider
                        If the user clicks on a window's arrows this moves
                        the window upwards, downwards, to the right or to the
                        left by one line/character. If you click in the grey
                        area of the slider the window should move by a page in
                        the corresponding direction. 
                         element 0 : 24
                         element 1 : window number
                         element 2 : action to perform:
                                 0 page up
                                 1 page down
                                 2 row up
                                 3 row down
                                 4 page left
                                 5 page right
                                 6 column left
                                 7 column right
 
                        -  Moving the horizontal slider
                        GEM returns the new position of the slider as a
                        value between 0 (the leftmost position) and 1000
                        (the rightmost). 
                         element 0 : 25
                         element 1 : window number
                         element 2 : slider position between 0 and 1000.
 
                        - Moving the vertical slider 
                        GEM returns the new position of the slider as a
                        value between 0 (the top position) and 1000 (the
                        bottom). 
                         element 0 : 26
                         element 1 : window number
                         element 2 : slider position between 0 and 1000. 
 
                        - Changing the size of a window
                        GEM returns the new size of the window.
                         element 0 : 27
                         element 1 : window number
                         element 2 : x co-ordinate of the top left of the
                                     window (should remain unchanged)  
                         element 3 : y co-ordinate of the top left of the 
                                     window (should remain unchanged) 
                         element 4 : the new width of the window
                         element 5 : the new height of the window
 
                        - Moving a window without changing the size
                        The user has moved the window by dragging on the
                        title bar. GEM returns the new window position that
                        the user wants. 
                         element 0 : 28
                         element 1 : window number
                         element 2 : new x co-ordinate of the top left of
                                     the window  
                         element 3 : new y co-ordinate of the top left of 
                                     the window 
                         element 4 : the width of the window (unchanged) 
                         element 5 : the new height of the window (unchanged)  
 
                       - Making a window the top one 
                        The user has clicked on a window to make it the front
                        one.
                         element 0 : 21 or 29 
                         element 1 : number of the window to become active
 
                        - Re-displaying the inside of a window
                        This event occurs when a window is opened, or when it 
                        becomes larger or when an object (another window or
                        dialog box) has deleted the interior of the window. 
                         element 0 : 20
                         element 1 : number of the window to redraw
 
                        Note :The toolbox function draw_box that displays
                        a dialog box on the screen, saves the screen before
                        displaying it and restores it afterwards. If there
                        is just one window on the screen, this event can be
                        ignored.
                        
        - ^&key_press^
                You can wait for a press of a key on the keyboard.
                If you aren't interested in what the user types you can use
                zero insead of &key_press.
                Otherwise the event function will return a code for the key 
                you have pressed in the key_press variable. The low order 
                byte of this is the ASCII code of the key; the higher order 
                bytes are special keyboard codes that GEM uses all the time. 
                This lets you detect Help keys, Alt combinations etc. 
                The C expression ^key_press % 256^ returns the normal ASCII
                code of the key pressed where key_press is the variable that you  
                passed to the event function. Obviously in this case you 
                can't check for keys with no ASCII equivalent like Undo or 
                the function keys.
                
        - ^&clickx^ and ^&clicky^
                You can wait for a click on a mouse button. 
                If you don't wish to wait for this event then these values
                must be 0. Instead of &clickx and &clicky, put the value 0.  
                Otherwise the event function returns the position of the 
                mouse at the moment of the mouse click.
                
                          
^RETURN VALUE^        
        This is the type of event that has occurred. Here is a list of
        the values returned depending on which event happened:
                value       event type
                  1         key press
                  2         mouse click
                  3         menu selection                    
                  4         window event
        
        
^EXAMPLE^
        
        The examples below only indicate how to call the event function
        depending on which sort of events you wish to wait for. For
        complete examples of event handling see the programs paleochr.c
        and events.c. 
        
        ^ int menu_title;                                                 ^
        ^ int menu_item;                                                  ^
        ^ int key_press;                                                  ^
        ^ int clickx;                                                     ^
        ^ int clicky;                                                     ^
        ^ short window[6];                                                ^
        ^ int event_type;                                                 ^
        ^ main                                                            ^
        ^ {                                                               ^
        ^ event_type = event(0, 0, 0, &key_press, &clickx, &clicky);      ^
        ^ /* wait for a key press or mouse click */                       ^
        ^                                                                 ^
        ^ event_type = event(&menu_title, &menu_item, 0, 0, 0, 0);        ^
        ^ /* wait for a mnu to be selected */                             ^
        ^                                                                 ^
        ^ event_type = event(0, 0, window, &key_press, &clickx, &clicky); ^   
        ^ /* wait for a key press, mouse click or window event */         ^
        ^ }                                                               ^
