ks.common.games
Class Solitaire

java.lang.Object
  ks.common.games.Solitaire

public abstract class Solitaire

extends java.lang.Object

The ultimate superclass of all Solitaire games.

Each solitaire plugin is a subclass of Solitaire. The most important method for developers is initialize which is invoked when the game is started (or when a new hand is requested).

initialize must satisfy three responsibilities:

1. Initialize the model
2. Initialize the view
3. Initialize the controllers

Most initialize methods will follow this suggested format:

 <blockquote>
  public void initialize() {
    initializeModel(getSeed());
    initializeView();
    initializeControllers();
  
    // Prepare initial game setup.
    ...
  }
  </blockquote>
 

where initializeModel,initializeView, and initializeControllers are protected methods of the plugin.

Initialize the Model

Each solitaire plugin constructs a model of basic elements to be found in any solitaire variation -- a deck, buildable columns, a pile of cards. Each model element has a name unique to the model. In the example above, note how the initializeModel takes the random seed which will be used to construct the appropriate deck shuffled using a randomized algorithm using this seed value.

Initialize the View

Each model element can be represented by exactly one View Widget within the Container, the entity in which the solitaire plugin executes. Each View widget is placed at a specific (x,y) location within the coordinates of the container, and has a calculated width, and height. Some Widgets have additional attributes that may be set by the user.

Initialize the Controllers

The real power of a solitaire plugin is in the way controller objects are constructed and attached to View Widgets. These controllers react to various Mouse Events within the Container -- MousePress, MouseRelease, MouseDrag, MouseMove, MouseEntered, and MouseExited. The controllers manage the user's interaction with the game, and thus the way the game is played.

Once a game is constructed, it becomes active within a container by adding it to the container. Each game knows its seed value, as well as the increment by which new seed values are generated with each successive hand.

Each Solitaire game has several default model elements, which users can construct views onto and place at whichever (x,y) coordinates they desire:

1. numberLeft -- MutableInteger
2. score -- MutableInteger

Creation date: (10/1/01 11:35:04 PM)

Field Summary

static java.lang.String	defaultDeckType Default deck type to use.
static java.lang.String	numLeftName Name of special numLeft object.
static java.lang.String	scoreName Name of special score object.

Method Summary

CardImages	getCardImages() Return the specific card images to use when calculating the dimensions within the View.
Container	getContainer() Returns the Container of the game.
java.lang.String	getDeckType() Standard Configuration.getValue(deckTypeVariable) contains deck type.
int	getIncrement() Returns the increment to be used to generate the next deck for this game.
Element	getModelElement(java.lang.String name) Returns the Model Element maintained by this Solitaire Variation with desired name.
java.util.Enumeration	getModelElements() Returns all Model Element maintained by this Solitaire variation.
java.util.Enumeration	getMoves() Return all moves made so far within this game.
abstract java.lang.String	getName() Every Solitaire variation must return its name.
MutableInteger	getNumLeft() Return the Element representing the number of cards left.
java.awt.Dimension	getPreferredSize() Returns the preferred size needed for this solitaire game to function.
MutableInteger	getScore() Return the model Element representing the score for a solitaire game.
int	getScoreValue() Return the score for a solitaire game as an int.
int	getSeed() Return the random seed used to shuffle the deck.
java.lang.String	getVersion() Every Solitaire variation may support a version.
java.util.Enumeration	getWidgets() Returns Enumeration of all Widgets maintained by this Solitaire variation.
abstract boolean	hasWon() Each solitaire game knows when it has won.
abstract void	initialize() Each solitaire game provides its own initialization routine.
void	nextHand() Update seed by a specific amount and restart solitaire game.
boolean	pushMove(Move m) Pushes given move onto our stack of existing moves.
void	refreshAll() Refresh all elements whose Widgets are now dirty.
void	refreshWidgets() Refresh all elements whose Widgets are now dirty.
void	refreshWidgets(java.awt.Rectangle clip) Refresh all elements whose Widgets are now dirty.
void	repaintAll() Forces entire game to be repainted, whether a View needs it or not.
void	repaintAll(java.awt.Rectangle clip) Forces entire game to be repainted, whether a View needs it or not.
void	repaintBackground(java.awt.Rectangle clip) Forces only background within clipping rectangle to be redrawn.
void	repaintWidgets(java.awt.Rectangle clip) Repaint all Widgets, whether they need to be redrawn or not.
void	resetHand() User has requested to play hand again.
void	setContainer(Container cont) Set the container in which this Solitaire game will be displayed and be active.
void	setIncrement(int newIncrement) Set the value for incrementing deck seed.
void	setSeed(int seed) Set seed value for this game.
boolean	undoMove() Solitaire game stores all moves and enables them to be undone.
void	updateNumberCardsLeft(int delta) Add delta to the number of cards left.
void	updateScore(int delta) Add delta to the score.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

