Common Classes

The Java implementation of a set of classes to support the creation of applications using the strategy game framework, is described here. Emphasis is on the concepts and the overall structure rather than the low-level detail, which is provided in the javadocs. None of these classes are required by the strategy game framework itself, but were generated simply to ease the future development of applications. Together these classes provide a wider framework for quickly implementing console applications and applets using the strategy game framework.

The common classes may be found in the common directory in the source code archive available on the downloads page. The structure of the common directory is as follows:

• src - Java source for the common classes.
• test-src - Unit tests for the common classes based on JUnit.
• bin - Target directory for classes when the code is built with Ant.
• test-bin - Target directory for unit tests when the code is built with Ant.
• test-results - Target directory for JUnit test results when the code is built with Ant.
• doc - Target directory for javadocs when the code is build with Ant.

Package Diagram

The package diagram below shows the package dependencies for the common classes.

Common AWT Classes

The common AWT classes provide a small set of GUI components for use in AWT applications or applets and reside in the net.lurgee.common.awt package. These classes are completely independent of the strategy game framework.

Widget

The Widget abstract class is a general-purpose GUI component, extended from java.awt.Container. It provides methods to load and unload images and to generate custom widget events. The class includes mouse event support by implementing the java.awt.event.MouseListener and java.awt.event.MouseMotionListener interfaces. As these interfaces are implemented by this base class, subclasses only need to override the mouse event methods relevant to them. All the common AWT classes are subclasses of Widget.

Text Widget

The TextWidget abstract class is a simple element that displays a text string whose colour is changed when the mouse cursor passes over it. The selectAction abstract method needs to be defined by concrete subclasses to provide the actions that are performed when a mouse button is pressed on the widget. The dimensions of the text widget and its position relative to the parent widget are specified on construction.

For example:

Button Widgets

The ButtonWidget abstract class is a generic button whose display can be changed if it is disabled, if the mouse cursor is over it, or if it has been pressed. The paint and selectAction abstract methods needs to be defined by concrete subclasses to paint the button appropriately and to provide the actions that are performed when a mouse button is pressed on the widget respectively. The dimensions of the button widget and its position relative to the parent widget, as well as the colours and the font to use are specified on construction.

The IconWidget abstract class extends ButtonWidget to provide a graphical icon-type button. Images are specified for the icon and optionally for its background. The icon image can be changed when the widget is disabled and the background image can be changed when the mouse cursor is over the icon (although only when the widget is enabled). Of the super class abstract methods, only the paint method is defined, so the selectAction abstract method needs to be defined by concrete subclasses to provide the actions that are performed when a mouse button is pressed on the widget. The dimensions of the icon widget and its position relative to the parent widget, as well as the filenames for each of the images are specified on construction.

For example:

The StatefulIconWidget abstract class extends IconWidget to provide an icon whose state changes every time it is clicked. An array of images is provided to it, each of which represents an icon state. The selectAction abstract method needs to be defined by concrete subclasses to provide the actions that are performed when a mouse button is pressed on the widget. The dimensions of the stateful icon widget and its position relative to the parent widget, as well as the filenames for each of the images are specified on construction.

Scrollbar Widget

The ScrollbarWidget class extends Widget to provide a graphical vertical scrollbar. The minimum and maximum values represented by the scrollbar are specified, as well as the current value. The position and size of the scroller thumb in the scrollbar are determined appropriately. The value represented by the scrollbar may be changed by dragging the scroller thumb with the mouse, by clicking the up and down buttons, or by clicking in the scrollbar above or below the scroller thumb. The up and down buttons, and the scroller thumb are implemented as inner classes that extend ButtonWidget. The dimensions of the scrollbar widget and its position relative to the parent widget, as well as the range of values represented by the scrollbar and the colours to use are specified on construction.

For example:

Window

The Window abstract class is a general-purpose modal window for use in applets, extended from Widget. All the windows in the common AWT classes are subclasses of Window. It provides methods to open and close the window, which also sets the properties of the parent widget appropriately so that the window is modal (i.e. so the parent widget does not respond to certain mouse events while the child window is open).

Main Window

The MainWindow abstract class extends Window to provide event dispatching functionality of custom widget events. This allows applets to be built more completely in an event-driven way. It also provides functionality for playing audio clips. Generally an applet should have one main window, which is the lowest level GUI component, and all other components should exist as children (or children of children, and so on) of the main window. This layout is needed to ensure that dispatching of widget events operates as intended.

Text Window

The TextWindow class extends Window to provide a window for displaying text. The text is wrapped to fit into the window horizontally and a vertical scrollbar is shown if required. The dimensions of the window are specified, but not the position as the window is always centred in the parent widget or the applet if there is no parent widget. The dimensions of the text window and the text to display, as well as the colours and the font to use are specified on construction.

For example:

Option Window

