ks.common.view
Class Container

java.lang.Object
  java.awt.Component
      java.awt.Canvas
          ks.common.view.Container

All Implemented Interfaces:

javax.accessibility.Accessible, java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable

public class Container

extends java.awt.Canvas

The container provides the environment within which all Solitare plug-ins execute.

The container is initialized with a Solitare Plug-in, and manages the interaction between the user and the game. All mouse events pass through the container, and are delivered to the appropriate widget based upon the (x,y) point of the mouse event.

All Undo requests (right mouse clicks) are first identified by the container, and are passed along to the solitaire game.

The container manages any Widgets that are being dragged on the screen. Typically, these are CardView widgets, but there is no limitation on this, and conceivably any widget could be dragged. The container also manages the Widget that initiated the drag event, called the dragSource.

Note: Container must be a java.awt.Component because many of the low-level image routines expect an ImageObserver, satisfied by java.awt.Canvas. In addition, this class implements key methods enabling events to be interpreted and delivered to the Solitaire subclass being viewed.

Note: Since V1.6, the container also is capable of remembering the source widget from which a drag originates, if the Controller invokes setDragSource (Widget w) accordingly. This source widget can then be asked to returnWidget(Widget w) a widget extracted from the source as part of the dragging procedure.

Note: Since V2.2, there is additional logic to enable 'shared state' model elements to exist. That is, there is some server-side state that stores information about shared state that is only accessed

See Also:

Serialized Form

Field Summary

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

Container()
Creates an empty container with no widgets.

Method Summary

void	addUser(java.lang.String newUser) Containers now need to know when users are entering, exiting
boolean	addWidget(Widget w) Adds the widget to the Container.
void	announce() Announces to GameInterface (if one is assigned) our current Status.
void	forceNextHand() Move on to play the next hand for this game.
Widget	getActiveDraggingObject() Returns the object being dragged.
RectangleHierarchy	getBackgroundImage() Return the background RectangleHierarchy representing the non-widget areas in container.
CardImages	getCardImages() Return the card images associated with this container.
java.lang.String	getCurrentUser() Return the current user for this container.
java.awt.Point	getDraggingAnchor() Return the offset within the dragging Widget for where the mouse was initially clicked.
Widget	getDragSource() Gets the source widget from which a drag originated.
IGameInterface	getGameInterface() Expose entity to whom container speaks.
java.awt.Point	getLastDrag() Returns the last Drag point, or null if no drag is in process.
java.util.Enumeration	getModelElements() Return the Model elements associated with the container's game as an Enumeration.
static Widget	getNothingBeingDragged() Returns a 'sentinel' object that represents the fact that nothing is being dragged.
Status	getStatus() Return the current status of the game being played.
RectangleHierarchyVisitor	getVisitor() Return visitor being used to draw background skin.
Widget	getWidget(java.awt.event.MouseEvent me) Return the widget (or null if none exist) that includes given mouse location.
java.util.Enumeration	getWidgets() Return the View Widgets in the container as an Enumeration.
boolean	hasWon() Check with plugin to see if the game has been won.
void	initialize(Solitaire myGame) Initialize using a Solitaire game that was already constructed elsewhere.
Widget	intersectsWidget(java.awt.Rectangle r) Returns the first Widget that intersects the given Rectangle (or null if none exist).
boolean	isActive() Determine whether the Container is active and ready to process events.
void	leaveTable() When a player wishes to leave the entire table.
void	paint(java.awt.Graphics g) Force all model elements to be redrawn.
void	processMessage(Message msg) Ability to process messages from the server is necessary for some versions of solitaire (like multi-solitaire).
void	processMouseEvent(java.awt.event.MouseEvent me) Container must send this mouse event to the appropriate controller for processing.
void	recalculateBackground() If container is resized, or its bounds are otherwise manipulated, this method recalculates the background RectangleHierarchy.
void	refreshAll() Refresh widgets in container.
void	refreshWidgets() Refresh widgets in container.
void	refreshWidgets(java.awt.Rectangle clip) Refresh widgets in container.
void	releaseDraggingObject() Releases the object being dragged by the container.
void	removeAllWidgets() Remove all widgets from this container to start fresh.
void	removeUser(java.lang.String exitingUser) Containers now need to know when users are entering, exiting
void	repaintAll() Force a repaint of all Widgets, whether they are dirty or not.
void	repaintAll(java.awt.Rectangle clip) Force a repaint of all Widgets, whether they are dirty or not.
void	repaintBackground() Refresh the background screen which is a hierarchy of rectangles to be filled using background image.
void	repaintBackground(java.awt.Rectangle clip) Refresh the background screen which is a hierarchy of rectangles to be filled using background image.
void	repaintWidgets(java.awt.Rectangle clip) Force a repaint of all Widgets that intersect given clip region, whether they are dirty or not.
void	resetHand() Reset existing game to redeal cards exactly as it was started.
void	resetStatus() Clears all stats for this container
void	setActive(boolean newActive) Activate the container (or deactivate it) to be able to process events.
void	setActiveDraggingObject(Widget newActiveDraggingObject, java.awt.event.MouseEvent me) Specifies the Widget being dragged.
void	setCurrentUser(java.lang.String user) Tell Container who the current user player is
void	setDragSource(Widget newDragSource) Sets the source widget from which a drag originated.
void	setGameInterface(IGameInterface gi) Container must speak to an outside entity about game results.
void	setLastDrag(java.awt.Point p) Tell container of last drag point (or null if ending a drag).
void	setMouseAdapter(java.awt.event.MouseAdapter ma) Alters the way in which this Container reacts to MouseEvents.
void	setMouseMotionAdapter(java.awt.event.MouseMotionAdapter ma) Alters the way in which this Container reacts to MouseMotion events.
void	setUndoAdapter(UndoAdapter ua) Alters the way in which this Container reacts to UndoRequested
void	setVisitor(RectangleHierarchyVisitor v) Sets the entity responsible for updating background skin of the container
java.util.Iterator	users() Containers now are able to expose the users playing on the table.
void	wonGame() The game has been won.