defaultDeckType

public static final java.lang.String defaultDeckType

Default deck type to use. Override by subclasses.

See Also:

Constant Field Values

scoreName

public static final java.lang.String scoreName

Name of special score object.

See Also:

Constant Field Values

numLeftName

public static final java.lang.String numLeftName

Name of special numLeft object.

See Also:

Constant Field Values

Method Detail

getCardImages

public CardImages getCardImages()

Return the specific card images to use when calculating the dimensions within the View.

Returns:

CardImages images to use for this game.

getContainer

public Container getContainer()

Returns the Container of the game.

Returns:

The Container in which the solitaire variation is played.

getIncrement

public int getIncrement()

Returns the increment to be used to generate the next deck for this game.

Returns:

int increment to be used to update random seed for successive games.

getModelElement

public Element getModelElement(java.lang.String name)

Returns the Model Element maintained by this Solitaire Variation with desired name.

Parameters:

name - A String representing the name of the desired Model Element

Returns:

The Element with the desired name, or null if not found.

Throws:

java.lang.IllegalArgumentException - if desired name is invalid (i.e., null).

getModelElements

public java.util.Enumeration getModelElements()

Returns all Model Element maintained by this Solitaire variation.

Returns:

Enumeration of Element objects.

getMoves

public java.util.Enumeration getMoves()

Return all moves made so far within this game.

Returns:

Enumeration Move objects that make up the history of the game.

getName

public abstract java.lang.String getName()

Every Solitaire variation must return its name.

Returns:

String the name of the solitaire variation.

getNumLeft

public MutableInteger getNumLeft()

Return the Element representing the number of cards left.

Returns:

The MutableInteger Element storing the number of cards left to play.

getPreferredSize

public java.awt.Dimension getPreferredSize()

Returns the preferred size needed for this solitaire game to function.

Each subclass should override this method if more space is needed initially when the solitaire version is initialized.

The default value returned is (769, 635).

Returns:

java.awt.Dimension the desired dimension of the game.

getScore

public MutableInteger getScore()

Return the model Element representing the score for a solitaire game.

Returns:

the MutableInteger Element representing the score for the game.

getScoreValue

public int getScoreValue()

Return the score for a solitaire game as an int.

Returns:

int represents the value of the score MutableInteger

getSeed

public int getSeed()

Return the random seed used to shuffle the deck.

Returns:

int represents the seed used for randomization algorithms

getVersion

public java.lang.String getVersion()

Every Solitaire variation may support a version. By default, this will always return "1.0";

Returns:

String

getWidgets

public java.util.Enumeration getWidgets()

Returns Enumeration of all Widgets maintained by this Solitaire variation.

Returns:

Enumeration of Element objects.

hasWon

public abstract boolean hasWon()

Each solitaire game knows when it has won.

Returns:

boolean true if the player has won the game.

initialize

public abstract void initialize()

Each solitaire game provides its own initialization routine.

By the time this method is called, the game is part of its Container.

nextHand

public void nextHand()

Update seed by a specific amount and restart solitaire game.

pushMove

