t3.portfolios
Class Portfolio

java.lang.Object
  extended by t3.portfolios.Portfolio
Direct Known Subclasses:
JotterPortfolio, PlainPortfolio, RootPortfolio, SwingFramePortfolio

public abstract class Portfolio
extends java.lang.Object

A portfolio consists of a tile (an image of a specified size displayed on the display surface) (optional) and zero or more child portfolios. It is sized, oriented and positioned on the desk surface with respect to its parent. You can subclass it and override callback methods to specify event handlers and a paint procedure.

None of these methods are thread safe. You should call them only either from a callback method, or from code running in portfolioServer.peformActionAsynchronously(...).

Coordinate spaces:

Making sense of the coordinate spaces:

There are methods to set the portfolio's position, orientation and size, either relative to its parent portfolio or absolutely on the display surface.

Visibility is also defined relative to the parent portfolio: if the parent portfolio is hidden then this portfolio is also hidden. If the parent portfolio is visible then this protfolio can be either hidden or visible.

Tiles are drawn onto the display surface in the following order: this portfolio's own tile is at the bottom; we recurse on the children portfolios, drawing their tiles and links on top; and then any PortfolioLinks from this portfolio are drawn on top of that.

The event model is described in the javadoc for PortfolioServer.

If you wish to call any of Portfolio's methods from code outside of portfolio callback methods then you must use performActionAsynchronouslyByCurrentThread, as described in the javadoc for PortfolioServer.

Author:
pjt40

Field Summary
 java.util.List<Portfolio> childrenTopToBottomReadOnly
           
 PortfolioCommonBehaviour commonBehaviour
           
static int FLAG_PREALLOCATE_IMAGE_BUFFERS
           
static int FLAG_USES_UNWARPED_RECTANGLES
           
 int portfolioFlags
           
 java.util.List<PortfolioLink> portfolioLinksFromThisReadOnly
           
 PortfolioServer portfolioServer
           
 int tileUpdateCompressionHints
           
static java.util.ArrayList<IdentifyUnwarpedRects.UnwarpedRect> unwarpedRectLinesList
           
static java.util.ArrayList<IdentifyUnwarpedRects.UnwarpedRect> unwarpedRectWordsList
           
 
Constructor Summary
Portfolio(boolean isRoot, PortfolioServer portfolioServer, Portfolio parent, PortfolioCommonBehaviour commonBehaviour, boolean hasTile, int tileWidth, int tileHeight, int tileFlags, int portfolioFlags)
          Creates a new Portfolio, using sensible default values for unwarped rectangle identification.
Portfolio(boolean isRoot, PortfolioServer portfolioServer, Portfolio parent, PortfolioCommonBehaviour commonBehaviour, boolean hasTile, int tileWidth, int tileHeight, int tileFlags, int portfolioFlags, int hereld_minw, int hereld_maxw, int hereld_minh, int hereld_maxh, int hereld_contrastThresh)
           
 
Method Summary
 void bringChildrenToFront(java.util.List<Portfolio> newChildrenTopToBottom)
          Sets the new child order, which governs the order in which tiles appear on the display surface.
 void bringChildToFront(Portfolio c)
          Sets the new child order, which governs the order in which tiles appear on the display surface.
 java.awt.image.BufferedImage createCompatibleBufferedImage(int w, int h)
          Creates a BufferedImage in a format compatible with this portfolio's tile.
protected  void customProcessAboutToBeDestroyed()
          Called when the portfolio is about to be destroyed.
protected abstract  void customProcessEndOfFDOPmode(PointInputDevice pid, int button)
          Implement this method to be notified when a PID stops being in FDOP mode.
protected abstract  boolean customProcessEventForThisPortfolioNotChildren(PortfolioEvent e, boolean bubbled)
          Implement this method to receive events.
protected abstract  void customProcessFDOPevent(PortfolioEvent e, double PORTxWhenEnteredFDOPmode, double PORTyWhenEnteredFDOPmode)
          Implement this method to receive FDOP mode events.
