ks.common.view
Class Widget

java.lang.Object
  ks.common.view.Widget

All Implemented Interfaces:

ElementListener

Direct Known Subclasses:

BuildablePileView, CardView, ColumnView, DeckView, EmptyWidget, IntegerView, PileView, RowView, StringView

public abstract class Widget

extends java.lang.Object

implements ElementListener

For all view.* entities, this is the superclass that defines important concepts.

The widget is drawn at location (x,y) extending width pixels to the right and height pixels down.

Every widget has an associated CardImages object to retrieve cards and the card reverse image. When a widget is initially constructed, it is marked as 'dirty'.

Constructor Summary

Widget(Element me)
Default constructor for Widgets.

Method Summary

java.awt.Rectangle	getBounds() Return the bounds of the Widget as a newly instantiated rectangle.
CardImages	getCardImages() Return the Cards of this widget.
Container	getContainer() Return the container for this Widget.
int	getHeight() Return the height of the widget.
java.awt.Image	getImage() Return the image of this Widget (used for drawing the Widget on screen).
Element	getModelElement() Return the Model Element associated with this Widget.
MouseManager	getMouseManager() Return the MouseManager associated with this Widget.
java.lang.String	getName() Return the name of this widget.
int	getWidth() Return the width of the widget.
int	getX() Return the x coordinate for the Widget's location.
java.awt.Point	getXY() Return the (x,y) coordinates of top-left corner of Widget as a Point.
int	getY() Return the y coordinate for the Widget's location.
boolean	inBounds(java.awt.Point p) If (x,y) point is within this widget, return true, else false.
boolean	isDirty() Determine whether this widget needs to be recalculated.
void	modelChanged(Element e) Respond to underlying changes in this widget's model.
void	paint() Default paint() method for a widget is to draw in peer's Graphics Context.
void	paint(java.awt.Graphics g) Each widget must contain the logic to visually represent itself into the given Graphics context.
void	paint(java.awt.Graphics g, java.awt.Rectangle clip) Each widget must contain the logic to visually represent itself into the given Graphics context.
abstract void	redraw() Redraws the view from the model.
void	refresh() Refresh is an optimized command that only redraws the widget if it is dirty.
void	refresh(java.awt.Rectangle clip) Refresh is an optimized command that only redraws the widget if it is dirty.
boolean	returnWidget(Widget w) Each Widget presents the graphical representation of an entity element.
void	setBounds(int x, int y, int width, int height) Set the graphical bounds for this widget within the Container.
void	setBounds(java.awt.Rectangle r) Set the graphical bounds for this widget within the Container using a Rectangle.
void	setContainer(Container container) All Widget objects need to know the Container within which they will be made visible.
void	setDirty(boolean newDirty) Determines whether this widget's screen representation needs to be recalculated.
void	setHeight(int newHeight) Set the height of this widget.
void	setImage(java.awt.Image newImage) To update the image as shown by this widget, the subclass will create an off-screen image and call this method.
void	setMouseAdapter(java.awt.event.MouseAdapter ma) Alter the way in which this Widget reacts to MouseEvents.
void	setMouseManager(MouseManager mm) Set the aggregate entity that consolidates MouseAdapter and MouseMotionAdapter.
void	setMouseMotionAdapter(java.awt.event.MouseMotionAdapter ma) Alter the way in which this Widget's MouseManager reacts to MouseMotion events.
void	setName(java.lang.String newName) Set the name for this Widget.
void	setUndoAdapter(UndoAdapter ua) Alter the way in which this Widget reacts to UndoRequested events.
void	setWidth(int newWidth) Set the width of this Widget.
void	setX(int newX) Set the X position of the widget.
void	setXY(int x, int y) Set the (x,y) position of the widget.
void	setY(int newY) Set the Y position of the widget.
java.lang.String	toString() Return String representation of the given View Widget.
java.awt.Point	translate(java.awt.Point p) Return new Point object that translates p into local widget coordinates.

Methods inherited from class java.lang.Object

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

Constructor Detail

Widget

public Widget(Element me)

Default constructor for Widgets. Used as super() within subclasses' constructors. Since V1.6.8 check for null argument.

Parameters:

me - ks.common.model.Element

Method Detail

getBounds

public java.awt.Rectangle getBounds()

Return the bounds of the Widget as a newly instantiated rectangle.

Returns:

java.awt.Rectangle

getContainer

public Container getContainer()

Return the container for this Widget.

Returns:

java.awt.Component

getHeight

public int getHeight()

Return the height of the widget.

Returns:

int

getImage

public java.awt.Image getImage()

Return the image of this Widget (used for drawing the Widget on screen).

Returns:

java.awt.Image

getModelElement

public Element getModelElement()

Return the Model Element associated with this Widget.

Returns:

ks.common.model.Element

getMouseManager

public MouseManager getMouseManager()

Return the MouseManager associated with this Widget.

At some point in the future, this manager will return boolean to signal whether it processed the event or not. This will allow us to produce a layered approach to controllers. Develop MouseMotionController, MouseController in controller package just for this purpose.

Returns:

ks.common.view.MouseManager

getCardImages

public CardImages getCardImages()

Return the Cards of this widget.

Returns:

CardImages

getName

public java.lang.String getName()

Return the name of this widget.

Returns:

String

getWidth

public int getWidth()

Return the width of the widget.

Returns:

int

getX

public int getX()

Return the x coordinate for the Widget's location.

Returns:

int

getXY

public java.awt.Point getXY()

Return the (x,y) coordinates of top-left corner of Widget as a Point.

Returns:

java.awt.Point

getY

public int getY()

Return the y coordinate for the Widget's location.

Returns:

int

inBounds

public boolean inBounds(java.awt.Point p)

