-
Notifications
You must be signed in to change notification settings - Fork 15
Expand file tree
/
Copy pathlayouts.html
More file actions
349 lines (312 loc) · 19.8 KB
/
layouts.html
File metadata and controls
349 lines (312 loc) · 19.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
<!DOCTYPE html>
<html lang="en">
<head>
<title>Layouts Reference</title>
<link rel="stylesheet" type="text/css" href="css/jazzy.css" />
<link rel="stylesheet" type="text/css" href="css/highlight.css" />
<meta charset='utf-8'>
<meta name="viewport" content="width=device-width, viewport-fit=cover, initial-scale=1.0" />
<script src="js/jquery.min.js" defer></script>
<script src="js/jazzy.js" defer></script>
</head>
<body>
<a title="Layouts Reference"></a>
<header>
<div class="content-wrapper">
<p>
<a href="index.html">CollectionView Docs</a>
<span class="no-mobile"> (63% documented)</span>
</p>
<p class="header-right">
<a href="https://github.com/TheNounProject/CollectionView">
<img src="img/gh.png"/>
<span class="no-mobile">View on GitHub</span>
</a>
</p>
</div>
</header>
<div id="breadcrumbs-container">
<div class="content-wrapper">
<p id="breadcrumbs">
<span class="no-mobile">
<a href="index.html">CollectionView Reference</a>
<img id="carat" src="img/carat.png" />
</span>
Layouts Reference
</p>
</div>
</div>
<div class="wrapper">
<div class="article-wrapper">
<article class="main-content">
<section>
<section class="section">
<h1 id='advanced-layouts' class='heading'>Advanced Layouts</h1>
<p>Every collection view relys on a <code><a href="Classes/CollectionViewLayout.html">CollectionViewLayout</a></code> object to provide the information. This allows a layout object to reason about the desired layout in whatever way is most appropriate for its goal. Every layout is a subclass of <code><a href="Classes/CollectionViewLayout.html">CollectionViewLayout</a></code>, an abstract class that provides the framework for collection view to access information it needs to display each item correctly.</p>
<p>A few layouts are provided and allow for customization. We’ll go through each of these layouts and some of the tips and tricks of each then discuss building your own layout.</p>
<hr>
<h2 id='collectionviewlistlayout' class='heading'>CollectionViewListLayout</h2>
<p>CollectionViewListLayout is a simple vertical list similar to an NSTableView/UITableView.</p>
<p>Some of the key customization tips for this layout are the <code>interitemSpacing</code> and <code>sectionInsets</code>. Also available via CollectionViewDelegateListLayout methods for per section values, these properties can turn an ordinary list into a card style list with minimal effort.</p>
<h2 id='collectionviewcolumnlayout' class='heading'>CollectionViewColumnLayout</h2>
<p>CollectionViewColumnLayout organizes items in each section into columns creating a grid or a pintrest style waterfall depending on your setup.</p>
<h4 id='coumns-and-width' class='heading'>Coumns and Width</h4>
<p>Your first choice is how many columns should be used in a given section. This number in conjunction with column spacing and section insets will determin the width of each item. In the example below our collection view is 800pt wide, with insets of 10 and column spacing of 10 wit 5 columns. This leaves 88pts for each cell, remember at this stage we are only worried about width.</p>
<p><img src="https://raw.githubusercontent.com/TheNounProject/CollectionView/master/img/column_layout.png" alt="ColumnLayoutSpacing" title="Column layout spacing"></p>
<p>Columns are always equal width and adjusting the spacing, insets, or number of columns will affect the width of each column equally.</p>
<h4 id='item-height' class='heading'>Item Height</h4>
<p>With the itemWidth set by the column, you have 3 options to set the height of each item. The first option to return a value is used meaning if <code>aspectRatioForItemAtIndexPath</code> is implemented it is used, otherwise, it checks the next one.</p>
<ol>
<li><code>aspectRatioForItemAtIndexPath</code> (delegate): Set the height as a ration of the width. For example height = 1:2 * calculatedWidth. value of 0 is ignored</li>
<li><code>heightForItemAtIndexPath</code> (delegate): Set the height to an exact value.</li>
<li><code>layout.defaultItemHeight</code>: A default height to use if the delegate does not supply a value</li>
</ol>
<p>A special case also exists if both a ratio and a height are returned by the delegate. in this case a height will be calculated by the ratio and added to the static height from <code>heightForItemAtIndexPath</code>. Considering the example above with a item width of 88 the following examples are valid where ratio and height represent the values returned by the associated delegate method:</p>
<pre class="highlight plaintext"><code>ratio = 1:2 (44)
height = 0
itemHeight = 44
ratio = 0:0 (0)
height = 50
itemHeight = 50
ratio = 1:2 (44)
height = 20
itemHeight = 64
</code></pre>
<p>When heights are consistent for each item, the items will display in a grif formation. When items vay in height they will take on a waterfall appearance, each item pinning to the previous item in the column. By default items are placed in columns from left to right. This is controlled by the <code>itemRenderDirection</code> and can be set to <code>rightToLeft</code> or <code>shortestFirst</code>.</p>
<h2 id='collectionviewflowlayout' class='heading'>CollectionViewFlowLayout</h2>
<p>A variation of UICollectionViewFlowLayout. This layout is primarily row based, but uses ItemStyles to group similar items together.</p>
<p>#### Styles</p>
<p>Flow layout uses styles to group items. The layout’s delegate, <code><a href="Protocols/CollectionViewDelegateFlowLayout.html">CollectionViewDelegateFlowLayout</a></code>, is responsible for providing a style for each item in the collection view. The styles are similar but can be used to create or break groupings based on size.</p>
<p><strong>Flow</strong> items are grouped together, always placing as many same height items in each row as possible. If the row becomes full or an flow item of a different height is provided, the layout will just to the next row and continue.</p>
<p><strong>Span</strong> items are always placed an their own row and fill the width of the Collection View.</p>
<p>Here you can see an example of how the firt two rows are created by grouping items with the same height. If the third item in the first row had a height of 80, it would have been moved to its own row. New rows will be created when either there is no room left for the next item, the item has a different height than the preceeding ite, or the item is a span.</p>
<p><img src="https://raw.githubusercontent.com/TheNounProject/CollectionView/master/img/flow_layout.png" alt="Flow Layout" title="Flow Layout"></p>
<h4 id='transformations' class='heading'>Transformations</h4>
<p>By default items are presented at the given size and left aligned. Transformations allow you to adjust the content of each row before moving on to the next row.</p>
<p>The <code>center</code> transformation will shift the contents in a row to be center aligned without changing the size of any items.</p>
<p>The <code>fill</code> tranformation will enlarge the items in a row proportionally to fill the row. If the items have already filled the row, no tranformation occurs. Note that this change the size of the items from the size provide by the items style and will affect the height of the entire row.</p>
<h4 id='spacing' class='heading'>Spacing</h4>
<p>Spacing options such as <code>interspanSpacing</code> and <code>spanGroupSpacingBefore</code> allow you to customize the space around different types of style groups.</p>
<p>The spanGroupSpacingBefore/After options will apply a set amount of space before or after a group of span items (one or more spans).</p>
<p><img src="https://raw.githubusercontent.com/TheNounProject/CollectionView/master/img/flow_layout_spacing.png" alt="Flow Layout Spacing" title="Flow Layout Spacing"></p>
<h2 id='custom-layouts' class='heading'>Custom Layouts</h2>
<p>Layouts are designed to make just about arrangment of a collection views contents possible. Creating a new layout requires subclassing <code><a href="Classes/CollectionViewLayout.html">CollectionViewLayout</a></code> and overriding its methods to be able to return the necessary data to the collection view when requested.</p>
<p>That said, it is important to prepare and deliver this data as efficiently as possible. The collection view relies on the layout to determine the location of items and what items exist at particular locations and requests this data often. Doing too much work to detmine this data can lead to slow performance while interacting with the collection view, including scrolling.</p>
<p>The first step in avoiding redundant calculations in a layout is to prepare as much as possible up front. The <code>prepare</code> method should be overriden to do this work. Typically this involved calculation item attributes and caching them for quick reference when requested by the collection view.</p>
<p>For more in depth details about creating a collection see the <code><a href="Classes/CollectionViewLayout.html">CollectionViewLayout</a></code> documentation and refer to the provided layouts.</p>
</section>
</section>
</article>
</div>
<div class="nav-wrapper">
<nav class="nav-bottom">
<ul class="nav-groups">
<li class="nav-group-name">
<a href="Guides.html">Guides</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="introduction.html">Introduction</a>
</li>
<li class="nav-group-task">
<a href="basic-setup.html">Basic Setup</a>
</li>
<li class="nav-group-task">
<a href="supplementary-views.html">Supplementary Views</a>
</li>
<li class="nav-group-task">
<a href="layouts.html">Layouts</a>
</li>
<li class="nav-group-task">
<a href="drag--drop.html">Drag & Drop</a>
</li>
<li class="nav-group-task">
<a href="content-updates.html">Content Updates</a>
</li>
<li class="nav-group-task">
<a href="results-controller.html">Results Controller</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="Collection View.html">Collection View</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="Classes/CollectionView.html">CollectionView</a>
</li>
<li class="nav-group-task">
<a href="Classes/CollectionView.html#/s:14CollectionViewAAC13SelectionModeO">– SelectionMode</a>
</li>
<li class="nav-group-task">
<a href="Protocols/CollectionViewDataSource.html">CollectionViewDataSource</a>
</li>
<li class="nav-group-task">
<a href="Protocols/CollectionViewDelegate.html">CollectionViewDelegate</a>
</li>
<li class="nav-group-task">
<a href="Protocols/CollectionViewDragDelegate.html">CollectionViewDragDelegate</a>
</li>
<li class="nav-group-task">
<a href="Classes/CollectionViewCell.html">CollectionViewCell</a>
</li>
<li class="nav-group-task">
<a href="Classes/CollectionReusableView.html">CollectionReusableView</a>
</li>
<li class="nav-group-task">
<a href="Classes/CollectionViewController.html">CollectionViewController</a>
</li>
<li class="nav-group-task">
<a href="Collection View.html#/s:14CollectionView0aB17LayoutElementKindV">CollectionViewLayoutElementKind</a>
</li>
<li class="nav-group-task">
<a href="Collection View.html#/s:14CollectionView0A15ElementCategoryO">CollectionElementCategory</a>
</li>
<li class="nav-group-task">
<a href="Collection View.html#/s:14CollectionView0aB9DirectionO">CollectionViewDirection</a>
</li>
<li class="nav-group-task">
<a href="Collection View.html#/s:14CollectionView0aB15ScrollDirectionO">CollectionViewScrollDirection</a>
</li>
<li class="nav-group-task">
<a href="Collection View.html#/s:14CollectionView0aB14ScrollPositionO">CollectionViewScrollPosition</a>
</li>
<li class="nav-group-task">
<a href="Classes/CollectionViewPreviewCell.html">CollectionViewPreviewCell</a>
</li>
<li class="nav-group-task">
<a href="Classes/CollectionViewPreviewController.html">CollectionViewPreviewController</a>
</li>
<li class="nav-group-task">
<a href="Protocols/CollectionViewPreviewTransitionCell.html">CollectionViewPreviewTransitionCell</a>
</li>
<li class="nav-group-task">
<a href="Protocols/CollectionViewPreviewControllerDelegate.html">CollectionViewPreviewControllerDelegate</a>
</li>
<li class="nav-group-task">
<a href="Collection View.html#/s:14CollectionView19AnimationCompletiona">AnimationCompletion</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="Collection View Layouts.html">Collection View Layouts</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="Classes/CollectionViewLayout.html">CollectionViewLayout</a>
</li>
<li class="nav-group-task">
<a href="Classes/CollectionViewLayoutAttributes.html">CollectionViewLayoutAttributes</a>
</li>
<li class="nav-group-task">
<a href="Classes/CollectionViewListLayout.html">CollectionViewListLayout</a>
</li>
<li class="nav-group-task">
<a href="Protocols/CollectionViewDelegateListLayout.html">CollectionViewDelegateListLayout</a>
</li>
<li class="nav-group-task">
<a href="Classes/CollectionViewColumnLayout.html">CollectionViewColumnLayout</a>
</li>
<li class="nav-group-task">
<a href="Classes/CollectionViewColumnLayout.html#/s:14CollectionView0aB12ColumnLayoutC0D8StrategyO">– LayoutStrategy</a>
</li>
<li class="nav-group-task">
<a href="Protocols/CollectionViewDelegateColumnLayout.html">CollectionViewDelegateColumnLayout</a>
</li>
<li class="nav-group-task">
<a href="Classes/CollectionViewFlowLayout.html">CollectionViewFlowLayout</a>
</li>
<li class="nav-group-task">
<a href="Classes/CollectionViewFlowLayout.html#/s:14CollectionView0aB10FlowLayoutC12RowTransformO">– RowTransform</a>
</li>
<li class="nav-group-task">
<a href="Classes/CollectionViewFlowLayout/ItemStyle.html">– ItemStyle</a>
</li>
<li class="nav-group-task">
<a href="Protocols/CollectionViewDelegateFlowLayout.html">CollectionViewDelegateFlowLayout</a>
</li>
<li class="nav-group-task">
<a href="Classes/CollectionViewHorizontalListLayout.html">CollectionViewHorizontalListLayout</a>
</li>
<li class="nav-group-task">
<a href="Protocols/CollectionViewDelegateHorizontalListLayout.html">CollectionViewDelegateHorizontalListLayout</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="Results Controller.html">Results Controller</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="Protocols/ResultsController.html">ResultsController</a>
</li>
<li class="nav-group-task">
<a href="Protocols/ResultsControllerDelegate.html">ResultsControllerDelegate</a>
</li>
<li class="nav-group-task">
<a href="Classes/MutableResultsController.html">MutableResultsController</a>
</li>
<li class="nav-group-task">
<a href="Classes/FetchedResultsController.html">FetchedResultsController</a>
</li>
<li class="nav-group-task">
<a href="Classes/RelationalResultsController.html">RelationalResultsController</a>
</li>
<li class="nav-group-task">
<a href="Classes/FetchedSetController.html">FetchedSetController</a>
</li>
<li class="nav-group-task">
<a href="Results Controller.html#/s:14CollectionView27ResultsControllerChangeTypeO">ResultsControllerChangeType</a>
</li>
<li class="nav-group-task">
<a href="Results Controller.html#/s:14CollectionView22ResultsControllerErrorO">ResultsControllerError</a>
</li>
<li class="nav-group-task">
<a href="Classes/CollectionViewProvider.html">CollectionViewProvider</a>
</li>
<li class="nav-group-task">
<a href="Classes/CollectionViewResultsProxy.html">CollectionViewResultsProxy</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="Other Enums.html">Other Enumerations</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="Enums/SortDescriptorResult.html">SortDescriptorResult</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="Other Extensions.html">Other Extensions</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="Extensions/IndexPath.html">IndexPath</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="Other Protocols.html">Other Protocols</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="Other Protocols.html#/s:14CollectionView30CustomDisplayStringConvertibleP">CustomDisplayStringConvertible</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="Other Structs.html">Other Structures</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="Structs/SortDescriptor.html">SortDescriptor</a>
</li>
</ul>
</li>
</ul>
</nav>
</div>
<div class="footer-wrapper">
<section id="footer">
<p>© 2018 <a class="link" href="" target="_blank" rel="external">Noun Project</a>. All rights reserved. (Last updated: 2018-10-16)</p>
<p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.9.3</a>, a <a class="link" href="https://realm.io" target="_blank" rel="external">Realm</a> project.</p>
</section>
</div>
</div>
</body>
</div>
</html>