^mouse^
 
        This function reads the position and state of the mouse buttons.
        It can also be used to wait for a mouse click.
        
^SYNTAX :^
        int x, y;
        int state;
        int button_no;
        state = mouse(&x, &y, button_no);
        
^PARAMETERS :^
 
        Function parameters :
                
        - ^x^ and ^y^
                Graphic co-ordinates of the mouse. These values will
                be between 0 and 639 for x, and between 0 and 399 or 0 and 
                199 depending on the resolution.
                These parameters are changed by the execution of the
                function.
                See the Notes section below.
                
        - ^button_no^
                This parameter indicates whether the mouse should
                wait for a click on the mouse or whether it should
                return the immediately to the main program without
                waiting.
                If button_no is 1, then the function waits for the left 
                button to be pressed. If it is equal to two, then the
                function waits for the right button to be pressed. If
                button_no is 3, then control is returned to the program
                when the user presses on both buttons simultaneously.
                If button_no is not 1 to 3 then the current mouse
                status is returned immediately. 
                
^RETURN VALUE^        
        This value indicates if one of the mouse buttons is down:
        
                ^Return value^        ^State of the mouse buttons^
                        0                 no buttons pressed
                        1                 left button down
                        2                 right button down
                        3                 both buttons down
        
^EXAMPLE^
        
        The following program waits for the user to click on the
        left button at two different places. Then a straight line is
        drawn between the two points where the user has clicked.
        
        ^ int x1, y1, x2, y2;       ^
        ^ main()                    ^
        ^ {                         ^
        ^       mouse(&x1, &y1, 1); ^
        ^       mouse(&x2, &y2, 1); ^
        ^       draw(x1,y1,x2,y2);  ^              
        ^ }                         ^
        
        The following call to the mouse function reads the current state
        of the mouse buttons and also its position on the screen. The
        function does not wait for a click on a mouse button.
        
        ^ button_state = mouse(&x, &y, 0); ^
        
^NOTES^
        The parameters x & y are modified by the function. They are not
        initialised before the call. Whilst the function is running,
        the new values are stored in the variables. These parameters
        are passed by address to the mouse function. This is due to 
        the present of the & in front of the variable names in the call.
        The & is absolutely essential.