The OptionWindow abstract class extends Window to provide a window which presents the user with a list of text options that they can select from. The options are implemented by anonymous classes that extend TextWidget. The dimensions of the window are not specified, but are rather determined automatically to fit the text and the options. The window is always centred in the parent widget or the applet if there is no parent widget. The selectAction abstract method needs to be defined by concrete subclasses to provide the actions that are performed when a mouse button is pressed on one of the options. The text to display and the options the user can select from, as well as the colours and the font to use are specified on construction.

For example:

Widget Events

The WidgetEvent class extends the Java AWTEvent class and represents a generic event that can be dispatched to widgets. Events are posted through a method on any Widget class and are passed up to the main window, which posts them to the AWT system event queue. When an event fires, children widgets of the main window (or children of children, and so on) that are registered as widget event listeners are informed of the event. This allows events to be globally sent to all interested widgets, easing development and facilitating looser coupling of classes. Data may be attached to events too.

Class Diagram

The UML sketch class diagram below shows the key classes that comprise the common AWT classes.

Common Applet Classes

The common applet classes provide abstracted functionality for creating an applet that uses the strategy game framework. The classes use both the strategy game framework classes and the common AWT classes.

Game

The AbstractGame abstract class is simply a container for wrapping all the game-related entities, such as a searcher and a board. It keeps a history of the game played by stored the board states after every move played and facilitates 'undo' operations. It also keeps the game state and a message regarding the current game state. Abstract methods are defined that concrete classes need to define appropriately for the game being implemented.

The Settings class keeps track of which player is being controlled by the user, the level that the computer is playing at and whether sound effects are on or off. The AbstractGame abstract class has an instance of the Settings class.

Game Applet

The AbstractGameApplet abstract class extends the java.applet.Applet class and provides common functionality that all applets require. In particular, it over-rides the default painting mechanism to provide support for double-buffering for a smoother user interface without flicker.

Game Window

The AbstractGameWindow abstract class extends the common AWT MainWindow class. It it an abstraction of a general game window and performs operations that are common to all games, including flow control and icon management. Concrete classes that extend this class need to do very little more than setup the components and paint the window to implement a functional game.

Board Widget

The AbstractBoardWidget abstract class extends the common AWT Widget class. It it an abstraction of a general widget for game board and performs operations that are common to all games, including animation control and the dispatching of common events. This class should be extended appropriately for the game being implemented.

Thinker

The Thinker class implements the java.lang.Runnable interface to allow the computer's search for a move to be done in a thread.

Animator

The Animator class implements the java.lang.Runnable interface to allow animations (such as flipping pieces in reversi, or sliding pieces into place in connect-four) to be done in a thread. An animator is able to animate any class that implements the Animatable interface, by repeatedly calling the animate method on this class until the thread is terminated or the animatable class indicates that the animation is complete.

Events

Various widget events are posted and handled during the execution of a game. The flow control is almost entirely based on these events. The event ids are defined in the Event class as follows:

Event id	Description	Data
PLAY_MOVE	Play a move	Move representing the move to be played
DONE_PLAYING	A move has been played or aborted	Boolean indicating if move was aborted
REFRESH_BOARD	Repaint the game board	none
ENABLE_BOARD	Enable the game board for user input	none
REFRESH_STATUS	Repaint the game status indicator(s)	none
OPEN_HELP	Open a help window	none
CLOSE_HELP	Close a help window	none
NEW_GAME	New game selected	none

The PLAY_MOVE and DONE_PLAYING events are handled by the AbstractGameWindow class and other events should be handled appropriately by the game being implemented, if relevant. Most of these events are posted by the common applet classes, but may be posted by the game being implemented as required.

Class Diagram

The UML sketch class diagram below shows the key classes that comprise the common applet classes.

Common Console Classes

The common console classes provide abstracted functionality for creating a console-based application that uses the strategy game framework.

Game

The AbstractGame abstract class is simply a container for wrapping all the game-related entities, such as a searcher and the competitors (which in turn may contain other game-related entities). Abstract methods are defined that concrete classes need to define appropriately for the game being implemented.

Competitors

The AbstractCompetitor abstract class wraps a Player object and adds abstracted operations for determining a move. Two concrete subclasses are defined. HumanCompetitor represents a user-controlled player in the game and determines the move to play via user input. ComputerCompetitor represents a computer-controlled player in the game and determines the move to play via a searcher in the strategy game framework.

Thinker

The Thinker class implements the java.lang.Runnable interface to allow the computer's search for a move to be done in a thread.

Statistics

The GameStats class can be used to collate and report back on statistics regarding games played. It uses two related classes, PlayerStats to store the statistics for a single player and ResultStats to store the result of a single game. PlayerStats implements the sgf SearchProgressListener interface and obtains feedback regarding the search and evaluation process directly from the strategy game framework.

Input and Output

All input and output operations are done through the Input and Output classes. This allows common functionality to be changed easily and facilitates testing by replacing the input or output classes with test versions.

Class Diagram

The UML sketch class diagram below shows the key classes that comprise the common console classes.