WINBGIM: Borland BGI Graphics & Mouse for Windows

The WINBGIM Library -- Version 6.0 -- August 9, 2004
Borland BGI Graphics and Mouse
For Windows Applications

The winbgim library allows you to use BGI graphics routines and simple mouse support for Windows applications that you write with CS1300's mingw32 gnu C++ compiler or with the Borland C++ compiler (version 5.02). It will probably work with other Windows compilers, too, but I haven't tried it.

The library originates from Konstantin Knizhnik's winbgi shareware. I spent some time adding a new initwindow function (to allow the graphics window to be initially opened at any size) and three new functions to allow simple mouse-driven processing. Mark Richardson then added some new functions to allow more than sixteen colors.

You are welcome to use and modify this library as you like. Let me know if you make interesting modifications.

How to use the winbgim library for the free mingw32 gnu C++ compiler

Download and install the free cs1300 tools, as described in www.cs.colorado.edu/~main/cs1300/README.html.
The header file: Change to the cs1300\include subdirectory and check whether you have the file graphics.h. If not, then download this file into that directory by holding down the left-shift key and clicking on this link: www.cs.colorado.edu/~main/cs1300/include/graphics.h.
The archieved library file: Change to the cs1300\lib subdirectory and check whether you have the file libbgi.a. If not, then download this file into that directory by holding down the left-shift key and clicking on this link: www.cs.colorado.edu/~main/cs1300/lib/libbgi.a.
Write your program as you normally would, using the BGI graphics functions. Be sure to include graphics.h.
When you create an executable (exe) program that uses the winbgim library, you must add the six options -lbgi -lgdi32 -lcomdlg32 -luuid -loleaut32 -lole32 (in that order) after any other file arguments to the compiler. For example, to compile the bgidemo0.cpp program you would give the compile command:
```
g++ bgidemo0.cpp -lbgi -lgdi32 -lcomdlg32 -luuid -loleaut32 -lole32 -o bgidemo0.exe
```
Note that each of these library options begins with the letter l (not the number one).
If you are working with the CS1300 version of the g++ compiler (from www.cs.colorado.edu/~main/cs1300/README.html), then you can get all these libraries automatically by using the bgi++ command instead of g++. For example:
```
bgi++ bgidemo0.cpp -o bgidemo0.exe
```
This command creates an executable file called bgidemo0.exe. Note that when it runs, it creates a small graphics window where all the bgi operations are performed. Any text i/o with cin and cout will be done in the other (console) window.

Graphics Stuff in the Library

Usual BGI Stuff: You can use any of the Borland BGI graphics functions.

Initialization: Normally, you initialize the BGI graphics by a call to detectgraph and a call to initgraph. You can still use those two function calls, or you may call a new function named initwindow. The function has two arguments that are the size of the graphics window that you want to create in pixels (width and height). For example, you can create a window that is 450 pixels wide and 300 pixels high with the statement:

initwindow(450, 450);

RGB Colors: The winbgim package supports two types of colors that may be used with any of the functions that expect colors as arguments:

The sixteen ordinary BGI colors. These are the integers 0 through 15 or you may use the symbolic names:

     BLACK          BLUE          GREEN         CYAN
     RED            MAGENTA       BROWN         LIGHTGRAY
     DARKGRAY       LIGHTBLUE     LIGHTGREEN    LIGHTCYAN
     LIGHTRED       LIGHTMAGENTA  YELLOW        WHITE

A color may be specified from red, green and blue components using a new macro called COLOR(r,g,b). Each of the r,g,b arguments must be a number in the range 0 to 255. For example, COLOR(255,100,0) is a mostly red color with some green and no blue. If you create one of these colors, it may be used as an argument to any of the BGI functions that expect a color. These colors may also be returned from BGI functions such as getbkcolor.

Three other macros (RED_VALUE, GREEN_VALUE, BLUE_VALUE, IS_BGI_COLOR and IS_RGB_COLOR) are explained in the examples below.