If (x,y) point is within this widget, return true, else false.

Parameters:

p - java.awt.Point

Returns:

boolean

isDirty

public boolean isDirty()

Determine whether this widget needs to be recalculated.

Returns:

boolean

modelChanged

public void modelChanged(Element e)

Respond to underlying changes in this widget's model.

See ElementListener.

Specified by:

modelChanged in interface ElementListener

Parameters:

e - ks.common.model.Element

paint

public void paint()

Default paint() method for a widget is to draw in peer's Graphics Context. Paint is an imperative command that forces the widget to draw itself.

If no Container is associated with this widget, an IllegalArgumentException is thrown. Creation date: (10/1/01 7:33:33 PM)

paint

public void paint(java.awt.Graphics g)

Each widget must contain the logic to visually represent itself into the given Graphics context. Paint is an imperative command that forces the widget to draw itself.

If the widget is dirty, or if it has never been drawn before, then it is redrawn before being painted to the screen, and is marked as clean.

Parameters:

g - java.awt.Graphics

paint

public void paint(java.awt.Graphics g,
                  java.awt.Rectangle clip)

Each widget must contain the logic to visually represent itself into the given Graphics context. Paint is an imperative command that forces the widget to draw itself.

Clip to this clip rectangle [clip is unaffected by this invocation.]

If the widget is dirty, or if it has never been drawn before, then it is redrawn before being painted to the screen. Because this method only paints within the specified clipping region, we are unable to definitively assert that the widget is clean, so the dirty status of the Widget is unaffected by this method invocation.

Parameters:

g - java.awt.Graphics

clip - java.awt.Rectangle

redraw

public abstract void redraw()

Redraws the view from the model. Each subclass must contain the specific logic.

refresh

public void refresh()

Refresh is an optimized command that only redraws the widget if it is dirty.

refresh

public void refresh(java.awt.Rectangle clip)

Refresh is an optimized command that only redraws the widget if it is dirty.

Clip to the specified rectangle [clip is unaffected.]

Parameters:

clip - java.awt.Rectangle

returnWidget

public boolean returnWidget(Widget w)

Each Widget presents the graphical representation of an entity element. It also provides basic mechanisms for extracting Cards or other structures of Cards from this underlying element. There is no standard means for doing this extraction, but this method can be used to undo such an extraction. For example, if on mousePress, a widget were to extract the topmost card from its column and make it available for dragging as a CardView, then this returnWidget() method would return the card back onto the underlying Column.

This method as provided returns true in all cases; simply override it in your Widget subclass as you deem appropriate.

This method will only work if the extraction methods, shown above, actually call the setDragSource() on the container when the initial extraction takes place.

Parameters:

w - ks.common.view.Widget

Returns:

boolean

Since:

V1.6

setBounds

public void setBounds(int x,
                      int y,
                      int width,
                      int height)

Set the graphical bounds for this widget within the Container.

Parameters:

x - int

y - int

width - int

height - int

setBounds

public void setBounds(java.awt.Rectangle r)

Set the graphical bounds for this widget within the Container using a Rectangle.

Parameters:

r - java.awt.Rectangle

setContainer

public void setContainer(Container container)

All Widget objects need to know the Container within which they will be made visible. This enables the widget to create an offscreen image whenever it needs to, by asking the container to do it for itself!

This method sets the cards field so that the widget knows the cards to be used for drawing.

Parameters:

container - Container

Since:

V2.1, the Container has determined its card images before widgets are added; here we just get the card images from the Container.

setDirty

public void setDirty(boolean newDirty)

Determines whether this widget's screen representation needs to be recalculated.

Parameters:

newDirty - boolean

setHeight

public void setHeight(int newHeight)

Set the height of this widget.

Parameters:

newHeight - int

setImage

public void setImage(java.awt.Image newImage)

To update the image as shown by this widget, the subclass will create an off-screen image and call this method. But, someone will ultimately have to call refresh once done.

This sets the dirty state of the Widget.

Parameters:

newImage - java.awt.Image

setMouseAdapter

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

Alter the way in which this Widget reacts to MouseEvents.

Add our own MouseController so we can return boolean values.

Parameters:

ma - java.awt.event.MouseAdapter

setMouseManager

public void setMouseManager(MouseManager mm)

Set the aggregate entity that consolidates MouseAdapter and MouseMotionAdapter.

Add our own Controllers so we can return boolean values.

Parameters:

mm - MouseManager

setMouseMotionAdapter

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

Alter the way in which this Widget's MouseManager reacts to MouseMotion events.

Add our own MouseMotionController

Parameters:

ma - java.awt.event.MouseMotionAdapter

setName

public void setName(java.lang.String newName)

Set the name for this Widget.

Parameters:

newName - java.lang.String

setUndoAdapter

public void setUndoAdapter(UndoAdapter ua)

Alter the way in which this Widget reacts to UndoRequested events.

Change this to be UndoController to be consistent with everything else in the universe!

Parameters:

ua - java.awt.event.UndoAdapter

setWidth

public void setWidth(int newWidth)

Set the width of this Widget.

Parameters:

newWidth - int

setX

public void setX(int newX)

Set the X position of the widget.

Parameters:

newX - int

setXY

public void setXY(int x,
                  int y)

Set the (x,y) position of the widget.

Parameters:

x - int

y - int

setY

public void setY(int newY)

Set the Y position of the widget.

Parameters:

newY - int

toString

public java.lang.String toString()

Return String representation of the given View Widget.

If this method is called on the EmptyWidget, then "[EMPTYWIDGET]" is returned.

Returns:

String

translate

public java.awt.Point translate(java.awt.Point p)

Return new Point object that translates p into local widget coordinates.

Parameters:

p - java.awt.Point

Returns:

java.awt.Point