Permalink
Browse files

Organized SSCollectionView documentation

* Added `visibleItems`
* Added `indexPathsForVisibleRows`
  • Loading branch information...
1 parent 5046dbd commit d422ca0e0c69867df1eedbdccb2ea2a9fcf21db1 @soffes soffes committed Oct 17, 2011
Showing with 143 additions and 76 deletions.
  1. +125 −72 SSToolkit/SSCollectionView.h
  2. +18 −4 SSToolkit/SSCollectionView.m
View
197 SSToolkit/SSCollectionView.h
@@ -46,50 +46,46 @@ typedef enum {
/**
Simple collection view.
- My goals are to be similar to UITableView and NSCollectionView when possible. Only scrolling vertically is currently
- supported.
+ My goals are to be similar to `UITableView` and `NSCollectionView` when possible. Only scrolling vertically is
+ currently supported.
Editing will be my next focus. Then animating changes when data changes and an option to disable that.
- Note: NSIndexPath is uses the same way UITableView uses it. The `row` property is used to specify the item
- instead of row. This is done to make working with other classes that use NSIndexPath (like NSFetchedResultsController)
- easier.
+ Note: `NSIndexPath` is uses the same way `UITableView` uses it. The `row` property is used to specify the item
+ instead of row. This is done to make working with other classes that use `NSIndexPath` (like
+ `NSFetchedResultsController`) easier.
*/
-@interface SSCollectionView : UIView <UITableViewDataSource, UITableViewDelegate>
+@interface SSCollectionView : UIView
-/**
- The object that acts as the data source of the receiving collection view.
- */
-@property (nonatomic, assign) id<SSCollectionViewDataSource> dataSource;
-
-/**
- The object that acts as the delegate of the receiving collection view.
- */
-@property (nonatomic, assign) id<SSCollectionViewDelegate> delegate;
+///------------------------------
+/// Configuring a Collection View
+///------------------------------
/**
- The style of the receiving collection view's headers and footers.
+ Returns a reusable collection view item object located by its identifier.
- Setting to `SSCollectionViewExtremitiesStyleFixed` will cause the headers and footer to behave like a `UITableView`
- with its style set to `UITableViewStylePlain`. Setting to `SSCollectionViewExtremitiesStyleScrolling` will cause the
- headers and footer to behave like a `UITableView` with its style set to `UITableViewStyleGrouped`. The default is
- `SSCollectionViewExtremitiesStyleFixed`.
+ @param identifier A string identifying the item object to be reused.
+
+ @return A `SSCollectionViewItem` object with the associated identifier or `nil` if no such object exists in the
+ reusable-item queue.
*/
-@property (nonatomic, assign) SSCollectionViewExtremitiesStyle extremitiesStyle;
+- (SSCollectionViewItem *)dequeueReusableItemWithIdentifier:(NSString *)identifier;
/**
- The minimum column spacing.
+ Returns the number of item (collection view items) in a specified section.
- The default is `0.0`.
+ @param section An index number that identifies a section of the collection.
+
+ @return The number of items in the section.
*/
-@property (nonatomic, assign) CGFloat minimumColumnSpacing;
+- (NSUInteger)numberOfItemsInSection:(NSUInteger)section;
/**
- The spacing between each row in the receiver. This does not add space above the first row or below the last.
+ The number of sections in the collection view.
- The row spacing is in points. The default is `20.0`.
+ `SSCollectionView` gets the value returned by this method from its data source and caches it.
*/
-@property (nonatomic, assign) CGFloat rowSpacing;
+@property (nonatomic, assign, readonly) NSUInteger numberOfSections;
/**
The background view of the collection view.
@@ -111,39 +107,33 @@ typedef enum {
@property (nonatomic, retain) UIView *collectionFooterView;
/**
- A Boolean value that determines whether selecting items is enabled.
+ The style of the receiving collection view's headers and footers.
- If the value of this property is `YES`, selecting is enabled, and if it is `NO`, selecting is disabled. The default is
- `YES`.
+ Setting to `SSCollectionViewExtremitiesStyleFixed` will cause the headers and footer to behave like a `UITableView`
+ with its style set to `UITableViewStylePlain`. Setting to `SSCollectionViewExtremitiesStyleScrolling` will cause the
+ headers and footer to behave like a `UITableView` with its style set to `UITableViewStyleGrouped`. The default is
+ `SSCollectionViewExtremitiesStyleFixed`.
*/
-@property (nonatomic, assign) BOOL allowsSelection;
+@property (nonatomic, assign) SSCollectionViewExtremitiesStyle extremitiesStyle;
/**
- The internal scroll view of the collection view. The delegate must not be overridden.
+ The minimum column spacing.
+
+ The default is `0.0`.
*/
-@property (nonatomic, retain, readonly) UIScrollView *scrollView;
+@property (nonatomic, assign) CGFloat minimumColumnSpacing;
/**
- The number of sections in the collection view.
+ The spacing between each row in the receiver. This does not add space above the first row or below the last.
- `SSCollectionView` gets the value returned by this method from its data source and caches it.
+ The row spacing is in points. The default is `20.0`.
*/
-@property (nonatomic, assign, readonly) NSUInteger numberOfSections;
+@property (nonatomic, assign) CGFloat rowSpacing;
-/**
- Reloads the items and sections of the receiver.
- */
-- (void)reloadData;
-/**
- Returns a reusable collection view item object located by its identifier.
-
- @param identifier A string identifying the item object to be reused.
-
- @return A `SSCollectionViewItem` object with the associated identifier or `nil` if no such object exists in the
- reusable-item queue.
- */
-- (SSCollectionViewItem *)dequeueReusableItemWithIdentifier:(NSString *)identifier;
+///-----------------------------
+/// Accessing Items and Sections
+///-----------------------------
/**
Returns the collection view item at the specified index path.
@@ -155,7 +145,7 @@ typedef enum {
@see indexPathForItem:
*/
-- (SSCollectionViewItem *)itemPathForIndex:(NSIndexPath *)indexPath;
+- (SSCollectionViewItem *)itemForIndexPath:(NSIndexPath *)indexPath;
/**
Returns an index path representing the row (index) and section of a given collection view item.
@@ -169,6 +159,44 @@ typedef enum {
- (NSIndexPath *)indexPathForItem:(SSCollectionViewItem *)item;
/**
+ Returns the collection view items that are visible in the receiver.
+
+ @return An array containing `SSCollectionViewItem` objects, each representing a visible item in the receiving
+ collection view. The array's order is undefined.
+ */
+- (NSArray *)visibleItems;
+
+/**
+ Returns an array of index paths each identifying a visible item in the receiver.
+
+ @return An array of `NSIndexPath` objects each representing a row index and section index that together identify a
+ visible item in the collection view. Returns `nil` if no items are visible. The array's order is undefined.
+ */
+- (NSArray *)indexPathsForVisibleRows;
+
+///------------------------------
+/// Scrolling the Collection View
+///------------------------------
+
+/**
+ Scrolls the receiver until an item identified by index path is at a particular location on the screen.
+
+ @param indexPath An index path that identifies an item in the table view by its row index and its section index.
+
+ @param scrollPosition A constant that identifies a relative position in the receiving collection view (top, middle,
+ bottom) for row when scrolling concludes.
+
+ @param animated `YES` if you want to animate the change in position, `NO` if it should be
+ immediate.
+ */
+- (void)scrollToItemAtIndexPath:(NSIndexPath *)indexPath atScrollPosition:(SSCollectionViewScrollPosition)scrollPosition animated:(BOOL)animated;
+
+
+///--------------------
+/// Managing Selections
+///--------------------
+
+/**
Selects an item in the receiver identified by index path, optionally scrolling the item to a location in the receiver.
Calling this method does cause the delegate to receive a `collectionView:willSelectRowAtIndexPath:` and
@@ -195,17 +223,21 @@ typedef enum {
- (void)deselectItemAtIndexPath:(NSIndexPath *)indexPath animated:(BOOL)animated;
/**
- Scrolls the receiver until an item identified by index path is at a particular location on the screen.
-
- @param indexPath An index path that identifies an item in the table view by its row index and its section index.
-
- @param scrollPosition A constant that identifies a relative position in the receiving collection view (top, middle,
- bottom) for row when scrolling concludes.
+ A Boolean value that determines whether selecting items is enabled.
- @param animated `YES` if you want to animate the change in position, `NO` if it should be
- immediate.
+ If the value of this property is `YES`, selecting is enabled, and if it is `NO`, selecting is disabled. The default is
+ `YES`.
*/
-- (void)scrollToItemAtIndexPath:(NSIndexPath *)indexPath atScrollPosition:(SSCollectionViewScrollPosition)scrollPosition animated:(BOOL)animated;
+@property (nonatomic, assign) BOOL allowsSelection;
+
+///------------------------------
+/// Reloading the Collection View
+///------------------------------
+
+/**
+ Reloads the items and sections of the receiver.
+ */
+- (void)reloadData;
/**
Reloads the specified item.
@@ -214,23 +246,28 @@ typedef enum {
*/
- (void)reloadItemsAtIndexPaths:(NSArray *)indexPaths;
+
+///-----------------------------------------------
+/// Accessing Drawing Areas of the Collection View
+///-----------------------------------------------
+
/**
- Returns the number of item (collection view items) in a specified section.
+ Returns the drawing area for a specified section of the receiver.
- @param section An index number that identifies a section of the collection.
+ @param section An index number identifying a section of the collection view.
- @return The number of items in the section.
+ @return A rectangle defining the area in which the collection view draws the section.
*/
-- (NSUInteger)numberOfItemsInSection:(NSUInteger)section;
+- (CGRect)rectForSection:(NSUInteger)section;
/**
- Returns the drawing area for a specified section of the receiver.
+ Returns the drawing area for the footer of the specified section.
@param section An index number identifying a section of the collection view.
- @return A rectangle defining the area in which the collection view draws the section.
+ @return A rectangle defining the area in which the collection view draws the section footer.
*/
-- (CGRect)rectForSection:(NSUInteger)section;
+- (CGRect)rectForFooterInSection:(NSUInteger)section;
/** Returns the drawing area for the header of the specified section.
@@ -240,14 +277,20 @@ typedef enum {
*/
- (CGRect)rectForHeaderInSection:(NSUInteger)section;
+
+///------------------------------------------
+/// Managing the Delegate and the Data Source
+///------------------------------------------
+
/**
- Returns the drawing area for the footer of the specified section.
-
- @param section An index number identifying a section of the collection view.
-
- @return A rectangle defining the area in which the collection view draws the section footer.
+ The object that acts as the data source of the receiving collection view.
*/
-- (CGRect)rectForFooterInSection:(NSUInteger)section;
+@property (nonatomic, assign) id<SSCollectionViewDataSource> dataSource;
+
+/**
+ The object that acts as the delegate of the receiving collection view.
+ */
+@property (nonatomic, assign) id<SSCollectionViewDelegate> delegate;
@end
@@ -312,6 +355,16 @@ typedef enum {
*/
- (NSUInteger)numberOfSectionsInCollectionView:(SSCollectionView *)aCollectionView;
+///-------------------------
+/// Acessing the Scroll View
+///-------------------------
+
+/**
+ The internal scroll view of the collection view. This should only be used to inspect its state. Its attributes must not
+ be overridden.
+ */
+@property (nonatomic, retain, readonly) UIScrollView *scrollView;
+
@end
View
22 SSToolkit/SSCollectionView.m
@@ -31,7 +31,7 @@
static NSString *kSSCollectionViewSectionFooterHeightKey = @"SSCollectionViewSectionFooterHeight";
static NSString *kSSCollectionViewSectionItemSizeKey = @"SSCollectionViewSectionItemSize";
-@interface SSCollectionView (PrivateMethods)
+@interface SSCollectionView () <UITableViewDataSource, UITableViewDelegate>
- (void)_initialize;
- (void)_reuseItem:(SSCollectionViewItem *)item;
- (void)_reuseItems:(NSArray *)items;
@@ -224,7 +224,7 @@ - (SSCollectionViewItem *)dequeueReusableItemWithIdentifier:(NSString *)identifi
}
-- (SSCollectionViewItem *)itemPathForIndex:(NSIndexPath *)indexPath {
+- (SSCollectionViewItem *)itemForIndexPath:(NSIndexPath *)indexPath {
__block SSCollectionViewItem *item = nil;
[_visibleItems enumerateObjectsUsingBlock:^(id object, BOOL *stop) {
if ([[(SSCollectionViewItem *)object indexPath] isEqual:indexPath]) {
@@ -248,7 +248,7 @@ - (void)selectItemAtIndexPath:(NSIndexPath *)indexPath animated:(BOOL)animated s
}
// Select
- SSCollectionViewItem *item = [self itemPathForIndex:indexPath];
+ SSCollectionViewItem *item = [self itemForIndexPath:indexPath];
[item setHighlighted:NO animated:NO];
[item setSelected:YES animated:YES];
@@ -272,7 +272,7 @@ - (void)deselectItemAtIndexPath:(NSIndexPath *)indexPath animated:(BOOL)animated
}
// Deselect
- SSCollectionViewItem *item = [self itemPathForIndex:indexPath];
+ SSCollectionViewItem *item = [self itemForIndexPath:indexPath];
[item setHighlighted:NO animated:NO];
[item setSelected:NO animated:YES];
@@ -340,6 +340,20 @@ - (CGRect)rectForFooterInSection:(NSUInteger)section {
}
+- (NSArray *)visibleItems {
+ return [_visibleItems allObjects];
+}
+
+
+- (NSArray *)indexPathsForVisibleRows {
+ NSMutableArray *indexPaths = [[NSMutableArray alloc] initWithCapacity:[_visibleItems count]];
+ for (SSCollectionViewItem *item in _visibleItems) {
+ [indexPaths addObject:[self indexPathForItem:item]];
+ }
+ return [indexPaths autorelease];
+}
+
+
#pragma mark - Private Methods
- (void)_initialize {

0 comments on commit d422ca0

Please sign in to comment.