abstract  void customRepaintTileForThisPortfolioNotChildren(java.awt.Rectangle r, java.awt.image.BufferedImage update, java.awt.Graphics2D g)
          Implement this method to draw into the portfolio's tile.
 void destroyThisAndAllDescendants()
          Destroys the portfolio and all its descendents.
 java.util.List<Portfolio> getAnscestorsList()
          Returns a list of all this portfolio's anscestors in order with this portfolio's parent at the head of the list and the root portfolio at the tail.
 java.util.Set<Portfolio> getAnscestorsSet()
          Returns a set containing all this portfolio's anscestors.
 java.awt.geom.GeneralPath getGpDESKoutlineOfOurTile()
          Returns the bounding box, in the coordinate space of the display surface, of this portfolio's tile.
 boolean getIntegerTileSpaceCoordsFromDESK(int[] intTileSpaceCoords, double[] dDESK)
          Converts coordinates from the coordinate space of the desk into the coordinate space of this portfolio's tile, rounding to the nearest integer.
 Jama.Matrix getmDESKtoPORTReadOnly()
          Returns the transform from the display surface's coordinate space to this portfolio's coordinate space.
 Jama.Matrix getmDESKtoTILE()
          Returns as a 3x3 matrix the transform from the coordinate space of the display surface to the coordinate space of this portfolio's tile.
 Portfolio getParent()
          Returns the parent portfolio, or throws an exception if this is the root portfolio.
 Portfolio getPortfolioAtCoordinates(double DESKx, double DESKy)
          Returns the portfolio corresponding to the topmost tile at the given coordinates or null if no such tile belongs to this portfolio or its anscestors.
 java.awt.geom.Rectangle2D getRDESKboundingBoxOfOurTile()
          Returns the bounding box, in the coordinate space of the display surface, of this portfolio's tile.
 java.awt.geom.Rectangle2D getRDESKboundingBoxOfOurTileAndAllDescendantsTiles()
          Returns the bounding box, in the coordinate space of the display surface, of this portfolio's tile and of all its descendents tiles.
 java.util.List<Portfolio> getThisAndAnscestorsList()
          Returns a list of this portfolio and all its anscestors in order with this portfolio at the head of the list and the root portfolio at the tail.
 java.util.Set<Portfolio> getThisAndAnscestorsSet()
          Returns a set containing this portfolio and all its anscestors.
 double getTileHeightInPORT()
          Get the height of this portfolio's tile, relative to this portfolio's coordinate space.
 int getTileHeightInTILE()
          Returns the height of this portfolio's tile, in tile space, i.e.
 double getTileWidthInPORT()
          Get the width of this portfolio's tile, relative to this portfolio's coordinate space.
 int getTileWidthInTILE()
          Returns the width of this portfolio's tile, in tile space, i.e.
 ScaRotTraTransformImmutableUniformScale gettPORTtoDESK()
          Returns the transform from this portfolio's coordinate space to the display surface's coordinate space.
 ScaRotTraTransformImmutableUniformScale gettPORTtoPPORT()
          Returns the transform from this portfolio's coordinate space to its parent portfolio's coordinate space.
 double[] getUd2PORTfromUd2DESK(double[] ud2DESK)
          Converts coordinates from the coordinate space of the desk into the coordinate space of this portfolio.
 boolean getVisibileWhenParentVisible()
          Returns true iff this portfolio would be visible supposing its parent portfolio is visible.
 boolean getVisibility()
          Returns true iff this portfolio is currently visible.
 boolean hasTile()
          Returns true iff this portfolio has a tile.
 boolean isDestroyed()
          Returns true iff this portfolio has been destroyed.
 boolean isRoot()
          Returns true iff this is the root portfolio.
 void setChildToPosition(Portfolio child, int newIndexTopToBottom)
           
 void setDESKtoPORT(Jama.Matrix mDESKtoPORT)
          Set this portfolio's coordinate space relative to the display surface's coordinate space.
 void setNewChildrenOrder(java.util.List<Portfolio> newChildrenTopToBottom)
          Sets the new child order, which governs the order in which tiles appear on the display surface.
 void setPORTtoDESK(ScaRotTraTransformImmutableUniformScale tPORTtoDESK)
          Set this portfolio's coordinate space as a scaled, rotated and translated version of the display surface's coordinate space.
 void setPORTtoPPORT(ScaRotTraTransformImmutableUniformScale tPORTtoPPORT)
          Set this portfolio's coordinate space as a scaled, rotated and translated version of the its parent portfolio's coordinate space.
 void setTileWidthAndHeightInPORT(double tileWidthInPORT, double tileHeightInPORT)
          Specify the width and height of this portfolio's tile, relative to this portfolio's coordinate space.
 void setVisibleWhenParentVisible(boolean v)
          Sets the visibility of this portfolio relative to its parent.
 void triggerRepaintEntireTile()
          Triggers a repaint of this portfolio's whole tile.
 void triggerRepaintTile(java.awt.Rectangle r)
          Triggers a repaint of a specified region of this portfolio's whole tile.
 void triggerRepaintTile(java.awt.Rectangle r, int recomputeUnwarpedRects)
          Triggers a repaint of a specified region of this portfolio's whole tile.
 void triggerRepaintTileByCopyingFromOtherPortfoliosTile(int sx, int sy, int dx, int dy, int w, int h, Portfolio source)
          Triggers a repaint of a specified region of this portfolio's whole tile by copying a region from another portfolio's tile.
 void unhookFromParentAndMakeChildOf(Portfolio p)
          Changes the ancestry tree so that this portfolio becomes a parent of the specified portfolio.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

