From bdebb5edec0b888cbbcd5cfd73e57c392810e0e9 Mon Sep 17 00:00:00 2001 From: jverkoey Date: Fri, 29 Mar 2013 09:32:49 -0700 Subject: [PATCH] [collections] Docs and delete the mutable collection view model because it's untested. --- src/Nimbus.xcodeproj/project.pbxproj | 1 + .../src/NICollectionViewCellFactory.h | 48 ++-- .../src/NICollectionViewModel+Private.h | 1 - src/collections/src/NICollectionViewModel.h | 97 ++------ src/collections/src/NICollectionViewModel.m | 104 -------- .../NIMutableCollectionViewModel+Private.h | 31 --- .../src/NIMutableCollectionViewModel.h | 235 ------------------ .../src/NIMutableCollectionViewModel.m | 169 ------------- src/collections/src/NimbusCollections.h | 23 +- 9 files changed, 72 insertions(+), 637 deletions(-) delete mode 100644 src/collections/src/NIMutableCollectionViewModel+Private.h delete mode 100644 src/collections/src/NIMutableCollectionViewModel.h delete mode 100644 src/collections/src/NIMutableCollectionViewModel.m diff --git a/src/Nimbus.xcodeproj/project.pbxproj b/src/Nimbus.xcodeproj/project.pbxproj index d38698e0d..f0b91973d 100644 --- a/src/Nimbus.xcodeproj/project.pbxproj +++ b/src/Nimbus.xcodeproj/project.pbxproj @@ -5668,6 +5668,7 @@ 66FC98541703F9D8004E8FB8 /* Release */, ); defaultConfigurationIsVisible = 0; + defaultConfigurationName = Release; }; C7BBC6FF16DDC0E700833DC9 /* Build configuration list for PBXNativeTarget "NimbusTextField" */ = { isa = XCConfigurationList; diff --git a/src/collections/src/NICollectionViewCellFactory.h b/src/collections/src/NICollectionViewCellFactory.h index f95d63c92..288ae1671 100644 --- a/src/collections/src/NICollectionViewCellFactory.h +++ b/src/collections/src/NICollectionViewCellFactory.h @@ -31,7 +31,7 @@ * * This factory is designed to be used with NICollectionViewModel, though one could easily use * it with other collection view data source implementations simply by providing nil for the - * collection view model. + * collection view model argument. * * If you instantiate an NICollectionViewCellFactory then you can provide explicit mappings from * objects to cells. This is helpful if the effort required to implement the NICollectionViewCell @@ -43,8 +43,8 @@ @interface NICollectionViewCellFactory : NSObject /** - * Creates a cell from a given object if and only if the object conforms to the NICollectionViewCellObject - * protocol. + * Creates a cell from a given object if and only if the object conforms to the + * NICollectionViewCellObject protocol. * * This method signature matches the NICollectionViewModelDelegate method so that you can * set this factory as the model's delegate: @@ -60,13 +60,13 @@ _model.delegate = (id)[NICollectionViewCellFactory class]; * * @code - (UICollectionViewCell *)collectionViewModel:(NICollectionViewModel *)collectionViewModel - cellForCollectionView:(UICollectionView *)collectionView - atIndexPath:(NSIndexPath *)indexPath - withObject:(id)object { + cellForCollectionView:(UICollectionView *)collectionView + atIndexPath:(NSIndexPath *)indexPath + withObject:(id)object { UICollectionViewCell* cell = [NICollectionViewCellFactory collectionViewModel:collectionViewModel - cellForCollectionView:collectionView - atIndexPath:indexPath - withObject:object]; + cellForCollectionView:collectionView + atIndexPath:indexPath + withObject:object]; if (nil == cell) { // Custom cell creation here. } @@ -85,8 +85,24 @@ _model.delegate = (id)[NICollectionViewCellFactory class]; */ - (void)mapObjectClass:(Class)objectClass toCellClass:(Class)collectionViewCellClass; +/** + * Returns the mapped cell class for an object at a given index path. + * + * Explicitly mapped classes in the receiver take precedence over implicitly mapped classes. + * + * This method is helpful when implementing layout calculation methods for your collection view. You + * can fetch the cell class and then perform any selectors that are necessary for calculating the + * dimensions of the cell before it is instantiated. + */ - (Class)collectionViewCellClassForItemAtIndexPath:(NSIndexPath *)indexPath model:(NICollectionViewModel *)model; +/** + * Returns the mapped cell class for an object at a given index path. + * + * This method is helpful when implementing layout calculation methods for your collection view. You + * can fetch the cell class and then perform any selectors that are necessary for calculating the + * dimensions of the cell before it is instantiated. + */ + (Class)collectionViewCellClassForItemAtIndexPath:(NSIndexPath *)indexPath model:(NICollectionViewModel *)model; @end @@ -112,10 +128,11 @@ _model.delegate = (id)[NICollectionViewCellFactory class]; /** * The protocol for an object that can be used in the NICollectionViewCellFactory. * - * @ingroup TableCellFactory + * @ingroup CollectionViewCellFactory */ @protocol NICollectionViewCellObject @required + /** The class of cell to be created when this object is passed to the cell factory. */ - (Class)collectionViewCellClass; @@ -124,16 +141,17 @@ _model.delegate = (id)[NICollectionViewCellFactory class]; /** * The protocol for a cell created in the NICollectionViewCellFactory. * - * Cells that implement this protocol are given the object that implemented the NICollectionViewCellObject - * protocol and returned this cell's class name in @link NICollectionViewCellObject::collectionViewCellClass collectionViewCellClass@endlink. + * Cells that implement this protocol are given the object that implemented the + * NICollectionViewCellObject protocol and returned this cell's class name in + * @link NICollectionViewCellObject::collectionViewCellClass collectionViewCellClass@endlink. * - * @ingroup TableCellFactory + * @ingroup CollectionViewCellFactory */ @protocol NICollectionViewCell @required /** - * Called when a cell is created and reused. + * Called both when a cell is created and when it is reused. * * Implement this method to customize the cell's properties for display using the given object. */ @@ -152,7 +170,7 @@ _model.delegate = (id)[NICollectionViewCellFactory class]; * to the cell view, you can create an NICollectionViewCellObject and pass the class name of the cell. * @code -[tableContents addObject:[NICollectionViewCellObject objectWithCellClass:[LoadMoreCell class]]]; +[contents addObject:[NICollectionViewCellObject objectWithCellClass:[LoadMoreCell class]]]; @endcode */ @interface NICollectionViewCellObject : NSObject diff --git a/src/collections/src/NICollectionViewModel+Private.h b/src/collections/src/NICollectionViewModel+Private.h index 342f329bc..2a6230001 100644 --- a/src/collections/src/NICollectionViewModel+Private.h +++ b/src/collections/src/NICollectionViewModel+Private.h @@ -25,7 +25,6 @@ - (void)_resetCompiledData; - (void)_compileDataWithListArray:(NSArray *)listArray; - (void)_compileDataWithSectionedArray:(NSArray *)sectionedArray; -- (void)_compileSectionIndex; @end diff --git a/src/collections/src/NICollectionViewModel.h b/src/collections/src/NICollectionViewModel.h index 12f195207..5591b24a2 100644 --- a/src/collections/src/NICollectionViewModel.h +++ b/src/collections/src/NICollectionViewModel.h @@ -27,26 +27,23 @@ // Classes used when creating NICollectionViewModels. @class NICollectionViewModelFooter; // Provides the information for a footer. -typedef enum { - NICollectionViewModelSectionIndexNone, // Displays no section index. - NICollectionViewModelSectionIndexDynamic, // Generates a section index from the first letters of the section titles. - NICollectionViewModelSectionIndexAlphabetical, // Generates an alphabetical section index. -} NICollectionViewModelSectionIndex; - /** - * A non-mutable table view model that complies to the UITableViewDataSource protocol. + * A non-mutable collection view model that complies to the UICollectionViewDataSource protocol. * - * This model allows you to easily create a data source for a UITableView without having to - * implement the UITableViewDataSource methods in your UITableViewController. + * This model allows you to easily create a data source for a UICollectionView without having to + * implement the UICollectionViewDataSource methods in your controller. * * This base class is non-mutable, much like an NSArray. You must initialize this model with * the contents when you create it. * - * @ingroup TableViewModels + * This model simply manages the data relationship with your collection view. It is up to you to + * implement the collection view's layout object. + * + * @ingroup CollectionViewModels */ @interface NICollectionViewModel : NSObject -#pragma mark Creating Table View Models +#pragma mark Creating Collection View Models // Designated initializer. - (id)initWithDelegate:(id)delegate; @@ -58,32 +55,22 @@ typedef enum { - (id)objectAtIndexPath:(NSIndexPath *)indexPath; -#pragma mark Configuration - -// Immediately compiles the section index. -- (void)setSectionIndexType:(NICollectionViewModelSectionIndex)sectionIndexType showsSearch:(BOOL)showsSearch showsSummary:(BOOL)showsSummary; - -@property (nonatomic, readonly, assign) NICollectionViewModelSectionIndex sectionIndexType; // Default: NICollectionViewModelSectionIndexNone -@property (nonatomic, readonly, assign) BOOL sectionIndexShowsSearch; // Default: NO -@property (nonatomic, readonly, assign) BOOL sectionIndexShowsSummary; // Default: NO - -#pragma mark Creating Table View Cells +#pragma mark Creating Collection View Cells @property (nonatomic, NI_WEAK) id delegate; @end /** - * A protocol for NICollectionViewModel to fetch rows to be displayed for the table view. + * A protocol for NICollectionViewModel to fetch rows to be displayed for the collection view. * - * @ingroup TableViewModels + * @ingroup CollectionViewModels */ @protocol NICollectionViewModelDelegate - @required /** - * Fetches a table view cell at a given index path with a given object. + * Fetches a collection view cell at a given index path with a given object. * * The implementation of this method will generally use object to customize the cell. */ @@ -114,7 +101,7 @@ typedef enum { @end -/** @name Creating Table View Models */ +/** @name Creating Collection View Models */ /** * Initializes a newly allocated static model with the given delegate and empty contents. @@ -139,7 +126,7 @@ typedef enum { * [NSDictionary dictionaryWithObject:@"Row 2" forKey:@"title"], * [NSDictionary dictionaryWithObject:@"Row 3" forKey:@"title"], * nil]; - * [[NIStaticTableViewModel alloc] initWithListArray:contents delegate:self]; + * [[NICollectionViewModel alloc] initWithListArray:contents delegate:self]; * @endcode * * @fn NICollectionViewModel::initWithListArray:delegate: @@ -166,7 +153,7 @@ typedef enum { * [NSDictionary dictionaryWithObject:@"Row 3" forKey:@"title"], * [NICollectionViewModelFooter footerWithTitle:@"Footer"], * nil]; - * [[NIStaticTableViewModel alloc] initWithSectionedArray:contents delegate:self]; + * [[NICollectionViewModel alloc] initWithSectionedArray:contents delegate:self]; * @endcode * * @fn NICollectionViewModel::initWithSectionedArray:delegate: @@ -185,60 +172,10 @@ typedef enum { */ -/** @name Configuration */ - -/** - * Configures the model's section index properties. - * - * Calling this method will compile the section index depending on the index type chosen. - * - * @param sectionIndexType The type of section index to display. - * @param showsSearch Whether or not to show the search icon at the top of the index. - * @param showsSummary Whether or not to show the summary icon at the bottom of the index. - * @fn NICollectionViewModel::setSectionIndexType:showsSearch:showsSummary: - */ - -/** - * The section index type. - * - * You will likely use NICollectionViewModelSectionIndexAlphabetical in practice. - * - * NICollectionViewModelSectionIndexNone by default. - * - * @fn NICollectionViewModel::sectionIndexType - */ +/** @name Creating Collection View Cells */ /** - * Whether or not the search symbol will be shown in the section index. - * - * NO by default. - * - * @fn NICollectionViewModel::sectionIndexShowsSearch - */ - -/** - * Whether or not the summary symbol will be shown in the section index. - * - * NO by default. - * - * @fn NICollectionViewModel::sectionIndexShowsSummary - */ - - -/** @name Creating Table View Cells */ - -/** - * A delegate used to fetch table view cells for the data source. + * A delegate used to fetch collection view cells for the data source. * * @fn NICollectionViewModel::delegate */ - -#if NS_BLOCKS_AVAILABLE - -/** - * A block used to create a UICollectionViewCell for a given object. - * - * @fn NICollectionViewModel::createCellBlock - */ - -#endif // #if NS_BLOCKS_AVAILABLE diff --git a/src/collections/src/NICollectionViewModel.m b/src/collections/src/NICollectionViewModel.m index aa2b12bc1..d431f2722 100644 --- a/src/collections/src/NICollectionViewModel.m +++ b/src/collections/src/NICollectionViewModel.m @@ -32,9 +32,6 @@ @implementation NICollectionViewModel @synthesize sections = _sections; @synthesize sectionIndexTitles = _sectionIndexTitles; @synthesize sectionPrefixToSectionIndex = _sectionPrefixToSectionIndex; -@synthesize sectionIndexType = _sectionIndexType; -@synthesize sectionIndexShowsSearch = _sectionIndexShowsSearch; -@synthesize sectionIndexShowsSummary = _sectionIndexShowsSummary; @synthesize delegate = _delegate; @@ -43,10 +40,6 @@ - (id)initWithDelegate:(id)delegate { if ((self = [super init])) { self.delegate = delegate; - _sectionIndexType = NICollectionViewModelSectionIndexNone; - _sectionIndexShowsSearch = NO; - _sectionIndexShowsSummary = NO; - [self _resetCompiledData]; } return self; @@ -166,89 +159,6 @@ - (void)_compileDataWithSectionedArray:(NSArray *)sectionedArray { } -/////////////////////////////////////////////////////////////////////////////////////////////////// -- (void)_compileSectionIndex { - _sectionIndexTitles = nil; - - // Prime the section index and the map - NSMutableArray* titles = nil; - NSMutableDictionary* sectionPrefixToSectionIndex = nil; - if (NICollectionViewModelSectionIndexNone != _sectionIndexType) { - titles = [NSMutableArray array]; - sectionPrefixToSectionIndex = [NSMutableDictionary dictionary]; - - // The search symbol is always first in the index. - if (_sectionIndexShowsSearch) { - [titles addObject:UITableViewIndexSearch]; - } - } - - // A dynamic index shows the first letter of every section in the index in whatever order the - // sections are ordered (this may not be alphabetical). - if (NICollectionViewModelSectionIndexDynamic == _sectionIndexType) { - for (NICollectionViewModelSection* section in _sections) { - NSString* headerTitle = section.headerTitle; - if ([headerTitle length] > 0) { - NSString* prefix = [headerTitle substringToIndex:1]; - [titles addObject:prefix]; - } - } - - } else if (NICollectionViewModelSectionIndexAlphabetical == _sectionIndexType) { - // Use the localized indexed collation to create the index. In English, this will always be - // the entire alphabet. - NSArray* sectionIndexTitles = [[UILocalizedIndexedCollation currentCollation] sectionIndexTitles]; - - // The localized indexed collection sometimes includes a # for summaries, but we might - // not want to show a summary in the index, so prune it out. It's not guaranteed that - // a # will actually be included in the section index titles, so we always attempt to - // remove it for consistency's sake and then add it back down below if it is requested. - for (NSString* letter in sectionIndexTitles) { - if (![letter isEqualToString:@"#"]) { - [titles addObject:letter]; - } - } - } - - // Add the section summary symbol if it was requested. - if (_sectionIndexShowsSummary) { - [titles addObject:@"#"]; - } - - // Build the prefix => section index map. - if (NICollectionViewModelSectionIndexNone != _sectionIndexType) { - - // Map all of the sections to indices. - NSInteger sectionIndex = 0; - for (NICollectionViewModelSection* section in _sections) { - NSString* headerTitle = section.headerTitle; - if ([headerTitle length] > 0) { - NSString* prefix = [headerTitle substringToIndex:1]; - if (nil == [sectionPrefixToSectionIndex objectForKey:prefix]) { - [sectionPrefixToSectionIndex setObject:[NSNumber numberWithInt:sectionIndex] forKey:prefix]; - } - } - ++sectionIndex; - } - - // Map the unmapped section titles to the next closest earlier section. - NSInteger lastIndex = 0; - for (NSString* title in titles) { - NSString* prefix = [title substringToIndex:1]; - if (nil != [sectionPrefixToSectionIndex objectForKey:prefix]) { - lastIndex = [[sectionPrefixToSectionIndex objectForKey:prefix] intValue]; - - } else { - [sectionPrefixToSectionIndex setObject:[NSNumber numberWithInt:lastIndex] forKey:prefix]; - } - } - } - - self.sectionIndexTitles = titles; - self.sectionPrefixToSectionIndex = sectionPrefixToSectionIndex; -} - - /////////////////////////////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////////////////////////// #pragma mark - @@ -315,20 +225,6 @@ - (id)objectAtIndexPath:(NSIndexPath *)indexPath { } -/////////////////////////////////////////////////////////////////////////////////////////////////// -- (void)setSectionIndexType:(NICollectionViewModelSectionIndex)sectionIndexType showsSearch:(BOOL)showsSearch showsSummary:(BOOL)showsSummary { - if (_sectionIndexType != sectionIndexType - || _sectionIndexShowsSearch != showsSearch - || _sectionIndexShowsSummary != showsSummary) { - _sectionIndexType = sectionIndexType; - _sectionIndexShowsSearch = showsSearch; - _sectionIndexShowsSummary = showsSummary; - - [self _compileSectionIndex]; - } -} - - @end diff --git a/src/collections/src/NIMutableCollectionViewModel+Private.h b/src/collections/src/NIMutableCollectionViewModel+Private.h deleted file mode 100644 index 1d91fe979..000000000 --- a/src/collections/src/NIMutableCollectionViewModel+Private.h +++ /dev/null @@ -1,31 +0,0 @@ -// -// Copyright 2011-2012 Jeff Verkoeyen -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. -// - -#import "NIMutableCollectionViewModel.h" - -@interface NIMutableCollectionViewModel (Private) - -@property (nonatomic, NI_STRONG) NSMutableArray* sections; // Array of NICollectionViewModelSection -@property (nonatomic, NI_STRONG) NSMutableArray* sectionIndexTitles; -@property (nonatomic, NI_STRONG) NSMutableDictionary* sectionPrefixToSectionIndex; - -@end - -@interface NICollectionViewModelSection (Mutable) - -- (NSMutableArray *)mutableRows; - -@end diff --git a/src/collections/src/NIMutableCollectionViewModel.h b/src/collections/src/NIMutableCollectionViewModel.h deleted file mode 100644 index 4e53832e6..000000000 --- a/src/collections/src/NIMutableCollectionViewModel.h +++ /dev/null @@ -1,235 +0,0 @@ -// -// Copyright 2011-2012 Jeff Verkoeyen -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. -// - -#import "NICollectionViewModel.h" - -@class NIMutableCollectionViewModel; - -/** - * A protocol for NIMutableCollectionViewModel to handle editing states for objects. - * - * @ingroup TableViewModels - */ -@protocol NIMutableCollectionViewModelDelegate - -@optional - -/** - * Asks the receiver whether the object at the given index path should be editable. - * - * If this method is not implemented, the default response is assumed to be NO. - */ -- (BOOL)collectionViewModel:(NIMutableCollectionViewModel *)collectionViewModel - canEditObject:(id)object - atIndexPath:(NSIndexPath *)indexPath - inTableView:(UICollectionView *)collectionView; - -/** - * Asks the receiver whether the object at the given index path should be moveable. - * - * If this method is not implemented, the default response is assumed to be NO. - */ -- (BOOL)collectionViewModel:(NIMutableCollectionViewModel *)collectionViewModel - canMoveObject:(id)object - atIndexPath:(NSIndexPath *)indexPath - inTableView:(UICollectionView *)collectionView; - -/** - * Asks the receiver whether the given object should be moved. - * - * If this method is not implemented, the default response is assumed to be YES. - * - * Returning NO will stop the model from handling the move logic. - */ -- (BOOL)collectionViewModel:(NIMutableCollectionViewModel *)collectionViewModel - shouldMoveObject:(id)object - atIndexPath:(NSIndexPath *)indexPath - toIndexPath:(NSIndexPath *)toIndexPath - inTableView:(UICollectionView *)collectionView; - -/** - * Asks the receiver what animation should be used when deleting the object at the given index path. - * - * If this method is not implemented, the default response is assumed to be - * UITableViewRowAnimationAutomatic. - */ -- (UITableViewRowAnimation)collectionViewModel:(NIMutableCollectionViewModel *)collectionViewModel - deleteRowAnimationForObject:(id)object - atIndexPath:(NSIndexPath *)indexPath - inTableView:(UICollectionView *)collectionView; - -/** - * Asks the receiver whether the given object should be deleted. - * - * If this method is not implemented, the default response is assumed to be YES. - * - * Returning NO will stop the model from handling the deletion logic. This is a good opportunity for - * you to show a UIAlertView or similar feedback prompt to the user before initiating the deletion - * yourself. - * - * If you implement the deletion of the object yourself, your code may resemble the following: -@code -NSArray *indexPaths = [self removeObjectAtIndexPath:indexPath]; -[collectionView deleteRowsAtIndexPaths:indexPaths withRowAnimation:UITableViewRowAnimationAutomatic]; -@endcode - */ -- (BOOL)collectionViewModel:(NIMutableCollectionViewModel *)collectionViewModel - shouldDeleteObject:(id)object - atIndexPath:(NSIndexPath *)indexPath - inTableView:(UICollectionView *)collectionView; - -@end - -/** - * The NIMutableCollectionViewModel class is a mutable table view model. - * - * When modifications are made to the model there are two ways to reflect the changes in the table - * view. - * - * - Call reloadData on the table view. This is the most destructive way to update the table view. - * - Call insert/delete/reload methods on the table view with the retuned index path arrays. - * - * The latter option is the recommended approach to adding new cells to a table view. Each method in - * the mutable table view model returns a data structure that can be used to inform the table view - * of the exact modifications that have been made to the model. - * - * Example of adding a new section: -@code -// Appends a new section to the end of the model. -NSIndexSet* indexSet = [self.model addSectionWithTitle:@"New section"]; - -// Appends a cell to the last section in the model (in this case, the new section we just created). -[self.model addObject:[NITitleCellObject objectWithTitle:@"A cell"]]; - -// Inform the table view that we've modified the model. -[self.collectionView insertSections:indexSet withRowAnimation:UITableViewRowAnimationAutomatic]; -@endcode - * - * @ingroup TableViewModels - */ -@interface NIMutableCollectionViewModel : NICollectionViewModel - -- (NSArray *)addObject:(id)object; -- (NSArray *)addObject:(id)object toSection:(NSUInteger)section; -- (NSArray *)addObjectsFromArray:(NSArray *)array; -- (NSArray *)insertObject:(id)object atRow:(NSUInteger)row inSection:(NSUInteger)section; -- (NSArray *)removeObjectAtIndexPath:(NSIndexPath *)indexPath; - -- (NSIndexSet *)addSectionWithTitle:(NSString *)title; -- (NSIndexSet *)insertSectionWithTitle:(NSString *)title atIndex:(NSUInteger)index; -- (NSIndexSet *)removeSectionAtIndex:(NSUInteger)index; - -- (void)updateSectionIndex; - -@property (nonatomic, NI_WEAK) id delegate; - -@end - -/** @name Modifying Objects */ - -/** - * Appends an object to the last section. - * - * If no sections exist, a section will be created without a title and the object will be added to - * this new section. - * - * @param object The object to append to the last section. - * @returns An array with a single NSIndexPath representing the index path of the new object - * in the model. - * @fn NIMutableCollectionViewModel::addObject: - */ - -/** - * Appends an object to the end of the given section. - * - * @param object The object to append to the section. - * @param section The index of the section to which this object should be appended. - * @returns An array with a single NSIndexPath representing the index path of the new object - * in the model. - * @fn NIMutableCollectionViewModel::addObject:toSection: - */ - -/** - * Appends an array of objects to the last section. - * - * If no section exists, a section will be created without a title and the objects will be added to - * this new section. - * - * @param array The array of objects to append to the last section. - * @returns An array of NSIndexPath objects representing the index paths of the objects in the - * model. - * @fn NIMutableCollectionViewModel::addObjectsFromArray: - */ - -/** - * Inserts an object into the given section at the given row. - * - * @param object The object to append to the section. - * @param row The row within the section at which to insert the object. - * @param section The index of the section in which the object should be inserted. - * @returns An array with a single NSIndexPath representing the index path of the new object - * in the model. - * @fn NIMutableCollectionViewModel::insertObject:atRow:inSection: - */ - -/** - * Removes an object at the given index path. - * - * If the index path does not represent a valid object then a debug assertion will fire and the - * method will return nil without removing any object. - * - * @param indexPath The index path at which to remove a single object. - * @returns An array with a single NSIndexPath representing the index path of the object that - * was removed from the model, or nil if no object exists at the given index path. - * @fn NIMutableCollectionViewModel::removeObjectAtIndexPath: - */ - -/** @name Modifying Sections */ - -/** - * Appends a section with a given title to the model. - * - * @param title The title of the new section. - * @returns An index set with a single index representing the index of the new section. - * @fn NIMutableCollectionViewModel::addSectionWithTitle: - */ - -/** - * Inserts a section with a given title to the model at the given index. - * - * @param title The title of the new section. - * @param index The index in the model at which to add the new section. - * @returns An index set with a single index representing the index of the new section. - * @fn NIMutableCollectionViewModel::insertSectionWithTitle:atIndex: - */ - -/** - * Removes a section at the given index. - * - * @param index The index in the model of the section to remove. - * @returns An index set with a single index representing the index of the removed section. - * @fn NIMutableCollectionViewModel::removeSectionAtIndex: - */ - -/** @name Updating the Section Index */ - -/** - * Updates the section index with the current section index settings. - * - * This method should be called after modifying the model if a section index is being used. - * - * @fn NIMutableCollectionViewModel::updateSectionIndex - */ diff --git a/src/collections/src/NIMutableCollectionViewModel.m b/src/collections/src/NIMutableCollectionViewModel.m deleted file mode 100644 index 77ded226e..000000000 --- a/src/collections/src/NIMutableCollectionViewModel.m +++ /dev/null @@ -1,169 +0,0 @@ -// -// Copyright 2011-2012 Jeff Verkoeyen -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. -// - -#import "NIMutableCollectionViewModel.h" - -#import "NICollectionViewModel+Private.h" -#import "NIMutableCollectionViewModel+Private.h" -#import "NimbusCore.h" - - -/////////////////////////////////////////////////////////////////////////////////////////////////// -/////////////////////////////////////////////////////////////////////////////////////////////////// -/////////////////////////////////////////////////////////////////////////////////////////////////// -@implementation NIMutableCollectionViewModel - -@synthesize delegate = _delegate; - - -/////////////////////////////////////////////////////////////////////////////////////////////////// -/////////////////////////////////////////////////////////////////////////////////////////////////// -#pragma mark - Public Methods - - -/////////////////////////////////////////////////////////////////////////////////////////////////// -- (NSArray *)addObject:(id)object { - NICollectionViewModelSection* section = self.sections.count == 0 ? [self _appendSection] : self.sections.lastObject; - [section.mutableRows addObject:object]; - return [NSArray arrayWithObject:[NSIndexPath indexPathForRow:section.mutableRows.count - 1 - inSection:self.sections.count - 1]]; -} - - -/////////////////////////////////////////////////////////////////////////////////////////////////// -- (NSArray *)addObject:(id)object toSection:(NSUInteger)sectionIndex { - NIDASSERT(sectionIndex >= 0 && sectionIndex < self.sections.count); - NICollectionViewModelSection *section = [self.sections objectAtIndex:sectionIndex]; - [section.mutableRows addObject:object]; - return [NSArray arrayWithObject:[NSIndexPath indexPathForRow:section.mutableRows.count - 1 - inSection:sectionIndex]]; -} - - -/////////////////////////////////////////////////////////////////////////////////////////////////// -- (NSArray *)addObjectsFromArray:(NSArray *)array { - NSMutableArray* indices = [NSMutableArray array]; - for (id object in array) { - [indices addObject:[[self addObject:object] objectAtIndex:0]]; - } - return indices; -} - - -/////////////////////////////////////////////////////////////////////////////////////////////////// -- (NSArray *)insertObject:(id)object atRow:(NSUInteger)row inSection:(NSUInteger)sectionIndex { - NIDASSERT(sectionIndex >= 0 && sectionIndex < self.sections.count); - NICollectionViewModelSection *section = [self.sections objectAtIndex:sectionIndex]; - [section.mutableRows insertObject:object atIndex:row]; - return [NSArray arrayWithObject:[NSIndexPath indexPathForRow:row inSection:sectionIndex]]; -} - - -/////////////////////////////////////////////////////////////////////////////////////////////////// -- (NSArray *)removeObjectAtIndexPath:(NSIndexPath *)indexPath { - NIDASSERT(indexPath.section < (NSInteger)self.sections.count); - if (indexPath.section >= (NSInteger)self.sections.count) { - return nil; - } - NICollectionViewModelSection* section = [self.sections objectAtIndex:indexPath.section]; - NIDASSERT(indexPath.row < (NSInteger)section.mutableRows.count); - if (indexPath.row >= (NSInteger)section.mutableRows.count) { - return nil; - } - [section.mutableRows removeObjectAtIndex:indexPath.row]; - return [NSArray arrayWithObject:indexPath]; -} - - -/////////////////////////////////////////////////////////////////////////////////////////////////// -- (NSIndexSet *)addSectionWithTitle:(NSString *)title { - NICollectionViewModelSection* section = [self _appendSection]; - section.headerTitle = title; - return [NSIndexSet indexSetWithIndex:self.sections.count - 1]; -} - - -/////////////////////////////////////////////////////////////////////////////////////////////////// -- (NSIndexSet *)insertSectionWithTitle:(NSString *)title atIndex:(NSUInteger)index { - NICollectionViewModelSection* section = [self _insertSectionAtIndex:index]; - section.headerTitle = title; - return [NSIndexSet indexSetWithIndex:index]; -} - - -/////////////////////////////////////////////////////////////////////////////////////////////////// -- (NSIndexSet *)removeSectionAtIndex:(NSUInteger)index { - NIDASSERT(index >= 0 && index < self.sections.count); - [self.sections removeObjectAtIndex:index]; - return [NSIndexSet indexSetWithIndex:index]; -} - - -/////////////////////////////////////////////////////////////////////////////////////////////////// -- (void)updateSectionIndex { - [self _compileSectionIndex]; -} - - -/////////////////////////////////////////////////////////////////////////////////////////////////// -/////////////////////////////////////////////////////////////////////////////////////////////////// -#pragma mark - Private Methods - - -/////////////////////////////////////////////////////////////////////////////////////////////////// -- (NICollectionViewModelSection *)_appendSection { - if (nil == self.sections) { - self.sections = [NSMutableArray array]; - } - NICollectionViewModelSection* section = nil; - section = [[NICollectionViewModelSection alloc] init]; - section.rows = [NSMutableArray array]; - [self.sections addObject:section]; - return section; -} - - -/////////////////////////////////////////////////////////////////////////////////////////////////// -- (NICollectionViewModelSection *)_insertSectionAtIndex:(NSUInteger)index { - if (nil == self.sections) { - self.sections = [NSMutableArray array]; - } - NICollectionViewModelSection* section = nil; - section = [[NICollectionViewModelSection alloc] init]; - section.rows = [NSMutableArray array]; - NIDASSERT(index >= 0 && index <= self.sections.count); - [self.sections insertObject:section atIndex:index]; - return section; -} - -@end - - -/////////////////////////////////////////////////////////////////////////////////////////////////// -/////////////////////////////////////////////////////////////////////////////////////////////////// -/////////////////////////////////////////////////////////////////////////////////////////////////// -@implementation NICollectionViewModelSection (Mutable) - - -/////////////////////////////////////////////////////////////////////////////////////////////////// -- (NSMutableArray *)mutableRows { - NIDASSERT([self.rows isKindOfClass:[NSMutableArray class]] || nil == self.rows); - - self.rows = nil == self.rows ? [NSMutableArray array] : self.rows; - return (NSMutableArray *)self.rows; -} - -@end diff --git a/src/collections/src/NimbusCollections.h b/src/collections/src/NimbusCollections.h index 6ae31c5b4..5208ec2d7 100644 --- a/src/collections/src/NimbusCollections.h +++ b/src/collections/src/NimbusCollections.h @@ -21,13 +21,32 @@ * @{ * *
+ * + * Collection views are a new feature in iOS 6 that enable powerful collections of views to be + * built. + * + * Collection views introduce a new concept of "layout" alongside the existing data source and + * delegate concepts. Nimbus Collections provides support only for the data source with the + * NICollectionViewModel. NICollectionViewModel behaves similarly to NITableViewModel in that you + * provide it with an array of objects which are mapped to cells using a factory. + */ + +#pragma mark * Collection View Models + +/** + * @defgroup CollectionViewModels Collection View Models + */ + +#pragma mark * Collection View Cell Factory + +/** + * @defgroup CollectionViewCellFactory Collection View Cell Factory */ #import #import -#import "NICollectionViewModel.h" -#import "NIMutableCollectionViewModel.h" #import "NICollectionViewCellFactory.h" +#import "NICollectionViewModel.h" /**@}*/