edu.stanford.hci.r3.paper
Class Region

java.lang.Object
  edu.stanford.hci.r3.paper.Region

Direct Known Subclasses:

ButtonRegion, CompoundRegion, GraphicsRegion, ImageRegion, PolygonalRegion, TextRegion, XMLRegion

public class Region
extends java.lang.Object

A region is defined by a Shape that outlines the region. Internally, the region remembers the Units that it is represented in. Thus, you may use whatever units pleases you.

Also, a region can be INPUT(REALTIME|BATCH), OUTPUT(REALTIME|INTERMITTENT), or STATIC. This is entirely determined by the type(s) of attachments (input event handlers, input filters, realtime outputs, print output) you add to a region. If you do not add anything, it is by default a STATIC region. For example, if you add an input event handler for a streaming pen, it becomes an INPUT(REALTIME) region. Regions that handle interactive input will automatically be overlaid with pattern when rendered to PDF or to a printer.

Regardless of whether the Shape is closed or not, we assume that all regions are closed Shapes. A rectangular region is represented using this class's Region(4 args) constructors.

This software is distributed under the BSD License.

Field Summary

protected Units	referenceUnits This is used only to interpret the shape's true physical size.
protected double	scaleX Internal horizontal scale of the region.
protected double	scaleY Internal vertical scale of the region.

Constructor Summary

	Region(java.lang.String name, double xInches, double yInches, double wInches, double hInches) For our American friends.
	Region(java.lang.String theName, java.awt.Shape s, Units u)
protected	Region(java.lang.String theName, Units u) A protected constructor so subclasses can assign the shape whichever way they please.
	Region(java.lang.String name, Units x, Units y, Units w, Units h) We will convert all the units to x's type.

Method Summary

void	addEventHandler(EventHandler handler) Keeps track of this event handler.
java.util.List<EventHandler>	getEventHandlers()
java.awt.Color	getFillColor()
Units	getHeight()
java.lang.String	getIsActiveString()
java.lang.String	getName()
double	getOpacity()
Units	getOriginX()
Units	getOriginY()
Sheet	getParentSheet()
RegionRenderer	getRenderer() Subclasses should override this, to customize rendering.
double	getScaleX()
double	getScaleY()
java.awt.Shape	getShape() Subclasses can modify the internal shape object.
java.awt.Color	getStrokeColor()
Units	getUnits() TODO: We should make sure that Units objects immutable if possible.
java.awt.geom.Rectangle2D	getUnscaledBounds2D()
Units	getUnscaledBoundsHeight()
Units	getUnscaledBoundsWidth()
java.awt.Shape	getUnscaledShapeCopy()
Units	getWidth()
boolean	isActive()
boolean	isVisible()
void	resetScale() Resets to the default scaling factors.
void	scaleRegion(double sX, double sY) Scales the points in the current region by a horizontal and vertical multiplier.
void	scaleRegionUniformly(double scale) Resizes the region uniformly in x and y.
void	setActive(boolean isRegionActive)
void	setFillColor(java.awt.Color theFillColor)
void	setName(java.lang.String theName)
void	setOpacity(double theOpacityFrom0To1)
void	setParentSheet(Sheet sheet) For traversing up the UI hierarchy, in Event Visualizations.
void	setScale(double newScaleX, double newScaleY) Replaces the scaling factors.
protected void	setShape(java.awt.Shape s) Subclasses can use this method to set the shape after constructing the object.
void	setStrokeColor(java.awt.Color strokeCol)
void	setVisible(boolean v)
java.lang.String	toString() Please override for more interesting output.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

referenceUnits

protected Units referenceUnits

This is used only to interpret the shape's true physical size. The value of the units object doesn't matter. Only the type of the unit matters.

scaleX

protected double scaleX

Internal horizontal scale of the region. When rendering, we will multiply the shape by this scale. This is only a RECOMMENDATION and not a requirement of the renderer, however, as some regions may not make sense if scaled after the fact. However, we will try to make sure most of our calculations respect this scaling factor.

scaleY

protected double scaleY

Internal vertical scale of the region. When rendering, we will multiply the shape by this scale.

Constructor Detail

Region

public Region(java.lang.String name,
              double xInches,
              double yInches,
              double wInches,
              double hInches)

For our American friends.

Parameters:

xInches -

yInches -

wInches -

hInches -

Region

public Region(java.lang.String theName,
              java.awt.Shape s,
              Units u)

Parameters:

name -

s - the shape that defines this region.

u - the reference unit for interpreting the shape's coordinates

Region

protected Region(java.lang.String theName,
                 Units u)

A protected constructor so subclasses can assign the shape whichever way they please. A Region doesn't really make sense without a shape, so use this constructor carefully (i.e., make sure to assign a sensible shape).

Parameters:

u -

Region

public Region(java.lang.String name,
              Units x,
              Units y,
              Units w,
              Units h)

