Main Page | Namespace List | Class Hierarchy | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages
GUI Tutorial.dox

Graphic User Interface Tutorial

Contents

Introduction

This section of the manual is dedicated to the creation of GUI's for games. As a tutorial, we will build the GUI for Tic-Tac-Toe.

GUI Controller Base Class

The GUI Controller Base Class provides an easy method to create the GUI for your game. It handles most of processing, event posting, and network connections needed. The CGUIController class provides some pure virtual functions which you will need to override in your derived classes.

Ex.










virtual void NewGame()=0;
Figure 1.1

This function is called when the CGUIController Base Class is told that a new game is being started by the game module. You will need to provide an implementation of this function and preform any initialization necessary for your game GUI.

Writing Your Controller Header File

We can now begin writing the Tic-Tac-Toe GUI. The CTicTacToeController class will be derived from the CGUIController. Following is the code for the CTicTacToeController.h.

#include "Caffeine.h"
#include "GUIController.h"
#include "TicTacToe.h"
#include "TicTacToeBoard.h"

class CTicTacToeController : public CGUIController
{
 Q_OBJECT 

public: //Public Member Functions

 //Non Caffeine Constructor
 CTicTacToeController(QWidget* target);
 //Caffeine Constructor
 CTicTacToeController(QWidget* target,
               uint32 studentID, const int8* name, uint32 nameLength,
               CaffeineGUID gameID,
        bool bIsSpectator=false);

 ~CTicTacToeController();

public slots:
 bool PieceClicked(uint32, uint32);
 void PieceTypeChanged(uint32, uint32, CTicTacToePiece::TYPE);

protected: //Protected Member Functions
 void NewGame();
 void Play(const CPiece*) { }
 void PlayMove(const CMove* m);
 bool CheckMove(CMove* m);
 bool CheckForWin();
 void UpdateCurrentPlayerPiece();
 void SetPlayerPiece(const CPiece* p);
 void TimeElapsed(const CPlayerPiece* piece);

 bool CheckForPieceWin(CTicTacToePiece p) const;

private: //Private Member Variables

 CTicTacToeBoard  m_board;
 CTicTacToePiece  m_playerPiece;

 struct PLAYERINFO
 {
  CEID            s_id;
  CTicTacToePiece s_piece;
 };

 PLAYERINFO m_playerList[2];
};
Figure 2.1

The first thing to do is include the necessary header files. In the case of GUIs the includes will most likely be Caffeine.h, GUIController.h, and the game header file. The Caffeine.h header file contains some important structures in the Caffeine Framework as well as the cross-platform typedefs for data types. It is best to use these type instead of the built-in types to insure that they are the proper size (Eg. use int32 instead of int and uin32 instead of unsigned int.)

Lets take a closer look at the class definition.

#include "Caffeine.h"
#include "GUIController.h"
#include "TicTacToe.h"
#include "TicTacToeBoard.h"

class CTicTacToeController : public CGUIController
{
 Q_OBJECT 

public: //Public Member Functions

 //Non Caffeine Constructor
 CTicTacToeController(QWidget* target);
 //Caffeine Constructor
 CTicTacToeController(QWidget* target,
                   uint32 studentID, const int8* name, uint32 nameLength,
                   CaffeineGUID gameID,
             bool bIsSpectator=false);

 ~CTicTacToeController();
Figure 2.2

Most of this should look familiar to you. The only new piece is the Q_OBJECT line. Please refer to the QT manuals for more information about this. The class contains two constructors, one which is called when the GUI is being used as a standalone (i.e. two human players on one GUI) and the other is called when using the the GUI along with the Caffeine Framework, as in a tournament setting.

protected: //Protected Member Functions
 void NewGame();
 void Play(const CPiece*) { }
 void PlayMove(const CMove* m);
 bool CheckMove(CMove* m);
 bool CheckForWin();
 void UpdateCurrentPlayerPiece();
 void SetPlayerPiece(const CPiece* p);
 void TimeElapsed(const CPlayerPiece* piece);

 bool CheckForPieceWin(CTicTacToePiece p) const;
Figure 2.3

The above functions are all protected members of the class. All of these are pure virtual functions of the CGUIController Base Class. Implementations for these functions will need to be provided in your derived class. These functions are called by the base class as directed by the messages recieved from the game module.

private: //Private Member Variables

 CTicTacToeBoard  m_board;
 CTicTacToePiece  m_playerPiece;

 struct PLAYERINFO
 {
  CEID            s_id;
  CTicTacToePiece s_piece;
 };