unwarpedRectWordsList

public static final java.util.ArrayList<IdentifyUnwarpedRects.UnwarpedRect> unwarpedRectWordsList

unwarpedRectLinesList

public static final java.util.ArrayList<IdentifyUnwarpedRects.UnwarpedRect> unwarpedRectLinesList

portfolioServer

public final PortfolioServer portfolioServer

childrenTopToBottomReadOnly

public java.util.List<Portfolio> childrenTopToBottomReadOnly

portfolioLinksFromThisReadOnly

public final java.util.List<PortfolioLink> portfolioLinksFromThisReadOnly

commonBehaviour

public final PortfolioCommonBehaviour commonBehaviour

tileUpdateCompressionHints

public int tileUpdateCompressionHints

portfolioFlags

public final int portfolioFlags

FLAG_USES_UNWARPED_RECTANGLES

public static final int FLAG_USES_UNWARPED_RECTANGLES
See Also:
Constant Field Values

FLAG_PREALLOCATE_IMAGE_BUFFERS

public static final int FLAG_PREALLOCATE_IMAGE_BUFFERS
See Also:
Constant Field Values
Constructor Detail

Portfolio

public Portfolio(boolean isRoot,
                 PortfolioServer portfolioServer,
                 Portfolio parent,
                 PortfolioCommonBehaviour commonBehaviour,
                 boolean hasTile,
                 int tileWidth,
                 int tileHeight,
                 int tileFlags,
                 int portfolioFlags)
Creates a new Portfolio, using sensible default values for unwarped rectangle identification.

Parameters:
isRoot - Should be false unless this is the root portfolio.
parent - The parent portfolio. This must not be null unless you are creating a root portfolio.
commonBehaviour - Specifies behaviour common across many portfolios, such as dragging.
hasTile - True iff the portfolio has an associated tile.
tileWidth - The tile width in pixels.
tileHeight - The tile height in pixels.
tileFlags - Tile flags. See t3.hrd.state.Tile for details. Specifying as 0 should do most of the time.
portfolioFlags -

Portfolio

public Portfolio(boolean isRoot,
                 PortfolioServer portfolioServer,
                 Portfolio parent,
                 PortfolioCommonBehaviour commonBehaviour,
                 boolean hasTile,
                 int tileWidth,
                 int tileHeight,
                 int tileFlags,
                 int portfolioFlags,
                 int hereld_minw,
                 int hereld_maxw,
                 int hereld_minh,
                 int hereld_maxh,
                 int hereld_contrastThresh)
