edu.umd.cs.jazz
Class ZDrawingSurface

java.lang.Object
  |
  +--edu.umd.cs.jazz.ZDrawingSurface

All Implemented Interfaces:

java.awt.print.Printable, java.io.Serializable

public class ZDrawingSurface

extends java.lang.Object

implements java.awt.print.Printable, java.io.Serializable

ZDrawingSurface represents the thing the camera renders onto. Typically, a drawing surface will be associated with a ZCanvas window. However, a drawing surface can also represent a printer, and thus rendering to a window and printer is implemented in the same way. The drawing surface is associated with a window or printer by specifying which Graphics2D to render onto.

Warning: Serialized and ZSerialized objects of this class will not be compatible with future Jazz releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Jazz. A future release of Jazz will provide support for long term persistence.

Author:

Benjamin B. Bederson

, Britt McAlister , Maria E. Jump

See Also:

ZNode, Serialized Form

RENDER_QUALITY_LOW

public static final int RENDER_QUALITY_LOW

See Also:

Constant Field Values

RENDER_QUALITY_MEDIUM

public static final int RENDER_QUALITY_MEDIUM

See Also:

Constant Field Values

RENDER_QUALITY_HIGH

public static final int RENDER_QUALITY_HIGH

See Also:

Constant Field Values

DEFAULT_HALO

public static final int DEFAULT_HALO

Number of pixels a point can miss an object and still pick it.

See Also:

Constant Field Values

ZDrawingSurface

public ZDrawingSurface()

Constructs a new Surface. Surfaces are associated with a top-level camera and serve as the surface onto which the camera projects.

ZDrawingSurface

public ZDrawingSurface(ZCamera camera,
                       ZNode cameraNode)

Constructs a new Surface, containing the given camera and associated camera node. Surfaces are always associated with a scenegraph, but are not attached to any output device (such as a window or a portal) to start. If this surface is attached to a window, then its component must be set with setComponent(javax.swing.JComponent)

Parameters:

cameraNode - The node the camera is attached to

ZDrawingSurface

public ZDrawingSurface(ZCamera camera,
                       ZNode cameraNode,
                       javax.swing.JComponent aComponent)

Constructs a new Surface, containing the given camera and associated camera node, along with a JComponent this surface is connected to. Surfaces are always associated with a scenegraph, but are not attached to any output device (such as a window or a portal) to start.

Parameters:

cameraNode - The node the camera is attached to

aComponent - The component this surface is connected to

setRenderQuality

public void setRenderQuality(int qualityRequested)

Specify that future rendering should occur at the specified quality. All rendering occurs at this quality except for when the surface is being interacted with or animated in which case it uses the interactingRenderQuality.

Parameters:

qualityRequested - Can be RENDER_QUALITY_LOW, RENDER_QUALITY_MEDIUM or RENDER_QUALITY_HIGH.

See Also:

setInteractingRenderQuality(int)

getRenderQuality

public int getRenderQuality()

Determine the render quality that is used when not interacting or animating.

Returns:

the normal render quality. Can be RENDER_QUALITY_LOW, RENDER_QUALITY_MEDIUM or RENDER_QUALITY_HIGH.

setInteractingRenderQuality

public void setInteractingRenderQuality(int qualityRequested)

Specify the render quality to be used during interaction and animation.

Parameters:

qualityRequested - Can be RENDER_QUALITY_LOW, RENDER_QUALITY_MEDIUM or RENDER_QUALITY_HIGH.

getInteractingRenderQuality

public int getInteractingRenderQuality()

Determine the render quality that is used during interaction and animation.

setUseFractionalMetrics

public void setUseFractionalMetrics(boolean useFractionalMetrics)

If set to true, then the fractional font metrics rendering hint is turned on. Note that this causes problems with editing Swing text components on the jazz surface since these components rely on integer math (as of JDK 1.4.0)

Parameters:

useFractionalMetrics - Are fractional metrics requested

getUseFractionalMetrics

public boolean getUseFractionalMetrics()

Get whether fraction metrics will be used

Returns:

Get whether fractional metrics will be used

getComponent

public javax.swing.JComponent getComponent()