Methods inherited from class java.awt.Canvas

addNotify, createBufferStrategy, createBufferStrategy, getAccessibleContext, getBufferStrategy, update

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, bounds, checkImage, checkImage, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, deliverEvent, disable, dispatchEvent, doLayout, enable, enable, enableInputMethods, getAlignmentX, getAlignmentY, getBackground, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeys, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMaximumSize, getMinimumSize, getMouseListeners, getMouseMotionListeners, getMouseWheelListeners, getName, getParent, getPeer, getPreferredSize, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, invalidate, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusCycleRoot, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isOpaque, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, minimumSize, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, preferredSize, prepareImage, prepareImage, print, printAll, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocusInWindow, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeys, setFocusTraversalKeysEnabled, setFont, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, setVisible, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle, validate

Methods inherited from class java.lang.Object

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

Constructor Detail

Container

public Container()

Creates an empty container with no widgets.

Method Detail

setCurrentUser

public void setCurrentUser(java.lang.String user)

Tell Container who the current user player is

Parameters:

user -

Since:

V2.2 to enable multiple solitaire

getCurrentUser

public java.lang.String getCurrentUser()

Return the current user for this container.

Since:

V2.2 to enable multiple solitaire

addWidget

public boolean addWidget(Widget w)

Adds the widget to the Container.

This method can only be called after the Container has been initialized. The Widget is added to the set of widgets, and a MouseManager is assigned, if one is not already in place.

The Boundary of the Widget is then added to the backgroundImage to maintain the background real estate that needs its own painting routines.

If the proposed widget intersects with an existing widget, a message is sent to stderr.

Parameters:

w - ks.common.view.Widget

Returns:

boolean true if the widget does not overlap with existing widgets

announce

public void announce()

Announces to GameInterface (if one is assigned) our current Status.

forceNextHand

public void forceNextHand()

Move on to play the next hand for this game.

Note: This is directly invoked by the user and signifies that they have given up for the given hand. If the user wins, call wonGame() instead.

getActiveDraggingObject

public Widget getActiveDraggingObject()

Returns the object being dragged. If no object is being dragged, the special getNothingBeingDragged() object is the value of this method.

Returns:

ks.common.view.Widget

getBackgroundImage

public RectangleHierarchy getBackgroundImage()

Return the background RectangleHierarchy representing the non-widget areas in container.

Returns:

ks.common.view.RectangleHierarchy

getDraggingAnchor

public java.awt.Point getDraggingAnchor()

Return the offset within the dragging Widget for where the mouse was initially clicked.

Returns:

Point

users

public java.util.Iterator users()

Containers now are able to expose the users playing on the table.