 PLAYERINFO m_playerList[2];
Figure 2.4

These last lines of code are the Tic-Tac-Toe specific member variables and functions. These will be game dependant. In this case they are a m_board variable of type CTicTacToeBoard, which is used to represent a Tic-Tac-Toe board, and a CTicTacToePiece, m_playerPiece, which represents the piece this player is using.

Writing Your Controller Implementation

Lets move on to the implementation of the CTicTacToeController class.

CTicTacToeController::CTicTacToeController(QWidget* target)
: CGUIController(target)
{
 if(!IsUsingCaffeine())
 {
  CEID p1, p2;
  p1.s_playerType = PLAYER_TYPE_HUMAN;
  p1.s_randNum    = 1;
  p1.s_stuID      = 1;
  p1.s_gameID     = TICTACTOE_GAME_GUID;
  p1.s_version    = TICTACTOE_GAME_VERSION;

  p2.s_playerType = PLAYER_TYPE_HUMAN;
  p2.s_randNum    = 2;
  p2.s_stuID      = 2;
  p2.s_gameID     = TICTACTOE_GAME_GUID;
  p2.s_version    = TICTACTOE_GAME_VERSION;

  AddPlayer(p1);
  AddPlayer(p2);

  m_playerList[0].s_id = p1;
  m_playerList[0].s_piece.SetType(CTicTacToePiece::X);
  m_playerList[1].s_id = p2;
  m_playerList[1].s_piece.SetType(CTicTacToePiece::O);
 }

 connect(&m_board, SIGNAL(PieceTypeChanged(uint32,uint32,CTicTacToePiece::TYPE)),
      this, SLOT(PieceTypeChanged(uint32,uint32,CTicTacToePiece::TYPE)));
}

CTicTacToeController::CTicTacToeController(QWidget* target,
                 uint32 studentID, const int8* name, uint32 nameLength,
                 CaffeineGUID gameID,
           bool bIsSpectator)
: CGUIController(target, studentID, name, nameLength, gameID, bIsSpectator)
{
 if(!IsUsingCaffeine())
 {
  CEID p1, p2;
  p1.s_playerType = PLAYER_TYPE_HUMAN;
  p1.s_randNum    = 1;
  p1.s_stuID      = 1;
  p1.s_gameID     = TICTACTOE_GAME_GUID;
  p1.s_version    = TICTACTOE_GAME_VERSION;

  p2.s_playerType = PLAYER_TYPE_HUMAN;
  p2.s_randNum    = 2;
  p2.s_stuID      = 2;
  p2.s_gameID     = TICTACTOE_GAME_GUID;
  p2.s_version    = TICTACTOE_GAME_VERSION;

  AddPlayer(p1);
  AddPlayer(p2);

  m_playerList[0].s_id = p1;
  m_playerList[0].s_piece.SetType(CTicTacToePiece::X);
  m_playerList[1].s_id = p2;
  m_playerList[1].s_piece.SetType(CTicTacToePiece::O);
 }

 connect(&m_board, SIGNAL(PieceTypeChanged(uint32,uint32,CTicTacToePiece::TYPE)),
      this, SLOT(PieceTypeChanged(uint32,uint32,CTicTacToePiece::TYPE)));
}

CTicTacToeController::~CTicTacToeController(void)
{
}
Figure 3.1

The first thing to do is create the class constructors and destructors. Out Tic-Tac-Toe GUI will have two different modes, one for a stand-alone game and another for use with the Caffeine Framework. The first constructor is called when the GUI will be used apart from the Caffeine Framework. The first thing we need to do in our constructor is to initialize our CGUIController base class. The next thing to do is set up the CEIDs of the players. The only lines important here are the player types, game GUID, and version number. The student ID and random number are used for unique identifaction of players. Our two new players are then added to the game and player list. The connect is a QT library function, for more information please refer to the QT manual.

The next constructor is called when using the Tic-Tac-Toe GUI in part with the Caffeine Framework. The code for this constructor is almost identical to that of the previous one. The only difference is that we pass a few more arguments this time, namely the student id, name, length of the name, game ID and whether or not we are a spectator(spectating is currently used). The remaining code is identical to the previous constructor except for your base class initialization. This time we need to add all the new information, studentID, name, nameLength, bIsSpectator.

Nothing is needed to be done in the destructor.

The next piece of code is fairly simple.

void CTicTacToeController::NewGame()
{ 
 m_board.NewGame();

 m_curPiece->SetPiece(&m_playerList[0].s_piece);
 m_curPiece->SetCEID(m_playerList[0].s_id);
}
Figure 3.2

The NewGame function is called at the onset of each game. All that is needed to be done here is to call the new game function in our Tic-Tac-Toe board representation class, m_board. This will set all nine spaces to empty. Next we set the current player to move, this is stored in m_curPiece.

The following functions are extremely straight forward, as such only there function signatures are provided.










void CTicTacToeController::UpdateCurrentPlayerPiece()













void CTicTacToeController::PlayMove(const CMove* m)

bool CTicTacToeController::CheckMove(CMove* m)
Figure 3.3

The UpdateCurrentPlayerPiece is used to determine which players turn it is to move. This information is then stored in the m_curPiece variable. Next we have the PlayMove function. This function simply forwards the CMove pointer m to the CTicTacToeBoard member function PlayMove casted as a CTicTacToeMove. The CheckMove function is almost identical to the PlayMove function, except it forwards the CMove pointer to the CheckMove function of CTicTacToeBoard.

The following functions are used to identify winning board states

bool CTicTacToeController::CheckForWin()
{
 bool rv = false;

 if(CheckForPieceWin(CTicTacToePiece::X))
 {
  m_winningMsgLen = 50;
  m_winningMsg = new int8[m_winningMsgLen];

  strncpy(m_winningMsg, "<h2>X Wins!!!</h2>", m_winningMsgLen);

  rv = true;
 }
 else if(CheckForPieceWin(CTicTacToePiece::O))
 {
  m_winningMsgLen = 50;
  m_winningMsg = new int8[m_winningMsgLen];

  strncpy(m_winningMsg, "<h2>O Wins!!!</h2>", m_winningMsgLen);
  
  rv = true;
 }
 else
 {
  bool bAllFull = true;
  for(int32 i=0; i<3; i++)
  {
   for(int32 j=0; j<3; j++)
   {
    if(m_board.GetPieceType(i,j) == CTicTacToePiece::EMPTY)
    {
     bAllFull = false;
    }
   }
  }

  if(bAllFull)
  {
   m_winningMsgLen = 50;
   m_winningMsg = new int8[m_winningMsgLen];

   strncpy(m_winningMsg, "<h2>Tie Game!!!</h2>", m_winningMsgLen);
   rv = true;
  }
 }

 return rv;
}

bool CTicTacToeController::CheckForPieceWin(CTicTacToePiece p) const
Figure 3.5

Lets look at the CheckForWin function first. This function is called to determine if the game is over. The first thing it does it check to see if either of the players have three in a row. This is were the CheckForPieceWin function comes in. This function returns true if there are three of the CTicTacToePiece, p, in a row, to indicate a win, otherwise it returns false. If neither of the players have won, the CheckForWin function then determines if a draw has occurred. This is done by determining if all of the locations on the board are full. If there are no empty spaces and neither player has won the a draw has occurred. If the game is over the CheckForWin function returns true otherwise false. Also as soon as a win or draw is detected the m_winningMsg variable is set to the desired winning message.

Lets now take a look at how our CTicTacToeController class handles user moves and board updates.

bool CTicTacToeController::PieceClicked(uint32 x, uint32 y)
{
 CTicTacToeMove m;
 m.SetPiece(m_playerPiece);
 m.SetLocation(x,y);

 return UserMove(&m);
}

void CTicTacToeController::PieceTypeChanged(uint32 x, uint32 y, CTicTacToePiece::TYPE type)
{
 CGameEvent* pGameEvent = new CGameEvent(CGameEvent::UPDATE_GUI_PIECE);
 CTicTacToeMove m;
 CTicTacToePiece p;

 p.SetType(type);
 m.SetLocation(x,y);
 m.SetPiece(p);

 pGameEvent->SetEventBody((int8*)&m,m.GetSize());

 PostEvent(pGameEvent);
}
Figure 3.6

The first function is called whenever a location on the board is clicked. The two arguments represent the x and y cooridinates of the location selected. This function builds a CTicTacToeMove object used to represent the move the user indicated. The move is then simply passed to our CGUIController base class. The PieceTypeChanged function is used to post an event to our GUI. In this case the evet is of type UPDATE_GUI_PIECE indicating that a move has been played and the GUI needs to display this new information. After our CTicTacToeMove and CTicTacToePiece objects have been correctly created all that is left to do is call the PostEvent function of the base class and the event will be correctly posted to our GUI.

Only two more funtions left for our CTicTacToeController class.

void CTicTacToeController::SetPlayerPiece(const CPiece* p)
{
 CTicTacToePiece piece = *((CTicTacToePiece*)p);

 m_playerPiece.SetType(piece.GetType());
}

void CTicTacToeController::TimeElapsed(const CPlayerPiece* piece)
{
 CTicTacToePiece* p = (CTicTacToePiece*)piece->GetPiece();

 if(p)
 {
  if(p->GetType() == CTicTacToePiece::X)
  {
   m_winningMsgLen = 50;
   m_winningMsg = new int8[m_winningMsgLen];

   strncpy(m_winningMsg, "<h2>O Wins!!!</h2>", m_winningMsgLen);
   m_bGameOver = true;
  }
  else if(p->GetType() == CTicTacToePiece::O)
  {
   m_winningMsgLen = 50;
   m_winningMsg = new int8[m_winningMsgLen];

   strncpy(m_winningMsg, "<h2>X Wins!!!</h2>", m_winningMsgLen);
   m_bGameOver = true;
  }

  delete p;
 }
}
Figure 3.7

The first function, SetPlayerPiece, is called to set the current piece to play. All this function does is set the m_playerPiece to the correct value. The TimeElapsed function is called whenever a player runs out of time. This function simple sets a friendly game over message indicating which player won and sets the m_bGameOver variable to true, indicating the game has ended.

Creating A GUI Game Board

Now its to move on to the actual GUI for Tic-Tac-Toe. If you are not familiar with QT you may want to take a little time off to refresh your memory.

Lets look at the CTicTacToeGUIBoard class. This class is used by our GUI to handle the graphical interface of the board.

class CTicTacToeGUIBoard : public QCanvasView
{
 Q_OBJECT

public: //Public Member Functions
    CTicTacToeGUIBoard(QWidget *parent = 0, const char *name = 0);
    ~CTicTacToeGUIBoard();