public boolean pushMove(Move m)

Pushes given move onto our stack of existing moves.

Parameters:

m - A Move object representing the most recent Move made in the solitaire game.

Returns:

boolean

refreshAll

public void refreshAll()

Refresh all elements whose Widgets are now dirty. Also redraw background. Not all Widgets are redrawn.

refreshWidgets

public void refreshWidgets()

Refresh all elements whose Widgets are now dirty. Not all Widgets are redrawn.

refreshWidgets

public void refreshWidgets(java.awt.Rectangle clip)

Refresh all elements whose Widgets are now dirty. Not all Widgets are redrawn.

Clip to only refresh widgets whose view intersects the clip rectangle. [clip is unaffected by this invocation. ]

Parameters:

clip - a Rectangle representing the region outside of which no drawing occurs.

repaintAll

public void repaintAll()

Forces entire game to be repainted, whether a View needs it or not. Background is redrawn.

Note that if you call container.repaint() the entire background is re-filled with the background color, introducing flicker. The repaintAll() method is our own protocol that avoids this flicker.

repaintAll

public void repaintAll(java.awt.Rectangle clip)

Forces entire game to be repainted, whether a View needs it or not.

Restrict drawing to the clip Rectangle. [clip is unaffected by this invocation].

Note that if you call container.repaint() the entire background is re-filled with the background color, introducing flicker. The repaintAll() method is our own protocol that avoids this flicker.

Parameters:

clip - a Rectangle representing the region outside of which no drawing occurs.

repaintWidgets

public void repaintWidgets(java.awt.Rectangle clip)

Repaint all Widgets, whether they need to be redrawn or not.

Clip to only refresh widgets whose view intersects the clip rectangle. [clip is unaffected by this invocation.]

Parameters:

clip - a Rectangle representing the region outside of which no drawing occurs.

resetHand

public void resetHand()

User has requested to play hand again.

setContainer

public void setContainer(Container cont)

Set the container in which this Solitaire game will be displayed and be active. New to V2.2 some solitaire variations need to know the number of players that are currently playing. Since this information can be determined from the container, it only makes sense to update that information upon set. Note that when a game is restarted, this information may indeed be invalid, so we take care to do this right.

Parameters:

cont - the Container in which this solitaire game will be executed.

setIncrement

public void setIncrement(int newIncrement)

Set the value for incrementing deck seed.

Parameters:

newIncrement - an integer representing the value to add to the random seed when generating successive solitaire deals.

setSeed

public void setSeed(int seed)

Set seed value for this game.

Parameters:

seed - an integer representing the seed for the randomization algorithm

undoMove

public boolean undoMove()

Solitaire game stores all moves and enables them to be undone. Once a request to undo is received, this takes care of it.

Returns:

boolean true means the move was successfully undone; false otherwise.

updateNumberCardsLeft

public void updateNumberCardsLeft(int delta)

Add delta to the number of cards left. If delta is negative, we are removing cards.

There is no check on the value

Parameters:

delta - an integer representing the value to add to the number of cards left. A negative number means reduce the number of cards left.

updateScore

public void updateScore(int delta)

Add delta to the score. If delta is negative, we are removing points.

There is no check on the score value.

Parameters:

delta - an integer representing the value to add to player's score. A negative number means lower the score.

getDeckType

public java.lang.String getDeckType()

Standard Configuration.getValue(deckTypeVariable) contains deck type.

Note: overload this method if your plugin requires a different deck type.

Note: this method is a bit of a hack since it uses the global Configuration information. Ideally, this should be moved out and 'set' from the outside instead of 'get' from here in the inside. Ah well...

Returns:

String deckType to use for this plugin.

Since:

V2.1

repaintBackground

public void repaintBackground(java.awt.Rectangle clip)

Forces only background within clipping rectangle to be redrawn.

Restrict drawing to the clip Rectangle. [clip is unaffected by this invocation].

Parameters:

clip - a Rectangle representing the region outside of which no drawing occurs.