From f9557619a7643c971e64e5b35583476202e77b7b Mon Sep 17 00:00:00 2001 From: George Mount Date: Fri, 29 Aug 2014 11:32:13 -0700 Subject: [PATCH] API Review: Improve javadoc. Bug 17189781 Also rename PatternMotion to PatternPathMotion Change-Id: I1c4dcbdd65e33cf9de1504277e31f9f7ede0380d --- api/current.txt | 13 ++-- core/java/android/transition/ArcMotion.java | 6 +- .../android/transition/ChangeTransform.java | 4 ++ ...ternMotion.java => PatternPathMotion.java} | 62 +++++++++---------- core/java/android/transition/Transition.java | 49 +++++++++++++++ .../transition/TransitionInflater.java | 4 +- core/res/res/values/attrs.xml | 10 +-- core/res/res/values/public.xml | 1 + 8 files changed, 102 insertions(+), 47 deletions(-) rename core/java/android/transition/{PatternMotion.java => PatternPathMotion.java} (68%) diff --git a/api/current.txt b/api/current.txt index d7ddcf1a5d453..616b19264e622 100644 --- a/api/current.txt +++ b/api/current.txt @@ -968,6 +968,7 @@ package android { field public static final int pathData = 16843807; // 0x101041f field public static final int pathPattern = 16842796; // 0x101002c field public static final int pathPrefix = 16842795; // 0x101002b + field public static final int patternPathData = 16843979; // 0x10104cb field public static final int permission = 16842758; // 0x1010006 field public static final int permissionFlags = 16843719; // 0x10103c7 field public static final int permissionGroup = 16842762; // 0x101000a @@ -31493,13 +31494,13 @@ package android.transition { method public abstract android.graphics.Path getPath(float, float, float, float); } - public class PatternMotion extends android.transition.PathMotion { - ctor public PatternMotion(); - ctor public PatternMotion(android.content.Context, android.util.AttributeSet); - ctor public PatternMotion(android.graphics.Path); + public class PatternPathMotion extends android.transition.PathMotion { + ctor public PatternPathMotion(); + ctor public PatternPathMotion(android.content.Context, android.util.AttributeSet); + ctor public PatternPathMotion(android.graphics.Path); method public android.graphics.Path getPath(float, float, float, float); - method public android.graphics.Path getPattern(); - method public void setPattern(android.graphics.Path); + method public android.graphics.Path getPatternPath(); + method public void setPatternPath(android.graphics.Path); } public final class Scene { diff --git a/core/java/android/transition/ArcMotion.java b/core/java/android/transition/ArcMotion.java index a27063d26a1c9..f95fb491ea1a3 100644 --- a/core/java/android/transition/ArcMotion.java +++ b/core/java/android/transition/ArcMotion.java @@ -41,9 +41,9 @@ import android.util.FloatMath; * {@code * <changeBounds> * <arcMotion android:minimumHorizontalAngle="15" - * android:minimumVerticalAngle="0" android:maximumAngle="90"/> - * </changeBounds> - * } + * android:minimumVerticalAngle="0" + * android:maximumAngle="90"/> + * </changeBounds>} * */ public class ArcMotion extends PathMotion { diff --git a/core/java/android/transition/ChangeTransform.java b/core/java/android/transition/ChangeTransform.java index cb0a8758b8403..1b8d57c59dd0d 100644 --- a/core/java/android/transition/ChangeTransform.java +++ b/core/java/android/transition/ChangeTransform.java @@ -99,6 +99,7 @@ public class ChangeTransform extends Transition { * @return true when a changed parent should execute the transition * inside the scene root's overlay or false if a parent change only * affects the transform of the transitioning view. + * @attr ref android.R.styleable#ChangeTransform_reparentWithOverlay */ public boolean getReparentWithOverlay() { return mUseOverlay; @@ -120,6 +121,7 @@ public class ChangeTransform extends Transition { * @return true when a changed parent should execute the transition * inside the scene root's overlay or false if a parent change only * affects the transform of the transitioning view. + * @attr ref android.R.styleable#ChangeTransform_reparentWithOverlay */ public void setReparentWithOverlay(boolean reparentWithOverlay) { mUseOverlay = reparentWithOverlay; @@ -132,6 +134,7 @@ public class ChangeTransform extends Transition { * view will be tracked. Default is true. * * @return whether parent changes will be tracked by the ChangeTransform. + * @attr ref android.R.styleable#ChangeTransform_reparent */ public boolean getReparent() { return mReparent; @@ -145,6 +148,7 @@ public class ChangeTransform extends Transition { * * @param reparent Set to true to track parent changes or false to only track changes * of the transitioning view without considering the parent change. + * @attr ref android.R.styleable#ChangeTransform_reparent */ public void setReparent(boolean reparent) { mReparent = reparent; diff --git a/core/java/android/transition/PatternMotion.java b/core/java/android/transition/PatternPathMotion.java similarity index 68% rename from core/java/android/transition/PatternMotion.java rename to core/java/android/transition/PatternPathMotion.java index e4045b40576a1..a609df6a0a394 100644 --- a/core/java/android/transition/PatternMotion.java +++ b/core/java/android/transition/PatternPathMotion.java @@ -34,36 +34,35 @@ import android.util.PathParser; * 
  * {@code
  * <changeBounds>
- *     <patternMotion android:pathData="M0 0 L0 100 L100 100"/>
- * </changeBounds>
- * }
+ *     <patternPathMotion android:patternPathData="M0 0 L0 100 L100 100"/>
+ * </changeBounds>}
  *