    void NewBoard();
    void SetPieceType(uint32 x, uint32 y, CTicTacToePiece::TYPE type);

signals: //Signals emitted by this class
    void PieceClicked(uint32, uint32);

protected: //Protected Member Functions
    void contentsMousePressEvent(QMouseEvent* event);
    void resizeEvent(QResizeEvent* event);
    
    void BuildBoard();
    void DestroyBoard(); 
    
private: //Private Member Variables
    CTicTacToeGUIPiece*** m_board;
    
    int32  m_tilesize;   
    QPoint m_offset;
};
Figure 4.1

This should not be anything new so lets move on to the member funtion implementations. We'll start with the class constructor and destructor.

CTicTacToeGUIBoard::CTicTacToeGUIBoard(QWidget *parent, const char *name)
 : QCanvasView(parent, name)
{       
    m_board = NULL; 
    setCanvas(new QCanvas(this, tr("TicTacToe Canvas")));
    BuildBoard();
    canvas()->update();
    update();           
}

CTicTacToeGUIBoard::~CTicTacToeGUIBoard()
{
    if(m_board)
        DestroyBoard();
}
Figure 4.2

These two functions are pretty straight forward. The constructor first calls the setCanvas function of the QT library. Then calls the BuildBoard function which readies our m_board variable for use. The following two function calls are both from the QT library for information on them please refer to the QT manuals. The class destructor calls the DestroyBoard function which deallocates the memory used for our board representation.

Lets move on to the board memory allocation, memory deletion, and setup. 









void CTicTacToeGUIBoard::BuildBoard()











void CTicTacToeGUIBoard::NewBoard()

void CTicTacToeGUIBoard::DestroyBoard()
Figure 4.3

The implementations of these three functions are fairly straightforward, and as such only the function signatures have been provided. The BuildBoard function as stated above allocates the memory needed for the m_board variable. The NewBoard function sets each location on the board to a CTicTacToePiece::EMPTY, we will discuse the CTicTacToePiece class later. And the DestroyBoard deallocates the memory previously allocated by BuildBoard.

Now lets take a look at how we handle events.

void CTicTacToeGUIBoard::contentsMousePressEvent(QMouseEvent* event)
{
    CTicTacToeGUIPiece* piece;
    QCanvasItemList items;
    
    if(event &&  event->button() == LeftButton)
    {
        items = canvas()->collisions(event->pos());
     if(items.count() && *items.begin())
     {
         switch((*items.begin())->rtti())
         {
         case CTicTacToeGUIPiece::RTTI:
             piece = (CTicTacToeGUIPiece*)(*items.begin());
          emit PieceClicked(piece->getRow(), piece->getCol());
             break;
         }
     }
    }
    
    canvas()->update();
    update();    
}

void CTicTacToeGUIBoard::resizeEvent(QResizeEvent*)
Figure 4.4

The contentsMousePressEvent function is called on when a mouse button is pressed over the board. The implementation of this function should be fairly straight forward for those experienced in QT. For more details of this implementation please refer the the QT manuals. The resizeEvent is also a fairly simple function to implement for those familar with QT.

Only one more function to implement for our CTicTacToeGUIBoard class.

void CTicTacToeGUIBoard::SetPieceType(uint32 x, uint32 y, CTicTacToePiece::TYPE type)
{
 if(x >= 0 && x < 3 &&
  y >= 0 && y < 3)
 {
  m_board[x][y]->setStyle(type);
 }

 canvas()->update();
 update();
}
Figure 4.5

This function is called whenever a move has been made. It simply updates the board to reflect this new move.

Creating GUI Game Pieces

Now its time to take a look at how GUI Game Pieces are created. For Tic-Tac-Toe this is handled by the CTicTacToePiece class. Lets take a look a the class definition first.

class CTicTacToeGUIPiece : public CGuiPiece
{
public: //Public Member Functions and Enumerations
    enum { RTTI = 1000 };
    
