/Users/rburkes/Projects/mobile/branches/release-1-2/devices/iphone/core/src/EMLib/EMGridView.h

/*
Copyright 2001, 2012, Oracle and/or its affiliates. All rights reserved.
Oracle and Java are registered trademarks of Oracle and/or its 
affiliates. Other names may be trademarks of their respective owners.
UNIX is a registered trademark of The Open Group.

This software and related documentation are provided under a license 
agreement containing restrictions on use and disclosure and are 
protected by intellectual property laws. Except as expressly permitted 
in your license agreement or allowed by law, you may not use, copy, 
reproduce, translate, broadcast, modify, license, transmit, distribute, 
exhibit, perform, publish, or display any part, in any form, or by any 
means. Reverse engineering, disassembly, or decompilation of this 
software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice 
and is not warranted to be error-free. If you find any errors, please 
report them to us in writing.
U.S. GOVERNMENT END USERS: Oracle programs, including any operating 
system, integrated software, any programs installed on the hardware, 
and/or documentation, delivered to U.S. Government end users are 
"commercial computer software" pursuant to the applicable Federal 
Acquisition Regulation and agency-specific supplemental regulations. 
As such, use, duplication, disclosure, modification, and adaptation 
of the programs, including any operating system, integrated software, 
any programs installed on the hardware, and/or documentation, shall be 
subject to license terms and license restrictions applicable to the 
programs. No other rights are granted to the U.S. Government.
This software or hardware is developed for general use in a variety 
of information management applications. It is not developed or 
intended for use in any inherently dangerous applications, including 
applications that may create a risk of personal injury. If you use 
this software or hardware in dangerous applications, then you shall 
be responsible to take all appropriate fail-safe, backup, redundancy, 
and other measures to ensure its safe use. Oracle Corporation and its 
affiliates disclaim any liability for any damages caused by use of this 
software or hardware in dangerous applications.
This software or hardware and documentation may provide access to or 
information on content, products, and services from third parties. 
Oracle Corporation and its affiliates are not responsible for and 
expressly disclaim all warranties of any kind with respect to 
third-party content, products, and services. Oracle Corporation and 
its affiliates will not be responsible for any loss, costs, or damages 
incurred due to your access to or use of third-party content, products, 
or services.
*/


#import <UIKit/UIKit.h>
#import <Three20/Three20.h>
#import <Three20/Three20+Additions.h>

@interface NSIndexPath(EMGridView) 

//@property(readonly) NSUInteger row;
@property(readonly) NSUInteger column;

+ (NSIndexPath *)indexPathForRow:(NSUInteger)row column:(NSUInteger)column;

@end

#pragma mark -

@protocol EMGridViewCell<NSObject>

- (id)object;
- (void)setObject:(id)object;
- (NSString *)reuseIdentifier;
- (void)prepareForReuse;

@optional

- (void)setSelected:(BOOL)selected animated:(BOOL)animated;

@end

#pragma mark -

@interface TTTableViewCell(EMGridView)<EMGridViewCell>

- (NSString *)reuseIdentifier;
- (void)prepareForReuse;

@end

#pragma mark -

@class EMGridView;

@protocol EMGridViewDataSource<NSObject>

@required

- (UIView<EMGridViewCell> *)gridView:(EMGridView *)gridView cellAtIndexPath:(NSIndexPath *)indexPath;

@end

#pragma mark -

@interface EMGridSection : NSObject {   
@private
        NSIndexPath *_minIndex;
        NSIndexPath *_maxIndex;
        NSArray *_indexes;
}

@property(nonatomic, readonly) NSIndexPath *minIndex;

@property(nonatomic, readonly) NSIndexPath *maxIndex;

@property(nonatomic, readonly) NSArray *indexes;

@end

#pragma mark -

@protocol EMGridViewDelegate<UIScrollViewDelegate>

@optional

- (void)gridView:(EMGridView *)gridView willDisplayGridSection:(EMGridSection *)gridSection;

- (void)gridView:(EMGridView *)gridView didDisplayGridSection:(EMGridSection *)gridSection;

- (void)gridView:(EMGridView *)gridView didSelectCellAtIndexPath:(NSIndexPath *)indexPath;

- (void)gridViewWillReloadData:(EMGridView *)gridView;

- (void) gridView:(EMGridView *)gridView didScrollToPage:(NSInteger)page;

- (CGSize)gridView:(EMGridView *)gridView sizeForCellAtIndexPath:(NSIndexPath *)indexPath;

@end


// Default number of pages to prefetch (before and after current page) when displaying current pageworth of content.
#define kPrefetchPageCountDefault 1

#pragma mark -

typedef enum EMGridViewLayoutDirection {
        EMGridViewLayoutDirectionHorizontal,
        EMGridViewLayoutDirectionVertical
} EMGridViewLayoutDirection;

#pragma mark -

@class EMGridGeometry;

