Merge branch 'release/0.6'

CHTCollectionViewWaterfallLayout.h

@@ -7,19 +7,31 @@
 
 #import <UIKit/UIKit.h>
 
-#pragma mark - Constants
+/**
+ *  Constants that specify the types of supplementary views that can be presented using a waterfall layout.
+ */
 
+/// A supplementary view that identifies the header for a given section.
 extern NSString *const CHTCollectionElementKindSectionHeader;
+/// A supplementary view that identifies the footer for a given section.
 extern NSString *const CHTCollectionElementKindSectionFooter;
 
 #pragma mark - CHTCollectionViewDelegateWaterfallLayout
 
 @class CHTCollectionViewWaterfallLayout;
 
+/**
+ *  The CHTCollectionViewDelegateWaterfallLayout protocol defines methods that let you coordinate with a
+ *  CHTCollectionViewWaterfallLayout object to implement a waterfall-based layout.
+ *  The methods of this protocol define the size of items.
+ *
+ *  The waterfall layout object expects the collection view’s delegate object to adopt this protocol.
+ *  Therefore, implement this protocol on object assigned to your collection view’s delegate property.
+ */
 @protocol CHTCollectionViewDelegateWaterfallLayout <UICollectionViewDelegate>
 @required
 /**
- *  Asks the delegate for the height of the specified item’s cell.
+ *  Asks the delegate for the size of the specified item’s cell.
  *
  *  @param collectionView
  *    The collection view object displaying the waterfall layout.
@@ -29,11 +41,9 @@ extern NSString *const CHTCollectionElementKindSectionFooter;
  *    The index path of the item.
  *
  *  @return
- *    The height of the specified item. Must be greater than 0.
+ *    The original size of the specified item. Both width and height must be greater than 0.
  */
-- (CGFloat)collectionView:(UICollectionView *)collectionView
-                   layout:(UICollectionViewLayout *)collectionViewLayout
- heightForItemAtIndexPath:(NSIndexPath *)indexPath;
+- (CGSize)collectionView:(UICollectionView *)collectionView layout:(UICollectionViewLayout *)collectionViewLayout sizeForItemAtIndexPath:(NSIndexPath *)indexPath;
 
 @optional
 /**
@@ -55,9 +65,7 @@ extern NSString *const CHTCollectionElementKindSectionFooter;
  *  @see
  *    headerHeight
  */
-- (CGFloat)collectionView:(UICollectionView *)collectionView
-                   layout:(UICollectionViewLayout *)collectionViewLayout
- heightForHeaderInSection:(NSInteger)section;
+- (CGFloat)collectionView:(UICollectionView *)collectionView layout:(UICollectionViewLayout *)collectionViewLayout heightForHeaderInSection:(NSInteger)section;
 
 /**
  *  Asks the delegate for the height of the footer view in the specified section.
@@ -73,36 +81,57 @@ extern NSString *const CHTCollectionElementKindSectionFooter;
  *    The height of the footer. If you return 0, no footer is added.
  *
  *  @discussion
- *    If you do not implement this method, the waterfall layout uses the value in its footerHeight property to set the size of the header.
+ *    If you do not implement this method, the waterfall layout uses the value in its footerHeight property to set the size of the footer.
  *
  *  @see
  *    footerHeight
  */
-- (CGFloat)collectionView:(UICollectionView *)collectionView
-                   layout:(UICollectionViewLayout *)collectionViewLayout
- heightForFooterInSection:(NSInteger)section;
+- (CGFloat)collectionView:(UICollectionView *)collectionView layout:(UICollectionViewLayout *)collectionViewLayout heightForFooterInSection:(NSInteger)section;
 @end
 
 #pragma mark - CHTCollectionViewWaterfallLayout
 
+/**
+ *  The CHTCollectionViewWaterfallLayout class is a concrete layout object that organizes items into waterfall-based grids 
+ *  with optional header and footer views for each section.
+ *
+ *  A waterfall layout works with the collection view’s delegate object to determine the size of items, headers, and footers 
+ *  in each section. That delegate object must conform to the `CHTCollectionViewDelegateWaterfallLayout` protocol.
+ *
+ *  Each section in a waterfall layout can have its own custom header and footer. To configure the header or footer for a view, 
+ *  you must configure the height of the header or footer to be non zero. You can do this by implementing the appropriate delegate 
+ *  methods or by assigning appropriate values to the `headerHeight` and `footerHeight` properties. 
+ *  If the header or footer height is 0, the corresponding view is not added to the collection view.
+ *
+ *  @note CHTCollectionViewWaterfallLayout doesn't support decoration view, and it supports vertical scrolling direction only.
+ */
 @interface CHTCollectionViewWaterfallLayout : UICollectionViewLayout
+
 /**
  *  @brief How many columns for this layout.
  *  @discussion Default: 2
  */
 @property (nonatomic, assign) NSInteger columnCount;
 
 /**
- *  @brief Width for each item.
- *  @discussion Default: 140
+ *  @brief The minimum spacing to use between successive columns.
+ *  @discussion Default: 10.0
  */
-@property (nonatomic, assign) CGFloat itemWidth;
+@property (nonatomic, assign) CGFloat minimumColumnSpacing;
+
+/**
+ *  @brief The minimum spacing to use between items in the same column.
+ *  @discussion Default: 10.0
+ *  @note This spacing is not applied to the space between header and columns or between columns and footer.
+ */
+@property (nonatomic, assign) CGFloat minimumInteritemSpacing;
 
 /**
  *  @brief Height for section header
  *  @discussion
  *    If your collectionView's delegate doesn't implement `collectionView:layout:heightForHeaderInSection:`,
  *    then this value will be used.
+ *
  *    Default: 0
  */
 @property (nonatomic, assign) CGFloat headerHeight;
@@ -112,19 +141,19 @@ extern NSString *const CHTCollectionElementKindSectionFooter;
  *  @discussion
  *    If your collectionView's delegate doesn't implement `collectionView:layout:heightForFooterInSection:`,
  *    then this value will be used.
+ *
  *    Default: 0
  */
 @property (nonatomic, assign) CGFloat footerHeight;
 
 /**
  *  @brief The margins that are used to lay out content in each section.
- *  @discussion Default: UIEdgeInsetsZero
+ *  @discussion
+ *    Section insets are margins applied only to the items in the section. 
+ *    They represent the distance between the header view and the columns and between the columns and the footer view. 
+ *    They also indicate the spacing on either side of columns. They do not affect the size of the headers or footers themselves.
+ *
+ *    Default: UIEdgeInsetsZero
  */
 @property (nonatomic, assign) UIEdgeInsets sectionInset;
-
-/**
- *  @brief Spacing between items vertically.
- *  @discussion It will be calculated automatically if you don't assign a value.
- */
-@property (nonatomic, assign) CGFloat verticalItemSpacing;
 @end