*/ -public class PatternMotion extends PathMotion { +public class PatternPathMotion extends PathMotion { - private Path mOriginalPattern; + private Path mOriginalPatternPath; - private final Path mPattern = new Path(); + private final Path mPatternPath = new Path(); private final Matrix mTempMatrix = new Matrix(); /** - * Constructs a PatternMotion with a straight-line pattern. + * Constructs a PatternPathMotion with a straight-line pattern. */ - public PatternMotion() { - mPattern.lineTo(1, 0); - mOriginalPattern = mPattern; + public PatternPathMotion() { + mPatternPath.lineTo(1, 0); + mOriginalPatternPath = mPatternPath; } - public PatternMotion(Context context, AttributeSet attrs) { - TypedArray a = context.obtainStyledAttributes(attrs, R.styleable.PatternMotion); + public PatternPathMotion(Context context, AttributeSet attrs) { + TypedArray a = context.obtainStyledAttributes(attrs, R.styleable.PatternPathMotion); try { - String pathData = a.getString(R.styleable.PatternMotion_pathData); + String pathData = a.getString(R.styleable.PatternPathMotion_patternPathData); if (pathData == null) { - throw new RuntimeException("pathData must be supplied for patternMotion"); + throw new RuntimeException("pathData must be supplied for patternPathMotion"); } Path pattern = PathParser.createPathFromPathData(pathData); - setPattern(pattern); + setPatternPath(pattern); } finally { a.recycle(); } @@ -71,14 +70,15 @@ public class PatternMotion extends PathMotion { } /** - * Creates a PatternMotion with the Path defining a pattern of motion between two coordinates. - * The pattern will be translated, rotated, and scaled to fit between the start and end points. - * The pattern must not be empty and must have the end point differ from the start point. + * Creates a PatternPathMotion with the Path defining a pattern of motion between two + * coordinates. The pattern will be translated, rotated, and scaled to fit between the start + * and end points. The pattern must not be empty and must have the end point differ from the + * start point. * - * @param pattern A Path to be used as a pattern for two-dimensional motion. + * @param patternPath A Path to be used as a pattern for two-dimensional motion. */ - public PatternMotion(Path pattern) { - setPattern(pattern); + public PatternPathMotion(Path patternPath) { + setPatternPath(patternPath); } /** @@ -87,10 +87,10 @@ public class PatternMotion extends PathMotion { * The pattern must not be empty and must have the end point differ from the start point. * * @return the Path defining a pattern of motion between two coordinates. - * @attr ref android.R.styleable#PatternMotion_pathData + * @attr ref android.R.styleable#PatternPathMotion_patternPathData */ - public Path getPattern() { - return mOriginalPattern; + public Path getPatternPath() { + return mOriginalPatternPath; } /** @@ -98,11 +98,11 @@ public class PatternMotion extends PathMotion { * The pattern will be translated, rotated, and scaled to fit between the start and end points. * The pattern must not be empty and must have the end point differ from the start point. * - * @param pattern A Path to be used as a pattern for two-dimensional motion. - * @attr ref android.R.styleable#PatternMotion_pathData + * @param patternPath A Path to be used as a pattern for two-dimensional motion. + * @attr ref android.R.styleable#PatternPathMotion_patternPathData */ - public void setPattern(Path pattern) { - PathMeasure pathMeasure = new PathMeasure(pattern, false); + public void setPatternPath(Path patternPath) { + PathMeasure pathMeasure = new PathMeasure(patternPath, false); float length = pathMeasure.getLength(); float[] pos = new float[2]; pathMeasure.getPosTan(length, pos, null); @@ -124,8 +124,8 @@ public class PatternMotion extends PathMotion { mTempMatrix.postScale(scale, scale); double angle = Math.atan2(dy, dx); mTempMatrix.postRotate((float) Math.toDegrees(-angle)); - pattern.transform(mTempMatrix, mPattern); - mOriginalPattern = pattern; + patternPath.transform(mTempMatrix, mPatternPath); + mOriginalPatternPath = patternPath; } @Override @@ -139,7 +139,7 @@ public class PatternMotion extends PathMotion { mTempMatrix.postRotate((float) Math.toDegrees(angle)); mTempMatrix.postTranslate(startX, startY); Path path = new Path(); - mPattern.transform(mTempMatrix, path); + mPatternPath.transform(mTempMatrix, path); return path; } diff --git a/core/java/android/transition/Transition.java b/core/java/android/transition/Transition.java index bd52e714a025d..0d1b56814ca6d 100644 --- a/core/java/android/transition/Transition.java +++ b/core/java/android/transition/Transition.java @@ -1989,8 +1989,33 @@ public abstract class Transition implements Cloneable { * by extending PathMotion and implementing * {@link android.transition.PathMotion#getPath(float, float, float, float)}. *

+ *

+ * When describing in XML, use a nested XML tag for the path motion. It can be one of + * the built-in tags arcMotion or patternPathMotion or it can + * be a custom PathMotion using pathMotion with the class + * attributed with the fully-described class name. For example:

+ * 
+     * {@code
+     * <changeBounds>
+     *     <pathMotion class="my.app.transition.MyPathMotion"/>
+     * </changeBounds>
+     * }
+     *
+ *

or

+ * 
+     * {@code
+     * <changeBounds>
+     *   <arcMotion android:minimumHorizontalAngle="15"
+     *     android:minimumVerticalAngle="0" android:maximumAngle="90"/>
+     * </changeBounds>
+     * }
+     *
+ * * @param pathMotion Algorithm object to use for determining how to interpolate in two * dimensions. If null, a straight-path algorithm will be used. + * @see android.transition.ArcMotion + * @see PatternPathMotion + * @see android.transition.PathMotion */ public void setPathMotion(PathMotion pathMotion) { if (pathMotion == null) { @@ -2004,7 +2029,31 @@ public abstract class Transition implements Cloneable { * Returns the algorithm object used to interpolate along two dimensions. This is typically * used to determine the View motion between two points. * + *

+ * When describing in XML, use a nested XML tag for the path motion. It can be one of + * the built-in tags arcMotion or patternPathMotion or it can + * be a custom PathMotion using pathMotion with the class + * attributed with the fully-described class name. For example:

+ * 
+     * {@code
+     * <changeBounds>
+     *     <pathMotion class="my.app.transition.MyPathMotion"/>
+     * </changeBounds>}
+     *
+ *

or

+ * 
+     * {@code
+     * <changeBounds>
+     *   <arcMotion android:minimumHorizontalAngle="15"
+     *              android:minimumVerticalAngle="0"
+     *              android:maximumAngle="90"/>
+     * </changeBounds>}
+     *
+ * * @return The algorithm object used to interpolate along two dimensions. + * @see android.transition.ArcMotion + * @see PatternPathMotion + * @see android.transition.PathMotion */ public PathMotion getPathMotion() { return mPathMotion; diff --git a/core/java/android/transition/TransitionInflater.java b/core/java/android/transition/TransitionInflater.java index 760ffe1814b9c..9009d6ab08d59 100644 --- a/core/java/android/transition/TransitionInflater.java +++ b/core/java/android/transition/TransitionInflater.java @@ -171,8 +171,8 @@ public class TransitionInflater { parent.setPathMotion(new ArcMotion(mContext, attrs)); } else if ("pathMotion".equals(name)) { parent.setPathMotion((PathMotion)createCustom(attrs, PathMotion.class, "pathMotion")); - } else if ("patternMotion".equals(name)) { - parent.setPathMotion(new PatternMotion(mContext, attrs)); + } else if ("patternPathMotion".equals(name)) { + parent.setPathMotion(new PatternPathMotion(mContext, attrs)); } else { throw new RuntimeException("Unknown scene name: " + parser.getName()); } diff --git a/core/res/res/values/attrs.xml b/core/res/res/values/attrs.xml index 3629cbbb62f51..d1cc1fd7a3140 100644 --- a/core/res/res/values/attrs.xml +++ b/core/res/res/values/attrs.xml @@ -5686,12 +5686,12 @@ - - - - + + + diff --git a/core/res/res/values/public.xml b/core/res/res/values/public.xml index 4bf45318bdb26..a4c347453e948 100644 --- a/core/res/res/values/public.xml +++ b/core/res/res/values/public.xml @@ -2290,6 +2290,7 @@ +