/*
 * Grid view class provides means of displaying information in the grid. It is similar to UITableView and uses delegate, data source and reusable cell components in the same fashion 
 * to define functionality of the grid. Grid view content area is divided into tiles - equally sized rectangles determining grid layout. A grid view cell, defined by the protocol 
 * EMGridViewCell, is subview, typically located within a tile, that displays grid cell info. EMGridViewCell is a counterpart of UITableViewCell in the grid implementation. 
 * A grid view specific extension of NSIndexPath describes a location (row and column) of the cell in the grid.  
 *
 * Grid view supports two modes of scrolling - paged and continuous. 
 */

@interface EMGridView : UIScrollView<UIScrollViewDelegate> {
        id<EMGridViewDataSource> _dataSource;
        id<EMGridViewDelegate> _gridViewDelegate;
        
        UIView *_cellContainerView;
        
        NSMutableDictionary *_displayedCells;
        
        // cell queues indexed by reusable cell indicator; individual cell queue is an array of cells
        NSMutableDictionary *_cellQueues;
        
        EMGridGeometry *_portraitGeometry;
        EMGridGeometry *_landscapeGeometry;
        
        UIDeviceOrientation _deviceOrientation;
        
        BOOL _geometryNeedsCalculation;
        
        BOOL _snapsToGrid;
        
        UIView<EMGridViewCell> *_selectedCell;
        
        NSUInteger _prefetchPageCount;
}

@property (nonatomic, assign) id<EMGridViewDataSource> dataSource;

@property (nonatomic, assign) id<EMGridViewDelegate> delegate; // Mask the UIScrollView delegate?

#pragma mark -

@property (nonatomic) UIDeviceOrientation deviceOrientation;

@property (nonatomic, readonly) UIView *cellContainerView;

@property (nonatomic, assign) BOOL snapsToGrid;

@property(nonatomic) NSUInteger prefetchPageCount;

- (id)initWithFrame:(CGRect)frame;


// Configuration methods. 

// IMPORTANT: make sure that only methods belonging to specific configuration type are used, i.e. for paged scrolling use methods defined in "Paged scrolling" section. 
// Attempt to use mix methods from both groups will lead to unexpected results. 

// Continuous (non-paged) scrolling. 

- (void)setTileSize:(CGSize)size forOrientation:(UIDeviceOrientation)orientation;
- (void)setMaxRows:(NSUInteger)maxRows forOrientation:(UIDeviceOrientation)orientation;
- (void)setMaxColumns:(NSUInteger)maxColumns forOrientation:(UIDeviceOrientation)orientation;
- (void)setTileLayoutDirection:(EMGridViewLayoutDirection)direction forOrientation:(UIDeviceOrientation)orientation;

// Paged scrolling. 

- (void)setPageRows:(NSUInteger)pageRows columns:(NSUInteger)pageColumns forOrientation:(UIDeviceOrientation)orientation;
- (void)setPageTileLayoutDirection:(EMGridViewLayoutDirection)direction forOrientation:(UIDeviceOrientation)orientation;
- (void)setPageLayoutDirection:(EMGridViewLayoutDirection)direction forOrientation:(UIDeviceOrientation)orientation;

// General (applicable to both paged and continuous modes) methods. 

- (CGSize)tileSizeForOrientation:(UIDeviceOrientation)orientation;
- (void)setCellInset:(UIEdgeInsets)inset forOrientation:(UIDeviceOrientation)orientation;


// TODO: Move to DataSource?
- (void)setMaxTiles:(NSUInteger)maxTiles;




// View (re)loading methods.

// Reloads all cells adjusting content offset if necessary, e.g. if grid dimensions changed. 
- (void)reloadDataAnimated:(BOOL)animated;
- (UIView<EMGridViewCell> *)dequeueReusableCellWithIdentifier:(NSString *)identifier;


// Grid state.

@property (nonatomic, readonly) CGSize tileSize;
@property (nonatomic, readonly) NSUInteger numberOfColumns;
@property (nonatomic, readonly) NSUInteger numberOfRows;

// General (paged and continuous mode) methods.

- (EMGridSection *)displayedTiles;
- (EMGridSection *)tilesForPage:(NSUInteger)page;
- (NSIndexPath *)indexPathForCell:(UIView<EMGridViewCell> *)cell;
- (NSUInteger)ordinalForIndexPath:(NSIndexPath *)indexPath;
- (NSIndexPath *)indexPathForOrdinal:(NSUInteger)ordinal;
- (UIView<EMGridViewCell> *)cellAtIndexPath:(NSIndexPath *)indexPath;
- (NSArray *)visibleCells;

// Paged mode only methods. 

- (NSUInteger)pageForIndexPath:(NSIndexPath *)indexPath;
- (NSUInteger)pageForOrdinal:(NSUInteger)ordinal;
- (NSIndexPath *)pageRelativeIndexPathForOrdinal:(NSUInteger)ordinal;

@property (nonatomic, readonly) NSUInteger maxPages;
@property (nonatomic, readonly) NSUInteger currentPage;
@property (nonatomic, readonly) NSUInteger tilesPerPage;



// Scrolling.

- (void)scrollToCellAtIndexPath:(NSIndexPath *)indexPath animated:(BOOL)animated;
- (void)scrollToPage:(NSUInteger)page animated:(BOOL)animated;

@end