Skip to content


Subversion checkout URL

You can clone with
Download ZIP
100644 132 lines (85 sloc) 11.926 kB
3cf7936 @AlanQuatermain Initial public revision. No major code changes aside from symbol pref…
1 h1=. AQGridView
7626d30 Updated README.
Jim Dovey authored
3 h3=. Winner of the _Best Developer Tool/Helper_ award at iPadDevCamp 2010 in San Jose
e4ef824 Added award details.
Jim Dovey authored
c37e347 Updated to latest Kobo version, complete with bugfixes around animati…
Jim Dovey authored
5 p=. Version 1.2 -- 10 January 2011
3cf7936 @AlanQuatermain Initial public revision. No major code changes aside from symbol pref…
7 p=. By "Jim Dovey" <br />
f99d888 @AlanQuatermain Updated the Kobo URL to point to the new Universal build of the Kobo …
8 Originally written for the "Kobo iPad Application":
3cf7936 @AlanQuatermain Initial public revision. No major code changes aside from symbol pref…
27ba25e @AlanQuatermain Added section containing other apps which make use of the project.
10 h3. Used In These Applications:
12 * "eBooks by Kobo": -- Bookshelf and multi-column table views, 'I'm Reading' overlay view. <br />
9a68813 Added iTunes link for Netflix Actors.
Jim Dovey authored
13 * "Netflix Actors": (Source code "here": -- Movie and actor chooser views. <br />
27ba25e @AlanQuatermain Added section containing other apps which make use of the project.
14 * "Stocks - The Finance App": -- Portfolio view contents. <br />
8ea9790 @AlanQuatermain Added Rivet for iPad to the users' list.
15 * "Rivet for iPad": -- Media shelves.
f72dbc6 @AlanQuatermain Updated README to include Slide by Slide reference.
16 * "Slide By Slide": -- Slideshow picker.
af3b94d Added AppStart to apps list.
Jim Dovey authored
17 * "AppStart for iPad": -- App reviews and guides.
f25bd64 @AlanQuatermain Added 'Slippy' application to the README.
18 * "Slippy": -- Level chooser.
cb536a1 @AlanQuatermain Added Equineline app courtesy of @drunknbass
19 * "Equineline Sales Catalog": -- Bookshelf view.
90ab0f3 @AlanQuatermain Added link for Completion iOS app.
20 * "Completion": -- Springboard-style home screen.
27ba25e @AlanQuatermain Added section containing other apps which make use of the project.
4dab91a @AlanQuatermain Added 'supporting' message.
22 h3. Supporting AQGridView
24 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":
3cf7936 @AlanQuatermain Initial public revision. No major code changes aside from symbol pref…
26 h2. Introduction
28 *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.
30 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.
32 h3. Similarities with UITableView
34 * A subclass of *UIScrollView*.
35 * Reusable grid cells, similar to *UITableViewCell*.
36 * Data source and delegate very similar to those used with UITableView.
37 * Immediate and batched changes to the content list (insert, remove, reorder, reload).
38 * Similar change animations (top, bottom, left, right, fade).
39 * Simple *AQGridViewController* provided which performs grid view setup for you, similar to *UITableViewController*.
40 * Support for custom header and footer views.
42 h3. Differences from UITableView
44 * No sections-- uses NSUInteger as its index location rather than NSIndexPath.
45 * Data source can specify a desired minimum size for all grid cells.
46 * Cells are not automatically resized to fit in layout grid-- this can be changed via a property.
47 * The delegate gets an opportunity to adjust the layout frame for each cell as it is displayed.
48 * The grid layout is adjusted to fit the contentSize width. You can specify left and/or right padding to reach a size which can be divided into three, five, etc. cells per row.
49 * A customizable 'glow' selection style, which places a glow around a cell's layer (or a specified sublayer) using the *shadowRadius* property of *CALayer*. Note that this is only available in iPhone OS 3.2 or later.
51 h3. Requirements
53 * The iPhone OS 3.2 SDK is needed to build. It can however run on iPhones running OS 3.0 (iPhone/iPad universal app compatible).
55 h3. How to get it
57 Download or clone it "from GitHub":
59 h3. How to use it in your project
61 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.
e659788 @kevinlawler Update README.textile to include installation instructions
kevinlawler authored
63 To include the project in your project named "MY_PROJECT":
65 # Clone the repo
66 # Delete the .git file
67 # If desired delete the Examples folder
68 # Move the cloned AQGridView file folder to the desired location in your project file folder
69 # Add the cloned folder to your project repo with @git add@ if desired
70 # From within Xcode, select "Add Files to 'MY_PROJECT'", select "AQGridView.xcodeproj" (leave the "Add to Targets" box checked)
71 # AQGridView should now appear in the Xcode Project Navigator / folder thing
72 # Click on the "MY_PROJECT" entry, Targets -> MY_PROJECT -> Build Phases -> Target Dependencies -> + "AQGridView"
73 # Click on the "MY_PROJECT" entry, Targets -> MY_PROJECT -> Build Phases -> Link Binary with Libraries -> + "libAQGridView.a"
74 # Click on the "MY_PROJECT" entry, Targets -> MY_PROJECT -> Build Settings -> Search Paths -> User Header Search Paths -> + "AQGridView"
75 # Click on the "MY_PROJECT" entry, Targets -> MY_PROJECT -> Build Settings -> Linking -> Other Linker Flags -> + "-ObjC"
76 # @#import "AQGridViewController.h"@
77 # AQGridViewController *grid = [AQGridViewController alloc];
78 # If this doesn't work try tweaking some of the settings referenced in setup for
3cf7936 @AlanQuatermain Initial public revision. No major code changes aside from symbol pref…
80 h2. Overview
82 AQGridView has a number of supporting internal classes. The ones you'll interact with directly are:
84 * AQGridView
85 * AQGridViewCell
86 * AQGridViewController
88 h3. Basic setup
90 Create a subclass of *AQGridViewController*. In <code>-viewDidLoad</code> you can change any properties you desire, add background, header, or footer views, and so on.
92 Unless you want a grid cell size of 96x128 (the default) you should implement the *AQGridViewDataSource* method <code>-portraitGridCellSizeForGridView:</code>, 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.
94 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 <code>resizesCellWidthToFit</code> 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 <code>-gridView:adjustCellFrame:withinGridCellFrame:</code> to tweak the auto-centered cell frame calculated by the grid view's layout code. For instance, the "Kobo iPad App": does this for its shelf view, and uses <code>resizesCellWidthToFit</code> for its two-column list view.
96 h2. Future Directions
98 * *Section support*. This will need a large amount of refactoring to support moves between sections, and will need a new way of keeping track of visible cell indices (it currently uses an NSRange).
99 * *High-performance rendering*. If cells don't need to update their content after being drawn, each row could be composited into a single view for reduced load on the CoreAnimation renderer. This would need support in the grid view for displaying these composited rows, and would also need special support in KBGridViewCell to mark individual cells as needing dynamic updates, so they could be skipped when compositing and displayed normally on top of the composited row. KVO would be used to keep track of this. NB: This would also need special handling for the 'glow' selection style (or possibly the tracking cell would always be placed on screen, regardless of its dynamism requirements).
af3b94d Added AppStart to apps list.
Jim Dovey authored
100 * -*Content adjustments*. There are possibly still a couple of deeply-buried bugs in the cell movement code inside *KBGridViewUpdateInfo*. These are a pain to track down, and the code in that class could possibly use some cleanup. This is also something which would need to change a lot for section support (it makes heavy use of *NSIndexSet* right now).-
3cf7936 @AlanQuatermain Initial public revision. No major code changes aside from symbol pref…
85537e8 @AlanQuatermain Updated the readme with details of known bugs and the two example pro…
102 h2. Known Bugs
104 * Don't try to pile multiple animations on top of one another. i.e. don't call -beginUpdates on a grid view whose -isAnimatingUpdates method returns YES. Bad things will happen, cells will end up in the wrong places, stacked on top of one another.
3cf7936 @AlanQuatermain Initial public revision. No major code changes aside from symbol pref…
106 h2. Examples
85537e8 @AlanQuatermain Updated the readme with details of known bugs and the two example pro…
108 All examples are located in the *Examples* folder.
110 h3. ImageDemo
112 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.
114 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.
116 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.
118 h3. SpringBoard
120 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.
d40dd2f Now uses background colour instead of alpha channel to implement fade…
Jim Dovey authored
122 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.
124 h3. ExpanderDemo
126 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).
128 The expansion is triggered by calling the <code>-expandCellsFromRect:ofView:</code> 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 <code>-viewDidAppear:</code>. This last function implements the last part of the expansion algorithm.
130 In <code>-expandCellsFromRect:ofView:</code>, 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 <code>-viewDidAppear:</code> 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.
132 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.
Something went wrong with that request. Please try again.