Returns:

Enumeration of String User names.

Since:

V2.2

removeUser

public void removeUser(java.lang.String exitingUser)

Containers now need to know when users are entering, exiting

Parameters:

exitingUser -

Since:

V2.2

addUser

public void addUser(java.lang.String newUser)

Containers now need to know when users are entering, exiting

Parameters:

newUser -

Since:

V2.2

getDragSource

public Widget getDragSource()

Gets the source widget from which a drag originated.

Note: dragSource must be manually set by the controller of the widget since there is no obvious way for the container to know the object for which the drag originates.

Returns:

ks.common.view.Widget

Since:

v1.6

getLastDrag

public java.awt.Point getLastDrag()

Returns the last Drag point, or null if no drag is in process.

This class variable is kept up-to-date by the various MouseManagers associated with each widget, as well as the MouseManagers with the Container itself that represents the background.

If this ever returns null, it means nothing is being dragged.

Returns:

java.awt.Point

getNothingBeingDragged

public static Widget getNothingBeingDragged()

Returns a 'sentinel' object that represents the fact that nothing is being dragged. This avoids the use of using null object references

Returns:

ks.common.view.Widget

getStatus

public Status getStatus()

Return the current status of the game being played.

This may include: score, number of cards left, number of wins, number of undo, number of times new game was pressed, number of times the game was reset.

Returns:

Status

getVisitor

public RectangleHierarchyVisitor getVisitor()

Return visitor being used to draw background skin.

Returns:

ks.common.view.RectangleHierarchyVisitor

getWidget

public Widget getWidget(java.awt.event.MouseEvent me)

Return the widget (or null if none exist) that includes given mouse location.

Parameters:

me - java.awt.event.MouseEvent

Returns:

ks.common.view.Widget

getWidgets

public java.util.Enumeration getWidgets()

Return the View Widgets in the container as an Enumeration.

Returns:

java.util.Enumeration

hasWon

public boolean hasWon()

Check with plugin to see if the game has been won.

Returns:

boolean whether the solitaire game has been won, according to the game's method hasWon.

initialize

public void initialize(Solitaire myGame)

Initialize using a Solitaire game that was already constructed elsewhere.

Parameters:

myGame - the plugin to be instantiated and activated.

Since:

V2.1 this method is responsible for setting the card images in the container as determined by the given Solitaire plugin

After this method, the Container is active.

intersectsWidget

public Widget intersectsWidget(java.awt.Rectangle r)

Returns the first Widget that intersects the given Rectangle (or null if none exist).

Parameters:

r - java.awt.Rectangle

Returns:

ks.common.view.Widget

isActive

public boolean isActive()

Determine whether the Container is active and ready to process events.

Note: When a container is active, all mouse events are processed.

Returns:

boolean

leaveTable

public void leaveTable()

When a player wishes to leave the entire table. Note that the GUI has already confirmed this with the user so we must now carry out the action.

paint

public void paint(java.awt.Graphics g)

Force all model elements to be redrawn. Since this method is used by low-level java.awt.* code, we must adhere to the semantics of paint(). Thus, all elements are redrawn (including the background)

Paint is an imperative command that forces the Container to draw itself.

The dragging of objects is managed separately.

Parameters:

g - java.awt.Graphics

processMouseEvent

public void processMouseEvent(java.awt.event.MouseEvent me)

Container must send this mouse event to the appropriate controller for processing.

If the container is inactive, no action is taken. The following mouse events can be global and do not apply to a specific Widget (not even handled yet):

MouseExited
MouseEntered

Parameters:

me - java.awt.event.MouseEvent

recalculateBackground

public void recalculateBackground()

If container is resized, or its bounds are otherwise manipulated, this method recalculates the background RectangleHierarchy.

refreshAll

public void refreshAll()

Refresh widgets in container. Note that this updates the background but only refreshes the widgets that have been marked as 'dirty'.

refreshWidgets

public void refreshWidgets()

Refresh widgets in container. This only refreshes the widgets that have been marked 'dirty'

refreshWidgets

public void refreshWidgets(java.awt.Rectangle clip)

Refresh widgets in container. This only refreshes the widgets that are marked 'dirty'.

Clip to the specified rectangle. Clip is unaffected by this method.

Parameters:

clip - java.awt.Rectangle

releaseDraggingObject

public void releaseDraggingObject()

