From 90507904616fd59db2a3dc62defde9e2749f58fb Mon Sep 17 00:00:00 2001 From: Nicolas Carranza Date: Sun, 7 Feb 2016 07:09:52 -0500 Subject: [PATCH] javadoc --- src/main/java/jpen/PLevel.java | 39 +++++--- src/main/java/jpen/PenDevice.java | 2 +- src/main/java/jpen/PenManager.java | 21 +++- src/main/java/jpen/PenProvider.java | 2 + src/main/java/jpen/event/PenListener.java | 1 + .../filter/RelativeLocationFilter.java | 98 ++++++++++--------- src/main/java/jpen/owner/PenOwner.java | 14 ++- src/main/java/jpen/owner/awt/AwtPenOwner.java | 3 + .../jpen/owner/awt/ComponentPenOwner.java | 5 +- 9 files changed, 120 insertions(+), 65 deletions(-) diff --git a/src/main/java/jpen/PLevel.java b/src/main/java/jpen/PLevel.java index 3ef89ee..9f7babf 100644 --- a/src/main/java/jpen/PLevel.java +++ b/src/main/java/jpen/PLevel.java @@ -31,13 +31,15 @@ import static java.lang.Math.*; public class PLevel - extends TypedValuedClass + extends TypedValuedClass implements java.io.Serializable { + private static final Logger L=Logger.getLogger(PLevel.class.getName()); //static{L.setLevel(Level.FINE);} public static final long serialVersionUID=1l; - public enum Type{ + public enum Type { + /** X axis value in pixels. The X axis points to the right of the screen. It's a left handed coordinate system: the Z axis points upside. */ @@ -86,23 +88,28 @@
  • Does the value grow (0 to 1) when the wheel is moved towards the pen tip? TILT_TYPES=Collections.unmodifiableSet(EnumSet.of(TILT_X, TILT_Y)); /** - Evaluates the azimuthX and altitude given the tilt values of the pen. + Evaluates the azimuthX and altitude given the tilt values of the pen, see {@link #evalAzimuthXAndAltitude(double[], double tiltX, double tiltY)}. - @see #evalAzimuthXAndAltitude(double[], double tiltX, double tiltY) + @param azimuthXAndAltitude array where the values (result) are going to be put in + @param pen where the necessary values to do the calculation (tilt values) are read from */ - public static void evalAzimuthXAndAltitude(double[] azimuthXAndAltitude, PenState pen){ + public static void evalAzimuthXAndAltitude(double[] azimuthXAndAltitude, PenState pen) { evalAzimuthXAndAltitude(azimuthXAndAltitude, pen.getLevelValue(TILT_X), pen.getLevelValue(TILT_Y)); } /** Evaluates the azimuthX and the altitude given the tilt ({@link #TILT_X}, {@link #TILT_Y}) values. Where:

    - {@code azimuthX} is the angle between the X axis and the projection of the pen against the X-Y plane. Clockwise direction. Range: -pi/2 and 3*pi/2

    + {@code azimuthX} is the angle between the X axis and the projection of the pen against the X-Y plane. Clockwise direction. Range: -pi/2 and 3*pi/2

    And {@code altitude} is the angle between the pen and the projection of the pen against the X-Y plane. Range: 0 to pi/2. + + @param azimuthXAndAltitude array where the values (result) are going to be put in + @param tiltX tilt value + @param tiltY tilt value */ - public static void evalAzimuthXAndAltitude(double[] azimuthXAndAltitude, double tiltX, double tiltY){ + public static void evalAzimuthXAndAltitude(double[] azimuthXAndAltitude, double tiltX, double tiltY) { if(tiltX<0) azimuthXAndAltitude[0]=PI; - else if(tiltX==0 && tiltY==0){ + else if(tiltX==0 && tiltY==0) { azimuthXAndAltitude[0]=0; azimuthXAndAltitude[1]=PI_over_2; return; @@ -111,26 +118,26 @@ else if(tiltX==0 && tiltY==0){ double tanTiltY=tan(tiltY); azimuthXAndAltitude[0]+=atan(tanTiltY/tan(tiltX)); azimuthXAndAltitude[1]=azimuthXAndAltitude[0]==0? - PI_over_2-tiltX: - Math.abs(atan(sin(azimuthXAndAltitude[0])/tanTiltY)); + PI_over_2-tiltX: + Math.abs(atan(sin(azimuthXAndAltitude[0])/tanTiltY)); } private static final double PI_over_2=PI/2; - - public boolean isMovement(){ + + public boolean isMovement() { return MOVEMENT_TYPES.contains(this); } - - public boolean isTilt(){ + + public boolean isTilt() { return TILT_TYPES.contains(this); } } - public PLevel(PLevel level){ + public PLevel(PLevel level) { this(level.typeNumber, level.value); } - public PLevel(Type type, float value){ + public PLevel(Type type, float value) { this(type.ordinal(), value); } diff --git a/src/main/java/jpen/PenDevice.java b/src/main/java/jpen/PenDevice.java index fe294a5..e6a19d8 100644 --- a/src/main/java/jpen/PenDevice.java +++ b/src/main/java/jpen/PenDevice.java @@ -61,7 +61,7 @@ public interface PenDevice { /** Don't call this method. It is only for use by the {@link PenManager}. This method is called when the provider {@link PenProvider#getUseRelativeLocationFilter()} is {@code true} and this {@code PenDevice} must change its {@code useFractionalMovement} mode. - @see #getUseFractionalMovements() + @param useFractionalMovements new value of {@code useFractionalMovements} to be set, see {@link #getUseFractionalMovements()} */ void penManagerSetUseFractionalMovements(boolean useFractionalMovements); diff --git a/src/main/java/jpen/PenManager.java b/src/main/java/jpen/PenManager.java index 11bb2ec..4458083 100644 --- a/src/main/java/jpen/PenManager.java +++ b/src/main/java/jpen/PenManager.java @@ -79,7 +79,9 @@ private synchronized static void setSingletonMode(boolean singletonMode) { private PenDevice systemMouseDevice; // may be null /** - Creates an {@code AwtPenOwner} and calls the {@link #PenManager(PenOwner)} constructor. Warning: see {@link jpen.owner.awt.AwtPenOwner}. + Creates an {@code AwtPenOwner} and calls the {@link #PenManager(PenOwner)} constructor. Warning: see {@link AwtPenOwner}. + + @param component where {@code PenEvent}s are going to be listened */ public PenManager(Component component) { this(new AwtPenOwner(component)); @@ -267,6 +269,9 @@ public boolean getPaused() { /** Schedules button events. You must construct a new {@code PButton} each time you call this method (do not reuse). + @param device source device + @param deviceTime time of event creation on device + @param button button value */ public void scheduleButtonEvent(PenDevice device, long deviceTime, PButton button) { if(paused) @@ -276,6 +281,10 @@ public void scheduleButtonEvent(PenDevice device, long deviceTime, PButton butto /** Schedules scroll events. You must construct a new {@code PScroll} each time you call this method (do not reuse). + + @param device source device + @param deviceTime time of event creation on device + @param scroll scroll value */ public void scheduleScrollEvent(PenDevice device, long deviceTime, PScroll scroll) { if(paused) @@ -289,6 +298,12 @@ public boolean scheduleLevelEvent(PenDevice device, long deviceTime, Collection< /** Schedules level events. You can reuse the levels {@code Collection} but you must construct new {@code PLevel}s each time you call this method. + + @param device source device + @param deviceTime time of even creation on device + @param levels level values + @param levelsOnScreen {@code true} if the level movement values are on the screen coordinate system, {@code false} otherwise + @return {@code true} if an event was scheduled, {@code false} false if it was filter out */ public boolean scheduleLevelEvent(PenDevice device, long deviceTime, Collection levels, boolean levelsOnScreen) { if(paused) @@ -298,6 +313,10 @@ public boolean scheduleLevelEvent(PenDevice device, long deviceTime, Collection< /** Uses reflection to get the first provider of the given class. + + @param providerClass class of {@link PenProvider} to search for + @param {@code providerClass} parametrization + @return the first {@link PenProvider} matching */ public T getProvider(Class providerClass) { for(PenProvider.Constructor constructor: getProviderConstructors()) { diff --git a/src/main/java/jpen/PenProvider.java b/src/main/java/jpen/PenProvider.java index 3ace284..b36bbf8 100644 --- a/src/main/java/jpen/PenProvider.java +++ b/src/main/java/jpen/PenProvider.java @@ -38,12 +38,14 @@ public interface Constructor { */ String getName(); /** + @param pm where the construction is being requested @return {@code true} if the {@code PenProvider} can be constructed on this system, {@code false} otherwise.This method usually test for the name of the operating system and returns {@code true} if it matches an operating system in which this provider can run. */ boolean constructable(PenManager pm); /** This method constructs the {@code PenProvider}. It is called only when {@link #constructable(PenManager)} returns {@code true}. When this methods completes, it is expected that the {@link #getConstructed()} method returns the {@code PenProvider} constructed. If the {@code PenProvider} couldn't be constructed due to some condition (e.g. the required native drivers are not present) then the {@link #getConstructionException()} method is expected to return an exception describing the condition. + @param pm where the construction is being requested @return {@code true} if the {@code PenProvider} was constructed. {@code false} if the {@code PenProvider} couldn't be constructed. */ boolean construct(PenManager pm); diff --git a/src/main/java/jpen/event/PenListener.java b/src/main/java/jpen/event/PenListener.java index 91888c0..264448b 100644 --- a/src/main/java/jpen/event/PenListener.java +++ b/src/main/java/jpen/event/PenListener.java @@ -30,6 +30,7 @@ Useful to detect if the listeners are taking too much time processing events ({@ The pen fires queued events at a given frequency (by default {@link jpen.Pen#DEFAULT_FREQUENCY}) in its own thread. Each cycle, after firing and processing the events, the pen calls jpen.event.PenListener.penTock(long availableMillis), where availableMillis is the time left of the period: {@code availableMillis=period-firingTime }, {@code period=1000/frequency}, and {@code firingTime} is the time spent in firing and processing events in the cycle.

    This method is called from the event dispatch thread if {@link Pen#getFirePenTockOnSwing()} is {@code true}. + @param availableMillis time of period left after processing events in milliseconds @see Pen#setFirePenTockOnSwing(boolean) */ void penTock(long availableMillis); // TODO: Pen parameter?? diff --git a/src/main/java/jpen/internal/filter/RelativeLocationFilter.java b/src/main/java/jpen/internal/filter/RelativeLocationFilter.java index 309a6f2..52821e6 100644 --- a/src/main/java/jpen/internal/filter/RelativeLocationFilter.java +++ b/src/main/java/jpen/internal/filter/RelativeLocationFilter.java @@ -31,14 +31,16 @@ import jpen.PenState; import jpen.PLevel; -public final class RelativeLocationFilter{ +public final class RelativeLocationFilter { + private static final Logger L=Logger.getLogger(RelativeLocationFilter.class.getName()); //static { L.setLevel(Level.ALL); } private PenDevice penDevice; private State state=State.UNDEFINED; - public enum State{ + public enum State { + /** The filter tries to see if the values are absolute or relative and sets the state if possible. */ @@ -59,16 +61,17 @@ The filter considers the sample values to be in relative mode and replace them w final Point2D.Float reference=new Point2D.Float(); final SamplePoint samplePoint=new SamplePoint(); static class SamplePoint - implements Cloneable{ + implements Cloneable { + PLevel levelX, levelY; boolean isComplete; - boolean reset(Collection sample){ + boolean reset(Collection sample) { levelX=levelY=null; int valuesCount=0; - out: - for(PLevel level: sample){ - switch(level.getType()){ + out: + for(PLevel level: sample) { + switch(level.getType()) { case X: valuesCount++; levelX=level; @@ -87,11 +90,11 @@ boolean reset(Collection sample){ return valuesCount>0; } - private void set(float x, float y){ + private void set(float x, float y) { set(x, y, null); } - private void set(float x, float y, Collection sample){ + private void set(float x, float y, Collection sample) { if(levelX!=null) levelX.value=x; else if(sample!=null) @@ -103,13 +106,13 @@ else if(sample!=null) } @Override - public SamplePoint clone(){ - try{ + public SamplePoint clone() { + try { SamplePoint clone=(SamplePoint)super.clone(); clone.levelX=new PLevel(levelX); clone.levelY=new PLevel(levelY); return clone; - }catch(CloneNotSupportedException ex){ + } catch(CloneNotSupportedException ex) { throw new AssertionError(ex); } } @@ -117,37 +120,42 @@ public SamplePoint clone(){ final Point2D.Float deviation=new Point2D.Float(); final Point2D.Float absDeviation=new Point2D.Float(); - private final Rule[] rules=new Rule[]{ - //new LogToFileRule(), - new AbsoluteLocationRule(), - new AbsoluteOnARowRule(), - new RelativeOnSlopesRule(), - }; - interface Rule{ + private final Rule[] rules=new Rule[] { + //new LogToFileRule(), + new AbsoluteLocationRule(), + new AbsoluteOnARowRule(), + new RelativeOnSlopesRule(), + }; + interface Rule { + void reset(); State evalFilterNextState(RelativeLocationFilter filter); } - public void reset(){ + public void reset() { penDevice=null; resetRules(); } - private void resetRules(){ - for(Rule rule: rules){ + private void resetRules() { + for(Rule rule: rules) { rule.reset(); } } /** - @return {@code true} if the state changed to a definitive value. + @param penState the current pen values + @param penDevice where the {@code sample} levels are coming from + @param sample level values to be filtered/changed according to the {@code state} of this {@code RelativeLocationFilter} + @param levelsOnScreen {@code true} if the given {@code sample} levels are on the screen coordinate system + @return {@code true} if the state of this {@code RelativeLocationFilter} changed to a definitive value. */ - public boolean filter(PenState penState, PenDevice penDevice, Collection sample, boolean levelsOnScreen){ - if(!levelsOnScreen) // only levelsOnScreen is supported + public boolean filter(PenState penState, PenDevice penDevice, Collection sample, boolean levelsOnScreen) { + if(!levelsOnScreen) // only levelsOnScreen are supported return false; if(state.equals(State.OFF)) return false; - if(this.penDevice!=penDevice){ + if(this.penDevice!=penDevice) { this.penDevice=penDevice; state=State.UNDEFINED; resetRules(); @@ -162,11 +170,11 @@ public boolean filter(PenState penState, PenDevice penDevice, Collection return true; boolean stateChanged=false; - if(state.equals(State.UNDEFINED)){ + if(state.equals(State.UNDEFINED)) { setupDeviation(); stateChanged=evalStateFromRules(); } - switch(state){ + switch(state) { case ABSOLUTE: break; case RELATIVE: @@ -174,20 +182,20 @@ public boolean filter(PenState penState, PenDevice penDevice, Collection break; case UNDEFINED: samplePoint.set(penState.getLevelValue(PLevel.Type.X), - penState.getLevelValue(PLevel.Type.Y)); // then it won't cause a level event because movement + penState.getLevelValue(PLevel.Type.Y)); // then it won't cause a level event because of movement break; default: } return stateChanged; } - private static boolean evalIsSystemMouseDevice(PenDevice device){ + private static boolean evalIsSystemMouseDevice(PenDevice device) { return device.getProvider().getConstructor().getPenManager().isSystemMouseDevice(device); } - private boolean setupReference(){ + private boolean setupReference() { PointerInfo pointerInfo=AccessController.doPrivileged(getPointerInfoAction); - if(pointerInfo==null){ + if(pointerInfo==null) { L.warning("No mouse found. Can not correct devices on relative (mouse) mode."); state=State.OFF; return false; @@ -196,28 +204,28 @@ private boolean setupReference(){ return true; } - private final PrivilegedAction getPointerInfoAction=new PrivilegedAction(){ - //@Override - public PointerInfo run(){ - return MouseInfo.getPointerInfo(); - } - }; + private final PrivilegedAction getPointerInfoAction=new PrivilegedAction() { + //@Override + public PointerInfo run() { + return MouseInfo.getPointerInfo(); + } + }; - private void setupDeviation(){ - if(samplePoint.levelX!=null){ + private void setupDeviation() { + if(samplePoint.levelX!=null) { deviation.x=samplePoint.levelX.value-reference.x; absDeviation.x=Math.abs(deviation.x); } - if(samplePoint.levelY!=null){ + if(samplePoint.levelY!=null) { deviation.y=samplePoint.levelY.value-reference.y; absDeviation.y=Math.abs(deviation.y); } } - private boolean evalStateFromRules(){ - for(Rule rule: rules){ + private boolean evalStateFromRules() { + for(Rule rule: rules) { State nextState=rule.evalFilterNextState(this); - if(nextState!=null){ + if(nextState!=null) { this.state=nextState; return true; } @@ -225,7 +233,7 @@ private boolean evalStateFromRules(){ return false; } - public State getState(){ + public State getState() { return state; } } \ No newline at end of file diff --git a/src/main/java/jpen/owner/PenOwner.java b/src/main/java/jpen/owner/PenOwner.java index a24fc83..0b02855 100644 --- a/src/main/java/jpen/owner/PenOwner.java +++ b/src/main/java/jpen/owner/PenOwner.java @@ -30,11 +30,15 @@ public interface PenOwner{ /** Called once by the {@link PenManager#PenManager(PenOwner)} constructor to get the available {@link jpen.PenProvider.Constructor}s and use them to setup the {@link PenProvider}s. + + @return the available {@link PenProvider.Constructor}s */ Collection getPenProviderConstructors(); /** Called once by the {@link PenManager#PenManager(PenOwner)} constructor to allow this PenOwner to access the PenManager through the given {@link PenManagerHandle}. + + @param penManagerHandle value to set as a member if needed */ void setPenManagerHandle(PenManagerHandle penManagerHandle); @@ -49,11 +53,16 @@ public interface PenManagerHandle{ Object getPenSchedulerLock(); /** Unpause/pause the scheduling of {@link jpen.PenEvent}s done by the {@link PenManager}'s {@link PenProvider}s. + + @param paused value to set on the {@link PenManager} */ void setPenManagerPaused(boolean paused); /** Retrieve the tag stored on the given {@code PenEvent}. See {@link #evalPenEventTag(PenEvent)}. + + @param ev where the tag is to be retrieved from + @return the tag stored on the given {@code ev} */ Object retrievePenEventTag(PenEvent ev); } @@ -71,7 +80,10 @@ public interface PenManagerHandle{ boolean isDraggingOut(); /** - This method is called by the {@code PenManager}'s machinary when creating a {@code PenEvent}. This method returns a tag to be stored on the given {@code PenEvent} or {@code null} if no tagging is needed (the {@code PenManager} machinary stores this tag on the private {@code PenEvent}'s {@code penOwnerTag} field ). The tag can be later retrieved using {@link PenManagerHandle#retrievePenEventTag(PenEvent)}. + This method is called by the {@code PenManager}'s machinery when creating a {@code PenEvent}. This method returns a tag to be stored on the given {@code PenEvent} or {@code null} if no tagging is needed (the {@code PenManager} machinery stores this tag on the private {@code PenEvent}'s {@code penOwnerTag} field ). The tag can be later retrieved using {@link PenManagerHandle#retrievePenEventTag(PenEvent)}. + + @param ev event to be tagged + @return the tag to be set on the given {@code ev} or {@code null} if the feature isn't needed */ Object evalPenEventTag(PenEvent ev); diff --git a/src/main/java/jpen/owner/awt/AwtPenOwner.java b/src/main/java/jpen/owner/awt/AwtPenOwner.java index 79f1542..dee9113 100644 --- a/src/main/java/jpen/owner/awt/AwtPenOwner.java +++ b/src/main/java/jpen/owner/awt/AwtPenOwner.java @@ -62,7 +62,10 @@ public void mouseEntered(MouseEvent ev) { }; /** Warning: See {@link AwtPenOwner}. + + @param component to be based on */ + @SuppressWarnings("javadoc") public AwtPenOwner(Component component) { this.component=component; } diff --git a/src/main/java/jpen/owner/awt/ComponentPenOwner.java b/src/main/java/jpen/owner/awt/ComponentPenOwner.java index d0a0439..52f036f 100644 --- a/src/main/java/jpen/owner/awt/ComponentPenOwner.java +++ b/src/main/java/jpen/owner/awt/ComponentPenOwner.java @@ -167,9 +167,12 @@ protected void draggingOutDisengaged() { /** Checks if the given {@link Component} holds the {@link Component#getTreeLock()} before actually getting and returning the {@link jpen.owner.PenOwner.PenManagerHandle#getPenSchedulerLock()}. Prefer using this method instead of {@link jpen.owner.PenOwner.PenManagerHandle#getPenSchedulerLock()} to be shure you aren't causing deadlocks because the {@link ComponentPenClip} methods hold the {@link Component#getTreeLock()}. + + @param component to check if the AWT component tree lock is being held and avoid deadlock, may be null + @return the pen scheduler even synchronization lock */ protected Object getPenSchedulerLock(Component component) { - if(component!=null && Thread.currentThread().holdsLock(component.getTreeLock())) + if(component!=null && Thread.holdsLock(component.getTreeLock())) throw new AssertionError("tryed to hold penSchedulerLock while holding Component's treeLock"); return penManagerHandle.getPenSchedulerLock(); }