Parameters:
isRoot - Should be false unless this is the root portfolio.
portfolioServer - The PortfolioServer which you wish to create the portfolio.
parent - The parent portfolio. This must not be null unless you are creating a root portfolio.
commonBehaviour - Specifies behaviour common across many portfolios, such as dragging.
hasTile - True iff the portfolio has an associated tile.
tileWidth - The tile width in pixels.
tileHeight - The tile height in pixels.
tileFlags - Tile flags. See t3.hrd.state.Tile for details. Specifying as 0 should do most of the time.
usesUnwarpedRects - True iff the tile should use unwarped rectangles for improved legibility.
hereld_areaMax - Maximum unwarped rectangles area in pixels for identifying unwarped rectangles.
hereld_areaMin - Minimum unwarped rectangles area in pixels for identifying unwarped rectangles.
hereld_contrastThresh - Contrast threshold for identifying unwarped rectangles.
Method Detail

isRoot

public final boolean isRoot()
Returns true iff this is the root portfolio.

Returns:

getParent

public final Portfolio getParent()
Returns the parent portfolio, or throws an exception if this is the root portfolio.

Returns:

getThisAndAnscestorsList

public final java.util.List<Portfolio> getThisAndAnscestorsList()
Returns a list of this portfolio and all its anscestors in order with this portfolio at the head of the list and the root portfolio at the tail.

Returns:

getThisAndAnscestorsSet

public final java.util.Set<Portfolio> getThisAndAnscestorsSet()
Returns a set containing this portfolio and all its anscestors.

Returns:

getAnscestorsList

public final java.util.List<Portfolio> getAnscestorsList()
Returns a list of all this portfolio's anscestors in order with this portfolio's parent at the head of the list and the root portfolio at the tail.

Returns:

getAnscestorsSet

public final java.util.Set<Portfolio> getAnscestorsSet()
Returns a set containing all this portfolio's anscestors.

Returns:

unhookFromParentAndMakeChildOf

public final void unhookFromParentAndMakeChildOf(Portfolio p)
Changes the ancestry tree so that this portfolio becomes a parent of the specified portfolio.

Parameters:
p -

getPortfolioAtCoordinates

public final Portfolio getPortfolioAtCoordinates(double DESKx,
                                                 double DESKy)
Returns the portfolio corresponding to the topmost tile at the given coordinates or null if no such tile belongs to this portfolio or its anscestors.

Parameters:
DESKx -
DESKy -
Returns:

bringChildToFront

public final void bringChildToFront(Portfolio c)
Sets the new child order, which governs the order in which tiles appear on the display surface. The specified portfolio will be brought to the front.

Parameters:
c -

bringChildrenToFront

public final void bringChildrenToFront(java.util.List<Portfolio> newChildrenTopToBottom)
Sets the new child order, which governs the order in which tiles appear on the display surface. The specified list must contain each child at most once. Omitted children will appear behind the specified children and their relative ordering will be preserved.

Parameters:
newChildrenTopToBottom -

setNewChildrenOrder

public final void setNewChildrenOrder(java.util.List<Portfolio> newChildrenTopToBottom)
Sets the new child order, which governs the order in which tiles appear on the display surface. The specified list must contain each child exactly once.

Parameters:
newChildrenTopToBottom -

setChildToPosition

public final void setChildToPosition(Portfolio child,
                                     int newIndexTopToBottom)

destroyThisAndAllDescendants

public final void destroyThisAndAllDescendants()
Destroys the portfolio and all its descendents.


isDestroyed

public final boolean isDestroyed()
Returns true iff this portfolio has been destroyed.

Returns:

setVisibleWhenParentVisible

public final void setVisibleWhenParentVisible(boolean v)
Sets the visibility of this portfolio relative to its parent.

Parameters:
v -

getVisibility

public final boolean getVisibility()
Returns true iff this portfolio is currently visible.

Returns:

getVisibileWhenParentVisible

public final boolean getVisibileWhenParentVisible()
Returns true iff this portfolio would be visible supposing its parent portfolio is visible.

Returns:

setDESKtoPORT

