doc
|
00001 /* 00002 Copyright 2001, 2012, Oracle and/or its affiliates. All rights reserved. 00003 Oracle and Java are registered trademarks of Oracle and/or its 00004 affiliates. Other names may be trademarks of their respective owners. 00005 UNIX is a registered trademark of The Open Group. 00006 00007 This software and related documentation are provided under a license 00008 agreement containing restrictions on use and disclosure and are 00009 protected by intellectual property laws. Except as expressly permitted 00010 in your license agreement or allowed by law, you may not use, copy, 00011 reproduce, translate, broadcast, modify, license, transmit, distribute, 00012 exhibit, perform, publish, or display any part, in any form, or by any 00013 means. Reverse engineering, disassembly, or decompilation of this 00014 software, unless required by law for interoperability, is prohibited. 00015 The information contained herein is subject to change without notice 00016 and is not warranted to be error-free. If you find any errors, please 00017 report them to us in writing. 00018 U.S. GOVERNMENT END USERS: Oracle programs, including any operating 00019 system, integrated software, any programs installed on the hardware, 00020 and/or documentation, delivered to U.S. Government end users are 00021 "commercial computer software" pursuant to the applicable Federal 00022 Acquisition Regulation and agency-specific supplemental regulations. 00023 As such, use, duplication, disclosure, modification, and adaptation 00024 of the programs, including any operating system, integrated software, 00025 any programs installed on the hardware, and/or documentation, shall be 00026 subject to license terms and license restrictions applicable to the 00027 programs. No other rights are granted to the U.S. Government. 00028 This software or hardware is developed for general use in a variety 00029 of information management applications. It is not developed or 00030 intended for use in any inherently dangerous applications, including 00031 applications that may create a risk of personal injury. If you use 00032 this software or hardware in dangerous applications, then you shall 00033 be responsible to take all appropriate fail-safe, backup, redundancy, 00034 and other measures to ensure its safe use. Oracle Corporation and its 00035 affiliates disclaim any liability for any damages caused by use of this 00036 software or hardware in dangerous applications. 00037 This software or hardware and documentation may provide access to or 00038 information on content, products, and services from third parties. 00039 Oracle Corporation and its affiliates are not responsible for and 00040 expressly disclaim all warranties of any kind with respect to 00041 third-party content, products, and services. Oracle Corporation and 00042 its affiliates will not be responsible for any loss, costs, or damages 00043 incurred due to your access to or use of third-party content, products, 00044 or services. 00045 */ 00046 00047 00048 #import <UIKit/UIKit.h> 00049 #import <Three20/Three20.h> 00050 #import <Three20/Three20+Additions.h> 00051 00057 @interface NSIndexPath(EMGridView) 00058 00059 //@property(readonly) NSUInteger row; 00060 @property(readonly) NSUInteger column; 00061 00062 + (NSIndexPath *)indexPathForRow:(NSUInteger)row column:(NSUInteger)column; 00063 00064 @end 00065 00066 #pragma mark - 00067 00068 @protocol EMGridViewCell<NSObject> 00069 00070 - (id)object; 00071 - (void)setObject:(id)object; 00072 - (NSString *)reuseIdentifier; 00073 - (void)prepareForReuse; 00074 00075 @optional 00076 00077 - (void)setSelected:(BOOL)selected animated:(BOOL)animated; 00078 00079 @end 00080 00081 #pragma mark - 00082 00083 @interface TTTableViewCell(EMGridView)<EMGridViewCell> 00084 00085 - (NSString *)reuseIdentifier; 00086 - (void)prepareForReuse; 00087 00088 @end 00089 00090 #pragma mark - 00091 00092 @class EMGridView; 00093 00094 @protocol EMGridViewDataSource<NSObject> 00095 00096 @required 00097 00098 - (UIView<EMGridViewCell> *)gridView:(EMGridView *)gridView cellAtIndexPath:(NSIndexPath *)indexPath; 00099 00100 @end 00101 00102 #pragma mark - 00103 00108 @interface EMGridSection : NSObject { 00109 @private 00110 NSIndexPath *_minIndex; 00111 NSIndexPath *_maxIndex; 00112 NSArray *_indexes; 00113 } 00114 00118 @property(nonatomic, readonly) NSIndexPath *minIndex; 00119 00123 @property(nonatomic, readonly) NSIndexPath *maxIndex; 00124 00128 @property(nonatomic, readonly) NSArray *indexes; 00129 00130 @end 00131 00132 #pragma mark - 00133 00137 @protocol EMGridViewDelegate<UIScrollViewDelegate> 00138 00139 @optional 00140 00141 - (void)gridView:(EMGridView *)gridView willDisplayGridSection:(EMGridSection *)gridSection; 00142 00143 - (void)gridView:(EMGridView *)gridView didDisplayGridSection:(EMGridSection *)gridSection; 00144 00145 - (void)gridView:(EMGridView *)gridView didSelectCellAtIndexPath:(NSIndexPath *)indexPath; 00146 00147 - (void)gridViewWillReloadData:(EMGridView *)gridView; 00148 00149 - (void) gridView:(EMGridView *)gridView didScrollToPage:(NSInteger)page; 00150 00155 - (CGSize)gridView:(EMGridView *)gridView sizeForCellAtIndexPath:(NSIndexPath *)indexPath; 00156 00157 @end 00158 00159 00160 // Default number of pages to prefetch (before and after current page) when displaying current pageworth of content. 00161 #define kPrefetchPageCountDefault 1 00162 00163 #pragma mark - 00164 00165 typedef enum EMGridViewLayoutDirection { 00166 EMGridViewLayoutDirectionHorizontal, 00167 EMGridViewLayoutDirectionVertical 00168 } EMGridViewLayoutDirection; 00169 00170 #pragma mark - 00171 00172 @class EMGridGeometry; 00173 00174 /* 00175 * 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 00176 * 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 00177 * EMGridViewCell, is subview, typically located within a tile, that displays grid cell info. EMGridViewCell is a counterpart of UITableViewCell in the grid implementation. 00178 * A grid view specific extension of NSIndexPath describes a location (row and column) of the cell in the grid. 00179 * 00180 * Grid view supports two modes of scrolling - paged and continuous. 00181 */ 00182 00183 @interface EMGridView : UIScrollView<UIScrollViewDelegate> { 00184 id<EMGridViewDataSource> _dataSource; 00185 id<EMGridViewDelegate> _gridViewDelegate; 00186 00187 UIView *_cellContainerView; 00188 00189 NSMutableDictionary *_displayedCells; 00190 00191 // cell queues indexed by reusable cell indicator; individual cell queue is an array of cells 00192 NSMutableDictionary *_cellQueues; 00193 00194 EMGridGeometry *_portraitGeometry; 00195 EMGridGeometry *_landscapeGeometry; 00196 00197 UIDeviceOrientation _deviceOrientation; 00198 00199 BOOL _geometryNeedsCalculation; 00200 00201 BOOL _snapsToGrid; 00202 00203 UIView<EMGridViewCell> *_selectedCell; 00204 00205 NSUInteger _prefetchPageCount; 00206 } 00207 00211 @property (nonatomic, assign) id<EMGridViewDataSource> dataSource; 00212 00216 @property (nonatomic, assign) id<EMGridViewDelegate> delegate; // Mask the UIScrollView delegate? 00217 00218 #pragma mark - 00219 00223 @property (nonatomic) UIDeviceOrientation deviceOrientation; 00224 00228 @property (nonatomic, readonly) UIView *cellContainerView; 00229 00233 @property (nonatomic, assign) BOOL snapsToGrid; 00234 00243 @property(nonatomic) NSUInteger prefetchPageCount; 00244 00245 - (id)initWithFrame:(CGRect)frame; 00246 00247 00248 // Configuration methods. 00249 00250 // 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. 00251 // Attempt to use mix methods from both groups will lead to unexpected results. 00252 00253 // Continuous (non-paged) scrolling. 00254 00255 - (void)setTileSize:(CGSize)size forOrientation:(UIDeviceOrientation)orientation; 00256 - (void)setMaxRows:(NSUInteger)maxRows forOrientation:(UIDeviceOrientation)orientation; 00257 - (void)setMaxColumns:(NSUInteger)maxColumns forOrientation:(UIDeviceOrientation)orientation; 00258 - (void)setTileLayoutDirection:(EMGridViewLayoutDirection)direction forOrientation:(UIDeviceOrientation)orientation; 00259 00260 // Paged scrolling. 00261 00262 - (void)setPageRows:(NSUInteger)pageRows columns:(NSUInteger)pageColumns forOrientation:(UIDeviceOrientation)orientation; 00263 - (void)setPageTileLayoutDirection:(EMGridViewLayoutDirection)direction forOrientation:(UIDeviceOrientation)orientation; 00264 - (void)setPageLayoutDirection:(EMGridViewLayoutDirection)direction forOrientation:(UIDeviceOrientation)orientation; 00265 00266 // General (applicable to both paged and continuous modes) methods. 00267 00268 - (CGSize)tileSizeForOrientation:(UIDeviceOrientation)orientation; 00269 - (void)setCellInset:(UIEdgeInsets)inset forOrientation:(UIDeviceOrientation)orientation; 00270 00271 00272 // TODO: Move to DataSource? 00273 - (void)setMaxTiles:(NSUInteger)maxTiles; 00274 00275 00276 00277 00278 // View (re)loading methods. 00279 00280 // Reloads all cells adjusting content offset if necessary, e.g. if grid dimensions changed. 00281 - (void)reloadDataAnimated:(BOOL)animated; 00282 - (UIView<EMGridViewCell> *)dequeueReusableCellWithIdentifier:(NSString *)identifier; 00283 00284 00285 // Grid state. 00286 00287 @property (nonatomic, readonly) CGSize tileSize; 00291 @property (nonatomic, readonly) NSUInteger numberOfColumns; 00295 @property (nonatomic, readonly) NSUInteger numberOfRows; 00296 00297 // General (paged and continuous mode) methods. 00298 00299 - (EMGridSection *)displayedTiles; 00300 - (EMGridSection *)tilesForPage:(NSUInteger)page; 00301 - (NSIndexPath *)indexPathForCell:(UIView<EMGridViewCell> *)cell; 00302 - (NSUInteger)ordinalForIndexPath:(NSIndexPath *)indexPath; 00303 - (NSIndexPath *)indexPathForOrdinal:(NSUInteger)ordinal; 00304 - (UIView<EMGridViewCell> *)cellAtIndexPath:(NSIndexPath *)indexPath; 00305 - (NSArray *)visibleCells; 00306 00307 // Paged mode only methods. 00308 00309 - (NSUInteger)pageForIndexPath:(NSIndexPath *)indexPath; 00310 - (NSUInteger)pageForOrdinal:(NSUInteger)ordinal; 00311 - (NSIndexPath *)pageRelativeIndexPathForOrdinal:(NSUInteger)ordinal; 00312 00313 @property (nonatomic, readonly) NSUInteger maxPages; 00314 @property (nonatomic, readonly) NSUInteger currentPage; 00315 @property (nonatomic, readonly) NSUInteger tilesPerPage; 00316 00317 00318 00319 // Scrolling. 00320 00321 - (void)scrollToCellAtIndexPath:(NSIndexPath *)indexPath animated:(BOOL)animated; 00322 - (void)scrollToPage:(NSUInteger)page animated:(BOOL)animated; 00323 00324 @end 00325