








                                                         C H A P T E R
                                                                     1

                                                          Introduction

            The MegaToolbox is a set of four separate function
            libraries for C and C++ programming environments under
            the MS-DOS operating system. The separate libraries that
            make up the MegaToolbox are

                 Console library. This provides a number of routines
                 for interfacing to the video display in standard
                 text mode. It provides the functionality of the
                 standard C output routines, but can be configured to
                 send the output to the display in any of the
                 available colors, and the output can be mapped and
                 clipped to any rectangular window on the screen. The
                 routines are similar in operation to the set of
                 console output routines provided with the Borland
                 C++ and Turbo C++ range of compilers, but they are
                 faster and more configurable.

                 Event handling library. This library provides a set
                 of low level routines to maintain a queue of
                 keyboard and mouse events. Naturally the events are
                 not restricted to just keyboard and mouse events,
                 but can be any type of user defined event. This
                 allows the program to easily combine the keyboard
                 and mouse into a single system for interacting with
                 the user.

                 Mouse library. This library provides a high level
                 language interface to the mouse driver, allowing the
                 user program to fully control the mouse and to
                 install a custom mouse event handler. Full control
                 of the mouse in both text and graphics modes is
                 provided.

                 Sysinfo library. This library provides a set of
                 diagnostic routines that can be called upon to
                 identify the type of computer system that a program
                 is running on. It can automatically determine things
                 such as the processor type (8086 - 80486), BIOS
                 class, extended keyboard support, video display
                 subsystem type and so on.

            Chapter's 3 to 6 provides a complete reference to the
            user callable functions in the MegaToolbox, and a more
            detailed explanation of each Libraries capabilities.

            This set of libraries is aimed at the experienced
            programmer, so no tutorial documentation or information
            on generally using libraries to write and successfully
            compile programs is given. For more information you will



            Chapter 1 - Introduction                                   1






            need to consult the documentation that came with your
            compiler.


























































            2                              MegaToolbox Library Reference


































































            Chapter 1 - Introduction                                   3










                                                         C H A P T E R
                                                                     2

                                           About the Library Reference

            The following chapters provide a detailed reference to
            the routines in the MegaToolbox. All of the routines are
            grouped by the library that they appear in. Thus all of
            the routines in the CONSOLE handling library are in a
            separate chapter to those in the MOUSE library. Within
            each chapter the routines are in alphabetical order.
            There is an individual entry for every function in the
            library. If you wanted to determine what the CON_puts()
            routine does, you would look it up in the CONSOLE library
            section under CON_puts, where you would find an entry for
            CON_puts that

                 Summarises what CON_puts does

                 Gives the syntax for calling the CON_puts routine

                 Tells you which header file(s) contain the prototype
                 for CON_puts

                 Gives a detailed description of how CON_puts is
                 implemented and how it relates to other console
                 output routines.

                 Makes a reference to other related library routines

                 If appropriate gives and example of how the function
                 is used, or refers you to a function entry where
                 there is an example.

            The following sample library entry explains how to find
            out such details about the routines in the MegaToolbox.
            Note that all of the example programs in the reference
            manual are included in the distribution, in fact, the
            examples in the reference manual are taken directly from
            the real working examples.

















            Chapter 2 - About the Library Reference                    5






            How to use reference entries

            Function    Summary of what the function does

            Syntax      function(modifier parameter[, ... ]);

                        This gives you the declaration syntax for the
                        function. The [, ... ] indicates that other
                        parameters and modifiers may follow.

            Prototype   header.h
            in
                        This lists the header file(s) containing the
                        prototype for the function. The prototype of
                        a function may be contained in more than one
                        header file, in which case all the files
                        would be listed, so use whichever one is more
                        appropriate.

            Remarks     This section describes what the function
                        does, the parameters it takes and any details
                        that you might need to know in order to get
                        full use out of the function.

            Return      This section describes the value returned by
            value       the function (if any).

            See also    This sections gives a list of other related
                        functions in the library that may be of
                        interest.






























            6                              MegaToolbox Library Reference









                                                         C H A P T E R
                                                                     3

                                                         Mouse Library

            The mouse library provides a uniform high level interface
            to microsoft and compatible mice. For full compatibility
            with this library, the system must have must have one of
            the following mice installed:

                 Microsoft Mouse version 6.1 or later, or any mouse
                 compatible with this mouse.
                 Logitech Mouse version 3.4 or later.
                 Mouse Systems' PC Mouse version 6.22 or later.
                 IMSI mouse version 6.11 or later.

            The routines that comprise the mouse library are all
            memory model independant. This means that there is only
            one mouse library called "mouse.lib" in the distribution
            that is designed to be used in any of the standard 80x86
            memory models. You use the same library for writing small
            model programs as you use for writing huge model
            programs.

            MS_constrain

            Function    Constrains the movement of the mouse cursor.

            Syntax      void huge MS_constrain(int left, int top, int
                        right, int bottom);

            Prototype   mouse.h
            in

            Remarks     MS_constrain() limits the movement of the
                        mouse cursor to the specified rectangle on
                        the display.

            Return      None.
            value


            MS_dblSpeed

            Function    Sets the mouse double speed threshold.

            Syntax      void huge MS_dblSpeed(int threshold);

            Prototype   mouse.h
            in







            Chapter 3 - Mouse Library                                  7






            Remarks     MS_dblSpeed() sets the double speed threshold
                        for the mouse cursor. When the speed of the
                        cursor passes a certain point, the effective
                        speed is doubled to provide a form of
                        acceleration on demand. The default value is
                        64 mickeys per second.

            Return      None.
            value

            See also    MS_speed


            MS_exit

            Function    Gracefully de-installs the mouse routines.

            Syntax      void huge MS_exit(void);

            Prototype   mouse.h
            in

            Remarks     Before a program exists, it _MUST_ call
                        MS_exit() to de-install any installed
                        interrupt handlers that the mouse routines
                        have installed. A call to MS_exit() will hide
                        the mouse cursor and remove any installed
                        user mouse handling routines.

                        A good way to do this is to register the
                        MS_exit() function as an exit function, or
                        call it from a registered exit function
                        (registered with atexit() ).

            Return      None.
            value

            See also    MS_init


            MS_getCrtPage

            Function    Gets the current video page used for
                        displaying the mouse cursor.

            Syntax      int huge MS_getCrtPage(void);

            Prototype   mouse.h
            in

            Remarks     MS_getCrtPage() returns the current video
                        page number that the mouse driver is
                        currently displaying he mouse cursor on.

            Return      The CRT page used for displaying the mouse
            value       cursor.

            See also    MS_setCrtPage


            8                              MegaToolbox Library Reference








            MS_hide

            Function    Hides the mouse cursor

            Syntax      void huge MS_hide(void);

            Prototype   mouse.h
            in

            Remarks     The MS_hide() function decreases the value of
                        the mouse drivers internal cursor flag by 1.
                        When the value of the internal cursor flag
                        reaches 0, the mouse cursor is visible and
                        subsequen calls to MS_show() will have no
                        effect. When the mouse cursor flag is less
                        than 0, the mouse cursor is hidden from view.

            Return      none.
            value

            See also    MS_show


            MS_init

            Function    Initialise the mouse interface module.

            Syntax      int huge MS_init(void);

            Prototype   mouse.h
            in

            Remarks     This routine should be called before ANY
                        calls to the routines in the mouse interface
                        module. The purpose of this routine is to set
                        up the mouse interrupt subroutine so that
                        event may be captured, and to initialise the
                        mouse if it is present. You must ensure that
                        MS_exit() is called before the program
                        terminates. It also performs a hardware reset
                        on the mouse driver - see MS_softReset() for
                        an explanation of the mouse drivers default
                        state.

                        MS_init() returns the number of buttons on
                        the mouse, or it returns 0 if the mouse is
                        not present or a mouse device driver is not
                        installed.

            Return      Number of buttons on the mouse (0 if no mouse
            value       installed)

            See also    MS_exit





            Chapter 3 - Mouse Library                                  9






            MS_motion

            Function    Reads the value of the horizontal and
                        vertical motion counters

            Syntax      void huge MS_motion(int far *h,int far *v);

            Prototype   mouse.h
            in

            Remarks     The MS_motion() function returns the
                        horizontal and vertical mickey counts since
                        your program last called this function. The
                        mickey count is the distance that the mouse
                        has moved in 1/200th's of an inch increments.
                        The mickey count always ranges from -32768 to
                        32767, where a positive count indicates a
                        move to the right or down, while a negative
                        count represents a move to the left or up.
                        The mickey counts are reset each time the
                        function is called.

            Return      none.
            value

            See also    MS_pos, MS_pressed, MS_released


            MS_moveTo

            Function    Moves the mouse cursor to a new location

            Syntax      void huge MS_moveTo(int h,int v);

            Prototype   mouse.h
            in

            Remarks     The MS_moveTo() function move the cursor to
                        the new location (h,v) on the screen (where
                        (h,v) is specified in display coordinates).

            Return      none.
            value

            See also    MS_pos


            MS_pos

            Function    Determine the current position and status of
                        the mouse.

            Syntax      void huge MS_pos(ms_status far *stat);

            Prototype   mouse.h
            in




            10                             MegaToolbox Library Reference






            Remarks     The MS_pos() function returns the current
                        position and button status of the mouse. The
                        information is returned in an ms_status
                        structure, which is defined in the mouse.h
                        header file as:

                        typedef struct {
                            int         but_status;
                            int         but_count;
                            int         x;
                            int         y;
                            } ms_status;

                        The but_status field determines which buttons
                        are currently down (if any). Bit 0 represents
                        the left button (0 = up, 1 = down), bit 1
                        represents the right button while bit 2
                        represent the middle button if present. The x
                        and y fields provide the current location of
                        the mouse cursor. The but_count field is not
                        used.

            Return      none.
            value

            See also    MS_pressed, MS_released, MS_motion


            MS_pressed

            Function    Determine the number and location of previous
                        button presses.

            Syntax      void huge MS_pressed(int which,ms_status far
                        *stat);

            Prototype   mouse.h
            in

            Remarks     The MS_pressed() function determines the
                        number of button presses and the position of
                        the last button pressed for the designated
                        button, since the last call to this routine.
                        It also returns the current button status for
                        all buttons. The information is returned in
                        an ms_status structure, defined in the
                        mouse.h header file as:

                        typedef struct {
                            int         but_status;
                            int         but_count;
                            int         x;
                            int         y;
                            } ms_status;






            Chapter 3 - Mouse Library                                 11






                        The pressed member function returns the
                        status of all buttons in the but_status
                        field. determines which buttons are currently
                        down (if any). Bit 0 represents the left
                        button (0 = up, 1 = down), bit 1 represents
                        the right button while bit 2 represent the
                        middle button if present. The x and y fields
                        provide the location of the last button press
                        for the button designated by 'which', and
                        but_count field holds the number of presses
                        since the last call to this function for the
                        designated button.

                        The mouse.h header file provides three macros
                        to designate which button to check, these
                        are:

                        #define leftBut     0
                        #define rightBut    1
                        #define middleBut   2

            Return      none.
            value

            See also    MS_pos, MS_released, MS_motion


            MS_released

            Function    Determine the number and location of previous
                        button releases.

            Syntax      void huge MS_released(int which,ms_status far
                        *stat);

            Prototype   mouse.h
            in

            Remarks     The MS_released() function determines the
                        number of button releases and the position of
                        the last button release for the designated
                        button, since the last call to this routine.
                        It also returns the current button status for
                        all buttons. The information is returned in
                        an ms_status structure, defined in the
                        mouse.h header file as:

                        typedef struct {
                            int         but_status;
                            int         but_count;
                            int         x;
                            int         y;
                            } ms_status;







            12                             MegaToolbox Library Reference






                        The pressed member function returns the
                        status of all buttons in the but_status
                        field. determines which buttons are currently
                        down (if any). Bit 0 represents the left
                        button (0 = up, 1 = down), bit 1 represents
                        the right button while bit 2 represent the
                        middle button if present. The x and y fields
                        provide the location of the last button
                        release for the button designated by 'which',
                        and but_count field holds the number of
                        releases since the last call to this function
                        for the designated button.

                        The mouse.h header file provides three macros
                        to designate which button to check, these
                        are:

                        #define leftBut     0
                        #define rightBut    1
                        #define middleBut   2

            Return      none.
            value

            See also    MS_pos, MS_pressed, MS_motion


            MS_restoreState

            Function    Restores the state of the mouse driver to a
                        previously saved state.

            Syntax      void huge MS_restoreState(void far
                        *theState);

            Prototype   mouse.h
            in

            Remarks     The MS_restoreState() function restores the
                        state of the mouse driver to that of a state
                        that has been previously saved using the
                        MS_saveState() function. Use this is you wish
                        to make a number of temporary changes to the
                        mouse driver, such as changing the mouse
                        cursor temporarily etc.

            Return      none.
            value

            See also    MS_saveState, MS_stateSize.










            Chapter 3 - Mouse Library                                 13






            MS_saveState

            Function    Saves the current state of the mouse driver.

            Syntax      void huge MS_saveState(void far *theState);

            Prototype   mouse.h
            in

            Remarks     The MS_saveState() function saves the current
                        state of the mouse driver and places it into
                        a buffer pointed to by 'theState'. Note that
                        this buffer MUST be allocated BEFORE calling
                        MS_saveState(), and must be at least as large
                        as that specified by MS_stateSize(). The best
                        solution is to allocate the memory via
                        malloc() or something similar.

                        MS_saveState() saves the entire state of the
                        mouse, including the text and graphics
                        cursors, position etc.

            Return      none.
            value

            See also    MS_stateSize, MS_restoreState


            MS_setCrtPage

            Function    Sets the CRT page for displaying the mouse
                        cursor.

            Syntax      void huge MS_setCrtPage(int page);

            Prototype   mouse.h
            in

            Remarks     The MS_setCrtPage() function tells the mouse
                        driver on which page to draw the mouse
                        cursor's image. Some video modes only have 1
                        page available, but others allow for multiple
                        pages. The default page number is 0.

            Return      none.
            value

            See also    MS_getCrtPage












            14                             MegaToolbox Library Reference






            MS_setCursor

            Function    Sets the graphics mode cursor to a new shape.

            Syntax      void huge MS_setCursor(cursor far *curs);

            Prototype   mouse.h
            in

            Remarks     The MS_setCursor() function sets the graphics
                        mode cursor, and takes a pointer to the
                        graphics cursor's definition as a parameter.
                        The stucture of a graphics cursor is defined
                        in the header file mouse.h as:

                        typedef struct {
                            bits16      screenmask;
                            bits16      cursormask;
                            int         hotspot_x;
                            int         hotspot_y;
                            } cursor;

                        The cursor hotspot value defines a point
                        relative to the top left corner of the cursor
                        block that specifies the position of the
                        cursor block relative to the mouse pointers
                        actual position. The hotspot coordinate may
                        range in value from -128 to 127, although
                        typical values range from 0 to 15. The
                        screenmask and cursormask define the actual
                        image of the cursor. The screenmask is used
                        to 'punch' a hole in the background where the
                        cursor should go. For every 0 bit in the
                        screenmask, a hole is punched (in the
                        background color). The cursormask is used to
                        fill in the hole. For every 1 bit in the
                        cursormask, a white pixel is placed in the
                        image.

            Return      none.
            value

            See also    MS_setTextCursor


            MS_setTextCursor

            Function    Sets the text mode mouse cursor
                        representation

            Syntax      void huge MS_setTextCursor(int type,int
                        screenMask,int cursorMask);

            Prototype   mouse.h
            in





            Chapter 3 - Mouse Library                                 15






            Remarks     The MS_setTextCursor() function sets the
                        value of the current text cursor. It takes as
                        parameters a cursor type (HARDWARE or
                        SOFTWARE), and values for the screenmask and
                        cursormask. If the cursor type is HARDWARE,
                        the screenmask and cursormask define the
                        cursor scan line start and scan line end
                        values respectively (as per the normal BIOS
                        text cursor). If the cursor type is SOFTWARE
                        (most common), the screenmask and cursormask
                        represent the characters and attributes to
                        mask the affected location with. The
                        screenmask value is logically 'and'ed with
                        the affected character, to determine which
                        bits of the affected character shall be
                        preserved. The cursormask is then logically
                        'xor'ed with the affected character, so for
                        every 1 bit in the cursormask, a bit is
                        flipped in the affected character (remember
                        that we are working both the ASCII definition
                        and the attribute). The standard text mode
                        cursor is defined with a screenmask of 0xFFFF
                        (to not change the affected character), and a
                        cursormask of 0x7700, which inverts the color
                        of the affected character.

            Return      none.
            value

            See also    MS_setCursor


            MS_show

            Function    Shows the mouse cursor

            Syntax      void huge MS_show(void);

            Prototype   mouse.h
            in

            Remarks     The MS_show() function increases the value of
                        the mouse drivers internal cursor flag by 1.
                        When the value of the internal cursor flag
                        reaches 0, the mouse cursor
                        is visible and subsequent calls to MS_show()
                        will have no effect. When the mouse cursor
                        flag is less than 0, the mouse cursor is
                        hidden from view.

            Return      none.
            value

            See also    MS_hide






            16                             MegaToolbox Library Reference






            MS_softReset

            Function    Performs a software reset on the mouse driver

            Syntax      int huge MS_softReset(void);

            Prototype   mouse.h
            in

            Remarks     The MS_softReset() member function performs a
                        software reset on the mouse driver and mouse,
                        and returns the number of buttons on the
                        mouse. The MS_softReset() function resets the
                        mouse driver to the following default state:

                        Cursor Position:          center of screen
                        Internal cursor flag:     -1 (cursor hidden)
                        Graphics cursor:          Arrow
                        Text cursor:              Reverse video block
                        Interrupt routines:       Re-installed
                        Horizontal
                        mickey-per-pixel ratio:   8 to 8
                        Vertical
                        mickey-per-pixel ratio:   16 to 8
                        Double speed threshold:   64 mickeys per
                        second
                        Minimum cursor position:  (0,0)
                        Maximum cursor position:  (xmax,ymax)
                        CRT page number:          0

                        MS_softReset() ensure that any user installed
                        mouse interrupt handler are re-installed
                        after the mouse driver is reset. Note that
                        'xmax' and 'ymax' are the current video
                        display mode maximum x and y coordinates.

            Return      Number of buttons on the mouse.
            value

            See also    MS_init


            MS_speed

            Function    Sets the horizontal and vertical mouse speed.

            Syntax      void huge MS_speed(int hratio,int vratio);

            Prototype   mouse.h
            in

            Remarks     The MS_speed() function sets the horizontal
                        and vertical mouse cursor speed (or
                        sensitivity) to those of 'hratio' and
                        'vratio' respectively. The speed values range
                        from 1 to 100 where a value of 1 gives 1/32
                        times, and 100 gives 14/4 times. A value of
                        50 specifies the default mickey ratio of 1.


            Chapter 3 - Mouse Library                                 17







            Return      none.
            value

            See also    MS_dblSpeed


            MS_stateSize

            Function    Determines the size of buffer needed to save
                        the mouse driver state.

            Syntax      int huge MS_stateSize(void);

            Prototype   mouse.h
            in

            Remarks     The MS_stateSize() function determines the
                        number of bytes required to save the state of
                        the mouse driver, so that it can be saved and
                        restored with the MS_saveState() and
                        MS_restoreState() functions.

            Return      Size of required save buffer in bytes.
            value

            See also    MS_saveState, MS_restoreState


            MS_swapIntSub

            Function    Installs a new interrupt handling routine.

            Syntax      void huge MS_swapIntSub(int num,intsub far
                        *newSub,intsub far *oldSub);

            Prototype   mouse.h
            in






















            18                             MegaToolbox Library Reference






            Remarks     MS_swapIntSub() swaps the specified mouse
                        interrupt subroutine handler with newsub and
                        returns the old one in oldsub. The intsub
                        structure used for passing the information is
                        defined in the mouse.h header file as:

                        typedef struct {
                            void    far *addr;
                            int         mask;
                            } intsub;

                        where the addr field contains the interrupt
                        subroutines address, and the mask field
                        contains the value of the interrupt
                        subroutines call mask. The call mask is an
                        integer value that defines which conditions
                        cause the mouse interrupt to call the
                        associated interrupt handling routine. Each
                        bit in the call mask corresponds to a
                        specific condition, as shown in the following
                        table:

                        Mask bit:  Condition:
                        0          Cursor position has changed
                        1          Left button pressed
                        2          Left button released
                        3          Right button pressed
                        4          Right button released
                        5          Middle button pressed
                        6          Middle button released
                        7-15       Not used

                        To enable the subroutine for a given
                        condition, set the corresponding call mask
                        bit to 1 in the intsub structure. Your
                        program may set any combination of bits that
                        it wishes. When any one of the conditions is
                        met, the mouse hardware interrupt calls the
                        subroutine, which determines the condition
                        that occurred by examing the value of the AX
                        register. When the mouse software makes a
                        call to the subroutine it loads the following
                        information into the CPU registers:

                        Register:  Information:
                        AX         Condition mask (bit is set only if
                                   condition is met.
                        BX         Button state
                        CX         Horizontal cursor coordinate
                        DX         Vertical cursor ccordinate
                        SI         Horizontal mickey counts
                        DI         Vertical mickey counts








            Chapter 3 - Mouse Library                                 19






                        Since the subroutine is passed all of its
                        parameters in machine registers, the routine
                        will need to be written in assembly language
                        (you could write most of the routine in C,
                        but you would need to provide a small
                        assembly language stub to pass the parameters
                        on the stack). To disable a handler, set it's
                        mask to all zeroes.

                        Three interrupt handlers are available for
                        use. Generally, the first handler is
                        available for use by user programs, while the
                        second and third are reserved for use by the
                        MegaTOOLBOX and the MegaGraph graphics
                        library. Handler 2 is used for the event
                        handling routines in the event handling
                        library, while the MegaGraph graphics library
                        uses handler 3 to control the mouse cursor on
                        the current graphics screen.

            Return      none.
            value






































            20                             MegaToolbox Library Reference









                                                         C H A P T E R
                                                                     4

                                                         Event Library

            The event library provides a way to collect keyboard
            events, mouse events and user defined events together and
            treat them all in a uniform manner. The event module
            provides a single priority event queue, which allows your
            programs to respond to user events such as keydown's,
            keyrepeat's, keyup's, mouse clicks and even mouse
            movements in the exact order that the user performed
            them. The event module also provides extra information
            along with the event, such as the exact time that the
            event occurred and the state of the keyboard modifier
            keys (ctrl, alt and shift).

            The event module calls upon some of the routines in the
            mouse module to setup the collection of mouse events.
            Thus if you wish to use the routines in the event module,
            you will also need to link in the mouse module library.

            The event module installs a custom keyboard interrupt
            subroutine to collect keyboard events and place them in
            the event queue. To maintain compatibility with the BIOS
            and DOS key collection routines the event module also
            intercepts calls to the BIOS to obtain keypress
            information, and removes the first
            keyboard event from the event queue and returns it. Thus
            you may still use other library routines and code that
            call getch() or the BIOS to obtain keypress information
            along with the event handling library. The event module
            also automatically determines if extended keyboard
            support is present and will return the extended key codes
            if one is detected.


            EVT_asciiCode

            Function    Returns the ascii code of a keyboard event
                        message

            Syntax      char EVT_asciiCode(long message);

            Prototype   event.h
            in

            Remarks     This is a simple macro to extract the ASCII
                        character code from the message field of a
                        keyboard event.

            Return      ASCII code for key that was pressed.
            value

            See also    EVT_scanCode


            Chapter 4 - Event Library                                 21








            EVT_delay

            Function    Halts program execution for a specified time
                        waiting for an event.

            Syntax      void EVT_delay(event *evt,int mask,uint
                        time);

            Prototype   event.h
            in

            Remarks     Halts program execution until a specified
                        time has elapsed, or an event of the type
                        specified by 'mask' has occurred. You may
                        combine the masks for different event types
                        with a simple logical OR. The time to wait is
                        passed as a multiple of 1 millisecond in the
                        'time' parameter.

                        The event is returned in the structure
                        pointed to by 'evt'. If the routine times out
                        before an event occurred, the 'what' field of
                        the event will be set to a NULLEVT, otherwise
                        the event that was caught is removed from the
                        event queue and returned. Refer to
                        EVT_getNext for a description of the event
                        structure.

                        Note that EVT_delay will return immediately
                        if there is already a pending event of the
                        specified type waiting in the event queue.
                        You can call EVT_flush to flush all pending
                        events of the specified type to
                        unconditionally halt program execution.

            Return      None.
            value

            See also    EVT_halt, EVT_flush


            EVT_flush

            Function    Flushes all events of a specified type from
                        the event queue.

            Syntax      void EVT_flush(int mask);

            Prototype   event.h
            in

            Remarks     Flushes (removes) all pending events of the
                        type specified in the 'mask' parameter from
                        the event queue. You may combine the masks
                        for different event types with a simple
                        logical OR.


            22                             MegaToolbox Library Reference







            Return      None.
            value

            See also    EVT_halt, EVT_delay


            EVT_getNext

            Function    Retrieves the next pending event from the
                        event queue.

            Syntax      bool EVT_getNext(event *evt,int mask);

            Prototype   event.h
            in

            Remarks     Retrieves the next pending event defined
                        specified by the 'mask' parameter from the
                        event queue. You may combine the masks for
                        different event types with a simple logical
                        OR. The event queue is adjusted to reflect
                        the new state after the event has been
                        removed.

                        The event is returned in the structure
                        pointed to by the 'evt' parameter, which is
                        defined in the "event.h" header file as:

                        typedef struct {
                            uint        what;
                            long        when;
                            int         where_x;
                            int         where_y;
                            long        message;
                            int         modifiers;
                            } event;























            Chapter 4 - Event Library                                 23






                        The what field defines the type of event that
                        occurred, and will contain one of the
                        following codes defined in "event.h":

                        #define NULLEVT     0x0000
                        #define KEYDOWN     0x0001
                        #define KEYREPEAT   0x0002
                        #define KEYUP       0x0004
                        #define MOUSEDOWN   0x0008
                        #define MOUSEUP     0x0010
                        #define MOUSEMOVE   0x0020
                        #define TIMERTICK   0x0040
                        #define USEREVT     0x0080

                        All application specific event should begin
                        with the USEREVT code and build from there.
                        Since the event code is stored in a 16 bit
                        integer, there is a maximum of 16 different
                        event codes that can be distinguished. You
                        can store extra information about the event
                        in the 'message' field to distinguish between
                        events of the same class (for instance the
                        button used in a MOUSEDOWN event).

                        The when field contains the time in ticks
                        since midnight that the event occurred. This
                        field can be useful to determine whether two
                        mouse clicks were performed close enough
                        together to be recognised as a 'double
                        click'.

                        The where_x and where_y fields contain the
                        location of the mouse cursor at the time of
                        the specified mouse event. These fields are
                        not used for keyboard events, and may contain
                        event specific information for user defined
                        events if required.

                        The message field is a 32 bit long integer
                        that contains event specific information.
                        This field is used to store the ASCII code
                        and keyboard scan code of keyboard events
                        (see EVT_asciiCode and EVT_scanCode to
                        extract this information from events), and
                        button press information for mouse events. It
                        may contain any event specific information
                        for user defined events. The bit masks for
                        the MOUSEDOWN and MOUSEUP event  message
                        fields is defined in "event.h" as:

                        #define LEFTBMASK   0x0001
                        #define RIGHTBMASK  0x0004
                        #define BOTHBMASK   0x0005
                        #define MIDDLEMASK  0x0010
                        #define LEFTMBMASK  0x0011
                        #define RIGHTMBMASK 0x0014
                        #define ALLBMASK    0x0015



            24                             MegaToolbox Library Reference






                        The modifiers field contains information
                        about the state of the keyboard shift
                        modifiers (ctrl, alt and shift) and the state
                        of the mouse buttons for mouse events. The
                        modifier masks are defined in "event.h" as:

                        #define LEFTBUT     0x0001
                        #define RIGHTBUT    0x0002
                        #define MIDDLEBUT   0x0004
                        #define RIGHTSHIFT  0x0008
                        #define LEFTSHIFT   0x0010
                        #define CTRLSTATE   0x0020
                        #define ALTSTATE    0x0040
                        #define LEFTCTRL    0x0080
                        #define LEFTALT     0x0100
                        #define SHIFTKEY    (LEFTSHIFT | RIGHTSHIFT)

                        If an event of the specified type was not in
                        the event queue, the what field of the event
                        will be set to NULLEVT, and EVT_getNext will
                        return false.

                        KEYUP event's only report the raw keyboatd
                        scancode for the key that was pressed, and
                        does not do any conversion of this scancode
                        to standard ASCII character codes. Note also
                        that the scan codes returned by the BIOS are
                        slightly different to the raw scancodes,
                        since the BIOS modifies the scancodes for
                        some
                        keys when a keyboard modifier is held down
                        (ie: Shift-F1 etc).

                        The TIMERTICK event is used to report that a
                        specified time interval has elapsed since the
                        last TIMERTICK event occurred. See
                        EVT_setTimerTick() for information on how to
                        set this up.

            Return      True if an event was pending, false if not.
            value

            See also    EVT_peekNext, EVT_post, EVT_setTimerTick


            EVT_halt

            Function    Halts program until a specified event occurs.

            Syntax      void EVT_halt(event *evt,int mask);

            Prototype   event.h
            in







            Chapter 4 - Event Library                                 25






            Remarks     Halts program execution until an event of the
                        type specified by 'mask' has occurred. You
                        may combine the masks for different event
                        types with a simple logical OR.

                        The event is returned in the structure
                        pointed to by 'evt'. The event that was
                        caught is removed from the event queue and
                        returned. Refer to EVT_getNext for a
                        description of the event structure.

                        Note that EVT_halt will return immediately if
                        there is already a pending event of the
                        specified type waiting in the event queue.
                        You can call EVT_flush to flush all pending
                        events of the specified type to
                        unconditionally halt program execution.

            Return      None.
            value

            See also    EVT_delay, EVT_flush


            EVT_init

            Function    Initialises the event handling module

            Syntax      void EVT_init(void);

            Prototype   event.h
            in

            Remarks     This routine _MUST_ be called before you can
                        use the event handling routines. It installs
                        the custom mouse and keyboard interrupt
                        handlers so that events will be posted to the
                        event queue when they occur. It also ensures
                        that the keyboard and mouse interrupt
                        routines are properly removed upon program
                        termination. It does this by registering an
                        exit function with atexit() to be called upon
                        program termination.

                        If a program that uses the event handling
                        routines terminates via the abort() function
                        or any other function that does NOT call all
                        valid exit functions upon program
                        termination, the keyboard and mouse ISR's
                        will not be restored and the machine will
                        most probably crash as soon as a key is
                        pressed or the mouse is moved.

            Return      None.
            value





            26                             MegaToolbox Library Reference






            EVT_mouseMove

            Function    Turns on or off the collection of mouse
                        movement events.

            Syntax      bool EVT_mouseMove(bool set);

            Prototype   event.h
            in

            Remarks     By default mouse movement events are ignored.
                        This routine is used to change the state of
                        mouse movement collection. If the 'set'
                        parameter is true, mouse movement collection
                        is turned on, otherwise it is turned off.

                        Moving the mouse only a few centimeters can
                        generate LOTS of movement events, which can
                        quickly fill up the event queue if they are
                        not processed in time. You should only turn
                        on mouse movement collection when you really
                        need it, and turn it off again when you have
                        finished.

                        The old value of the mouse movement
                        collection flag is returned.

            Return      Old value of mouse movement flag.
            value


            EVT_peekNext

            Function    Peeks at the next pending event in the event
                        queue.

            Syntax      bool EVT_peekNext(event *evt,int mask);

            Prototype   event.h
            in

            Remarks     Peeks at the next pending event defined
                        specified by the 'mask' parameter in the
                        event queue. In contrast to EVT_getNext, the
                        event is not removed from the event queue.
                        You may combine the masks for different event
                        types with a simple logical OR.

                        Refer to EVT_getNext for a description of the
                        event structure.

            Return      True if an event is pending, false if not.
            value

            See also    EVT_getNext, EVT_post





            Chapter 4 - Event Library                                 27






            EVT_post

            Function    Posts a user defined event to the event queue

            Syntax      bool EVT_post(int what,long message,ms_status
                        *stat,int modifiers);

            Prototype   event.h
            in

            Remarks     This routine is normally used to post user
                        events to the event queue, but may also be
                        used to post both mouse and keyboard events
                        to the event queue.

                        The what field contains the type of event to
                        post, while the message and modifiers fields
                        contain the information to store in the
                        associated parts of the event structure. The
                        stat field is used to pass mouse status
                        information, such as the button state and
                        location of the mouse cursor (refer to the
                        mouse interface documentation for information
                        on the ms_status structure) to be stored in
                        the posted event.

                        If you pass a NULL for the stat field, the
                        event posting routine will obtain the current
                        mouse status information from the mouse
                        module for you.

                        If you pass a -1 as the value for the
                        modifiers, the modifier field will be set to
                        the current state of the keyboard modifiers
                        along with the current state of the mouse
                        buttons (this is taken from the status info
                        passed or the info obtain from the mouse
                        module).

            Return      True if event was posted, false if event
            value       queue is full.

            See also    EVT_getNext, EVT_peekNext


            EVT_scanCode

            Function    Returns the keyboard scan code of a keyboard
                        event message

            Syntax      char EVT_scanCode(long message);

            Prototype   event.h
            in






            28                             MegaToolbox Library Reference






            Remarks     This is a simple macro to extract the
                        keyboard scan code from the message field of
                        a keyboard event. All keys have a special
                        scan code that can be used to identify
                        exactly which key was pressed. Information
                        about keyboard scan codes can be found in any
                        good book on the IBM PC's BIOS.

            Return      Keyboard scan code for key that was pressed.
            value

            See also    EVT_asciiCode


            EVT_setTimerTick

            Function    Set the interval between TIMERTICK events

            Syntax      int EVT_setTimerTick(int ticks);

            Prototype   event.h
            in

            Remarks     This routine sets the number of ticks between
                        each posting of the TIMERTICK
                        event to the event queue. The TIMERTICK event
                        is off by default. You can turn off the
                        posting of TIMERTICK events by setting the
                        tick interval to 0.

                        One tick is approximately equal to 1/18.2 of
                        a second. To work out a precise
                        interval given in seconds, use the following
                        expression:

                            ticks = secs * (1193180.0 / 65536.0);

            Return      Old value of timer tick interval
            value





















            Chapter 4 - Event Library                                 29










                                                         C H A P T E R
                                                                     5

                                                       Sysinfo Library

            The sysinfo module contains a number of routines for
            determining system specific information about a user's
            machine at runtime. Information such as the type of
            micro-processor installed, floating point co-processor
            (if present), video display type or the type of BIOS
            installed on the machine can be determined.

            It can be time consuming to continually determine system
            configuration information whenever it is needed, so the
            library only interrogates the system for static
            information (information that will not change during
            program execution) once. After that the information is
            cached for later retrieval.

            The system information library provides complete support
            for the extended video modes of the EGA and VGA,
            providing routines for setting the system into the
            EGA/VGA 43/50 line text video modes and back again to the
            standard 25 line text mode. It also provides routines to
            swap between the monochrome and color video adapters if
            two adapters are installed in the same machine.

            Most of the routines in the library are very straight
            forward, so no programming examples are given. Instead
            reference is made to the example programs in the
            distribution that use the specified function. These
            example programs are quite useful in their own right.


            SYS_biosClass

            Function    Determines the type of BIOS installed.

            Syntax      class_type SYS_biosClass(void);

            Prototype   sysinfo.h
            in















            Chapter 5 - Sysinfo Library                               31






            Remarks     This routine returns the type of system BIOS
                        that is installed in the machine. The system
                        BIOS is used to provide all system input and
                        output routines, and sometimes it is
                        necessary to know if a compatible BIOS exists
                        if functions not present in an earlier BIOS
                        must be used.

                        The routine returns a value of the type
                        'class_type', and enumeration defined in
                        "sysinfo.h" as:

                        typedef enum {
                            PC_class,
                            PCXT_class,
                            PCAT_class,
                            PS2_class
                            } class_type;

            Return      Type of system BIOS installed.
            value


            SYS_cpu

            Function    Determine the type of Central Processing Unit
                        present

            Syntax      cpu_type SYS_cpu(void);

            Prototype   sysinfo.h
            in

            Remarks     This function determines the type of Central
                        Processing Unit (CPU) installed in the
                        system. It returns a value of the type
                        'cpu_type' an enumeration defined in the
                        "sysinfo.h" header file as:

                        typedef enum {
                            cpu_86,
                            cpu_186,
                            cpu_286,
                            cpu_286p,
                            cpu_386,
                            cpu_386p,
                            cpu_486,
                            cpu_486p
                            } cpu_type;

                        where the numbering corresponds to the
                        different types of Intel 80x86 processor
                        common in most IBM PC compatible machines.
                        When a 'p' succeeds the cpu type it means
                        that the cpu is currently running in
                        protected mode.




            32                             MegaToolbox Library Reference






            Return      Type of cpu installed in the system.
            value

            See also    SYS_fpu


            SYS_extKeyboard

            Function    Determines if extended keyboard support is
                        present.

            Syntax      bool SYS_extKeyboard(void);

            Prototype   sysinfo.h
            in

            Remarks     This function will return true if the system
                        BIOS has extended keyboard support built in.
                        Most AT style BIOS's and all PS/2 BIOS's
                        support the extended keyboard, but a lot of
                        PC/XT type clones also support the extended
                        keyboard. Extended keyboard support allows
                        programs to read the F11 and F12 keys that
                        exists on all AT style 101/102 key keyboards.

            Return      True if extended keyboard support is present,
            value       false if not.


            SYS_fpu

            Function    Determine the type of co-processor present.

            Syntax      fpu_type SYS_fpu(void);

            Prototype   sysinfo.h
            in

            Remarks     This routine will determine the type of
                        floating point co-processor that is installed
                        in the system, if one exists. It returns a
                        value of the type 'fpu_type', and enumeration
                        defined in the "sysinfo.h" file as:

                        typedef enum {
                            fpu_none,
                            fpu_87,
                            fpu_287,
                            fpu_387,
                            fpu_487
                            } fpu_type;

                        Note that this routine will correctly
                        determine if an 80287 co-processor is
                        installed in an 80386 type machine.

            Return      Type of co-processor present.
            value


            Chapter 5 - Sysinfo Library                               33







            See also    SYS_cpu


            SYS_getSubSys

            Function    Determines video subsystem information.

            Syntax      void SYS_getSubSys(subsys_type *subSystem);

            Prototype   sysinfo.h
            in

            Remarks     This routine detects the type of video
                        subsystem that is installed in the system,
                        returning the information in the structure
                        pointed to by the 'subSystem' parameter. This
                        routine will detect most of the common PC
                        video subsystems. The 'subsys ' structure in
                        defined in the file "sysinfo.h" as:

                        typedef struct {
                            adapter_type    adapter1;
                            adapter_type    adapter2;
                            display_type    display1;
                            display_type    display2;
                            videoram_type   videoram1;
                            videoram_type   videoram2;
                            } subsys_type;

                        where the adapter1/display1/videoram1 entries
                        define the currently active video subsystem,
                        while the adapter2/display2/videoram2 entries
                        define the inactive video subsystem (if two
                        adapters are present in the system).

























            34                             MegaToolbox Library Reference






                        The adapter1/adapter2 entries are of the type
                        'adapter_type' defined in the "sysinfo.h"
                        file as:

                        typedef enum  {
                            no_adapter,
                            MDA_adapter,
                            CGA_adapter,
                            EGA_adapter,
                            MCGA_adapter,
                            VGA_adapter,
                            SVGA_adapter,    - VESA SuperVGA
                            HGC_adapter
                            } adapter_type;

                        The display1/display2 entries are of the type
                        'display_type' defined in the "sysinfo.h"
                        file as:

                        typedef enum {
                            no_display,
                            MDA_display,
                            CGA_display,
                            EGA_display,
                            PS2mono_display,
                            PS2color_display
                            } display_type;

                        Standard VGA displays are detected as PS2
                        type displays.

            Return      None.
            value


            SYS_getVideoMode

            Function    Return the current video mode.

            Syntax      int SYS_getVideoMode(void);

            Prototype   sysinfo.h
            in

            Remarks     This routine returns the current BIOS video
                        mode number. The mode number is returned as
                        an integer. If the EGA/VGA 43/50 line mode is
                        currently set, the high bit of the number
                        returned (bit 15) is set. This is intended
                        primarily so that
                        you can save the original video mode that the
                        machine was in upon program startup, and
                        reset it upon program termination (which will
                        reset 43/50 line mode if it was on).

            Return      Current BIOS video mode number.
            value



            Chapter 5 - Sysinfo Library                               35






            See also    SYS_setVideoMode


            SYS_modeColor

            Function    Makes the color display the active display

            Syntax      bool SYS_modeColor(void);

            Prototype   sysinfo.h
            in

            Remarks     In a system with two adapters installed (one
                        mono, one color) this routine sets the color
                        display to be the active display and returns
                        true. If only one display is present in the
                        system, it returns false.

            Return      True if color display is now active, false if
            value       only one adapter in system.

            See also    SYS_modeMono


            SYS_modeMono

            Function    Makes the monochrome display the active
                        display

            Syntax      bool SYS_modeMono(void);

            Prototype   sysinfo.h
            in

            Remarks     In a system with two adapters installed (one
                        mono, one color) this routine sets the
                        monochrome display to be the active display
                        and returns true. If only one display is
                        present in the system, it returns false.

            Return      True if monochrome display is now active,
            value       false if only one adapter in system.

            See also    SYS_modeColor


            SYS_screenLines

            Function    Determines the number of screen lines for
                        current video mode.

            Syntax      int SYS_screenLines(void);

            Prototype   sysinfo.h
            in





            36                             MegaToolbox Library Reference






            Remarks     Returns the number of screen lines for the
                        currently active video mode. This will
                        normally be 25, 43 or 50. Some VGA adapters
                        come with special software to set them into
                        high resolution text modes, so the value may
                        well be higher than this. Use this routine
                        and SYS_getScreenWidth to re-size your
                        applications to the display's real
                        resolution.

            Return      Number of screen lines for current video
            value       mode.

            See also    SYS_getScreenWidth


            SYS_screenWidth

            Function    Determines the screen width for the current
                        video mode.

            Syntax      int SYS_screenWidth(void);

            Prototype   sysinfo.h
            in

            Remarks     Returns the character width for the currently
                        active video mode. This will normally be 80.
                        Some VGA adapters come with special software
                        to set them into high resolution text modes,
                        so the value may well be higher than this.
                        Use this routine and SYS_getScreenLines to
                        re-size your applications to the display's
                        real resolution.

            Return      Screen width for current video mode.
            value

            See also    SYS_screenLines


            SYS_set25lines

            Function    Sets the display into 25 line mode.

            Syntax      bool SYS_set25lines(void);

            Prototype   sysinfo.h
            in

            Remarks     This function attempts to set the video
                        display into the normal 25 line video mode.
                        If the 25 line mode could not be properly
                        set, it returns false. Otherwise it returns
                        true.

            Return      True if 25 line mode set, false it not.
            value


            Chapter 5 - Sysinfo Library                               37







            See also    SYS_set43lines


            SYS_set43lines

            Function    Sets the display into the EGA/VGA 43 line
                        mode

            Syntax      bool SYS_set43lines

            Prototype   sysinfo.h
            in

            Remarks     This function attempts to set the video
                        display into the EGA/VGA 43 line mode if
                        possible. If the 43 line mode could not be
                        set, it returns false. Otherwise it returns
                        true. Note that on VGA systems, the number of
                        scanlines will be reduced to 350 to provide
                        exactly 43 lines of text.

            Return      True if 43 line mode set, false otherwise
            value

            See also    SYS_set25lines, SYS_set50lines


            SYS_set50lines

            Function    Sets the display into the VGA 50 line mode

            Syntax      bool SYS_set50lines

            Prototype   sysinfo.h
            in

            Remarks     This function attempts to set the video
                        display into the VGA 50 line mode if
                        possible. If the 50 line mode could not be
                        set, it returns false. Otherwise it returns
                        true. EGA adapters cannot support the 50 line
                        mode, so use SYS_set43lines for the EGA.

            Return      True if 50 line mode set, false otherwise
            value

            See also    SYS_set25lines, SYS_set43lines












            38                             MegaToolbox Library Reference






            SYS_setVideoMode

            Function    Sets a new video mode.

            Syntax      void SYS_setVideoMode(int mode);

            Prototype   sysinfo.h
            in

            Remarks     This routine should be used to set up a new
                        video mode. This routine will set the EGA/VGA
                        43/50 line mode if bit 15 of the passed video
                        mode number is set (and the video mode number
                        is mode number 3). Thus you can use this
                        routine to restore any video mode that was
                        saved with the SYS_getVideoMode routine.
                        This is the normal use for this routine.

                        You should use this routine to change video
                        modes if you want the information maintained
                        by the System Information module to remain
                        current. This routine is primarily designed
                        for working with text modes (consult a BIOS
                        programming reference for video mode
                        numbers).

            Return      None.
            value

            See also    SYS_getVideoMode






























            Chapter 5 - Sysinfo Library                               39









                                                         C H A P T E R
                                                                     6

                                                       Console Library

            This library provides a number of routines for
            interfacing to the video display in standard text mode.
            It provides the functionality of the standard C output
            routines, but can be configured to send the output to the
            display in any of the available colors, and the output
            can be mapped and clipped to any rectangular window on
            the screen. The routines are similar in operation to the
            set of console output routines provided with the Borland
            C++ and Turbo C++ range of compilers, but they are faster
            and more configurable.

            The console library comes in three basic flavours; direct
            video output, video BIOS output or auto-switching between
            both at runtime. Direct video output is much faster than
            using the video BIOS character output routines, but by
            using the video BIOS you are guaranteed (supposedly) to
            have the best compatability across computer systems. If
            you select either the direct video or video BIOS
            libraries at link time, the routines will be hardwired to
            provide the desired style of output. If you select the
            auto-switching library at link time, the value of the
            global variable "directvideo" (see below) is used to
            determine whether output should go direct to video ram,
            or through the video BIOS. Please refer to the "read.me"
            file in the distribution for the current library naming
            conventions to identify which library to link with your
            programs.

            In order to function correctly, the console library needs
            to call upon certain routines in the sysinfo library, so
            you will need to link in a version of the sysinfo library
            when you use the console library.

                                                      Global Variables

            The console library provides a number of global variables
            that can be changed at runtime to modify the way that
            they library output routines work. These global variables
            are defined in the "console.h" header file as:

                extern  bool    checksnow;
                extern  bool    checkCGAsnow;
                extern  bool    directvideo;
                extern  int     wrapmode;

            The checksnow variable is used by the low level direct
            video output routines to determine if snow checking
            should be performed. On the original CGA video adapter
            and some early clones, writing directly to the video
            display memory caused snow or fuzz to appear on the


            40                             MegaToolbox Library Reference






            display. To fix this problem, you need to ensure that
            data is only written during the vertical and horizontal
            screen retraces. This slows down the video output
            considerably, but it stops the snow on the screen (and is
            still faster than using the video BIOS).

            Most newer video adapter such as the EGA and VGA do not
            have this problem, so snow checking can be avoided. The
            console library automatically checks when it is
            initialised what sort of video adapter is installed,
            always turning snow checking off if a CGA adapter is not
            present. If a CGA adapter is present, the value of the
            checkCGAsnow variable is assigned to checksnow. Thus you
            should not change the value of checksnow directly (except
            for experimentation :-), but should allow the user to
            modify the setting of snow checking for CGA systems, as
            most new CGA clones do not have the snow problem.

            The directvideo flag is used by the auto-switching
            version of the library to determine whether output should
            be sent via the video BIOS, or direct to video memory.
            Naturally direct video is faster, but it can be useful to
            allow the user to turn on video BIOS output at runtime
            for compatability with multitasking systems such as
            Desqview and Windows. This flag is ignored in the direct
            video and video BIOS libraries.

            The wrapmode flag is used to set the way line wrapping
            occurs. The wrapmode flag is normally set to 1, which
            causes lines to wrap at the window boundary onto the next
            line, possibly causing the window to scroll if the last
            line of the window was being written. If you set wrapmode
            to 0, the line will wrap back to the start of the same
            line, and the window will not scroll. It can be useful to
            change the value of wrapmode when you wish to write to
            the bottom right hand character in a window without
            causing it to scroll (wrapmode only affects the formatted
            output routines like CON_printf, CON_puts etc).

            CON_clreol

            Function    Clears all text from the cursor to right edge
                        of window

            Syntax      void CON_clreol(void);

            Prototype   console.h
            in

            Remarks     This routine clears all text from the current
                        cursor location to the righthand edge of the
                        currently active window. The cleared area is
                        filled in with the current background
                        character and attribute.

            Return      None.
            value



            Chapter 6 - Console Library                               41






            CON_clrscr

            Function    Clears the current text window

            Syntax      void CON_clrscr(void);

            Prototype   console.h
            in

            Remarks     This routine clears the currently active text
                        window in the currently active background
                        character and attribute.

            Return      None.
            value


            CON_cursorOff

            Function    Hides the text cursor from view

            Syntax      void CON_cursorOff(void);

            Prototype   console.h
            in

            Return      None.
            value

            See also    CON_setCursor, CON_getCursor,
                        CON_restoreCursor


            CON_delline

            Function    Deletes the line that the text cursor is on.

            Syntax      void CON_delline(void);

            Prototype   console.h
            in

            Remarks     This routine deletes the entire line of text
                        that the cursor is on, and scrolls all lines
                        up one position to fill in the deleted space.
                        The last line of the window is filled with
                        the currently active background character and
                        attribute.

            Return      None.
            value

            See also    CON_insline







            42                             MegaToolbox Library Reference






            CON_fillAttr

            Function    Changes the attribute's for a block of text

            Syntax      void CON_fillAttr(int left,int top,int
                        right,int bottom,int attr);

            Prototype   console.h
            in

            Remarks     This routine changes the text attributes for
                        the block of text enclosed in the rectangle
                        defined by (left,top,right,bottom), setting
                        the attributes to 'attr'.

                        Note that this routine is relative to the
                        currently active window, but the output is
                        not clipped to the window's extents.

            Return      None.
            value

            See also    CON_fillText, CON_makeAttr


            CON_fillText

            Function    Fills a block of text with the specified
                        character and attribute

            Syntax      void CON_fillText(int left,int top,int
                        right,int bottom,int attr,int ch);

            Prototype   console.h
            in

            Remarks     This routine fills the block of text enclosed
                        in the rectangle defined by
                        (left,top,right,bottom) to the value of
                        'attr' and 'ch'.

                        Note that this routine is relative to the
                        currently active window, but the output is
                        not clipped to the window's extents.

            Return      None.
            value

            See also    CON_fillAttr, CON_makeAttr











            Chapter 6 - Console Library                               43






            CON_getActivePage

            Function    Returns the page currently receiving video
                        output

            Syntax      int CON_getActivePage(void);

            Prototype   console.h
            in

            Remarks     Returns the page number of the currently
                        active video page. The active video page is
                        the video page that all video output is sent
                        to. You may write output to an active video
                        page that is not currently visible.

            Return      Currently active video page number.
            value

            See also    CON_setVisualPage, CON_getVisualPage,
                        CON_setActivePage


            CON_getAttr

            Function    Returns the current foreground attribute

            Syntax      int CON_getAttr(void);

            Prototype   console.h
            in

            Remarks     This routine returns the currently active
                        foreground character attribute. The
                        foreground character attribute defines the
                        foreground and background color's for all
                        output routines that do not explicitly accept
                        an attribute as a parameter (CON_printf etc).

                        This routine is normally used to save the
                        current attribute value and restore it at a
                        later date.

            Return      Current foreground character attribute value.
            value

            See also    CON_setAttr, CON_setForeColor,
                        CON_setBackColor












            44                             MegaToolbox Library Reference






            CON_getBackground

            Function    Gets the background character and attribute

            Syntax      void CON_getBackground(int *attr,int *ch);

            Prototype   console.h
            in

            Remarks     This routine return the current background
                        character and attribute. The background
                        character and attribute are used to clear
                        parts of the window upon demand, such as
                        after scrolling.

            Return      None.
            value

            See also    CON_setBackground


            CON_getCursor

            Function    Returns the definition for the current text
                        cursor shape

            Syntax      int CON_getCursor(void);

            Prototype   console.h
            in

            Remarks     This routine returns the definition of the
                        currently active text cursor. It is normally
                        used to save the current state of the text
                        cursor, so that it can be restored at a later
                        date.

            Return      Current text cursor definition.
            value

            See also    CON_setCursor, CON_restoreCursor,
                        CON_cursorOff


            CON_getVisualPage

            Function    Returns the currently visible text page
                        number

            Syntax      int CON_getVisualPage(void);

            Prototype   console.h
            in

            Return      Currently visible text page number.
            value




            Chapter 6 - Console Library                               45






            See also    CON_setVisualPage, CON_setActivePage,
                        CON_getActivePage


            CON_getWindow

            Function    Gets the dimension of the currently active
                        text window

            Syntax      void CON_getWindow(int *left,int *top,int
                        *right,int *bottom);

            Prototype   console.h
            in

            Remarks     This routine returns the dimensions of the
                        currently active text window. It is normally
                        used to save the text window dimensions so
                        that it can be restored at a later date.

            Return      None.
            value

            See also    CON_setWindow


            CON_gotoxy

            Function    Moves the cursor to a new location

            Syntax      void CON_gotoxy(int x,int y);

            Prototype   console.h
            in

            Remarks     This routine is used to move the text cursor
                        to a new location on the screen. All
                        formatted output begins at the current cursor
                        location.

            Return      None.
            value

            See also    CON_wherex, CON_wherey


            CON_init

            Function    Initialises the console module

            Syntax      void CON_init(void);

            Prototype   console.h
            in






            46                             MegaToolbox Library Reference






            Remarks     This routine initialised the console module
                        routines and internal variables. It _MUST_ be
                        called before any of the console output
                        routines are used, and it should also be
                        called after a new video mode is selected.

            Return      None.
            value


            CON_insline

            Function    Inserts a blank line at the text cursor
                        location

            Syntax      void CON_insline(void);

            Prototype   console.h
            in

            Remarks     This routine is used to insert a blank line
                        at the text cursor location. The line is
                        filled with the current background character
                        and attribute, and the window is scrolled
                        down one line to make room.

            Return      None.
            value

            See also    CON_delline


            CON_makeAttr

            Function    Computes an attribute byte from two colors

            Syntax      char CON_makeAttr(int background,int
                        foreground);

            Prototype   console.h
            in



















            Chapter 6 - Console Library                               47






            Remarks     This is a macro that computes a text
                        attribute byte given a foreground and
                        background attribute value. The colors
                        available are defined in the "console.h"
                        header file as:

                        enum COLORS {
                            BLACK,
                            BLUE,
                            GREEN,
                            CYAN,
                            RED,
                            MAGENTA,
                            BROWN,
                            LIGHTGRAY,
                            DARKGRAY,
                            LIGHTBLUE,
                            LIGHTGREEN,
                            LIGHTCYAN,
                            LIGHTRED,
                            LIGHTMAGENTA,
                            YELLOW,
                            WHITE
                            };

                        Foreground colors may be any one of these,
                        but background colors can only be one of the
                        first 8, but may contain a blink bit. The
                        blink bit is bit 3 of the background color,
                        or you can set the blink bit for an attribute
                        value by using the definition:

                        #define BLINK   128

                        from the "console.h" header file. Thus you
                        could define a yellow on blue attribute that
                        is blinking as:

                            CON_makeAttr(BLUE,YELLOW) | BLINK

                        or

                            CON_makeAttr(BLUE | 4,YELLOW)

            Return      None.
            value

            See also    CON_setForeColor, CON_setBackColor












            48                             MegaToolbox Library Reference






            CON_maxx

            Function    Returns the current window's maximum X
                        coordinate

            Syntax      int CON_maxx(void);

            Prototype   console.h
            in

            Remarks     Since all text coordinates are relative to 0,
                        this value will be one less than the number
                        of columns for the current window. Thus for
                        an 80 column window, this routine will return
                        the value 79.

            Return      Maximum X coordinate for current window
            value

            See also    CON_maxy


            CON_maxy

            Function    Returns the current window's maximum Y
                        coordinate

            Syntax      int CON_maxy(void);

            Prototype   console.h
            in

            Remarks     Since all text coordinates are relative to 0,
                        this value will be one less than the number
                        of rows for the current window. Thus for a 25
                        row window, this routine will return the
                        value 24.

            Return      Maximum Y coordinate for current window
            value

            See also    CON_maxx


            CON_moveText

            Function    Moves a block of text on the screen

            Syntax      void CON_moveText(int left,int top,int
                        right,int bottom,int destleft,int desttop);

            Prototype   console.h
            in







            Chapter 6 - Console Library                               49






            Remarks     This routine is used to move a block of text
                        from one position on the screen to another.
                        This routine will work correctly even for
                        overlapping blocks of text. Normally this
                        routine is used to move windows around on the
                        screen, but it is also used by the console
                        routine internally to perform scrolling.

                        Note that this routine is relative to the
                        currently active window, but the output is
                        not clipped to the window's extents.

            Return      None.
            value

            See also    CON_saveText, CON_restoreText


            CON_printf

            Function    Writes formatted output to the console.

            Syntax      void CON_printf(char *format, ...);

            Prototype   console.h
            in

            Remarks     This routine works the same as the standard C
                        printf() routine, but it is mapped to the
                        current window and the text is displayed in
                        the current text color. The following are
                        valid format characters:

                          \f  Clear window and home cursor
                          \n  Advance a line, scrolling window if
                        necessary
                          \r  Move to left edge of window
                          \b  Move one character left (non-
                        destructive)

                        The text cursor is moved to the end of the
                        output string.

                        If the global variable wrapmode is set to 1,
                        the string will wrap at the edge of the
                        window and continue at the start of the next
                        line, possibly causing the window to scroll.
                        If wrapmode is set to 0, the string will wrap
                        to the start of the same line, and no
                        scrolling will be performed.

                        For information on the formatting characters
                        and the usual calling sequence for printf
                        style routines, refer to the documentation
                        that came with your compiler.

            Return      None.
            value


            50                             MegaToolbox Library Reference







            See also    CON_puts, CON_putc


            CON_putc

            Function    Outputs a single formatted character

            Syntax      void CON_putc(int c);

            Prototype   console.h
            in

            Remarks     This routine outputs a single formatted
                        character. The following are valid format
                        characters:

                          \f  Clear window and home cursor
                          \n  Advance a line, scrolling window if
                        necessary
                          \r  Move to left edge of window
                          \b  Move one character left (non-
                        destructive)

                        The text cursor is moved one to the right.

                        If the global variable wrapmode is set to 1,
                        the string will wrap at the edge of the
                        window and continue at the start of the next
                        line, possibly causing the window to scroll.
                        If wrapmode is set to 0, the string will wrap
                        to the start of the same line, and no
                        scrolling will be performed.

            Return      None.
            value

            See also    CON_puts, CON_printf


            CON_puts

            Function    Outputs a single formatted string

            Syntax      void CON_puts(char *str);

            Prototype   console.h
            in












            Chapter 6 - Console Library                               51






            Remarks     This routine works the same as the standard C
                        puts() routine, but it is mapped to the
                        current window and the text is displayed in
                        the current text color. The following are
                        valid format characters:

                          \f  Clear window and home cursor
                          \n  Advance a line, scrolling window if
                        necessary
                          \r  Move to left edge of window
                          \b  Move one character left (non-
                        destructive)

                        The text cursor is moved to the end of the
                        output string.

                        If the global variable wrapmode is set to 1,
                        the string will wrap at the edge of the
                        window and continue at the start of the next
                        line, possibly causing the window to scroll.
                        If wrapmode is set to 0, the string will wrap
                        to the start of the same line, and no
                        scrolling will be performed.

            Return      None.
            value

            See also    CON_putc, CON_printf


            CON_restoreCursor

            Function    Restore the text cursor to a previous state

            Syntax      void CON_restoreCursor(int scans);

            Prototype   console.h
            in

            Remarks     This routine restores the text cursor to a
                        previously state that was saved by calling
                        CON_getCursor.

            Return      None.
            value

            See also    CON_getCursor, CON_cursorOff, CON_setCursor













            52                             MegaToolbox Library Reference






            CON_restoreText

            Function    Restores a block of text saved with
                        CON_saveText

            Syntax      void CON_restoreText(int left,int top,int
                        right,int bottom,void *source);

            Prototype   console.h
            in

            Remarks     This routine is used to restore a block of
                        text previously saved with a call to
                        CON_saveText. The block of text does not need
                        to be sent to the same location on screen,
                        but should be the same dimensions. This
                        routine is normally used to restore the text
                        under pop-up windows and menus.

                        Note that this routine is relative to the
                        currently active window, but the output is
                        not clipped to the window's extents.

            Return      None.
            value

            See also    CON_saveText, CON_moveText


            CON_saveText

            Function    Saves a block of text into a buffer in
                        memory.

            Syntax      void CON_saveText(int left,int top,int
                        right,int bottom,void *destin);

            Prototype   console.h
            in

            Remarks     This routine is used to save a block of text
                        that can be later restored with a call to
                        CON_restoreText. This routine is normally
                        used to save the text under pop-up windows
                        and menus.

                        The buffer must be pre-allocated before you
                        call CON_saveText. To compute the size of the
                        buffer, use the following equation:

                            size = (cols * rows * 2).

                        Note that this routine is relative to the
                        currently active window, but the output is
                        not clipped to the window's extents.

            Return      None.
            value


            Chapter 6 - Console Library                               53







            See also    CON_restoreText, CON_moveText


            CON_scroll

            Function    Scrolls the current window

            Syntax      void CON_scroll(int direction,int amt);

            Prototype   console.h
            in

            Remarks     This routine scrolls the current window in
                        the specified direction by the specified
                        number of lines. The direction should be one
                        of the following values defined in the
                        "console.h" header file:

                        #define SCROLL_UP       1
                        #define SCROLL_DOWN     2
                        #define SCROLL_LEFT     3
                        #define SCROLL_RIGHT    4

            Return      None.
            value


            CON_setActivePage

            Function    Sets the active video page

            Syntax      void CON_setActivePage(int page);

            Prototype   console.h
            in

            Remarks     This routine sets the active video page to a
                        new number. The active video page is the page
                        that all output is sent to. The active video
                        page need not be visible.

            Return      None.
            value

            See also    CON_getActivePage, CON_setVisualPage,
                        CON_getVisualPage


            CON_setAttr

            Function    Sets the new foreground character attribute

            Syntax      void CON_setAttr(int attr);

            Prototype   console.h
            in



            54                             MegaToolbox Library Reference






            Remarks     This routine sets the foreground character
                        attribute. The foreground character attribute
                        defines the foreground color and background
                        color for all text output routines that do no
                        explicitly accept an attribute value
                        (CON_printf etc). You can create a valid
                        attribute by using CON_makeAttr.

            Return      None.
            value

            See also    CON_makeAttr, CON_getAttr


            CON_setBackground

            Function    Sets the background character and attribute

            Syntax      void CON_setBackground(int attr,int ch);

            Prototype   console.h
            in

            Remarks     This routine sets the current background
                        character and attribute. The background
                        character and attribute are used to clear
                        parts of the window upon demand, such as
                        after scrolling.

            Return      None.
            value

            See also    CON_getBackground


            CON_setBackColor

            Function    Sets the background color for the foreground
                        character attribute

            Syntax      void CON_setBackColor(int newcolor);

            Prototype   console.h
            in

            Remarks     This routine sets the background color value
                        for the foreground character attribute to the
                        value of 'newcolor'. The foreground character
                        attribute defines the foreground color and
                        background color for all text output routines
                        that do no explicitly accept an attribute
                        value (CON_printf etc).

            Return      None.
            value

            See also    CON_setAttr, CON_getAttr, CON_setForeColor



            Chapter 6 - Console Library                               55






            CON_setCursor

            Function    Sets the cursor to a pre-defined style

            Syntax      void CON_setCursor(int type);

            Prototype   console.h
            in

            Remarks     This routine is used to set the cursor to
                        pre-defined style. Two styles are defined in
                        the "console.h" header file. These are:

                        #define CURSOR_NORMAL   1
                        #define CURSOR_FULL     2

                        The CURSOR_NORMAL cursor is a single
                        underline bar that is the default cursor upon
                        program startup. The CURSOR_FULL cursor is a
                        full character block cursor.

            Return      None.
            value

            See also    CON_getCursor, CON_restoreCursor,
                        CON_cursorOff


            CON_setForeColor

            Function    Sets the foreground color for the foreground
                        character attribute

            Syntax      void CON_setForeColor(int newcolor);

            Prototype   console.h
            in

            Remarks     This routine sets the foreground color value
                        for the foreground character attribute to the
                        value of 'newcolor'. The foreground character
                        attribute defines the foreground color and
                        background color for all text output routines
                        that do no explicitly accept an attribute
                        value (CON_printf etc).

            Return      None.
            value

            See also    CON_setAttr, CON_getAttr, CON_setBackColor










            56                             MegaToolbox Library Reference






            CON_setVisualPage

            Function    Sets the currently visible text page

            Syntax      void CON_setVisualPage(int page);

            Prototype   console.h
            in

            Remarks     This routine is used to change the currently
                        visible text display page. You can use this
                        routine to instantly display a page of text
                        that was created offscreen.

            Return      None.
            value

            See also    CON_getVisualPage, CON_setActivePage,
                        CON_getActivePage


            CON_setWindow

            Function    Sets the dimensions of the current text
                        window

            Syntax      void CON_setWindow(int left,int top,int
                        right,int bottom);

            Prototype   console.h
            in

            Remarks     This routine is used to change the dimensions
                        and location of the current text window to
                        another location on the screen. All output is
                        mapped into this window, and most output
                        (except block text routines) are clipped to
                        fit inside this window.

            Return      None.
            value

            See also    CON_getWindow


            CON_wherex

            Function    Returns the X coordinate of the text cursor

            Syntax      int CON_wherex(void);

            Prototype   console.h
            in

            Remarks     This function returns the current X location
                        of the text cursor within the current text
                        window.



            Chapter 6 - Console Library                               57






            Return      Current X coordinate of the text cursor
            value       within current window.

            See also    CON_gotoxy, CON_wherey


            CON_wherey

            Function    Returns the Y coordinate of the text cursor

            Syntax      int CON_wherey(void);

            Prototype   console.h
            in

            Remarks     This function returns the current Y location
                        of the text cursor within the current text
                        window.

            Return      Current Y coordinate of the text cursor
            value       within the current window.

            See also    CON_gotoxy, CON_wherex


            CON_write

            Function    Writes a string to the current window

            Syntax      void CON_write(int x,int y,int attr,char
                        *str);

            Prototype   console.h
            in

            Remarks     This routine writes a string to the current
                        window starting at the location (x,y) in the
                        specified attribute. The string is clipped to
                        the bounds of the window so it can never
                        exceed the maximum window width in length.

                        This routine does no formatting, so it is the
                        fastest method to write characters directly
                        to the display for drawing menus, windows
                        etc.

            Return      None.
            value

            See also    CON_writec










            58                             MegaToolbox Library Reference






            CON_writec

            Function    Writes a single character to the current
                        window

            Syntax      void CON_writec(int x,int y,int attr,int c);

            Prototype   console.h
            in

            Remarks     This routine writes a single character and
                        attribute to the current window. The
                        character is clipped to the bounds of the
                        window, so it cannot appear outside of the
                        window boundary.

                        This routine does no formatting, so it is the
                        fastest way to write a single character to
                        the display.

            Return      None.
            value

            See also    CON_write




































            Chapter 6 - Console Library                               59










                                                C  O  N  T  E  N  T  S



            Chapter 1 - Introduction ................................1

            Chapter 2 - Library reference ...........................3
                 How to use reference entries .......................4

            Chapter 3 - Mouse Library ...............................5
                 MS_constrain .......................................5
                 MS_dblSpeed ........................................5
                 MS_exit ............................................6
                 MS_getCrtPage ......................................6
                 MS_hide ............................................6
                 MS_init ............................................7
                 MS_motion ..........................................7
                 MS_moveTo ..........................................7
                 MS_pos .............................................8
                 MS_pressed .........................................8
                 MS_released ........................................9
                 MS_restoreState ...................................10
                 MS_saveState ......................................10
                 MS_setCrtPage .....................................10
                 MS_setCursor ......................................11
                 MS_setTextCursor ..................................11
                 MS_show ...........................................12
                 MS_softReset ......................................12
                 MS_speed ..........................................13
                 MS_stateSize ......................................13
                 MS_swapIntSub .....................................13

            Chapter 4 - Event Library ..............................15
                 EVT_asciiCode .....................................15
                 EVT_delay .........................................15
                 EVT_flush .........................................16
                 EVT_getNext .......................................16
                 EVT_halt ..........................................18
                 EVT_init ..........................................19
                 EVT_mouseMove .....................................19
                 EVT_peekNext ......................................19
                 EVT_post ..........................................20
                 EVT_scanCode ......................................20
                 EVT_setTimerTick ..................................21

            Chapter 5 - Sysinfo Library ............................23
                 SYS_biosClass .....................................23
                 SYS_cpu ...........................................24
                 SYS_extKeyboard ...................................24
                 SYS_fpu ...........................................24
                 SYS_getSubSys .....................................25
                 SYS_getVideoMode ..................................26
                 SYS_modeColor .....................................26
                 SYS_modeMono ......................................27
                 SYS_screenLines ...................................27


            Chapter 6 - Console Library                                i






                 SYS_screenWidth ...................................27
                 SYS_set25lines ....................................28
                 SYS_set43lines ....................................28
                 SYS_set50lines ....................................28
                 SYS_setVideoMode ..................................29

            Chapter 6 - Console Library ............................30
                 Global Variables ..................................30
                 CON_clreol ........................................31
                 CON_clrscr ........................................31
                 CON_cursorOff .....................................31
                 CON_delline .......................................32
                 CON_fillAttr ......................................32
                 CON_fillText ......................................32
                 CON_getActivePage .................................33
                 CON_getAttr .......................................33
                 CON_getBackground .................................33
                 CON_getCursor .....................................34
                 CON_getVisualPage .................................34
                 CON_getWindow .....................................34
                 CON_gotoxy ........................................34
                 CON_init ..........................................35
                 CON_insline .......................................35
                 CON_makeAttr ......................................35
                 CON_maxx ..........................................36
                 CON_maxy ..........................................37
                 CON_moveText ......................................37
                 CON_printf ........................................37
                 CON_putc ..........................................38
                 CON_puts ..........................................39
                 CON_restoreCursor .................................39
                 CON_restoreText ...................................39
                 CON_saveText ......................................40
                 CON_scroll ........................................40
                 CON_setActivePage .................................41
                 CON_setAttr .......................................41
                 CON_setBackground .................................41
                 CON_setBackColor ..................................41
                 CON_setCursor .....................................42
                 CON_setForeColor ..................................42
                 CON_setVisualPage .................................42
                 CON_setWindow .....................................43
                 CON_wherex ........................................43
                 CON_wherey ........................................43
                 CON_write .........................................44
                 CON_writec ........................................44














            ii                             MegaToolbox Library Reference