 CTicTacToeGUIPiece(QCanvas* pParent, int32 row, int32 col,
  CTicTacToePiece::TYPE style=CTicTacToePiece::EMPTY);
    int32 rtti() const;
    void redraw(const int32 x, const int32 y, 
  const int32 width, const int32 height);
    
    int32 getRow() const;
    int32 getCol() const;
    
    const QPoint& getPosition() const;           

private: //Private Member Variables
    
    QPoint m_boardPosition;
    
    static bool   m_StaticImagesLoaded;
    static QImage m_EmptyImage;
    static QImage m_XImage;
    static QImage m_OImage;    
};
Figure 4.6

The heart of our CTicTacToeGUIPiece class is the CGuiPiece base class. This class handles a lot of the lower level implentation details which we, now, no longer need to worry about. The important things to note here are the QImages required for displaying the different piece types.

Lets move on to the function implentations. 

CTicTacToeGUIPiece::CTicTacToeGUIPiece(QCanvas* pParent, int32 row, int32 col,
            CTicTacToePiece::TYPE style)
: CGuiPiece(pParent)
{
    if(!m_StaticImagesLoaded)
    {
        m_EmptyImage = QImage::fromMimeSource("Empty.png");
        m_XImage = QImage::fromMimeSource("X.png");
        m_OImage = QImage::fromMimeSource("O.png");
  m_StaticImagesLoaded = true;
    }

 m_boardPosition.setX(row);
 m_boardPosition.setY(col);
 
    m_style = style;   
 redraw(0, 0, 0, 0);
    show();
}
Figure 4.7

Once again we will start with the class constructor. This constructor first initializes its base class and then loads the static QImages if they haven't been previously loaded.

Lets move on to the redraw function

void CTicTacToeGUIPiece::redraw(const int32 x, const int32 y, const int32 width, const int32 height)
{
 m_width  = width;
 m_height = height;

    QImage newImage;
    switch(m_style)
    {    
 case CTicTacToePiece::X:
        newImage = m_XImage.smoothScale(width, height);
        break;
 case CTicTacToePiece::O:
        newImage = m_OImage.smoothScale(width, height);
        break;
 case CTicTacToePiece::EMPTY:
        newImage = m_EmptyImage.smoothScale(width, height);
        break;
    }
    
    m_pixmap.convertFromImage(newImage);
    move(x, y);

    canvas()->update();
    update();
}
Figure 4.8

The redraw function is called to draw the appropriate piece on the board.

Creating the GUI Main Window

It is now time to write the actual GUI code. The CTicTacToeGUI class holds our implementation of the Tic-Tac-Toe GUI. Lets take a look at the class definition.

#include <qmainwindow.h>

#include "TicTacToe.h"
#include "TicTacToeGUIBoard.h"

class CTicTacToeController;
class QAction;
class QToolBar;
class QPopupMenu;
class QGridLayout;
class QCustomEvent;
class CGUIClock;

class CTicTacToeGUI: public QMainWindow
{
    Q_OBJECT

public: //Public Member Functions

