Chess User Interface With GTK 2.0

Modified 6-29-2004 by Brian Sanderson

Project Files

The following list contains a short description of these files, as well as links to them for convenient online viewing. You will need to download the tar file in order to get all of the necessary files.

File	Description
chessgui.h chessgui.cpp	The chessgui files provide the Graphical User Interface; you probably will not have to edit these files.
chess.h chess.cpp	This is the GUI frontend that you will modify. It contains functions to access the GUI such as placing pieces, highlighting squares, dealing with user mouse clicks, etc.
chessinclude.h	The chessinclude file gives you constants that will be useful to allow you to access the image files and colors used by the ChessGui.
messagebox.h messagebox.cpp inputbox.h inputbox.cpp buttonbox.h buttonbox.cpp	Messagebox, inputbox, and buttonbox classes provide support for various simple dialog boxes. These functions are invoked using the Chess::messagebox, Chess::inputbox, and Chess::buttonbox functions.
makefile	This example makefile has been included which will compile all the files provided. Please look through the makefile.
chess.tgz	A compressed tar file containing all the above files. You will need to download this file into your chess project directory and extract it.

You will note that all the commands to the compiler which compile files that access the GUI have the following code after them:

`pkg-config gtkmm-2.0 --cflags` -Iimages

You will also note that the line in the makefile which creates the executable has the following options:

`pkg-config gtkmm-2.0 --libs`

This is essential to load the graphics libraries required. An example command to compile the Chess class would be:

g++ -c chess.cpp `pkg-config gtkmm-2.0 --cflags` -Iimages

The Graphical User Interface

As you can see, the interface is divided into 5 main sections:

The Chess Board: This provides 64 squares for chess pieces. Each square can be indexed by column, row co-ordinates.
The Buttons: New Game, Load Game, Save Game, Undo Move
The Text Area: Allows you to display a history of all the moves in the game.
The Text Box: Used for entering the filename of the game to load and save.
The Labels: These are at the top and bottom of the board and can be used to display appropriate messages about the state of the game.

Event-driven functions

The Chess class provides several event functions that allow you to get input from the user interface. These functions are event-driven, meaning that they are called only when the event happens. These functions are found in the chess.cpp file and you should change these functions to suit your design:

void on_mouse_button_released(int c, int r, int button);
This function will be called whenever a user clicks and releases a mouse button on a square of the chess board. c represents the column and r the row of the square on the board and button is which mouse button was clicked (1 for left, 2 for middle, 3 for right, 4 for mouse wheel up, 5 for mouse wheel down).
void on_button_clicked(int which_button);
This function will be called whenever a user clicks a button on the user interface. The parameter which_button will be 0 for the New Game button, 1 for the Load button, 2 for the Save button and 3 for the Undo button.
int on_delete_event();
This function gets called when the user closes the User Interface. It deletes all objects created.

GUI Convenience functions

In addition to the event functions the Chess class also has some useful functions that you can call that are convenience functions from the chessgui.cpp file.

void top_label_set_text(const char *text);
This function sets the label at the top of the board.
void bottom_label_set_text(const char *text);
This function sets the label at the bottom of the board.
void info_area_clear();
This function clears the information area of the UI.
void info_area_put_text(const char *text);
This function adds the text into the information area of the UI.
void input_box_clear();
This function clears the input box of the UI.
const char *input_box_get_text();
This function returns the information that is in the input box.

Piece and square manipulation functions

Several new piece and square convenience functions have been provided in the Chess class to reduce the difficulty of dealing with the lower level GUI functions:

void place_piece(int c, int r, int piece);
This function places a piece on the board at row r and column c. piece is an int cooresponding to which piece to place on the board. A list of these values can be found in the chess.h include file.
void clear_piece(int c, int r);
This function clears a piece on the board at row r and column c.
void highlight_square(int c, int r, int color);
This function places a highlight on a given square at row r and column c. color is the color to set the tile to. It is a hexidecimal number with the format 0xRRGGBB. (Note: BLUE_SQUARE defined in chessinclude.h is a good color to use).
void unhighlight_square(int c, int r);
This function removes a highlight from a given square.

Dialog box functions

Some other functions have been provided for you in the chess.h and chess.cpp files. They give you easy access to three kinds of dialog box:

int message_box(const char *title, const char *message, int box_type=MB_OK_BOX);
This function opens a message box and returns the index of the button pushed. The return value is 1-based, so if the first button is clicked, 1 will be returned. Valid types of box are: MB_OK_BOX, MB_OK_CANCEL_BOX and MB_YESNO_BOX. If the return value is 0, the user has clicked the close button in the top right hand corner of the dialog box rather than pushing on of the buttons provided.
const char *input_box(const char *title, const char *message, const char* label);
This function opens a dialog that allows a user to input text. It returns the text that they enter in the dialog.
int button_box(const char *title, const char *message, const char **button_labels, int num_buttons);
This function opens a message box with user definable buttons (the labels of the buttons are taken from the array button_labels) and returns the index of the button pushed. The return value is 1-based, so if the first button is clicked, 1 will be returned. If the return value is 0, the user has clicked the close button in the top right hand corner of the dialog box rather than pushing on of the buttons provided.

These are the primary functions that you will need for interacting with the User Interface. There are other functions provided by the User Interface (for example, for supporting drag-and-drop movement of game pieces), however, you are not required to use them (although you are welcome to do so if you so desire).