public final void setDESKtoPORT(Jama.Matrix mDESKtoPORT)
Set this portfolio's coordinate space relative to the display surface's coordinate space.

Parameters:
mDESKtoPORT -

setPORTtoDESK

public final void setPORTtoDESK(ScaRotTraTransformImmutableUniformScale tPORTtoDESK)
Set this portfolio's coordinate space as a scaled, rotated and translated version of the display surface's coordinate space.

Parameters:
tPORTtoDESK -

setPORTtoPPORT

public final void setPORTtoPPORT(ScaRotTraTransformImmutableUniformScale tPORTtoPPORT)
Set this portfolio's coordinate space as a scaled, rotated and translated version of the its parent portfolio's coordinate space.

Parameters:
tPORTtoPPORT -

gettPORTtoDESK

public final ScaRotTraTransformImmutableUniformScale gettPORTtoDESK()
Returns the transform from this portfolio's coordinate space to the display surface's coordinate space.

Returns:

getmDESKtoPORTReadOnly

public final Jama.Matrix getmDESKtoPORTReadOnly()
Returns the transform from the display surface's coordinate space to this portfolio's coordinate space.

Returns:

gettPORTtoPPORT

public final ScaRotTraTransformImmutableUniformScale gettPORTtoPPORT()
Returns the transform from this portfolio's coordinate space to its parent portfolio's coordinate space.

Returns:

getRDESKboundingBoxOfOurTileAndAllDescendantsTiles

public final java.awt.geom.Rectangle2D getRDESKboundingBoxOfOurTileAndAllDescendantsTiles()
Returns the bounding box, in the coordinate space of the display surface, of this portfolio's tile and of all its descendents tiles. If no area then it returns a rectangle with no area, so beware when unioning - you may need to use a special union function that ignores zero-area rectangles.

Returns:

getRDESKboundingBoxOfOurTile

public final java.awt.geom.Rectangle2D getRDESKboundingBoxOfOurTile()
Returns the bounding box, in the coordinate space of the display surface, of this portfolio's tile.

Returns:

getGpDESKoutlineOfOurTile

public final java.awt.geom.GeneralPath getGpDESKoutlineOfOurTile()
Returns the bounding box, in the coordinate space of the display surface, of this portfolio's tile.

Returns:

getUd2PORTfromUd2DESK

public final double[] getUd2PORTfromUd2DESK(double[] ud2DESK)
Converts coordinates from the coordinate space of the desk into the coordinate space of this portfolio. Coordinates are unhomogenous in a double array with two elements.

Parameters:
ud2DESK -
Returns:

setTileWidthAndHeightInPORT

public final void setTileWidthAndHeightInPORT(double tileWidthInPORT,
                                              double tileHeightInPORT)
Specify the width and height of this portfolio's tile, relative to this portfolio's coordinate space.

Parameters:
tileWidthInPORT -
tileHeightInPORT -

getTileWidthInPORT

public final double getTileWidthInPORT()
Get the width of this portfolio's tile, relative to this portfolio's coordinate space.


getTileHeightInPORT

public final double getTileHeightInPORT()
Get the height of this portfolio's tile, relative to this portfolio's coordinate space.


hasTile

public final boolean hasTile()
Returns true iff this portfolio has a tile.

Returns:

getTileWidthInTILE

public final int getTileWidthInTILE()
Returns the width of this portfolio's tile, in tile space, i.e. the width of the tile image in pixels.

Returns:

getTileHeightInTILE

public final int getTileHeightInTILE()
Returns the height of this portfolio's tile, in tile space, i.e. the height of the tile image in pixels.

Returns:

getIntegerTileSpaceCoordsFromDESK

public final boolean getIntegerTileSpaceCoordsFromDESK(int[] intTileSpaceCoords,
                                                       double[] dDESK)
Converts coordinates from the coordinate space of the desk into the coordinate space of this portfolio's tile, rounding to the nearest integer. Coordinates are unhomogenous in an array with two elements.

Parameters:
ud2DESK -
Returns:

createCompatibleBufferedImage

public final java.awt.image.BufferedImage createCompatibleBufferedImage(int w,
                                                                        int h)