    CTicTacToeGUI(QWidget* pParent=0, const char* name=0,
    bool bUsingCaffeine = false,
    uint64 studentID=0,
    const QString& studentName = "");
    ~CTicTacToeGUI();

protected: //Protected Member Functions
    void closeEvent( QCloseEvent* );
    void customEvent(QCustomEvent*);

signals: //Signals emitted by this class
    void PlayMove(const CTicTacToeMove&);
    void PieceChanged(const CTicTacToePiece&);

private slots: //Private slots of this class

    void NewGame();
    void OpenGame();
  
    void Save();
    void SaveAs();      

    void About();
    void AboutQt();
    void SetTime();

private: //Private Member Functions

    void CreateActions();
    void CreateMenus();
    void CreateToolbars();
    void CreateStatusbar();

    void ReadSettings();
    void WriteSettings();

    bool MaybeSave();
    void LoadFile( const QString& fileName );
    void SaveFile( const QString& fileName);

private: //Private Member Variables

    CTicTacToeController* m_pController;   
    CTicTacToeGUIBoard*   m_pBoard;
    CGUIClock*            m_pMyClock;
    CGUIClock*            m_pOpClock;

    CTicTacToePiece m_curPlayer;

    QString m_filename;

    QAction* m_pNewGameAct;
    QAction* m_pOpenGameAct;
    QAction* m_pSaveGameAct;
    QAction* m_pExitGameAct;
    QAction* m_pSetGameTimeAct;
    QAction* m_pAboutAct;
    QAction* m_pAboutQtAct;