RGB Examples:

    setcolor(BLUE);             // Change drawing color to BLUE.
    setcolor(COLOR(255,100,0);  // Change drawing color to reddish-green.
    setpalette(4, BLUE);        // Change palette entry 4 to BLUE.
    setpalette(4, COLOR(9,9,9));// Change palette entry 4 to nearly black.
     
    int current = getcolor( );  // Set current to current drawing color.

    if (IS_BGI_COLOR(current))  // Check whether it is a BGI color.
       cout << "Current BGI drawing color is: " << current << end;

    if (IS_RGB_COLOR(current))  // Check whether it is an RGB color.
       cout << "Current RGB drawing color has these components:\n"
            << "Red:   " << RED_VALUE(current)   << '\n'
            << "Green: " << GREEN_VALUE(current) << '\n'
            << "Blue:  " << BLUE_VALUE(current)  << '\n'

int getdisplaycolor(int color): The actual color placed on the screen with putpixel might not be this exact rgb color that you want because of video mode limitations. The return value of this function tells you what actual color will be put on the screen for a requested color.

Mouse Stuff in the Library

There are three functions to use the mouse:

int mousex( )
int mousey( )
These return the current x and y coordinates of the mouse. If the mouse has never been in the graphics window, then both coordinates are zero. If the mouse used to be in the window, but now it has gone elsewhere, then the coordinates are the last known position within the window.
bool ismouseclick(kind) This function returns true if there is an unprocessed mouse event of the specified kind. The argument to ismouseclick is one of these constants from the winbgim.h file:

WM_MOUSEMOVE
if you want to detect a mouse movement
WM_LBUTTONDBLCLK
...detect when the left mouse button is double clicked
WM_LBUTTONDOWN
...detect when the left mouse button is clicked down
WM_LBUTTONUP
...detect when the left mouse button is released up
WM_MBUTTONDBLCLK
...detect when the middle mouse button is double clicked
WM_MBUTTONDOWN
...detect when the middle mouse button is clicked down
WM_MBUTTONUP
...detect when the middle mouse button is released up
WM_RBUTTONDBLCLK
...detect when the right mouse button is double clicked
WM_RBUTTONDOWN
...detect when the right mouse button is clicked down
WM_RBUTTONUP
...detect when the right mouse button is released up

The middle mouse button handlers aren't working on my machine. I haven't yet tracked down the reason--it could be a broken mouse or it could be a bug in my programming.
A mouse event can be processed by calling getmouseclick (which gets the coordinates of the event), or by calling clearmouseclick (which processes the event without providing its coordinates). These two functions are described below.
void getmouseclick(kind, int& xint& y) This function sets x and y to the pixel coordinates of an unprocessed event of the specified kind. If there is no such event, then the function sets both x and y to -1. The value of the argument kind may be any of the constants listed above. After calling getmouseclick, for a particular kind of event, the ismouseclick will return false for that kind of event until another such event occurs.
void clearmouseclick(kind) This is just like getmouseclick, except it does not provide the x and y coordinates of the event. The value of the argument kind may be any of the constants listed above. After calling clearmouseclick, for a particular kind of event, the ismouseclick will return false for that kind of event until another such event occurs.
void registermousehandler(kind, h) Most mouse processing can be carried out with the ismouseclick and getmouseclick. But sometimes you need more control. In general, you can obtain more control by writing a different "handler function" to handle each different kind of mouse event, and you "register" each of your handlers by calling registermousehandler. The first argument to registermousehandler is one of the constants listed above. The second argument to registermousehandler must be the name of the handler function that you wrote. This function must be a void function with two int parameters. Whenever the specified mouse event occurs, your handler will be called and the two int parameters will be the x and y positions where the event happened.

A Mouse Example with `ismouseclick` and `getmouseclick`

Suppose that you want a program to wait for a left mouse click. Then the program should print the x and y coordinates of the most recent left click. Here's a function to accomplish that:

void wait_for_left_click( )
{
    const int DELAY = 50; // Milliseconds of delay between checks
    int x, y;

    while (!ismouseclick(WM_LBUTTONDOWN))
        delay(DELAY);
    getmouseclick(WM_LBUTTONDOWN, x, y);
    cout << "Latest left click at: " << x << " " << y << endl;
}

A Mouse Example with a Handler

Suppose that whenever the right mouse button is clicked you want to print a message with the x and y coordinates of the click. Then you would start by writing your handler function, perhaps like this:

void my_right_click_handler(int x, int y)
{
    cout << "Right mouse click at " 
         << x << " and " << y << endl;
}

Now, somewhere in your program (after you've initialized the graphics window), you must register this fine handler with the statement:

registermousehandler(WM_RBUTTONDOWN, my_right_click_handler);

In general, the work carried out in a handler must be small. If you need to do a lot of work, have the handler change a global variable that will later trigger the large work. Then the handler can return quickly.

Keyboard Stuff in the Library

There are three functions that were originally part of Borland's conio.h. These functions are now in winbgim.h, and you do not need to include conio.h to use them::

void delay(int millisec)
int getch( )
int kbhit( )
The first function delays the compuation for the specified number of milliseconds.
The getch function gets a character from the keyboard without waiting for any key. In order to use getch, the graphics window must be active (by clicking in it or clicking on its title bar). The actual return value from getch is usually the ASCII value of the key that was pressed, so if you want to store this into a character, you need: c = (char) getch( ); If you press one of the keypad keys (arrows, Home, etc.), then getch first returns the value 0. Then, at the next call, it will KEY_HOME KEY_UP KEY_PGUP KEY_LEFT KEY_CENTER KEY_RIGHT KEY_END KEY_DOWN KEY_PGDN KEY_INSERT KEY_DELETE
The kbhit function returns 0 if there are no characters now waiting to be read (with getch). It returns a non-zero if there are some characters waiting to be read.

Double-Buffering Support

I added two functions, getactivepage() and getvisualpage() to help support double-buffering. They return the page number of the active page (where drawing is currently taking place) and the visual page (the one on the screen). The original winbgi was designed to support up to 16 pages, but I have only used pages 1 and 2 myself. NOTE: Using page number 0 might mess up the colors. I use pages 1-2 for double buffering.

Support for Writing to the Graphics Screen

I added an outputstream, bgiout. It's used is described in bgiout.html.

Support for Printing, Reading and Writing Images

The graphics window now has a print option in the windows menu button, so the user can print the screen at any time. In additon, there are these new functions:

Support for Multiple Windows

The initiwindow function can now be called multiple times to create more than one graphics window. The initwindow documentation describes how these multiple windows are used.

Other Relevant Files

Winbgim functions documentation.
Konstantin Knizhnik's original documentation.
The graphics.h header file.
The source code.
Sample programs: bgidemo0.cpp (extensive program), bgidemo1.cpp (shows registermousehandler), bgidemo2.cpp (shows COLOR macro), bgidemo3.cpp (shows COLOR again), bgidemo4.cpp (shows getmouseclick) that use the winbgim library.
A sample program testget.cpp that uses getch and also shows how to print numbers in graphics mode.
Double-buffering Example dblbuff.cpp.

Writing Windows Programs

You may have noticed that any program that's compiled with g++ or bgi++ will always open a DOS command window when the program is run. If you want to stop this window from opening, then add the option -mwindows to the compile line (just after g++ or bgi++).

WINBGIM Version 6.0 Posted August 9, 2004

Michael Main (email main@colorado.edu)

The WINBGIM Library -- Version 6.0 -- August 9, 2004 Borland BGI Graphics and Mouse For Windows Applications