edu.washington.cs.supple.render
Class WidgetBag

java.lang.Object
  edu.washington.cs.supple.render.WidgetBag

All Implemented Interfaces:

java.lang.Cloneable

public final class WidgetBag

extends java.lang.Object

implements java.lang.Cloneable

Author:

Krzysztof Gajos During rendering process objects of this class are supposed to hold all widget alternatives considered for a given element in the interface hierarchy

Field Summary

protected java.util.Vector	availableWidgets
protected java.util.Vector	changedWidgets
protected java.util.Hashtable	children
protected static float	costConstraint
protected java.util.Vector	currentWidgets
protected UiObject	object
protected WidgetBag	parent
protected java.util.Collection	relevantFactors
protected java.util.Vector	renderingConstraintEnforcers
protected java.util.Vector	renderingHintEnforcers
protected SearchParameters	searchParameters
protected static java.awt.Dimension	sizeConstraint
protected Solution	solution
protected java.util.Stack	stack
protected SuppleType	type

Constructor Summary

WidgetBag(UiObject object, WidgetBag parent, java.util.Collection widgets, SearchParameters searchParameters)

Method Summary

void	addChild(WidgetBag child) Adds a bew child bag to this bag.
protected void	addRenderingConstraintEnforcer(RenderingConstraintEnforcer enforcer) Adds a new rendering constraint enforcer (provided it hasn't been added already)
protected void	addRenderingHintEnforcer(RenderingHintEnforcer enforcer) Adds a new rendering hint enforcer (provided it hasn't been added already)
protected void	changed() Called by the object itself when a significant change occurs (though when a membership change happens, the membershipChanged() method should be called instead).
protected void	childChanged() Clears all the children-related cache data structures and then forwards the call to its parent if it has one
java.util.Enumeration	children()
java.lang.Object	clone() Returns a clone of this WidgetBag (we probably need a deep clone operations so the children hashtable should be populated with clones of the children - KZG)
boolean	equals(java.lang.Object o) Two bags are considered equal if they correspond to the same type
java.util.Vector	getAvailableWidgets()
java.util.Collection	getBagCollection() Returns this widget bag subtree as a collection
WidgetBag	getChild(UiObject object)
java.util.Vector	getChildren()
float	getCost()
static float	getCostConstraint()
java.util.Vector	getCurrentWidgets()
float	getEffortEstimate(ActionDescription a) Computes the worst case effort estimate based on the effort estimates for all possible widgets
protected float	getHintCost(Widget w) Calculates the cost added by all the rendering hints for a given widget
java.awt.Dimension	getMaxChildSize(int hints)
java.awt.Dimension	getMaxChildSize(int hints, java.util.Collection objects) Returns the max size of the specified subset of children
java.awt.Dimension	getMinChildSize(int hints, UiObject child) Returns the min size of the specified child
java.awt.Dimension[]	getMinCombinedChildSize(int hints, UiObject child, AlignedLayoutHelper helper)
java.awt.Dimension[]	getMinCombinedSize(int hints, AlignedLayoutHelper helper) Calculates the minimum size of this element assuming that it is going to end up in an aligned container
java.awt.Dimension	getMinSize(int hints)
int	getNumChildren()
int	getNumCurrentWidgets()
WidgetBag	getParent()
java.util.Vector	getRenderingConstraintEnforcers()
Solution	getSolution() returns the widget tree reflecting the current solution (in fact, it will return the cached solution, care needs to be taken to call resetSolution when search restarts)
protected float	getSumChildCost()
java.awt.Dimension	getSumChildSize(int hints)
java.awt.Dimension	getSumChildSize(int hints, java.util.Collection objects) Returns the sum of the sizes of the specified subset of children
SuppleType	getType()
UiObject	getUiObject()
Widget	getWidget() If the bag is set (i.e.
boolean	hasChildren()
boolean	hasCurrentWidgetsOtherThan(java.lang.Class widgetClass) Checks if the bag is currently considering widgets of types other than the one specified
boolean	hasCurrentWidgetsOtherThan(java.lang.Class[] widgetClasses) Checks if the bag is currently considering widgets of types other than the ones specified
int	hashCode() uses the hashcode of the corresponding type
boolean	isLeaf()
boolean	isRoot()
boolean	isSet() This method lets you check if this bag has been assigned a widget
protected void	membershipChanged() Called when the list of currentWidgets changes; it first calls the changed() method on this bag and then informs all bags linked to this one by rendering hints of the change
int	numChildren()
protected void	popTheStack() Pops the most recent value of current widgets from the stack; if it's different from what we currently have, changed() is called
boolean	propagate(int levels) Prunes the list of current widgets (if necessary); if no widgets are left, failure is reported.
boolean	propagate(int levels, boolean withConstraints) Prunes the list of current widgets (if necessary); it than propagates through the constraints.
boolean	propagate(int levels, boolean withConstraints, boolean pruneByCost) Prunes the list of current widgets (if necessary); it than propagates through the constraints.
protected boolean	propagateConstraints(int levels) propagates explicit rendering constraints (as opposed to the size and cost constraints which are built into the structure of the problem)
protected boolean	prune(boolean pruneByCost) Does prunning of widgets within this bag; if something gets prunned, it calls changed(); If it ends up with an empty set of current widets, it returns false to indicate failure
float	recomputeCost(boolean updateWidgetCosts) Discards the cached cost throughout the subtree rooted at this bag and returns freshly computed cost
void	reset() Prepares all data structures of this bag for a new search
protected void	resetCostCache(boolean updateWidgetCosts) resets the cost cache for this bag and for all of its children
void	resetSolution() forgetting the most recently created solution
void	restoreCurrentWidgets() Restores the list of current widgets to the full set of available widgets
void	restoreCurrentWidgets(java.util.Vector v) Used when the search backtracks and needs to restore the pool of legal widgets
protected boolean	satisfiesConstraints(Widget w)
static void	setCostConstraint(float c) Sets a static variable indicating the maximum allowed cost for the solution
void	setCurrentWidget(Widget w) Used during search process to set the current widget
void	setParent(WidgetBag parent) Sets the parent of this widget bag
static void	setSizeConstraint(java.awt.Dimension constr) For now we shall assume that there is a single size constraint on all components
java.lang.String	toPrettyString(java.lang.String pref)
java.lang.String	toString()
void	undoPropagate(int levels) pops the old state from the stack and asks the parent to do the same
void	undoPropagate(int levels, boolean withConstraints)
void	updateWidgetCosts() Causes the widget bag to recompute costs for all of the widgets (called, for example, when the usage counts are recomputed)
void	widgetCostChanged(Widget w) Called by a widget if its cost changes

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

parent

protected WidgetBag parent

children

protected java.util.Hashtable children

object

protected UiObject object

type

protected SuppleType type

availableWidgets

protected java.util.Vector availableWidgets

currentWidgets

protected java.util.Vector currentWidgets

changedWidgets

protected java.util.Vector changedWidgets

stack

protected java.util.Stack stack

renderingHintEnforcers

protected java.util.Vector renderingHintEnforcers

renderingConstraintEnforcers

protected java.util.Vector renderingConstraintEnforcers

searchParameters

protected SearchParameters searchParameters

relevantFactors

protected java.util.Collection relevantFactors

sizeConstraint

protected static java.awt.Dimension sizeConstraint

costConstraint

protected static float costConstraint

solution

protected Solution solution

Constructor Detail

WidgetBag

public WidgetBag(UiObject object,
                 WidgetBag parent,
                 java.util.Collection widgets,
                 SearchParameters searchParameters)

Parameters:

parent - The parent bag (or null for root)

widgets - possible widgets for this element

searchParameters - the parameters of this search

Method Detail

clone

public java.lang.Object clone()

Returns a clone of this WidgetBag (we probably need a deep clone operations so the children hashtable should be populated with clones of the children - KZG)

reset

public void reset()

Prepares all data structures of this bag for a new search

setSizeConstraint

public static void setSizeConstraint(java.awt.Dimension constr)

For now we shall assume that there is a single size constraint on all components

Parameters:

constr - the max size any component can assume

setCostConstraint

public static void setCostConstraint(float c)

Sets a static variable indicating the maximum allowed cost for the solution

Parameters:

c - maximum cost the entire solution is allowed to incur

getCostConstraint

public static float getCostConstraint()

addRenderingHintEnforcer

protected void addRenderingHintEnforcer(RenderingHintEnforcer enforcer)

Adds a new rendering hint enforcer (provided it hasn't been added already)

Parameters:

enforcer -

addRenderingConstraintEnforcer

protected void addRenderingConstraintEnforcer(RenderingConstraintEnforcer enforcer)

Adds a new rendering constraint enforcer (provided it hasn't been added already)

Parameters:

enforcer -

getRenderingConstraintEnforcers

public java.util.Vector getRenderingConstraintEnforcers()

isRoot

public boolean isRoot()

Returns:

true if this is the root (has no parent); false otherwise

numChildren

public int numChildren()

Returns:

the number of children this bag has

isSet

public boolean isSet()

This method lets you check if this bag has been assigned a widget

Returns:

true if the bag has exactly one current widget, false otherwise

getWidget

public Widget getWidget()

If the bag is set (i.e. has only one current widget), this method will return the widget; otherwise it will return null

Returns:

the current widget

getSolution

public Solution getSolution()

returns the widget tree reflecting the current solution (in fact, it will return the cached solution, care needs to be taken to call resetSolution when search restarts)

Returns:

the widget tree reflecting the current solution.

Throws:

java.lang.RuntimeException - if there is no solution

resetSolution

public void resetSolution()

forgetting the most recently created solution

isLeaf

public boolean isLeaf()

Returns:

true if this a leaf bag (has no children), false otherwise

getParent

public WidgetBag getParent()

Returns:

the parent of this bag or null if root

getChildren

public java.util.Vector getChildren()

Returns:

the children of this bag or null if root

setParent

public void setParent(WidgetBag parent)

Sets the parent of this widget bag

Parameters:

parent - the parent of this widget bag

getType

public SuppleType getType()

Returns:

the type corresponding to this bag

getUiObject

public UiObject getUiObject()

Returns:

the corresponding ui object

getAvailableWidgets

public java.util.Vector getAvailableWidgets()

Returns:

the pointer to the vector holding the available widgets -- do not modify!

getCurrentWidgets

public java.util.Vector getCurrentWidgets()

Returns:

the clone of the vector holding the widgets that still have not been eliminated by the search process

hasCurrentWidgetsOtherThan

public boolean hasCurrentWidgetsOtherThan(java.lang.Class[] widgetClasses)

Checks if the bag is currently considering widgets of types other than the ones specified

Parameters:

widgetClasses - a collection of class objects

Returns:

true if there is a currentWidget that is not of any of the types mentioned in widgetClasses; false otherwise

hasCurrentWidgetsOtherThan

public boolean hasCurrentWidgetsOtherThan(java.lang.Class widgetClass)

Checks if the bag is currently considering widgets of types other than the one specified

Parameters:

widgetClass - a class object

Returns:

true if there is a currentWidget that is not of the type specified; false otherwise

getNumCurrentWidgets

public int getNumCurrentWidgets()

Returns:

the number of widgets still under consideration

setCurrentWidget

public void setCurrentWidget(Widget w)

Used during search process to set the current widget

Parameters:

w - the current widget

restoreCurrentWidgets

public void restoreCurrentWidgets()

Restores the list of current widgets to the full set of available widgets

restoreCurrentWidgets

public void restoreCurrentWidgets(java.util.Vector v)

Used when the search backtracks and needs to restore the pool of legal widgets

Parameters:

v - the old list of valid widgets

getMinSize

public java.awt.Dimension getMinSize(int hints)

Parameters:

hints - Hints specifying the variant of the widgets to be taken into account (see hint for Widget.getSize())

Returns:

the minimum dimensions calculated from the currently available widgets (with compliance to the hints)

getMaxChildSize

public java.awt.Dimension getMaxChildSize(int hints)

Parameters:

hints -

Returns:

returns the max dimensions reported by the child widgetd bags (based on the currently available widgets)

getMaxChildSize

public java.awt.Dimension getMaxChildSize(int hints,
                                          java.util.Collection objects)

Returns the max size of the specified subset of children

Parameters:

hints - rendering hints that should be obeyed when calculating sizes

objects - the list of the subset of children

Returns:

the maximum size of the specified subset of children

getMinCombinedSize

public java.awt.Dimension[] getMinCombinedSize(int hints,
                                               AlignedLayoutHelper helper)

Calculates the minimum size of this element assuming that it is going to end up in an aligned container

Parameters:

hints - extra hints that should be passed to the widgets when querying their sizes

helper - a helper object that will help determine how to treat different widets and how to calculate label size

Returns:

the minimum size this widget will take

getMinCombinedChildSize

public java.awt.Dimension[] getMinCombinedChildSize(int hints,
                                                    UiObject child,
                                                    AlignedLayoutHelper helper)

getMinChildSize

public java.awt.Dimension getMinChildSize(int hints,
                                          UiObject child)

Returns the min size of the specified child

Parameters:

hints - rendering hints that should be obeyed when calculating sizes

child - the child

Returns:

the minimum size of the specified child

getSumChildSize

public java.awt.Dimension getSumChildSize(int hints)

Parameters:

hints -

Returns:

returns the sum of the two dimensions of all the child widget bags

getSumChildSize

public java.awt.Dimension getSumChildSize(int hints,
                                          java.util.Collection objects)

Returns the sum of the sizes of the specified subset of children

Parameters:

hints - rendering hints that should be obeyed when calculating sizes

objects - the list of the subset of children

Returns:

the sum of the sizes of the specified subset of children

getSumChildCost

protected float getSumChildCost()

Returns:

the minimum cost guaranteed to be incurred by the child widget bags

getCost

public float getCost()

Returns:

the current cost of this bag (this includes an estimate of the cost of the children)

updateWidgetCosts

public void updateWidgetCosts()

Causes the widget bag to recompute costs for all of the widgets (called, for example, when the usage counts are recomputed)

recomputeCost

public float recomputeCost(boolean updateWidgetCosts)

Discards the cached cost throughout the subtree rooted at this bag and returns freshly computed cost

Returns:

the current cost

resetCostCache

protected void resetCostCache(boolean updateWidgetCosts)

resets the cost cache for this bag and for all of its children

getHintCost

protected float getHintCost(Widget w)

Calculates the cost added by all the rendering hints for a given widget

Parameters:

w - widget

Returns:

calculated cost due to the rendering hints

getEffortEstimate

public float getEffortEstimate(ActionDescription a)

Computes the worst case effort estimate based on the effort estimates for all possible widgets

Parameters:

a - an action description

Returns:

an effort estimate for this widget bag

propagate

public boolean propagate(int levels)

Prunes the list of current widgets (if necessary); if no widgets are left, failure is reported. If all is well, we call propagate on the parent and return the result.

Parameters:

levels - how many levels to propagate

Returns:

true if everything is still consistent; false if there was a failure

propagate

public boolean propagate(int levels,
                         boolean withConstraints)

Prunes the list of current widgets (if necessary); it than propagates through the constraints. If no widgets are left, failure is reported. If all is well, we call propagate on the parent and return the result.

Parameters:

levels - how many levels to propagate

withConstraints - set it to true if you want the explicit rendering constraints to be propagated as well

Returns:

true if everything is still consistent; false if there was a failure

propagate

public boolean propagate(int levels,
                         boolean withConstraints,
                         boolean pruneByCost)

Prunes the list of current widgets (if necessary); it than propagates through the constraints. If no widgets are left, failure is reported. If all is well, we call propagate on the parent and return the result.

Parameters:

levels - how many levels to propagate

withConstraints - set it to true if you want the explicit rendering constraints to be propagated as well

pruneByCost - set it to true if it is safe to prune widgets that are too expensive (it is generally not safe to do it with shortcuts present)

Returns:

true if everything is still consistent; false if there was a failure

propagateConstraints

protected boolean propagateConstraints(int levels)

propagates explicit rendering constraints (as opposed to the size and cost constraints which are built into the structure of the problem)

Parameters:

levels - how far to propagate

Returns:

false if a violated constraint was reported; true otherwise

prune

protected boolean prune(boolean pruneByCost)

Does prunning of widgets within this bag; if something gets prunned, it calls changed(); If it ends up with an empty set of current widets, it returns false to indicate failure

Parameters:

pruneByCost - set it to true if it is safe to prune widgets that are too expensive (it is generally not safe to do it with shortcuts present)

Returns:

true if there are still widgets left, false otherwise

satisfiesConstraints

protected boolean satisfiesConstraints(Widget w)

popTheStack

protected void popTheStack()

Pops the most recent value of current widgets from the stack; if it's different from what we currently have, changed() is called

undoPropagate

public void undoPropagate(int levels)

pops the old state from the stack and asks the parent to do the same

undoPropagate

public void undoPropagate(int levels,
                          boolean withConstraints)

membershipChanged

protected void membershipChanged()

Called when the list of currentWidgets changes; it first calls the changed() method on this bag and then informs all bags linked to this one by rendering hints of the change

changed

protected void changed()

Called by the object itself when a significant change occurs (though when a membership change happens, the membershipChanged() method should be called instead).

childChanged

protected void childChanged()

Clears all the children-related cache data structures and then forwards the call to its parent if it has one

widgetCostChanged

public void widgetCostChanged(Widget w)

Called by a widget if its cost changes

Parameters:

w - the changed widget

addChild

public void addChild(WidgetBag child)

Adds a bew child bag to this bag. If there already exists a bag for a particular UI object, the old one will be replaced by the new one

Parameters:

child - the child bag to be added

getChild

public WidgetBag getChild(UiObject object)

Parameters:

object - the UI object for which you want a child bag

Returns:

the child widget bag corresponding to object

children

public java.util.Enumeration children()

Returns:

a new vector with all the children of this bag

hasChildren

public boolean hasChildren()

getNumChildren

public int getNumChildren()

getBagCollection

public java.util.Collection getBagCollection()

Returns this widget bag subtree as a collection

equals

public boolean equals(java.lang.Object o)

Two bags are considered equal if they correspond to the same type

See Also:

Object.equals(java.lang.Object)

hashCode

public int hashCode()

uses the hashcode of the corresponding type

See Also:

Object.hashCode()

toString

public java.lang.String toString()

toPrettyString

public java.lang.String toPrettyString(java.lang.String pref)