    QPopupMenu* m_pFileMenu;
    QPopupMenu* m_pOptionsMenu;
    QPopupMenu* m_pHelpMenu;

    QToolBar* m_pFileToolbar; 

    QGridLayout* m_pMainFormLayout;
};
Figure 4.9

Lets start by looking at the include header files and class declarations.

#include <qmainwindow.h>

#include "TicTacToe.h"
#include "TicTacToeGUIBoard.h"

class CTicTacToeController;
class QAction;
class QToolBar;
class QPopupMenu;
class QGridLayout;
class QCustomEvent;
class CGUIClock;
Figure 4.10

All of these includes and class declarations are from the QT library except the CTicTacToeController and the CGUIClock classes. We have already went over the CTicTacToeController class. The CGUIClock class is a class provided by the Caffeine Framework facilitate the easy creation of game clocks for GUIs.

The rest of the class definitions declare functions to handle our menu bar options, handle events, create actions and toolbars, and create pop-up windows. Lets take a look at how to implement these functions.

As always we will begin with the CTicTacToeGUI constructor and destructor.

CTicTacToeGUI::CTicTacToeGUI(QWidget* pParent, const char* name,
        bool bUsingCaffeine,
        uint64 studentID,
        const QString& studentName)
: QMainWindow( pParent, name, WDestructiveClose )
{ 
        setCentralWidget( new QWidget( this, "qt_central_widget" ) );
        m_pMainFormLayout = 
        new QGridLayout( centralWidget(), 2, 1, 11, 6, "mainFormLayout");

 m_pMyClock = new CGUIClock(centralWidget(), "MyClock");
 m_pOpClock = new CGUIClock(centralWidget(), "OpClock");
        m_pBoard = new CTicTacToeGUIBoard(centralWidget(), "Board");
 
 QHBoxLayout* pClockLayout = new QHBoxLayout;
 pClockLayout->addWidget(m_pMyClock);
 pClockLayout->addWidget(m_pOpClock);

 m_pMainFormLayout->addLayout(pClockLayout,0,0);
        m_pMainFormLayout->addWidget(m_pBoard,1,0);
 m_pMainFormLayout->setRowSpacing(0,40);

 if(bUsingCaffeine)
 {
  m_pController = new CTicTacToeController(this,
                                    studentID,studentName,
                                    studentName.length(),
                                    TICTACTOE_GAME_GUID);  
 }
 else
 {
  m_pController = new CTicTacToeController(this);
 }

 connect(m_pBoard, SIGNAL(PieceClicked(uint32,uint32)), 
  m_pController, SLOT(PieceClicked(uint32,uint32)));

 m_pController->start();

        CreateActions();
        CreateMenus();
        CreateToolbars();
        CreateStatusbar();

 m_pNewGameAct->setEnabled(!m_pController->IsUsingCaffeine());

        statusBar()->message( tr("Ready"), 2000 );       

 resize( 460, 540 );
}

CTicTacToeGUI::~CTicTacToeGUI()
{
 m_pController->Stop();
 m_pController->wait();

 if(m_pController)
  delete m_pController;
 if(m_pBoard)
  delete m_pBoard;
}
Figure 4.11

In the constructor the first thing we do is initialize the QMainWindow base class. Most of the code in the constructor is initializing the QT components. For more information please refer to the QT manuals. The bUsingCaffeine variable is used to determine whether or not we are using this GUI as a standalone or along with the Caffeine Framework. We need to initialize the CTicTacToeController object depending on the value of bUsingCaffeine. We then call the QT library function connect and call Start on the CTicTacToeController object to start the thread. The next four lines call functions to create the menus, toolbars, actions and status bar. We then set the status bar to a friendly message and resize the window.

The destructor is fairly straight forward. First thing to do is stop the CTicTacToeController thread. Then delete any dynamically allocated memory.

Now lets move on to creating the menu, toolbars and actions needed.

void CTicTacToeGUI::CreateActions()
{
    m_pNewGameAct = new QAction(tr("&New Game"), tr("Ctrl+N"), this);
    m_pNewGameAct->setIconSet(QPixmap::fromMimeSource("new.png"));
    m_pNewGameAct->setStatusTip(tr("Start a new Tic-Tac-Toe game"));
    connect(m_pNewGameAct, SIGNAL(activated()), this, SLOT(NewGame()));
    
    m_pExitGameAct = new QAction(tr("E&xit"), tr("Ctrl+Q"), this);
    m_pExitGameAct->setStatusTip(tr("Exit Tic-Tac-Toe"));
    connect(m_pExitGameAct, SIGNAL(activated()), this, SLOT(close()));

    m_pSetGameTimeAct = new QAction(tr("Set Game &Time"), 0, this);
    m_pSetGameTimeAct->setStatusTip(tr("Set the Game Time per Player"));
    connect(m_pSetGameTimeAct, SIGNAL(activated()), this, SLOT(SetTime()));
    
    m_pAboutAct = new QAction(tr("&About Tic-Tac-Toe"), 0, this);
    m_pAboutAct->setStatusTip(tr("Display the Tic-Tac-Toe About box"));
    connect(m_pAboutAct, SIGNAL(activated()), this, SLOT(About()));
    
    m_pAboutQtAct = new QAction(tr("About &Qt"), 0, this);
    m_pAboutQtAct->setStatusTip(tr("Display the Qt About box"));
    connect(m_pAboutQtAct, SIGNAL(activated()), this, SLOT(AboutQt()));
}

void CTicTacToeGUI::CreateMenus()
{
    m_pFileMenu = new QPopupMenu(this);
    m_pNewGameAct->addTo(m_pFileMenu);
    m_pFileMenu->insertSeparator();
    m_pExitGameAct->addTo(m_pFileMenu);

    m_pOptionsMenu = new QPopupMenu(this);
    m_pSetGameTimeAct->addTo(m_pOptionsMenu);
    
    m_pHelpMenu = new QPopupMenu(this);
    m_pAboutAct->addTo(m_pHelpMenu);
    m_pAboutQtAct->addTo(m_pHelpMenu);
    
    menuBar()->insertItem(tr("&File"), m_pFileMenu);
    menuBar()->insertSeparator();
    menuBar()->insertItem(tr("&Options"), m_pOptionsMenu);
    menuBar()->insertSeparator();
    menuBar()->insertItem(tr("&Help"), m_pHelpMenu);
}

void CTicTacToeGUI::CreateToolbars()
{
    m_pFileToolbar = new QToolBar(tr("File"), this);
    m_pNewGameAct->addTo(m_pFileToolbar);
}

void CTicTacToeGUI::CreateStatusbar()
{
 //Nothing to do...
}
Figure 4.12

The CreateActions function creates and initializes the actions needed for our menu and toolbar items. The CreateMenus and CreateToolbars functions setup the desired menu and toolbar items.

Lets now take a look at the NewGame function.

void CTicTacToeGUI::NewGame()
{
    m_pController->StartNewGame();
    m_pBoard->NewBoard();
}

All that is required to be done in this function is to call the StartNewGame function of the CTicTacToeController class and the NewBoard function of the CTicTacToeGUIBoard class to get everything ready for the new game.

The opening and saving of games is not supported in our example so we'll skip ahead to the SetTime function.

void CTicTacToeGUI::SetTime()
{
 CSetTimeDialog dlg;

 if(dlg.exec() == QDialog::Accepted)
 {
  m_pController->SetPlayerTime(dlg.GetTime());
 }
}
Figure 4.13

This function executes a simple dialog window requesting that the user enter the time per game. This information is then passed to the CTicTacToeController object which controls the game time. For more information on the construction of dialog windows please see the QT manuals.

We'll now take a look at the two event handling functions in the CTicTacToeGUI class.

void CTicTacToeGUI::closeEvent( QCloseEvent* ce )
{
    ce->accept();
    return;
}

void CTicTacToeGUI::customEvent(QCustomEvent* event)
{
 CGameEvent* pGameEvent;
 switch(event->type())
 {
 case CGameEvent::STARTGAME:
  m_pBoard->NewBoard();
  break;
 case CGameEvent::PLAY:
  {
   pGameEvent = (CGameEvent*)event;
   CTicTacToePiece* pPiece = (CTicTacToePiece*)pGameEvent->GetEventBody();
   if(pPiece)
   {
    if(pPiece->GetType() == CTicTacToePiece::X)
    {
     m_curPlayer.SetType(CTicTacToePiece::X);
     statusBar()->message("X's Turn");
    }
    else if(pPiece->GetType() == CTicTacToePiece::O)
    {
     m_curPlayer.SetType(CTicTacToePiece::O);
     statusBar()->message("O's Turn");
    }

    delete (int8*)pPiece;
   }
   else
   {
    statusBar()->message("Your turn");
   }
  }
  break;
 case CGameEvent::OP_PLAY:
  statusBar()->message("Opponent's Turn");
  break;
 case CGameEvent::MOVE:
  break;
 case CGameEvent::SETPIECE:
  break;
 case CGameEvent::UPDATE_GUI_PIECE:
  {
   pGameEvent = (CGameEvent*)event;
   CTicTacToeMove* pMove = (CTicTacToeMove*)pGameEvent->GetEventBody();
   if(pMove)
   {
    uint32 x = pMove->GetX();
    uint32 y = pMove->GetY();
    
    CTicTacToePiece p = pMove->GetPiece();
    m_pBoard->SetPieceType(x,y,p.GetType());

    delete pMove;
   }
  }
  break;
 case CGameEvent::WIN:
  {
   pGameEvent = (CGameEvent*)event;
   m_pMyClock->Stop();
   m_pOpClock->Stop();

   const int8* msg = pGameEvent->GetEventBody();
   if(msg)
   {
    QMessageBox::message("Game Over", msg);

    delete msg;
   }      
  }
  break;
 case CGameEvent::TIME:
  {
   pGameEvent = (CGameEvent*)event;
   uint32* pTime = (uint32*)pGameEvent->GetEventBody();
   if(pTime)
   {
    if(m_pController->IsUsingCaffeine())
    {
     m_pOpClock->Stop();
     m_pMyClock->Reset(*pTime);
     m_pMyClock->Start();
    }
    else
    {
     if(m_curPlayer.GetType() == CTicTacToePiece::X)
     {
      m_pOpClock->Stop();
      m_pMyClock->Reset(*pTime);
      m_pMyClock->Start();
     }
     else if(m_curPlayer.GetType() == CTicTacToePiece::O)
     {
      m_pMyClock->Stop();
      m_pOpClock->Reset(*pTime);
      m_pOpClock->Start();
     }
    }
   }
  }
  break;
 case CGameEvent::OP_TIME:
  {
   pGameEvent = (CGameEvent*)event;
   uint32* pTime = (uint32*)pGameEvent->GetEventBody();
   if(pTime)
   {
    m_pMyClock->Stop();
    m_pOpClock->Reset(*pTime);
    m_pOpClock->Start();
   }
  }
  break;
 case CGameEvent::ENDGAME:
  break;
 case CGameEvent::DISCONNECTED:
  {
   pGameEvent = (CGameEvent*)event;
   const int8* msg = pGameEvent->GetEventBody();
   if(msg)
   {
    QMessageBox::message("Disconnected", msg);

    delete msg;
   }      
   else
    QMessageBox::message("Disconnected",
     "Disconnected from Caffeine Client");
  }
  break;
 default:
  QMainWindow::customEvent(event);
  break;
 } 
}
Figure 4.14

Whenever the user tries to exit the Tic-Tac-Toe GUI the closeEvent function is called. Since we are not saving games in our example all this function needs to do is call the accept function of the QCloseEvent. The customEvent function is what is used to handle custom game events. These events are defined in the CGameEvent class of the Caffeine Framework. Here is a quick overview of these events:

STARTGAME: This event is posted upon reciept of the GAME_START message from the game module. Upon reciept of this we need to reset our internal Tic-Tac-Toe board representation to the orignal state.

PLAY:

Finishing the GUI

Copyright (c) 2005 Matt Bruns, Pat Hammond, Kevin Markussen, Travis Service, Brain Shaver

SourceForge.net Logo