h1=. AQGridView
h3=. Winner of the Best Developer Tool/Helper award at iPadDevCamp 2010 in San Jose
p=. Version 1.2 -- 10 January 2011
p=. By "Jim Dovey":mailto:jimdovey@mac.com
Originally written for the "Kobo iPad Application":http://itunes.apple.com/ca/app/ebooks-by-kobo/id301259483?mt=8
h3. Used In These Applications:
h3. Supporting AQGridView
People have asked how they can show their support. Other than implementing nice features & pushing them back upstream, you can always take a look at my "Amazon Wish List":http://amzn.com/w/34WILFNNUUDKQ.
h2. Introduction
AQGridView is an attempt to create something similar to NSCollectionView on the iPhone. If CALayoutManager were available on the iPhone, specifically the CAConstraintLayoutManager, then this would be relatively easy to put together. However, since none of those exist, there's a lot of work to be done.
AQGridView is based around the programming model of UITableView and its associated classes. To create this class I looked long and hard at how UITableView does what it does, and attempted to replicate it as closely as possible. This means that if you are familiar with table view programming on the iPhone or iPad, you will find AQGridView simple to pick up.
h3. Similarities with UITableView
h3. Differences from UITableView
h3. Requirements
h3. How to get it
Download or clone it "from GitHub":http://github.com/AlanQuatermain/AQGridView
h3. How to use it in your project
This project compiles to a static library which you can include, or you can just reference the source files directly. Note that there are some resources to copy into your project for the tableview-style selection backgrounds.
To include the project in your project named "MY_PROJECT":
h2. Overview
AQGridView has a number of supporting internal classes. The ones you'll interact with directly are:
h3. Basic setup
Create a subclass of AQGridViewController. In -viewDidLoad you can change any properties you desire, add background, header, or footer views, and so on.
Unless you want a grid cell size of 96x128 (the default) you should implement the AQGridViewDataSource method -portraitGridCellSizeForGridView:, from which you can return a suitable minimum size for your cells. This is used as the basis of the layout grid; the grid view will expand the width of this size until it reaches a factor of the current content size, then uses that for its layout.
Cells will be placed in the center of each layout grid rectangle. By default, the cells are not resized to fill this grid rectangle, but you can change this using the resizesCellWidthToFit property of AQGridView. If your cell should not be positioned dead center (for example, if your cell contains an image with a shadow on one side, and the image should be centered, not the whole thing) then you can implement the AQGridViewDelegate method -gridView:adjustCellFrame:withinGridCellFrame: to tweak the auto-centered cell frame calculated by the grid view's layout code. For instance, the "Kobo iPad App":http://itunes.apple.com/ca/app/ebooks-by-kobo-hd/id364742849?mt=8 does this for its shelf view, and uses resizesCellWidthToFit for its two-column list view.
h2. Future Directions
h2. Known Bugs
h2. Examples
All examples are located in the Examples folder.
h3. ImageDemo
This is the demo which was presented at iPad Dev Camp in San Jose. It is primarily a showcase for automatic content reordering and animation, but also includes examples of the two main cell types: centered empty-space bordered cells, and filled line-separated cells.
Rotating the display will change the number of columns in the grid, with the associated animation. In addition, there are two buttons which cause items to be reordered. The top left button will shuffle the image order randomly, and the top right button will return everything to its original position.
The second button at the top right of the screen will pop up a menu which changes from the default empty-space grid style to a UITableView-like 'filled cell' grid style. In this version, the cells are automatically resized to fit their grid slots, and the selection style (and the cells' behavior when selected) will match UITableView more closely.
h3. SpringBoard
This is a new demo which shows how to use gesture recognizers to implement a manual reordering interface similar to that used by the iPad springboard. If you tap and hold on a cell for half a second, it will pop out of the grid, whereupon you can drag it around and drop it in a new position by letting go. The rest of the cells move out of the way as you drag your chosen cell around.
Additionally, it shows how to use the left and right insets to force the grid view to create the desired number of columns. In portrait mode, we want four columns, and the default width of 768 divides by four nicely, so we leave the insets at zero. In landscape mode we want five columns, and so we inset left & right by two pixels each to reduce the grid's layout width to 1020 pixels, which is cleanly divisible by 5. As a result, rotating to landscape mode results in five columns being visible.
h3. ExpanderDemo
This demo shows how to make a new grid view instance expand into existence from a single point. The ExpanderDemoViewController implements a basic grid view with a single cell. When this cell is tapped, it creates a new instance of ExpandingGridViewController, which then expands its image cells into view (only using those cells which would be visible, not ALL cells).
The expansion is triggered by calling the -expandCellsFromRect:ofView: method of ExpandingGridViewController. Before calling this, you must set the expanding grid view's frame (so it can figure out what cells should be visible at what indices) and add it to a superview (so the passed rectangle can be mapped across). Afterward you should ensure that you call the new controller's -viewDidAppear:. This last function implements the last part of the expansion algorithm.
In -expandCellsFromRect:ofView:, the controller converts the source rectangle into its own view's coordinate space and caches it. It also goes through the grid view's cell list and stores their existing frames ready to animate them later. Lastly, it sets its view's background colour to clear. Then in -viewDidAppear: it first moves all the visible cells to the saved starting rectangle, then in an animation block it restores its background colour and moves the cells to their original positions.
Also: Yes, this example contains a memory leak, and doesn't go in reverse. The only exemplary code is in the two methods discussed above.