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

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

1. Download and install the free cs1300 tools, as described in www.cs.colorado.edu/~main/cs1300/README.html.

2. 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.

3. 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.

4. Write your program as you normally would, using the BGI graphics functions. Be sure to include graphics.h.

5. 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

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:

1. 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
   

2. 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

• 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

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

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

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

• 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

Support for Writing to the Graphics Screen

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:

• getimage
• imagesize
• printimage
• putimage
• readimagefile
• writeimagefile

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++).