From c16771fe1fc29830985ef9b344b64dc33758c232 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 24 Oct 2026 10:58:41 +0000 Subject: [PATCH] Document the public API in the Javadoc Replace the "Created by" headers with descriptions (keeping the authors as @author), document Alignment, FlowLayoutOptions and the FlowLayoutManager builder methods, add a usage example and package descriptions, and mark the helper classes as internal. Release 1.10.2 to publish the new Javadoc. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01QwfmMR3bsQCfffkJXMD6m2 --- README.md | 2 +- .../xiaofeng/flowlayoutmanager/Alignment.java | 10 +++- .../flowlayoutmanager/FlowLayoutManager.java | 57 ++++++++++++++++++- .../flowlayoutmanager/FlowLayoutOptions.java | 16 +++++- .../flowlayoutmanager/LayoutContext.java | 5 +- .../flowlayoutmanager/LayoutHelper.java | 5 +- .../LayoutManagerAppender.java | 6 +- .../flowlayoutmanager/ScrollbarHelper.java | 6 +- .../flowlayoutmanager/cache/CacheHelper.java | 5 +- .../flowlayoutmanager/cache/Line.java | 4 +- .../flowlayoutmanager/cache/package-info.java | 4 ++ .../flowlayoutmanager/package-info.java | 9 +++ gradle.properties | 4 +- 13 files changed, 113 insertions(+), 20 deletions(-) create mode 100644 flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/cache/package-info.java create mode 100644 flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/package-info.java diff --git a/README.md b/README.md index d7646cf..87e8084 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ The library is published on Maven Central, add the dependency (remember to check ```groovy dependencies { - implementation 'io.github.simonebortolin:FlowLayoutManager:1.10.1' + implementation 'io.github.simonebortolin:FlowLayoutManager:1.10.2' } ``` diff --git a/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/Alignment.java b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/Alignment.java index def84c8..05a6bba 100644 --- a/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/Alignment.java +++ b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/Alignment.java @@ -1,10 +1,16 @@ package com.xiaofeng.flowlayoutmanager; /** - * Created by xhan on 4/11/16. + * Horizontal alignment of the items in each line of a {@link FlowLayoutManager}. + * + * @author xhan + * @see FlowLayoutManager#setAlignment(Alignment) */ public enum Alignment { - LEFT, + /** Items start from the left edge, lines are filled left to right. */ + LEFT, + /** Items start from the right edge, lines are filled right to left. */ RIGHT, + /** Items are laid out left to right and each line is centered. */ CENTER } diff --git a/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/FlowLayoutManager.java b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/FlowLayoutManager.java index 68b4c1e..e26d72a 100644 --- a/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/FlowLayoutManager.java +++ b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/FlowLayoutManager.java @@ -17,8 +17,19 @@ import java.util.List; /** - * Layout manager for flow views. support different view height, support item add/removed notification - * support align to left/right edge. support scroll/smooth scroll. + * A {@link RecyclerView.LayoutManager} that lays out items in flow style: items are placed in a + * line until it is full, then a new line starts, like words in a paragraph. + * + *

Items can have different sizes. It supports predictive item animations, scroll and smooth + * scroll, auto measurement, left, right or center alignment ({@link #setAlignment(Alignment)}), + * a limit of items per line ({@link #maxItemsPerLine(int)}, {@link #singleItemPerLine()}) and a + * limit of lines ({@link #maxLines(int)}). + * + * 

{@code
+ * recyclerView.setLayoutManager(new FlowLayoutManager()
+ *         .setAlignment(Alignment.LEFT)
+ *         .maxItemsPerLine(3));
+ * }
*/ public class FlowLayoutManager extends RecyclerView.LayoutManager { @@ -38,11 +49,16 @@ public class FlowLayoutManager extends RecyclerView.LayoutManager { // number of items that fit in the first maxLines lines, refreshed on every real layout. private int maxLinesItemCount = Integer.MAX_VALUE; + /** + * Creates a layout manager with centered lines and no limits. + */ public FlowLayoutManager() { flowLayoutOptions = new FlowLayoutOptions(); } /** + * Creates a layout manager with centered lines that shows at most {@code maxLines} lines. + * * @param maxLines max number of lines to show, <= 0 to show all lines. */ public FlowLayoutManager(int maxLines) { @@ -671,6 +687,10 @@ private int getChildAdapterPosition(View child) { return ((RecyclerView.LayoutParams) child.getLayoutParams()).getViewAdapterPosition(); } + /** + * @param child a child view of the RecyclerView + * @return the layout position of {@code child} + */ public int getChildLayoutPosition(View child) { return ((RecyclerView.LayoutParams) child.getLayoutParams()).getViewLayoutPosition(); } @@ -766,11 +786,22 @@ private boolean isChildRemoved(View child) { return ((RecyclerView.LayoutParams) child.getLayoutParams()).isItemRemoved(); } + /** + * Sets the alignment of the items in each line, {@link Alignment#CENTER} by default. + * + * @param alignment the alignment + * @return this layout manager + */ public FlowLayoutManager setAlignment(Alignment alignment) { flowLayoutOptions.alignment = alignment; return this; } + /** + * Puts each item in its own line, same as {@code maxItemsPerLine(1)}. + * + * @return this layout manager + */ public FlowLayoutManager singleItemPerLine() { flowLayoutOptions.itemsPerLine = 1; @@ -783,6 +814,12 @@ public FlowLayoutManager singleItemPerLine() { return this; } + /** + * Puts at most {@code itemsPerLine} items in each line. + * + * @param itemsPerLine max number of items in a line, <= 0 for no limit + * @return this layout manager + */ public FlowLayoutManager maxItemsPerLine(int itemsPerLine) { flowLayoutOptions.itemsPerLine = itemsPerLine; @@ -796,7 +833,10 @@ public FlowLayoutManager maxItemsPerLine(int itemsPerLine) { } /** - * Show at most maxLines lines, items after the last line are not laid out. + * Shows at most {@code maxLines} lines, items after the last line are not laid out. + * + * @param maxLines max number of lines to show, <= 0 to show all lines + * @return this layout manager */ public FlowLayoutManager maxLines(int maxLines) { flowLayoutOptions.maxLines = maxLines; @@ -804,6 +844,11 @@ public FlowLayoutManager maxLines(int maxLines) { return this; } + /** + * Shows all lines, removing the limit set with {@link #maxLines(int)}. + * + * @return this layout manager + */ public FlowLayoutManager removeMaxLinesLimit() { return maxLines(FlowLayoutOptions.MAX_LINES_NO_LIMIT); } @@ -856,6 +901,12 @@ private int countItemsInMaxLines(RecyclerView.Recycler recycler) { return itemCount; } + /** + * Puts as many items in a line as fit, removing the limit set with + * {@link #maxItemsPerLine(int)} or {@link #singleItemPerLine()}. + * + * @return this layout manager + */ public FlowLayoutManager removeItemPerLineLimit() { flowLayoutOptions.itemsPerLine = FlowLayoutOptions.ITEM_PER_LINE_NO_LIMIT; diff --git a/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/FlowLayoutOptions.java b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/FlowLayoutOptions.java index 77fca0e..9914f4e 100644 --- a/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/FlowLayoutOptions.java +++ b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/FlowLayoutOptions.java @@ -1,12 +1,22 @@ package com.xiaofeng.flowlayoutmanager; /** - * Created by xhan on 4/11/16. + * Layout options of a {@link FlowLayoutManager}: alignment, items per line and max lines. + * Set them with the {@link FlowLayoutManager} builder methods. + * + * @author xhan */ public class FlowLayoutOptions { + /** Value of {@link #itemsPerLine} that puts as many items in a line as fit. */ public static final int ITEM_PER_LINE_NO_LIMIT = 0; + /** Value of {@link #maxLines} that shows all lines. */ public static final int MAX_LINES_NO_LIMIT = 0; + /** Alignment of the items in each line, {@link Alignment#CENTER} by default. */ public Alignment alignment = Alignment.CENTER; + /** + * Max number of items in a line. {@link #ITEM_PER_LINE_NO_LIMIT} (or any value <= 0) + * puts as many items as fit. + */ public int itemsPerLine = ITEM_PER_LINE_NO_LIMIT; /** * Max number of lines to show, items after the last line are not laid out. @@ -14,6 +24,10 @@ public class FlowLayoutOptions { */ public int maxLines = MAX_LINES_NO_LIMIT; + /** + * @param layoutOptions options to copy + * @return a copy of {@code layoutOptions} + */ public static FlowLayoutOptions clone(FlowLayoutOptions layoutOptions) { FlowLayoutOptions result = new FlowLayoutOptions(); result.alignment = layoutOptions.alignment; diff --git a/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/LayoutContext.java b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/LayoutContext.java index 311389a..6522c19 100644 --- a/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/LayoutContext.java +++ b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/LayoutContext.java @@ -1,7 +1,10 @@ package com.xiaofeng.flowlayoutmanager; /** - * Created by xhan on 4/11/16. + * State of a layout pass: the layout options and the number of items already placed in the + * current line. Used internally by {@link FlowLayoutManager}. + * + * @author xhan */ public class LayoutContext { public FlowLayoutOptions layoutOptions; diff --git a/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/LayoutHelper.java b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/LayoutHelper.java index 0829f99..e35e7aa 100644 --- a/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/LayoutHelper.java +++ b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/LayoutHelper.java @@ -4,7 +4,10 @@ import androidx.recyclerview.widget.RecyclerView; /** - * Created by xhan on 4/11/16. + * Geometry helpers of the visible area and of the line breaking rules. Used internally by + * {@link FlowLayoutManager}. + * + * @author xhan */ public class LayoutHelper { RecyclerView.LayoutManager layoutManager; diff --git a/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/LayoutManagerAppender.java b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/LayoutManagerAppender.java index de18ff4..299e72a 100644 --- a/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/LayoutManagerAppender.java +++ b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/LayoutManagerAppender.java @@ -5,9 +5,11 @@ import android.view.View; /** - * Created by Anton Dudakov (dude.bw@gmail.com) on 04/10/16. + * A view measured in a line, laid out once the line is complete so that it can be shifted + * for {@link Alignment#CENTER}. Used internally by {@link FlowLayoutManager}. + * + * @author Anton Dudakov */ - public class LayoutManagerAppender { View mView; diff --git a/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/ScrollbarHelper.java b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/ScrollbarHelper.java index 0dfcc37..41c35e8 100644 --- a/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/ScrollbarHelper.java +++ b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/ScrollbarHelper.java @@ -16,16 +16,14 @@ package com.xiaofeng.flowlayoutmanager; -/** - * Created by Anton Dudakov (dude.bw@gmail.com) on 13/10/16. - */ - import androidx.recyclerview.widget.OrientationHelper; import androidx.recyclerview.widget.RecyclerView; import android.view.View; /** * A helper class to do scroll offset calculations. + * + * @author Anton Dudakov */ class ScrollbarHelper { diff --git a/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/cache/CacheHelper.java b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/cache/CacheHelper.java index 83c2992..cc10f7f 100644 --- a/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/cache/CacheHelper.java +++ b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/cache/CacheHelper.java @@ -4,8 +4,9 @@ import android.util.SparseArray; /** - * A Helper class that will save Line information (items count, total width etc.) and will be used - * for layout, that will avoid low efficiency layout + * Cache of the item sizes and of the resulting lines (item count, total width etc.), so that + * {@link com.xiaofeng.flowlayoutmanager.FlowLayoutManager} does not have to lay out every item + * from the beginning when scrolling. Used internally by the layout manager. */ public class CacheHelper { public static final int NOT_FOUND = -1; diff --git a/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/cache/Line.java b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/cache/Line.java index af86ffa..3a8e5a6 100644 --- a/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/cache/Line.java +++ b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/cache/Line.java @@ -1,7 +1,9 @@ package com.xiaofeng.flowlayoutmanager.cache; /** - * Created by xhan on 4/28/16. + * Cached information of a laid out line: item count, total width and tallest item. + * + * @author xhan */ public class Line { public int itemCount; diff --git a/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/cache/package-info.java b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/cache/package-info.java new file mode 100644 index 0000000..9a4cc40 --- /dev/null +++ b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/cache/package-info.java @@ -0,0 +1,4 @@ +/** + * Line cache used internally by {@link com.xiaofeng.flowlayoutmanager.FlowLayoutManager}. + */ +package com.xiaofeng.flowlayoutmanager.cache; diff --git a/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/package-info.java b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/package-info.java new file mode 100644 index 0000000..910256e --- /dev/null +++ b/flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/package-info.java @@ -0,0 +1,9 @@ +/** + * {@link com.xiaofeng.flowlayoutmanager.FlowLayoutManager}, a RecyclerView layout manager that lays + * out items in flow style, and its options. + * + *

Use {@link com.xiaofeng.flowlayoutmanager.FlowLayoutManager} and + * {@link com.xiaofeng.flowlayoutmanager.Alignment}; the other classes are used internally by the + * layout manager. + */ +package com.xiaofeng.flowlayoutmanager; diff --git a/gradle.properties b/gradle.properties index c6ce3fe..e8dccd2 100644 --- a/gradle.properties +++ b/gradle.properties @@ -1,6 +1,6 @@ # Version of the library and of the sample app, used by CI to tag and release. -VERSION_NAME=1.10.1 -VERSION_CODE=21 +VERSION_NAME=1.10.2 +VERSION_CODE=22 # Keep it as low as the dependencies allow, library and sample app share it. MIN_SDK=21