Get the component that this surface is attached to, or null if none.

Returns:

The component this surface is attached to, or null if none.

setComponent

public void setComponent(javax.swing.JComponent aComponent)

Set the component that this surface is attached to, or null if none.

Parameters:

aComponent - The component this surface is attached to, or null if none.

setCamera

public void setCamera(ZCamera cam,
                      ZNode camNode)

Sets the camera that this surface is rendered with.

Parameters:

cam - The new camera

camNode - The camera's node

getCamera

public ZCamera getCamera()

Get the camera this surface is associated with.

Returns:

the camera this surface is associated with.

getCameraNode

public ZNode getCameraNode()

Get the camera node this surface is associated with.

Returns:

the camera node this surface is associated with.

isInteracting

public boolean isInteracting()

Determine if the user interacting with the surface

Returns:

true if the user is interacting with the surface, false otherwise.

setInteracting

public void setInteracting(boolean v)

Specify if the user is interacting with the surface or not. Typically, event handlers will set this to true on a button press event, and to false on a button release event. This allows Jazz to change the render quality to favor speed during interaction, and quality when not interacting.

Parameters:

v - true if the user is interacting with the surface, false otherwise.

repaint

public void repaint()

A utility function to repaint the entire component. This results in request being queued for the entire component to be painted. The paint does not happen immediately, but instead occurs when the queued request comes to the head of the Swing event queue and is fired.

paint

public void paint(java.awt.Graphics g)

Paints the camera this surface sees.

paintImmediately

public void paintImmediately()

Force this surface to immediately paint any regions that are out of date and marked for future repainting.

pick

public ZSceneGraphPath pick(int x,
                            int y)

Returns the path to the first object intersecting the specified rectangle within DEFAULT_HALO pixels as searched in reverse (front-to-back) order, or null if no objects satisfy criteria. If no object is picked, then the path contains just the top-level camera as a terminal object.

Parameters:

x - X-coord of pick point in window coordinates.

y - Y-coord of pick point in window coordinates.

Returns:

The ZSceneGraphPath to the picked object.

pick

public ZSceneGraphPath pick(int x,
                            int y,
                            int halo)

Returns the path to the first object intersecting the specified rectangle within halo pixels as searched in reverse (front-to-back) order, or null if no objects satisfy criteria. If no object is picked, then the path contains just the top-level camera as a terminal object.

Parameters:

x - X-coord of pick point in window coordinates.

y - Y-coord of pick point in window coordinates.

halo - The amount the point can miss an object and still pick it

Returns:

The ZSceneGraphPath to the picked object.

findNodes

public java.util.ArrayList findNodes(ZFindFilter filter)

Return the list of nodes that are accepted by the specified filter in the portion of the scenegraph visible within the camera attached to this surface. If a node is not "findable", then neither that node, nor any of its descendants will be included. The filter specifies whether or not a given node should be accepted by this search, and whether the children of a node should be searched.

Parameters:

filter - The filter that decides whether or not to include individual nodes in the find list

Returns:

The nodes found

See Also:

ZNode.isFindable(), ZFindFilter

printSurface

public void printSurface()

Constructs a new PrinterJob, allows the user to select which printer to print to, and prints the surface.

print

public int print(java.awt.Graphics graphics,
                 java.awt.print.PageFormat pageFormat,
                 int pageIndex)

Prints the surface into the specified Graphics context in the specified format. A PrinterJob calls the printable interface to request that a surface be rendered into the context specified by the graphics. The format of the page to be drawn is specified by PageFormat. The zero based index of the requested page is specified by pageIndex. If the requested page does not exist then this method returns NO_SUCH_PAGE; otherwise PAGE_EXISTS is returned. If the printable object aborts the print job then it throws a PrinterException

Specified by:

print in interface java.awt.print.Printable

Parameters:

graphics - the context into which the page is drawn

pageFormat - the size and orientation of the page being drawn

pageIndex - the zero based index of the page to be drawn

dump

public java.lang.String dump()

Generate a string that represents this object for debugging.

Returns:

the string that represents this object for debugging

See Also:

ZDebug.dump(edu.umd.cs.jazz.ZNode)