Creates a BufferedImage in a format compatible with this portfolio's tile.

Parameters:
w -
h -
Returns:

triggerRepaintEntireTile

public final void triggerRepaintEntireTile()
Triggers a repaint of this portfolio's whole tile. The repaint callback will be called.


triggerRepaintTile

public final void triggerRepaintTile(java.awt.Rectangle r)
Triggers a repaint of a specified region of this portfolio's whole tile. The repaint callback will be called. If the tile uses unwarped rectangles then these are recomputed.

Parameters:
r -

triggerRepaintTile

public final void triggerRepaintTile(java.awt.Rectangle r,
                                     int recomputeUnwarpedRects)
Triggers a repaint of a specified region of this portfolio's whole tile. The repaint callback will be called.

Parameters:
r -
recomputeUnwarpedRects - (0=use same unwarped rects as before, 1=remove old unwarped rects, 2=remove old unwarped rects and recompute new ones.)

triggerRepaintTileByCopyingFromOtherPortfoliosTile

public final void triggerRepaintTileByCopyingFromOtherPortfoliosTile(int sx,
                                                                     int sy,
                                                                     int dx,
                                                                     int dy,
                                                                     int w,
                                                                     int h,
                                                                     Portfolio source)
Triggers a repaint of a specified region of this portfolio's whole tile by copying a region from another portfolio's tile. The image data is not sent across the network - the copy takes place at the actual clients, so this is more efficient than calling triggerRepaintTile. The region is copied pixel for pixel. The repaint callback will be not be called.

Parameters:
r -

getmDESKtoTILE

public final Jama.Matrix getmDESKtoTILE()
Returns as a 3x3 matrix the transform from the coordinate space of the display surface to the coordinate space of this portfolio's tile.

Returns:

customRepaintTileForThisPortfolioNotChildren

public abstract void customRepaintTileForThisPortfolioNotChildren(java.awt.Rectangle r,
                                                                  java.awt.image.BufferedImage update,
                                                                  java.awt.Graphics2D g)
Implement this method to draw into the portfolio's tile. The supplied Graphics2D is in the same coordinate space as TILE, with the specified rectangle set to draw into the supplied BufferedImage.

Parameters:
r - rectangle in TILE space that must be redrawn.
update - BufferedImage of same dimensions as r, into which you draw.
g - Graphics2D which is configured to draw into update.

customProcessEventForThisPortfolioNotChildren

protected abstract boolean customProcessEventForThisPortfolioNotChildren(PortfolioEvent e,
                                                                         boolean bubbled)
Implement this method to receive events. See PortfolioServer for more information on the event model. Note that any events handled by this portfolio's PortfolioCommonBehaviour object will not be passed to this method.

Parameters:
e - Event
bubbled - True iff the event did not occur on this portfolio's tile but has been bubbled from one of its children.
Returns:
True iff the event should not be bubbled to this portfolio's parent.

customProcessFDOPevent

protected abstract void customProcessFDOPevent(PortfolioEvent e,
                                               double PORTxWhenEnteredFDOPmode,
                                               double PORTyWhenEnteredFDOPmode)
Implement this method to receive FDOP mode events. See PortfolioServer for more information on the event model. Note that any events handled by this portfolio's PortfolioCommonBehaviour object will not be passed to this method.

Parameters:
e - Event
PORTxWhenEnteredFDOPmode - PORT space coordinate of the PID when it entered FDOP mode.
PORTyWhenEnteredFDOPmode - PORT space coordinate of the PID when it entered FDOP mode.

customProcessEndOfFDOPmode

protected abstract void customProcessEndOfFDOPmode(PointInputDevice pid,
                                                   int button)
Implement this method to be notified when a PID stops being in FDOP mode. See PortfolioServer for more information on the event model. Note that any notifications handled by this portfolio's PortfolioCommonBehaviour object will not be passed to this method.

Parameters:
pid -
button -

customProcessAboutToBeDestroyed

protected void customProcessAboutToBeDestroyed()
Called when the portfolio is about to be destroyed.