- * The basic design here is to add a PCamera as the child of a Pnode (the lens + * The basic design here is to add a PCamera as the child of a PNode (the lens * node). The camera is the viewing part of the lens, and the node is the title * bar that can be used to move the lens around. Users of this lens will * probably want to set up some lens specific event handler and attach it to the @@ -64,18 +64,26 @@ public class PLens extends PNode { private static final long serialVersionUID = 1L; - public static double LENS_DRAGBAR_HEIGHT = 20; - public static Paint DEFAULT_DRAGBAR_PAINT = Color.DARK_GRAY; - public static Paint DEFAULT_LENS_PAINT = Color.LIGHT_GRAY; - private final PPath dragBar; private final PCamera camera; - private transient final PDragEventHandler lensDragger; + private final transient PDragEventHandler lensDragger; + /** The height of the drag bar. */ + public static double LENS_DRAGBAR_HEIGHT = 20; + + /** Default paint to use for the drag bar. */ + public static Paint DEFAULT_DRAGBAR_PAINT = Color.DARK_GRAY; + + /** Default paint to use when drawing the background of the lens. */ + public static Paint DEFAULT_LENS_PAINT = Color.LIGHT_GRAY; + + /** + * Constructs the default PLens. + */ public PLens() { // Drag bar gets resized to fit the available space, so any rectangle // will do here - dragBar = PPath.createRectangle(0, 0, 100, 100); + dragBar = PPath.createRectangle(0, 0, 1, 1); dragBar.setPaint(DEFAULT_DRAGBAR_PAINT); // This forces drag events to percolate up to PLens object dragBar.setPickable(false); @@ -100,33 +108,66 @@ }); } + /** + * Creates the default PLens and attaches the given layer to it. + * + * @param layer layer to attach to this PLens + */ public PLens(final PLayer layer) { this(); addLayer(0, layer); } + /** + * Returns the camera on which this lens is appearing. + * + * @return camera on which lens is appearing + */ public PCamera getCamera() { return camera; } + /** + * Returns the drag bar for this lens. + * + * @return this lens' drag bar + */ public PPath getDragBar() { return dragBar; } + /** + * Returns the event handler that this lens uses for its drag bar. + * + * @return drag bar's drag event handler + */ public PDragEventHandler getLensDraggerHandler() { return lensDragger; } + /** + * Adds the layer to the camera. + * + * @param index index at which to add the layer to the camera + * @param layer layer to add to the camera + */ public void addLayer(final int index, final PLayer layer) { camera.addLayer(index, layer); } + /** + * Removes the provided layer from the camera. + * + * @param layer layer to be removed + */ public void removeLayer(final PLayer layer) { camera.removeLayer(layer); } - // when the lens is resized this method gives us a chance to layout the - // lenses camera child appropriately. + /** + * When the lens is resized this method gives us a chance to layout the + * lenses camera child appropriately. + */ protected void layoutChildren() { dragBar.setPathToRectangle((float) getX(), (float) getY(), (float) getWidth(), (float) LENS_DRAGBAR_HEIGHT); camera.setBounds(getX(), getY() + LENS_DRAGBAR_HEIGHT, getWidth(), getHeight() - LENS_DRAGBAR_HEIGHT); diff --git a/extras/src/main/java/edu/umd/cs/piccolox/pswing/PComboBox.java b/extras/src/main/java/edu/umd/cs/piccolox/pswing/PComboBox.java index c65433b..ac88526 100644 --- a/extras/src/main/java/edu/umd/cs/piccolox/pswing/PComboBox.java +++ b/extras/src/main/java/edu/umd/cs/piccolox/pswing/PComboBox.java @@ -94,7 +94,7 @@ * * @param items The items to populate the PComboBox list */ - public PComboBox(final Object items[]) { + public PComboBox(final Object[] items) { super(items); init(); } @@ -110,7 +110,7 @@ } /** - * Create an empty PComboBox + * Create an empty PComboBox. */ public PComboBox() { super(); @@ -118,7 +118,7 @@ } /** - * Substitue our UI for the default + * Substitute our UI for the default. */ private void init() { setUI(new PBasicComboBoxUI()); @@ -128,23 +128,25 @@ * Clients must set the PSwing and PSwingCanvas environment for this * PComboBox to work properly. * - * @param pSwing - * @param canvas + * @param pSwingNode node that this PComboBox is attached to + * @param canvasEnvirnoment canvas on which the pSwing node is embedded */ - public void setEnvironment(final PSwing pSwing, final PSwingCanvas canvas) { - this.pSwing = pSwing; - this.canvas = canvas; + public void setEnvironment(final PSwing pSwingNode, final PSwingCanvas canvasEnvirnoment) { + this.pSwing = pSwingNode; + this.canvas = canvasEnvirnoment; } /** * The substitute look and feel - used to capture the mouse events on the * arrowButton and the component itself and to create our PopupMenu rather - * than the default + * than the default. */ protected class PBasicComboBoxUI extends BasicComboBoxUI { /** - * Create our Popup instead of theirs + * Create our Popup instead of swing's default. + * + * @return a new ComboPopup */ protected ComboPopup createPopup() { final PBasicComboPopup popup = new PBasicComboPopup(comboBox); @@ -154,24 +156,23 @@ } /** - * The substitute ComboPopupMenu that places itself correctly in Piccolo. + * The substitute ComboPopupMenu that places itself correctly in Piccolo2d. */ protected class PBasicComboPopup extends BasicComboPopup { - - /** - * - */ private static final long serialVersionUID = 1L; /** - * @param combo The parent ComboBox + * Creates a PBasicComboPopup that will position itself correctly in + * relation to the provided JComboBox. + * + * @param combo The associated ComboBox */ public PBasicComboPopup(final JComboBox combo) { super(combo); } /** - * Computes the bounds for the Popup in Piccolo if a PMouseEvent has + * Computes the bounds for the Popup in Piccolo2D if a PMouseEvent has * been received. Otherwise, it uses the default algorithm for placing * the popup. * @@ -200,10 +201,20 @@ return r1c; } + /** + * Returns the associated PSwing node. + * + * @return associated PSwing node + */ public PSwing getPSwing() { return pSwing; } + /** + * Returns the canvas on which the PSwing node is embedded. + * + * @return canvas on which the PSwing node is embedded + */ public PSwingCanvas getCanvas() { return canvas; } diff --git a/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwing.java b/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwing.java index 76e9789..e2b9185 100644 --- a/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwing.java +++ b/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwing.java @@ -150,7 +150,7 @@ */ /** - * PSwing is used to add Swing Components to a Piccolo canvas. + * PSwing is used to add Swing Components to a Piccolo2D canvas. *
* Example: adding a swing JButton to a PCanvas: * @@ -159,8 +159,8 @@ * JButton button = new JButton("Button"); * swing = new PSwing(canvas, button); * canvas.getLayer().addChild(swing); + * * - *
* ** NOTE: PSwing has the current limitation that it does not listen for Container @@ -190,10 +190,10 @@ *
** Warning: Serialized objects of this class will not be compatible with - * future Piccolo releases. The current serialization support is appropriate for - * short term storage or RMI between applications running the same version of - * Piccolo. A future release of Piccolo will provide support for long term - * persistence. + * future Piccolo2D releases. The current serialization support is appropriate + * for short term storage or RMI between applications running the same version + * of Piccolo2D. A future release of Piccolo2D will provide support for long + * term persistence. *
* * @author Sam R. Reid @@ -247,7 +247,7 @@ private final List listeningTo = new ArrayList(); /* The parent listener for camera/canvas changes. */ - private transient final PropertyChangeListener parentListener = new PropertyChangeListener() { + private final transient PropertyChangeListener parentListener = new PropertyChangeListener() { /** {@inheritDoc} */ public void propertyChange(final PropertyChangeEvent evt) { final PNode parent = (PNode) evt.getNewValue(); @@ -296,7 +296,12 @@ listenForCanvas(this); } - /** @deprecated by {@link PSwing(JComponent)} */ + /** + * @deprecated by {@link PSwing(JComponent)} + * + * @param swingCanvas canvas on which the PSwing node will be embedded + * @param component not used + */ public PSwing(final PSwingCanvas swingCanvas, final JComponent component) { this(component); } @@ -480,7 +485,7 @@ * Repaints the specified portion of this visual component. Note that the * input parameter may be modified as a result of this call. * - * @param repaintBounds + * @param repaintBounds bounds needing repainting */ public void repaint(final PBounds repaintBounds) { final Shape sh = getTransform().createTransformedShape(repaintBounds); @@ -634,7 +639,7 @@ /** * Clear out all the listeners registered to make sure there are no stray - * references + * references. * * @param fromParent Parent to start with for clearing listeners */ diff --git a/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingCanvas.java b/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingCanvas.java index 2d68151..0727fb6 100644 --- a/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingCanvas.java +++ b/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingCanvas.java @@ -45,6 +45,7 @@ */ public class PSwingCanvas extends PCanvas { private static final long serialVersionUID = 1L; + /** Key used to store the "Swing Wrapper" as an attribute of the PSwing node. */ public static final String SWING_WRAPPER_KEY = "Swing Wrapper"; private final ChildWrapper swingWrapper; diff --git a/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingEvent.java b/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingEvent.java index f63af63..a91c335 100644 --- a/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingEvent.java +++ b/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingEvent.java @@ -11,6 +11,10 @@ import edu.umd.cs.piccolo.PNode; import edu.umd.cs.piccolo.util.PPickPath; +/** + * Interface allowing PSwing events that originated from swing and are destined + * for PSwing nodes must conform to. + */ public interface PSwingEvent { /** * Returns the x,y position of the event in the local coordinate system of @@ -109,11 +113,11 @@ void dispatchTo(Object listener); /** - * Set the souce of this event. As the event is fired up the tree the source - * of the event will keep changing to reflect the scenegraph object that is - * firing the event. + * Set the source of this event. As the event is fired up the tree the + * source of the event will keep changing to reflect the scenegraph object + * that is firing the event. * - * @param aSource + * @param aSource the source of the event */ void setSource(Object aSource); diff --git a/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingEventHandler.java b/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingEventHandler.java index a58729c..1277755 100644 --- a/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingEventHandler.java +++ b/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingEventHandler.java @@ -57,8 +57,8 @@ * @author Sam Reid */ public class PSwingEventHandler implements PInputEventListener { - /** Used to listen for events */ - private PNode listenNode = null; + /** Used to listen for events. */ + private PNode listenNode = null; /** Tracks whether this event handler is active. */ private boolean active = false; @@ -75,7 +75,8 @@ /** Previous offset used for mouseEntered and exited events. */ private Point2D previousOffset = null; - private boolean recursing = false;// to avoid accidental recursive handling + /** Used to avoid accidental recursive handling. */ + private boolean recursing = false; /** Used for tracking the left button's state. */ private final ButtonData leftButtonData = new ButtonData(); @@ -94,7 +95,7 @@ * will receive the mouse events. * * @param canvas the canvas associated with this PSwingEventHandler. - * @param node the node the mouse listeners will be attached to. + * @param listenNode the node the mouse listeners will be attached to. */ public PSwingEventHandler(final PSwingCanvas canvas, final PNode listenNode) { this.canvas = canvas; @@ -103,6 +104,8 @@ /** * Constructs a new PSwingEventHandler for the given canvas. + * + * @param canvas to associate this event handler to */ public PSwingEventHandler(final PSwingCanvas canvas) { this.canvas = canvas; @@ -111,7 +114,7 @@ /** * Sets whether this event handler can fire events. * - * @param active + * @param active true if thie event handler can fire events */ void setActive(final boolean active) { if (this.active && !active) { @@ -129,19 +132,20 @@ /** * Returns if this event handler is active. * - * @return True if active + * @return true if can fire events */ public boolean isActive() { return active; } /** - * Finds the component at the specified location (must be showing). + * Finds the best visible component or subcomponent at the specified + * location. * - * @param component - * @param x - * @param y - * @return the component at the specified location. + * @param component component to test children or self for + * @param x x component of location + * @param y y component of location + * @return the component or subcomponent at the specified location. */ private Component findShowingComponentAt(final Component component, final int x, final int y) { if (!component.contains(x, y)) { @@ -176,17 +180,18 @@ } } } + return null; } /** - * Determines if any Swing components in Piccolo should receive the given + * Determines if any Swing components in Piccolo2D should receive the given * MouseEvent and forwards the event to that component. However, * mouseEntered and mouseExited are independent of the buttons. Also, notice * the notes on mouseEntered and mouseExited. * - * @param pSwingMouseEvent - * @param aEvent + * @param pSwingMouseEvent event being dispatched + * @param aEvent Piccolo2D event translation of the pSwingMouseEvent */ void dispatchEvent(final PSwingEvent pSwingMouseEvent, final PInputEvent aEvent) { final MouseEvent mEvent = pSwingMouseEvent.asMouseEvent(); @@ -365,8 +370,7 @@ private void handleButton(final PSwingEvent e1, final PInputEvent aEvent, final ButtonData buttonData) { final MouseEvent m1 = e1.asMouseEvent(); if (involvesSceneNode(buttonData)) { - // TODO: this probably won't handle viewing through multiple - // cameras. + // TODO: this probably won't handle viewing through multiple cameras. final Point2D pt = new Point2D.Double(m1.getX(), m1.getY()); cameraToLocal(e1.getPath().getTopCamera(), pt, buttonData.getPNode()); @@ -455,11 +459,11 @@ } /** - * Process a piccolo event and (if active) dispatch the corresponding Swing + * Process a Piccolo2D event and (if active) dispatch the corresponding Swing * event. * - * @param aEvent - * @param type + * @param aEvent Piccolo2D event being testing for dispatch to swing + * @param type is not used in this method */ public void processEvent(final PInputEvent aEvent, final int type) { if (aEvent.isMouseEvent()) { diff --git a/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingMouseEvent.java b/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingMouseEvent.java index 9e8cc6f..7197cfc 100644 --- a/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingMouseEvent.java +++ b/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingMouseEvent.java @@ -47,11 +47,13 @@ *
@@ -64,10 +66,10 @@ *
** Warning: Serialized objects of this class will not be compatible with - * future Piccolo releases. The current serialization support is appropriate for - * short term storage or RMI between applications running the same version of - * Piccolo. A future release of Piccolo will provide support for long term - * persistence. + * future Piccolo2d releases. The current serialization support is appropriate + * for short term storage or RMI between applications running the same version + * of Piccolo2d. A future release of Piccolo2d will provide support for long + * term persistence. *
* * @author Benjamin B. Bederson @@ -75,25 +77,24 @@ * @author Lance E. Good */ public class PSwingMouseEvent extends MouseEvent implements Serializable, PSwingEvent { - /** - * - */ private static final long serialVersionUID = 1L; private final int id; - private transient final PInputEvent event; + private final transient PInputEvent event; /** * Constructs a new PMouse event from a Java MouseEvent. * * @param id The event type (MOUSE_PRESSED, MOUSE_RELEASED, MOUSE_CLICKED, * MOUSE_ENTERED, MOUSE_EXITED) - * @param e The original Java mouse event when in MOUSE_RELEASED events. + * @param swingEvent The original swing mouse event when in MOUSE_RELEASED + * events. + * @param piccoloEvent used to query about the event's Piccolo context */ - protected PSwingMouseEvent(final int id, final MouseEvent e, final PInputEvent event) { - super((Component) e.getSource(), e.getID(), e.getWhen(), e.getModifiers(), e.getX(), e.getY(), e - .getClickCount(), e.isPopupTrigger()); + protected PSwingMouseEvent(final int id, final MouseEvent swingEvent, final PInputEvent piccoloEvent) { + super((Component) swingEvent.getSource(), swingEvent.getID(), swingEvent.getWhen(), swingEvent.getModifiers(), + swingEvent.getX(), swingEvent.getY(), swingEvent.getClickCount(), swingEvent.isPopupTrigger()); this.id = id; - this.event = event; + this.event = piccoloEvent; } /** @@ -101,18 +102,21 @@ * * @param id The event type (MOUSE_PRESSED, MOUSE_RELEASED, MOUSE_CLICKED, * MOUSE_ENTERED, MOUSE_EXITED, MOUSE_MOVED, MOUSE_DRAGGED) - * @param e The original Java mouse event when in MOUSE_DRAGGED and - * MOUSE_RELEASED events. + * @param swingEvent The original swing mouse event when in + * MOUSE_DRAGGED and MOUSE_RELEASED events. + * @param pEvent used to query about the event's Piccolo2d context + * + * @return the constructed PSwingEvent */ - public static PSwingEvent createMouseEvent(final int id, final MouseEvent e, final PInputEvent pEvent) { + public static PSwingEvent createMouseEvent(final int id, final MouseEvent swingEvent, final PInputEvent pEvent) { if (id == MouseEvent.MOUSE_MOVED || id == MouseEvent.MOUSE_DRAGGED) { - return new PSwingMouseMotionEvent(id, e, pEvent); + return new PSwingMouseMotionEvent(id, swingEvent, pEvent); } else if (id == MouseEvent.MOUSE_WHEEL) { - return new PSwingMouseWheelEvent(id, (MouseWheelEvent) e, pEvent); + return new PSwingMouseWheelEvent(id, (MouseWheelEvent) swingEvent, pEvent); } else { - return new PSwingMouseEvent(id, e, pEvent); + return new PSwingMouseEvent(id, swingEvent, pEvent); } } @@ -258,12 +262,18 @@ * of the event will keep changing to reflect the scenegraph object that is * firing the event. * - * @param aSource + * @param newSource the currently reported source of the event (will change + * as event is bubbled up) */ - public void setSource(final Object aSource) { - source = aSource; + public void setSource(final Object newSource) { + source = newSource; } + /** + * Returns this PSwingMouseEvent's MouseEvent. + * + * @return underlying mouse event of this PSwingMouseEvent + */ public MouseEvent asMouseEvent() { return this; } diff --git a/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingMouseMotionEvent.java b/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingMouseMotionEvent.java index d55f121..13c751d 100644 --- a/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingMouseMotionEvent.java +++ b/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingMouseMotionEvent.java @@ -77,10 +77,12 @@ * Constructs a new PMouse event from a Java MouseEvent. * * @param id The event type (MOUSE_MOVED, MOUSE_DRAGGED) - * @param e The original Java mouse event when in MOUSE_DRAGGED events. + * @param swingEvent The original Java mouse event when in MOUSE_DRAGGED events + * @param piccoloEvent Piccolo2d event to use when querying about the event's + * piccolo2d context */ - protected PSwingMouseMotionEvent(final int id, final MouseEvent e, final PInputEvent event) { - super(id, e, event); + protected PSwingMouseMotionEvent(final int id, final MouseEvent swingEvent, final PInputEvent piccoloEvent) { + super(id, swingEvent, piccoloEvent); } /** diff --git a/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingMouseWheelEvent.java b/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingMouseWheelEvent.java index d5e4737..8b4bfe5 100644 --- a/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingMouseWheelEvent.java +++ b/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingMouseWheelEvent.java @@ -58,13 +58,16 @@ * Constructs a new PMouseWheel event from a Java MouseWheelEvent. * * @param id The event type (MOUSE_WHEEL) - * @param e The original Java mouse wheel event. + * @param swingEvent The original swing mouse wheel event. + * @param piccoloEvent Piccolo2D event for use when querying about the + * event's piccolo2d context */ - protected PSwingMouseWheelEvent(final int id, final MouseWheelEvent e, final PInputEvent event) { - super((Component) e.getSource(), e.getID(), e.getWhen(), e.getModifiers(), e.getX(), e.getY(), e - .getClickCount(), e.isPopupTrigger(), e.getScrollType(), e.getScrollAmount(), e.getWheelRotation()); + protected PSwingMouseWheelEvent(final int id, final MouseWheelEvent swingEvent, final PInputEvent piccoloEvent) { + super((Component) swingEvent.getSource(), swingEvent.getID(), swingEvent.getWhen(), swingEvent.getModifiers(), + swingEvent.getX(), swingEvent.getY(), swingEvent.getClickCount(), swingEvent.isPopupTrigger(), + swingEvent.getScrollType(), swingEvent.getScrollAmount(), swingEvent.getWheelRotation()); this.id = id; - this.event = event; + this.event = piccoloEvent; } /** @@ -197,10 +200,10 @@ * of the event will keep changing to reflect the scenegraph object that is * firing the event. * - * @param aSource + * @param newSource the current source of the event to report */ - public void setSource(final Object aSource) { - source = aSource; + public void setSource(final Object newSource) { + source = newSource; } /** diff --git a/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingRepaintManager.java b/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingRepaintManager.java index 50960e5..e09a7ad 100644 --- a/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingRepaintManager.java +++ b/extras/src/main/java/edu/umd/cs/piccolox/pswing/PSwingRepaintManager.java @@ -78,7 +78,7 @@ private final Vector paintingComponents = new Vector(); /** - * Locks repaint for a particular (Swing) component displayed by PCanvas + * Locks repaint for a particular (Swing) component displayed by PCanvas. * * @param c The component for which the repaint is to be locked */ @@ -87,7 +87,7 @@ } /** - * Unlocks repaint for a particular (Swing) component displayed by PCanvas + * Unlocks repaint for a particular (Swing) component displayed by PCanvas. * * @param c The component for which the repaint is to be unlocked */ @@ -97,7 +97,7 @@ /** * Returns true if repaint is currently locked for a component and false - * otherwise + * otherwise. * * @param c The component for which the repaint status is desired * @return Whether the component is currently painting diff --git a/extras/src/main/java/edu/umd/cs/piccolox/swing/PCacheCanvas.java b/extras/src/main/java/edu/umd/cs/piccolox/swing/PCacheCanvas.java index 77eee4b..c05e908 100644 --- a/extras/src/main/java/edu/umd/cs/piccolox/swing/PCacheCanvas.java +++ b/extras/src/main/java/edu/umd/cs/piccolox/swing/PCacheCanvas.java @@ -35,16 +35,19 @@ import edu.umd.cs.piccolox.nodes.PCacheCamera; /** - * An extension of PCanvas that automatically installs a PCacheCamera + * An extension of PCanvas that automatically installs a PCacheCamera. * * @author Lance Good */ public class PCacheCanvas extends PCanvas { - /** - * - */ + private static final long serialVersionUID = 1L; + /** + * Creates a default scene with 1 root, 1 layer, and 1 PCacheCamera. + * + * @return constructed scene with PCacheCamera + */ protected PCamera createDefaultCamera() { final PRoot r = new PRoot(); final PLayer l = new PLayer(); diff --git a/extras/src/main/java/edu/umd/cs/piccolox/swing/PDefaultScrollDirector.java b/extras/src/main/java/edu/umd/cs/piccolox/swing/PDefaultScrollDirector.java index 912382c..4019c64 100644 --- a/extras/src/main/java/edu/umd/cs/piccolox/swing/PDefaultScrollDirector.java +++ b/extras/src/main/java/edu/umd/cs/piccolox/swing/PDefaultScrollDirector.java @@ -57,56 +57,44 @@ */ public class PDefaultScrollDirector implements PScrollDirector, PropertyChangeListener { - /** - * The viewport that signals this scroll director - */ + /** The viewport that signals this scroll director. */ protected PViewport viewPort; - /** - * The scrollpane that contains the viewport - */ + /** The scrollpane that contains the viewport. */ protected PScrollPane scrollPane; - /** - * The canvas that this class directs - */ + /** The canvas that this class directs. */ protected PCanvas view; - /** - * The canvas' camera - */ + /** The canvas' camera. */ protected PCamera camera; - /** - * The canvas' root - */ + /** The canvas' root. */ protected PRoot root; - /** - * Flag to indicate when scrolling is currently in progress - */ + /** Flag to indicate when scrolling is currently in progress. */ protected boolean scrollInProgress = false; /** - * The default constructor + * The default constructor. */ public PDefaultScrollDirector() { } /** - * Installs the scroll director and adds the appropriate listeners + * Installs the scroll director and adds the appropriate listeners. * - * @param viewPort The viewport on which this director directs - * @param view The ZCanvas that the viewport looks at + * @param targetViewPort viewport on which this director directs + * @param targetView PCanvas that the viewport looks at */ - public void install(final PViewport viewPort, final PCanvas view) { - scrollPane = (PScrollPane) viewPort.getParent(); - this.viewPort = viewPort; - this.view = view; + public void install(final PViewport targetViewPort, final PCanvas targetView) { + scrollPane = (PScrollPane) targetViewPort.getParent(); + this.viewPort = targetViewPort; + this.view = targetView; - if (view != null) { - camera = view.getCamera(); - root = view.getRoot(); + if (targetView != null) { + camera = targetView.getCamera(); + root = targetView.getRoot(); } if (camera != null) { @@ -122,7 +110,7 @@ } /** - * Uninstall the scroll director from the viewport + * Uninstall the scroll director from the viewport. */ public void unInstall() { viewPort = null; @@ -140,7 +128,7 @@ } /** - * Get the View position given the specified camera bounds + * Get the View position given the specified camera bounds. * * @param viewBounds The bounds for which the view position will be computed * @return The view position @@ -169,7 +157,7 @@ } /** - * Get the size of the view based on the specified camera bounds + * Get the size of the view based on the specified camera bounds. * * @param viewBounds The view bounds for which the view size will be * computed @@ -200,7 +188,7 @@ } /** - * Set the view position in a manner consistent with standardized scrolling + * Set the view position in a manner consistent with standardized scrolling. * * @param x The new x position * @param y The new y position @@ -249,7 +237,9 @@ /** * Invoked when the camera's view changes, or the bounds of the root or - * camera changes + * camera changes. + * + * @param pce property change event to examine */ public void propertyChange(final PropertyChangeEvent pce) { final boolean isRelevantViewEvent = PCamera.PROPERTY_VIEW_TRANSFORM == pce.getPropertyName(); @@ -271,9 +261,9 @@ } /** - * Should the ScrollPane be revalidated. This occurs when either the - * scrollbars are showing and should be remove or are not showing and should - * be added. + * Should the ScrollPane be revalidated. This occurs when either the scroll + * bars are showing and should be remove or are not showing and should be + * added. * * @return Whether the scroll pane should be revalidated */ diff --git a/extras/src/main/java/edu/umd/cs/piccolox/swing/PScrollDirector.java b/extras/src/main/java/edu/umd/cs/piccolox/swing/PScrollDirector.java index cbe8c78..fccba5d 100644 --- a/extras/src/main/java/edu/umd/cs/piccolox/swing/PScrollDirector.java +++ b/extras/src/main/java/edu/umd/cs/piccolox/swing/PScrollDirector.java @@ -44,40 +44,40 @@ public interface PScrollDirector { /** - * Installs the scroll director + * Installs the scroll director. * * @param viewport The viewport on which this director directs * @param view The ZCanvas that the viewport looks at */ - public void install(PViewport viewport, PCanvas view); + void install(PViewport viewport, PCanvas view); /** - * Uninstall the scroll director + * Uninstall the scroll director. */ - public void unInstall(); + void unInstall(); /** - * Get the View position given the specified camera bounds + * Get the View position given the specified camera bounds. * * @param viewBounds The bounds for which the view position will be computed * @return The view position */ - public Point getViewPosition(Rectangle2D viewBounds); + Point getViewPosition(Rectangle2D viewBounds); /** - * Set the view position + * Set the view position. * * @param x The new x position * @param y The new y position */ - public void setViewPosition(double x, double y); + void setViewPosition(double x, double y); /** - * Get the size of the view based on the specified camera bounds + * Get the size of the view based on the specified camera bounds. * * @param viewBounds The view bounds for which the view size will be * computed * @return The view size */ - public Dimension getViewSize(Rectangle2D viewBounds); + Dimension getViewSize(Rectangle2D viewBounds); } diff --git a/extras/src/main/java/edu/umd/cs/piccolox/swing/PScrollPane.java b/extras/src/main/java/edu/umd/cs/piccolox/swing/PScrollPane.java index d334611..5551db8 100644 --- a/extras/src/main/java/edu/umd/cs/piccolox/swing/PScrollPane.java +++ b/extras/src/main/java/edu/umd/cs/piccolox/swing/PScrollPane.java @@ -50,19 +50,21 @@ */ public class PScrollPane extends JScrollPane { - /** - * - */ private static final long serialVersionUID = 1L; - // A reusable null action + /** A reusable null action. */ protected PNullAction nullAction = null; - // Are key actions disabled on this component? + /** Controls whether key actions are disabled on this component. */ protected boolean disableKeyActions = false; /** - * Pass on the constructor info to the super + * Constructs a scollpane for the provided component with the specified + * scrollbar policies. + * + * @param view component being viewed through the scrollpane + * @param vsbPolicy vertical scroll bar policy + * @param hsbPolicy horizontal scroll bar policy */ public PScrollPane(final Component view, final int vsbPolicy, final int hsbPolicy) { super(view, vsbPolicy, hsbPolicy); @@ -74,28 +76,34 @@ } /** - * Pass on the constructor info to the super + * Constructs a scollpane for the provided component. + * + * @param view component being viewed through the scrollpane */ public PScrollPane(final Component view) { this(view, VERTICAL_SCROLLBAR_AS_NEEDED, HORIZONTAL_SCROLLBAR_AS_NEEDED); } /** - * Pass on the constructor info to the super + * Constructs a scollpane not attached to any component with the specified + * scroll bar policies. + * + * @param vsbPolicy vertical scroll bar policy + * @param hsbPolicy horizontal scroll bar policy */ public PScrollPane(final int vsbPolicy, final int hsbPolicy) { this(null, vsbPolicy, hsbPolicy); } /** - * Pass on the constructor info to the super + * Constructs a scollpane not attached to any component. */ public PScrollPane() { this(null, VERTICAL_SCROLLBAR_AS_NEEDED, HORIZONTAL_SCROLLBAR_AS_NEEDED); } /** - * Disable or enable key actions on this PScrollPane + * Disable or enable key actions on this PScrollPane. * * @param disable true disables key actions, false enables key actions */ @@ -111,7 +119,9 @@ } /** - * Sets the UI + * Sets the UI. + * + * @param ui the scroll pane ui to associate with this PScollPane */ public void setUI(final ScrollPaneUI ui) { super.setUI(ui); @@ -126,7 +136,7 @@ /** * Install custom key actions (in place of the Swing defaults) to correctly - * scroll the view + * scroll the view. */ protected void installCustomKeyActions() { final ActionMap map = getActionMap(); @@ -146,7 +156,7 @@ } /** - * Disables key actions on this PScrollPane + * Disables key actions on this PScrollPane. */ protected void disableKeyActions() { final ActionMap map = getActionMap(); @@ -168,9 +178,9 @@ } /** - * Overridden to create the Jazz viewport + * Overridden to create the Piccolo2D viewport. * - * @return The jazz version of the viewport + * @return the Piccolo2D version of the viewport */ protected JViewport createViewport() { return new PViewport(); @@ -178,16 +188,14 @@ /** * Action to scroll left/right/up/down. Modified from - * javax.swing.plaf.basic.BasicScrollPaneUI.ScrollAction + * javax.swing.plaf.basic.BasicScrollPaneUI.ScrollAction. * * Gets the view parameters (position and size) from the Viewport rather * than directly from the view - also only performs its actions when the - * relevant scrollbar is visible + * relevant scrollbar is visible. */ protected static class PScrollAction extends AbstractAction { - /** - * - */ + private static final int MINIMUM_SCROLL_SIZE = 10; private static final long serialVersionUID = 1L; /** Direction to scroll. */ protected int orientation; @@ -196,6 +204,15 @@ /** True indicates a block scroll, otherwise a unit scroll. */ private final boolean block; + /** + * Constructs a scroll action with the given name in the given + * orientiation stated and in the direction provided. + * + * @param name arbitrary name of action + * @param orientation horizontal or vertical + * @param direction 1 indicates scroll down, -1 up + * @param block true if block scroll as opposed to unit + */ protected PScrollAction(final String name, final int orientation, final int direction, final boolean block) { super(name); this.orientation = orientation; @@ -203,77 +220,90 @@ this.block = block; } - public void actionPerformed(final ActionEvent e) { - final JScrollPane scrollpane = (JScrollPane) e.getSource(); - // LEG: Modification to only perform these actions if the relevant - // scrollbar is actually showing - if (orientation == SwingConstants.VERTICAL && scrollpane.getVerticalScrollBar().isShowing() - || orientation == SwingConstants.HORIZONTAL && scrollpane.getHorizontalScrollBar().isShowing()) { + /** + * Performs the scroll action if the action was performed on visible + * scrollbars and if the viewport is valid. + * + * @param event the event responsible for this action being performed + */ + public void actionPerformed(final ActionEvent event) { + final JScrollPane scrollpane = (JScrollPane) event.getSource(); + if (!isScrollEventOnVisibleScrollbars(scrollpane)) { + return; + } - final JViewport vp = scrollpane.getViewport(); - Component view; - if (vp != null && (view = vp.getView()) != null) { - final Rectangle visRect = vp.getViewRect(); - // LEG: Modification to query the viewport for the - // view size rather than going directly to the view - final Dimension vSize = vp.getViewSize(); - int amount; + final JViewport vp = scrollpane.getViewport(); + if (vp == null) { + return; + } - if (view instanceof Scrollable) { - if (block) { - amount = ((Scrollable) view).getScrollableBlockIncrement(visRect, orientation, direction); - } - else { - amount = ((Scrollable) view).getScrollableUnitIncrement(visRect, orientation, direction); - } - } - else { - if (block) { - if (orientation == SwingConstants.VERTICAL) { - amount = visRect.height; - } - else { - amount = visRect.width; - } - } - else { - amount = 10; - } - } - if (orientation == SwingConstants.VERTICAL) { - visRect.y += amount * direction; - if (visRect.y + visRect.height > vSize.height) { - visRect.y = Math.max(0, vSize.height - visRect.height); - } - else if (visRect.y < 0) { - visRect.y = 0; - } - } - else { - visRect.x += amount * direction; - if (visRect.x + visRect.width > vSize.width) { - visRect.x = Math.max(0, vSize.width - visRect.width); - } - else if (visRect.x < 0) { - visRect.x = 0; - } - } - vp.setViewPosition(visRect.getLocation()); + Component view = vp.getView(); + if (view == null) { + return; + } + + final Rectangle visRect = vp.getViewRect(); + // LEG: Modification to query the viewport for the + // view size rather than going directly to the view + final Dimension vSize = vp.getViewSize(); + final int amount; + + if (view instanceof Scrollable) { + if (block) { + amount = ((Scrollable) view).getScrollableBlockIncrement(visRect, orientation, direction); + } + else { + amount = ((Scrollable) view).getScrollableUnitIncrement(visRect, orientation, direction); } } + else { + if (block) { + if (orientation == SwingConstants.VERTICAL) { + amount = visRect.height; + } + else { + amount = visRect.width; + } + } + else { + amount = MINIMUM_SCROLL_SIZE; + } + } + + if (orientation == SwingConstants.VERTICAL) { + visRect.y += amount * direction; + if (visRect.y + visRect.height > vSize.height) { + visRect.y = Math.max(0, vSize.height - visRect.height); + } + else if (visRect.y < 0) { + visRect.y = 0; + } + } + else { + visRect.x += amount * direction; + if (visRect.x + visRect.width > vSize.width) { + visRect.x = Math.max(0, vSize.width - visRect.width); + } + else if (visRect.x < 0) { + visRect.x = 0; + } + } + vp.setViewPosition(visRect.getLocation()); + } + + private boolean isScrollEventOnVisibleScrollbars(final JScrollPane scrollpane) { + return orientation == SwingConstants.VERTICAL && scrollpane.getVerticalScrollBar().isShowing() + || orientation == SwingConstants.HORIZONTAL && scrollpane.getHorizontalScrollBar().isShowing(); } } /** * Action to scroll to x,y location of 0,0. Modified from - * javax.swing.plaf.basic.BasicScrollPaneUI.ScrollEndAction + * javax.swing.plaf.basic.BasicScrollPaneUI.ScrollEndAction. * - * Only performs the event if a scrollbar is visible + * Only performs the event if a scrollbar is visible. */ private static class PScrollHomeAction extends AbstractAction { - /** - * - */ private static final long serialVersionUID = 1L; protected PScrollHomeAction(final String name) { @@ -295,23 +325,30 @@ /** * Action to scroll to last visible location. Modified from - * javax.swing.plaf.basic.BasicScrollPaneUI.ScrollEndAction + * javax.swing.plaf.basic.BasicScrollPaneUI.ScrollEndAction. * * Gets the view size from the viewport rather than directly from the view - - * also only performs the event if a scrollbar is visible + * also only performs the event if a scrollbar is visible. */ protected static class PScrollEndAction extends AbstractAction { - /** - * - */ private static final long serialVersionUID = 1L; + /** + * Constructs a scroll to end action with the given name. + * + * @param name name to assign to this action + */ protected PScrollEndAction(final String name) { super(name); } - public void actionPerformed(final ActionEvent e) { - final JScrollPane scrollpane = (JScrollPane) e.getSource(); + /** + * Scrolls to the end of the viewport if there are visible scrollbars. + * + * @param event event responsible for the scroll event + */ + public void actionPerformed(final ActionEvent event) { + final JScrollPane scrollpane = (JScrollPane) event.getSource(); // LEG: Modification to only perform these actions if one of the // scrollbars is actually showing if (scrollpane.getVerticalScrollBar().isShowing() || scrollpane.getHorizontalScrollBar().isShowing()) { @@ -331,14 +368,16 @@ /** * An action to do nothing - put into an action map to keep it from looking - * to its parent + * to its parent. */ protected static class PNullAction extends AbstractAction { - /** - * - */ private static final long serialVersionUID = 1L; + /** + * Does nothing. + * + * @param e Event responsible for this action + */ public void actionPerformed(final ActionEvent e) { } }