Google Git
Sign in
android / platform / tools / dokka-devsite-plugin / 3adcc28f9ebb13ca9b17d41f0e2bc88a5d0029ad / . / testData / paging / docs / reference / androidx / paging / PagedList.Config.Builder.html
blob: 9b3bee60df58266f4a43956b9aa63b99066635d4 [file] [log] [blame]
<html devsite="true">
<head>
<title>PagedList.Config.Builder</title>
{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %}
{% include "_shared/_reference-head-tags.html" %}
</head>
<body>
<h1>PagedList.Config.Builder</h1>
{% setvar page_path %}androidx/paging/PagedList.Config.Builder.html{% endsetvar %}
{% setvar can_switch %}1{% endsetvar %}
{% include "reference/_java_switcher2.md" %}
<p>
<pre>public final class PagedList.Config.Builder</pre>
</p>
<hr>
<p>Builder class for <code><a href="/reference/androidx/paging/PagedList.Config.html">PagedList.Config</a></code>.</p>
<p>You must at minimum specify page size with <code><a href="/reference/androidx/paging/PagedList.Config.Builder.html#setPageSize(kotlin.Int)">setPageSize</a></code>.</p>
<h2>Summary</h2>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2"><h3>Public constructors</h3></th>
</tr>
</thead>
<tbody>
<tr>
<td>
<div><code><a href="/reference/androidx/paging/PagedList.Config.Builder.html#Builder()">Builder</a>()</code></div>
</td>
</tr>
</tbody>
</table>
</div>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2"><h3>Public methods</h3></th>
</tr>
</thead>
<tbody>
<tr>
<td><code>final <a href="/reference/androidx/paging/PagedList.Config.html">PagedList.Config</a></code></td>
<td width="100%">
<div><code><a href="/reference/androidx/paging/PagedList.Config.Builder.html#build()">build</a>()</code></div>
<p>Creates a <code><a href="/reference/androidx/paging/PagedList.Config.html">PagedList.Config</a></code> with the given parameters.</p>
</td>
</tr>
<tr>
<td><code>final <a href="/reference/androidx/paging/PagedList.Config.Builder.html">PagedList.Config.Builder</a></code></td>
<td width="100%">
<div><code><a href="/reference/androidx/paging/PagedList.Config.Builder.html#setEnablePlaceholders(kotlin.Boolean)">setEnablePlaceholders</a>(boolean&nbsp;enablePlaceholders)</code></div>
<p>Pass false to disable null placeholders in <code><a href="/reference/androidx/paging/PagedList.html">PagedList</a></code>s using this <code><a href="/reference/androidx/paging/PagedList.Config.html">PagedList.Config</a></code>.</p>
</td>
</tr>
<tr>
<td><code>final <a href="/reference/androidx/paging/PagedList.Config.Builder.html">PagedList.Config.Builder</a></code></td>
<td width="100%">
<div><code><a href="/reference/androidx/paging/PagedList.Config.Builder.html#setInitialLoadSizeHint(kotlin.Int)">setInitialLoadSizeHint</a>(@<a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.ranges/-int-range/index.html">IntRange</a>&nbsp;int&nbsp;initialLoadSizeHint)</code></div>
<p>Defines how many items to load when first load occurs.</p>
</td>
</tr>
<tr>
<td><code>final <a href="/reference/androidx/paging/PagedList.Config.Builder.html">PagedList.Config.Builder</a></code></td>
<td width="100%">
<div><code><a href="/reference/androidx/paging/PagedList.Config.Builder.html#setMaxSize(kotlin.Int)">setMaxSize</a>(@<a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.ranges/-int-range/index.html">IntRange</a>&nbsp;int&nbsp;maxSize)</code></div>
<p>Defines how many items to keep loaded at once.</p>
</td>
</tr>
<tr>
<td><code>final <a href="/reference/androidx/paging/PagedList.Config.Builder.html">PagedList.Config.Builder</a></code></td>
<td width="100%">
<div><code><a href="/reference/androidx/paging/PagedList.Config.Builder.html#setPageSize(kotlin.Int)">setPageSize</a>(@<a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.ranges/-int-range/index.html">IntRange</a>&nbsp;int&nbsp;pageSize)</code></div>
<p>Defines the number of items loaded at once from the <code><a href="/reference/androidx/paging/PagingSource.html">PagingSource</a></code>.</p>
</td>
</tr>
<tr>
<td><code>final <a href="/reference/androidx/paging/PagedList.Config.Builder.html">PagedList.Config.Builder</a></code></td>
<td width="100%">
<div><code><a href="/reference/androidx/paging/PagedList.Config.Builder.html#setPrefetchDistance(kotlin.Int)">setPrefetchDistance</a>(@<a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.ranges/-int-range/index.html">IntRange</a>&nbsp;int&nbsp;prefetchDistance)</code></div>
<p>Defines how far from the edge of loaded content an access must be to trigger further loading.</p>
</td>
</tr>
</tbody>
</table>
</div>
<h2>Public constructors</h2>
<div><a name="Builder--"></a>
<h3 class="api-name" id="Builder()">Builder</h3>
<pre class="api-signature no-pretty-print">public&nbsp;final&nbsp;<a href="/reference/androidx/paging/PagedList.Config.Builder.html#Builder()">Builder</a>()</pre>
</div>
<h2>Public methods</h2>
<div><a name="build--"></a>
<h3 class="api-name" id="build()">build</h3>
<pre class="api-signature no-pretty-print">public&nbsp;final&nbsp;<a href="/reference/androidx/paging/PagedList.Config.html">PagedList.Config</a>&nbsp;<a href="/reference/androidx/paging/PagedList.Config.Builder.html#build()">build</a>()</pre>
<p>Creates a <code><a href="/reference/androidx/paging/PagedList.Config.html">PagedList.Config</a></code> with the given parameters.</p>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2">Returns</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><a href="/reference/androidx/paging/PagedList.Config.html">PagedList.Config</a></code></td>
<td width="100%">
<p>A new <code><a href="/reference/androidx/paging/PagedList.Config.html">PagedList.Config</a></code>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2">Throws</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>kotlin.IllegalArgumentException</code></td>
<td width="100%">
<p>if placeholders are disabled and prefetchDistance is set to 0</p>
</td>
</tr>
<tr>
<td><code>kotlin.IllegalArgumentException</code></td>
<td width="100%">
<p>if maximum size is less than pageSize + 2*prefetchDistance</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div><a name="setEnablePlaceholders-kotlin.Boolean-"></a>
<h3 class="api-name" id="setEnablePlaceholders(kotlin.Boolean)">setEnablePlaceholders</h3>
<pre class="api-signature no-pretty-print">public&nbsp;final&nbsp;<a href="/reference/androidx/paging/PagedList.Config.Builder.html">PagedList.Config.Builder</a>&nbsp;<a href="/reference/androidx/paging/PagedList.Config.Builder.html#setEnablePlaceholders(kotlin.Boolean)">setEnablePlaceholders</a>(boolean&nbsp;enablePlaceholders)</pre>
<p>Pass false to disable null placeholders in <code><a href="/reference/androidx/paging/PagedList.html">PagedList</a></code>s using this <code><a href="/reference/androidx/paging/PagedList.Config.html">PagedList.Config</a></code>.</p>
<p>If not set, defaults to true.</p>
<p>A <code><a href="/reference/androidx/paging/PagedList.html">PagedList</a></code> will present null placeholders for not-yet-loaded content if two conditions are met:</p>
<ol>
<li>
<p>Its <code><a href="/reference/androidx/paging/PagingSource.html">PagingSource</a></code> can count all unloaded items (so that the number of nulls to present is known).</p>
</li>
<li>
<p>placeholders are not disabled on the <code><a href="/reference/androidx/paging/PagedList.Config.html">PagedList.Config</a></code>.</p>
</li>
</ol>
<p>Call <code>setEnablePlaceholders(false)</code> to ensure the receiver of the PagedList (often a <code><a href="/reference/androidx/paging/PagedListAdapter.html">androidx.paging.PagedListAdapter</a></code>) doesn't need to account for null items.</p>
<p>If placeholders are disabled, not-yet-loaded content will not be present in the list. Paging will still occur, but as items are loaded or removed, they will be signaled as inserts to the <code><a href="/reference/androidx/paging/PagedList.Callback.html">PagedList.Callback</a></code>.</p>
<p><code><a href="/reference/androidx/paging/PagedList.Callback.html#onChanged(kotlin.Int,kotlin.Int)">PagedList.Callback.onChanged</a></code> will not be issued as part of loading, though a <code><a href="/reference/androidx/paging/PagedListAdapter.html">androidx.paging.PagedListAdapter</a></code> may still receive change events as a result of <code><a href="/reference/androidx/paging/PagedList.html">PagedList</a></code> diffing.</p>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2">Returns</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><a href="/reference/androidx/paging/PagedList.Config.Builder.html">PagedList.Config.Builder</a></code></td>
<td width="100%">
<p>this</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2">Parameters</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>boolean&nbsp;enablePlaceholders</code></td>
<td width="100%">
<p><code>false</code> if null placeholders should be disabled.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div><a name="setInitialLoadSizeHint-kotlin.Int-"></a>
<h3 class="api-name" id="setInitialLoadSizeHint(kotlin.Int)">setInitialLoadSizeHint</h3>
<pre class="api-signature no-pretty-print">public&nbsp;final&nbsp;<a href="/reference/androidx/paging/PagedList.Config.Builder.html">PagedList.Config.Builder</a>&nbsp;<a href="/reference/androidx/paging/PagedList.Config.Builder.html#setInitialLoadSizeHint(kotlin.Int)">setInitialLoadSizeHint</a>(@<a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.ranges/-int-range/index.html">IntRange</a>&nbsp;int&nbsp;initialLoadSizeHint)</pre>
<p>Defines how many items to load when first load occurs.</p>
<p>This value is typically larger than page size, so on first load data there's a large enough range of content loaded to cover small scrolls.</p>
<p>If not set, defaults to three times page size.</p>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2">Returns</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><a href="/reference/androidx/paging/PagedList.Config.Builder.html">PagedList.Config.Builder</a></code></td>
<td width="100%">
<p>this</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2">Parameters</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>@<a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.ranges/-int-range/index.html">IntRange</a>&nbsp;int&nbsp;initialLoadSizeHint</code></td>
<td width="100%">
<p>Number of items to load while initializing the <code><a href="/reference/androidx/paging/PagedList.html">PagedList</a></code></p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div><a name="setMaxSize-kotlin.Int-"></a>
<h3 class="api-name" id="setMaxSize(kotlin.Int)">setMaxSize</h3>
<pre class="api-signature no-pretty-print">public&nbsp;final&nbsp;<a href="/reference/androidx/paging/PagedList.Config.Builder.html">PagedList.Config.Builder</a>&nbsp;<a href="/reference/androidx/paging/PagedList.Config.Builder.html#setMaxSize(kotlin.Int)">setMaxSize</a>(@<a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.ranges/-int-range/index.html">IntRange</a>&nbsp;int&nbsp;maxSize)</pre>
<p>Defines how many items to keep loaded at once.</p>
<p>This can be used to cap the number of items kept in memory by dropping pages. This value is typically many pages so old pages are cached in case the user scrolls back.</p>
<p>This value must be at least two times the <code><a href="/reference/androidx/paging/PagedList.Config.Builder.html#setPrefetchDistance(kotlin.Int)">prefetchDistance</a></code> plus the <code><a href="/reference/androidx/paging/PagedList.Config.Builder.html#setPageSize(kotlin.Int)">pageSize</a></code>). This constraint prevent loads from being continuously fetched and discarded due to prefetching.</p>
<p>The max size specified here best effort, not a guarantee. In practice, if <code><a href="/reference/androidx/paging/PagedList.Config.Builder.html#maxSize()">maxSize</a></code> is many times the page size, the number of items held by the <code><a href="/reference/androidx/paging/PagedList.html">PagedList</a></code> will not grow above this number. Exceptions are made as necessary to guarantee:</p>
<ul>
<li>
<p>Pages are never dropped until there are more than two pages loaded. Note that a <code><a href="/reference/androidx/paging/PagingSource.html">PagingSource</a></code> may not be held strictly to <code><a href="/reference/androidx/paging/PagedList.Config.html#pageSize()">requested pageSize</a></code>, so two pages may be larger than expected.</p>
</li>
<li>
<p>Pages are never dropped if they are within a prefetch window (defined to be <code>pageSize + (2 * prefetchDistance)</code>) of the most recent load.</p>
</li>
</ul>
<p>If not set, defaults to <code><a href="/reference/androidx/paging/PagedList.Config.Companion.html#MAX_SIZE_UNBOUNDED()">PagedList.Config.Companion.MAX_SIZE_UNBOUNDED</a></code>, which disables page dropping.</p>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2">Returns</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><a href="/reference/androidx/paging/PagedList.Config.Builder.html">PagedList.Config.Builder</a></code></td>
<td width="100%">
<p>this</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2">Parameters</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>@<a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.ranges/-int-range/index.html">IntRange</a>&nbsp;int&nbsp;maxSize</code></td>
<td width="100%">
<p>Maximum number of items to keep in memory, or <code><a href="/reference/androidx/paging/PagedList.Config.Companion.html#MAX_SIZE_UNBOUNDED()">PagedList.Config.Companion.MAX_SIZE_UNBOUNDED</a></code> to disable page dropping.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2">See also</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><a href="/reference/androidx/paging/PagedList.Config.Companion.html#MAX_SIZE_UNBOUNDED()">MAX_SIZE_UNBOUNDED</a></code></td>
<td width="100%"></td>
</tr>
<tr>
<td><code><a href="/reference/androidx/paging/PagedList.Config.html#maxSize()">maxSize</a></code></td>
<td width="100%"></td>
</tr>
</tbody>
</table>
</div>
</div>
<div><a name="setPageSize-kotlin.Int-"></a>
<h3 class="api-name" id="setPageSize(kotlin.Int)">setPageSize</h3>
<pre class="api-signature no-pretty-print">public&nbsp;final&nbsp;<a href="/reference/androidx/paging/PagedList.Config.Builder.html">PagedList.Config.Builder</a>&nbsp;<a href="/reference/androidx/paging/PagedList.Config.Builder.html#setPageSize(kotlin.Int)">setPageSize</a>(@<a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.ranges/-int-range/index.html">IntRange</a>&nbsp;int&nbsp;pageSize)</pre>
<p>Defines the number of items loaded at once from the <code><a href="/reference/androidx/paging/PagingSource.html">PagingSource</a></code>.</p>
<p>Should be several times the number of visible items onscreen.</p>
<p>Configuring your page size depends on how your data is being loaded and used. Smaller page sizes improve memory usage, latency, and avoid GC churn. Larger pages generally improve loading throughput, to a point (avoid loading more than 2MB from SQLite at once, since it incurs extra cost).</p>
<p>If you're loading data for very large, social-media style cards that take up most of a screen, and your database isn't a bottleneck, 10-20 may make sense. If you're displaying dozens of items in a tiled grid, which can present items during a scroll much more quickly, consider closer to 100.</p>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2">Returns</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><a href="/reference/androidx/paging/PagedList.Config.Builder.html">PagedList.Config.Builder</a></code></td>
<td width="100%">
<p>this</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2">Parameters</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>@<a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.ranges/-int-range/index.html">IntRange</a>&nbsp;int&nbsp;pageSize</code></td>
<td width="100%">
<p>Number of items loaded at once from the <code><a href="/reference/androidx/paging/PagingSource.html">PagingSource</a></code>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2">Throws</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>kotlin.IllegalArgumentException</code></td>
<td width="100%">
<p>if pageSize is &lt; <code>1</code>.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div><a name="setPrefetchDistance-kotlin.Int-"></a>
<h3 class="api-name" id="setPrefetchDistance(kotlin.Int)">setPrefetchDistance</h3>
<pre class="api-signature no-pretty-print">public&nbsp;final&nbsp;<a href="/reference/androidx/paging/PagedList.Config.Builder.html">PagedList.Config.Builder</a>&nbsp;<a href="/reference/androidx/paging/PagedList.Config.Builder.html#setPrefetchDistance(kotlin.Int)">setPrefetchDistance</a>(@<a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.ranges/-int-range/index.html">IntRange</a>&nbsp;int&nbsp;prefetchDistance)</pre>
<p>Defines how far from the edge of loaded content an access must be to trigger further loading.</p>
<p>Should be several times the number of visible items onscreen.</p>
<p>If not set, defaults to page size.</p>
<p>A value of 0 indicates that no list items will be loaded until they are specifically requested. This is generally not recommended, so that users don't observe a placeholder item (with placeholders) or end of list (without) while scrolling.</p>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2">Returns</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><a href="/reference/androidx/paging/PagedList.Config.Builder.html">PagedList.Config.Builder</a></code></td>
<td width="100%">
<p>this</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2">Parameters</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>@<a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.ranges/-int-range/index.html">IntRange</a>&nbsp;int&nbsp;prefetchDistance</code></td>
<td width="100%">
<p>Distance the <code><a href="/reference/androidx/paging/PagedList.html">PagedList</a></code> should prefetch.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</body>
</html>