Releases the object being dragged by the container.

Note: this will also reset the dragSource and lastDrag to null.

removeAllWidgets

public void removeAllWidgets()

Remove all widgets from this container to start fresh.

repaintAll

public void repaintAll()

Force a repaint of all Widgets, whether they are dirty or not.

This method repaints background also.

repaintAll

public void repaintAll(java.awt.Rectangle clip)

Force a repaint of all Widgets, whether they are dirty or not. Also draw background.

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

This method avoids the default fillRect over the whole background (which flickers the screen).

Parameters:

clip - java.awt.Rectangle

repaintBackground

public void repaintBackground()

Refresh the background screen which is a hierarchy of rectangles to be filled using background image.

repaintBackground

public void repaintBackground(java.awt.Rectangle clip)

Refresh the background screen which is a hierarchy of rectangles to be filled using background image.

Restrict to the clip Rectangular region. [clip is unaffected by this invocation.]

Parameters:

clip - java.awt.Rectangle

repaintWidgets

public void repaintWidgets(java.awt.Rectangle clip)

Force a repaint of all Widgets that intersect given clip region, whether they are dirty or not.

Restrict drawing to the clip rectangle [clip is unaffected].

This method avoids the default fillRect over the whole background (which flickers the screen).

Parameters:

clip - java.awt.Rectangle

resetHand

public void resetHand()

Reset existing game to redeal cards exactly as it was started.

resetStatus

public void resetStatus()

Clears all stats for this container

setActive

public void setActive(boolean newActive)

Activate the container (or deactivate it) to be able to process events.

Parameters:

newActive - boolean

setActiveDraggingObject

public void setActiveDraggingObject(Widget newActiveDraggingObject,
                                    java.awt.event.MouseEvent me)

Specifies the Widget being dragged. Note: this is called once. Thereafter, for each drag event, MouseManagers for the Widgets update the lastDrag Point in the container.

We also take as input the MouseEvent associated with this dragging object; this enables us to calculate the anchor.

Take some care if MouseEvent is null.

Parameters:

newActiveDraggingObject - ks.common.view.Widget

me - MouseEvent

setDragSource

public void setDragSource(Widget newDragSource)

Sets the source widget from which a drag originated.

Note: dragSource must be manually set by the controller of the widget since there is no obvious way for the container to know the object for which the drag originates.

Passing in null simply means that the drag is released.

Parameters:

newDragSource - ks.common.view.Widget

Since:

v1.6

setGameInterface

public void setGameInterface(IGameInterface gi)

Container must speak to an outside entity about game results. This method sets that entity.

Parameters:

gi - ks.games.GameInterface

getGameInterface

public IGameInterface getGameInterface()

Expose entity to whom container speaks.

setLastDrag

public void setLastDrag(java.awt.Point p)

Tell container of last drag point (or null if ending a drag).

Parameters:

p - java.awt.Point

setMouseAdapter

public void setMouseAdapter(java.awt.event.MouseAdapter ma)

Alters the way in which this Container reacts to MouseEvents.

Parameters:

ma - java.awt.event.MouseAdapter

setMouseMotionAdapter

public void setMouseMotionAdapter(java.awt.event.MouseMotionAdapter ma)

Alters the way in which this Container reacts to MouseMotion events.

Parameters:

ma - java.awt.event.MouseMotionAdapter

setUndoAdapter

public void setUndoAdapter(UndoAdapter ua)

Alters the way in which this Container reacts to UndoRequested

Parameters:

ua - UndoAdapter

setVisitor

public void setVisitor(RectangleHierarchyVisitor v)

Sets the entity responsible for updating background skin of the container

Parameters:

v - the RectangleHierarchyVisitor to be used.

wonGame

public void wonGame()

The game has been won. Move on to the next game.

getModelElements

public java.util.Enumeration getModelElements()

Return the Model elements associated with the container's game as an Enumeration.

This method is not used during play. It is being provided to anticipate the need of a sophisticated Beta-testing GUI application that can inspect and manipulate the state of a solitaire plug-in.

Returns:

java.util.Enumeration

getCardImages

public CardImages getCardImages()

Return the card images associated with this container.

Returns:

CardImages the cardImages used by the plugin active within this container.

processMessage

public void processMessage(Message msg)

Ability to process messages from the server is necessary for some versions of solitaire (like multi-solitaire).

Parameters:

msg -