We will convert all the units to x's type. Thus, if you pass in an Inch, Centimeter, Foot, Points, we will convert everything to Inches. It's OK to keep the x object around, because we only use it to interpret the shape object.

Parameters:

x -

y -

w -

h -

Method Detail

addEventHandler

public void addEventHandler(EventHandler handler)

Keeps track of this event handler. The PaperToolkit will dispatch events to these, whenever the event deals with this region. A particular kind of event handler can be thought of as a "content filter," which will grab input and "change" the meaning of the input in some way. The canonical example is the HandwritingRecognizer, as it will collect ink and then change it into ASCII text.

Parameters:

handler -

getEventHandlers

public java.util.List<EventHandler> getEventHandlers()

Returns:

the event engine will access the event handlers, to invoke events.

getFillColor

public java.awt.Color getFillColor()

Returns:

getHeight

public Units getHeight()

Returns:

the height of the region (or its rectangular bounding box)

getIsActiveString

public java.lang.String getIsActiveString()

Returns:

getName

public java.lang.String getName()

Returns:

getOpacity

public double getOpacity()

Returns:

how opaque this region's background will be. If it's 0, we will not render the background fillColor at all.

getOriginX

public Units getOriginX()

Returns:

getOriginY

public Units getOriginY()

Returns:

getParentSheet

public Sheet getParentSheet()

getRenderer

public RegionRenderer getRenderer()

Subclasses should override this, to customize rendering. Otherwise, you'll just get gray boxes, which is what RegionRenderer does.

Returns:

the renderer for this region

getScaleX

public double getScaleX()

Returns:

getScaleY

public double getScaleY()

Returns:

getShape

public java.awt.Shape getShape()

Subclasses can modify the internal shape object.

Returns:

the internal shape, at your peril.

getStrokeColor

public java.awt.Color getStrokeColor()

getUnits

public Units getUnits()

TODO: We should make sure that Units objects immutable if possible.

Returns:

a pointer to the actual units object.

getUnscaledBounds2D

public java.awt.geom.Rectangle2D getUnscaledBounds2D()

Returns:

a bounds object that represents the UNSCALED internal shape.

getUnscaledBoundsHeight

public Units getUnscaledBoundsHeight()

Returns:

getUnscaledBoundsWidth

public Units getUnscaledBoundsWidth()

Returns:

getUnscaledShapeCopy

public java.awt.Shape getUnscaledShapeCopy()

Returns:

a copy of the internal shape as a Java2D GeneralPath. You should use this with getScaleX/Y to determine the true shape. Alternatively, use getScaledShapeCopy()

getWidth

public Units getWidth()

Returns:

the width of the region (or its rectangular bounding box).

isActive

public boolean isActive()

Returns:

if this region is an active (NON-STATIC) region. This means that upon rendering to PDF/Printer, pattern will be displayed over this region.

isVisible

public boolean isVisible()

Returns:

whether the region will be visible. TODO: The renderer SHOULD respect this flag.

resetScale

public void resetScale()

Resets to the default scaling factors.

scaleRegion

public void scaleRegion(double sX,
                        double sY)

Scales the points in the current region by a horizontal and vertical multiplier.

Parameters:

sX -

sY -

scaleRegionUniformly

public void scaleRegionUniformly(double scale)

Resizes the region uniformly in x and y. We actually just store the number and scale it whenever we need to render the final region. The Lazy Approach. =) This is nice because we can scale the region multiple times without getting aliasing effects.

Parameters:

scale -

setActive

public void setActive(boolean isRegionActive)

Parameters:

isRegionActive - determines whether this will be an active region or not

setFillColor

public void setFillColor(java.awt.Color theFillColor)

Parameters:

theFillColor -

setName

public void setName(java.lang.String theName)

Parameters:

theName - the name of the region. Name it something useful, like "Blue Button for Changing Pen Colors"

setOpacity

public void setOpacity(double theOpacityFrom0To1)

Parameters:

theOpacityFrom0To1 - bounds checked from 0.0 to 1.0

setParentSheet

public void setParentSheet(Sheet sheet)

For traversing up the UI hierarchy, in Event Visualizations.

Parameters:

sheet -

setScale

public void setScale(double newScaleX,
                     double newScaleY)

Replaces the scaling factors.

Parameters:

newScaleX -

newScaleY -

setShape

protected void setShape(java.awt.Shape s)

Subclasses can use this method to set the shape after constructing the object.

Parameters:

s -

setStrokeColor

public void setStrokeColor(java.awt.Color strokeCol)

setVisible

public void setVisible(boolean v)

Parameters:

v - whether the region will be visible

toString

public java.lang.String toString()

Please override for more interesting output. This will print the name of the class along with all the segments of the shape.

Overrides:

toString in class java.lang.Object

Returns:

the String representation of this Region

See Also:

Object.toString()