NIPhotoAlbumScrollView Class Reference

Overview

A paged scroll view that shows a collection of photos.

This view provides a light-weight implementation of a photo viewer, complete with pinch-to-zoom and swiping to change photos. It is designed to perform well with large sets of photos and large images that are loaded from either the network or disk.

It is intended for this view to be used in conjunction with a view controller that implements the data source protocol and presents any required chrome.

See Also

NIToolbarPhotoViewController

Inheritance diagram for NIPhotoAlbumScrollView:

Tasks
Data Source
id < NIPhotoAlbumScrollViewDataSource >	dataSource property
id < NIPhotoAlbumScrollViewDelegate >	delegate property
Configuring Functionality
BOOL	zoomingIsEnabled property
BOOL	zoomingAboveOriginalSizeIsEnabled property
UIColor *	photoViewBackgroundColor property
Configuring Presentation
UIImage *	loadingImage property
Notifying the View of Loaded Photos
(void)	- didLoadPhoto:atIndex:photoSize:
State
NSInteger	centerPageIndex property
NSInteger	numberOfPages property
(UIView < NIPagingScrollViewPage > *)	- centerPageView
Configuring Presentation
CGFloat	pageMargin property
NIPagingScrollViewType	type property
Data Source
(void)	- reloadData
(UIView < NIPagingScrollViewPage > *)	- dequeueReusablePageWithIdentifier:
Changing the Visible Page
(BOOL)	- hasNext
(BOOL)	- hasPrevious
(void)	- moveToNextAnimated:
(void)	- moveToPreviousAnimated:
(BOOL)	- moveToPageAtIndex:animated:updateVisiblePagesWhileScrolling:
(BOOL)	- moveToPageAtIndex:animated:
Rotating the Scroll View
(void)	- willRotateToInterfaceOrientation:duration:
(void)	- willAnimateRotationToInterfaceOrientation:duration:
[NIPhotoScrollViewDelegate] Zooming
(void)	- photoScrollViewDidDoubleTapToZoom:didZoomIn:

Method Documentation

dataSource

The data source for this photo album view.

@property (nonatomic, weak) id<NIPhotoAlbumScrollViewDataSource> dataSource;

Discussion

This is the only means by which this photo album view acquires any information about the album to be displayed.

delegate

The delegate for this photo album view.

@property (nonatomic, weak) id<NIPhotoAlbumScrollViewDelegate> delegate;

Discussion

Any user interactions or state changes are sent to the delegate through this property.

zoomingIsEnabled

Whether zooming is enabled or not.

@property (nonatomic) BOOL zoomingIsEnabled;

Discussion

Regardless of whether this is enabled, only original-sized images will be zoomable. This is because we often don't know how large the final image is so we can't calculate min and max zoom amounts correctly.

By default this is YES.

zoomingAboveOriginalSizeIsEnabled

Whether small photos can be zoomed at least until they fit the screen.

@property (nonatomic) BOOL zoomingAboveOriginalSizeIsEnabled;

Discussion

See Also

NIPhotoScrollView::zoomingAboveOriginalSizeIsEnabled

By default this is YES.

photoViewBackgroundColor

The background color of each photo's view.

@property (nonatomic, strong) UIColor* photoViewBackgroundColor;

Discussion

By default this is [UIColor blackColor].

loadingImage

An image that is displayed while the photo is loading.

@property (nonatomic, strong) UIImage* loadingImage;

Discussion

This photo will be presented if no image is returned in the data source's implementation of photoAlbumScrollView:photoAtIndex:photoSize:isLoading:.

Zooming is disabled when showing a loading image, regardless of the state of zoomingIsEnabled.

By default this is nil.

didLoadPhoto:atIndex:photoSize:

Notify the scroll view that a photo has been loaded at a given index.

- (void)didLoadPhoto:(UIImage *)image atIndex:(NSInteger)photoIndex photoSize:(NIPhotoScrollViewPhotoSize)photoSize;

Discussion

You should notify the completed loading of thumbnails as well. Calling this method is fairly lightweight and will only update the images of the visible pages. Err on the side of calling this method too much rather than too little.

The photo at the given index will only be replaced with the given image if photoSize is of a higher quality than the currently-displayed photo's size.

centerPageIndex

The current center page index.

@property (nonatomic) NSInteger centerPageIndex;

Discussion

This is a zero-based value. If you intend to use this in a label such as "page ## of n" be sure to add one to this value.

Setting this value directly will center the new page without any animation.

numberOfPages

The total number of pages in this paging view, as gathered from the data source.

@property (nonatomic, readonly) NSInteger numberOfPages;

Discussion

This value is cached after reloadData has been called.

Until reloadData is called the first time, numberOfPages will be NIPagingScrollViewUnknownNumberOfPages.

pageMargin

The number of pixels on either side of each page.

@property (nonatomic) CGFloat pageMargin;

Discussion

The space between each page will be 2x this value.

By default this is NIPagingScrollViewDefaultPageMargin.

type

The type of paging scroll view to display.

@property (nonatomic) NIPagingScrollViewType type;

Discussion

This property allows you to configure whether you want a horizontal or vertical paging scroll view. You should set this property before you present the scroll view and not modify it after.

By default this is NIPagingScrollViewHorizontal.

reloadData

Force the view to reload its data by asking the data source for information.

- (void)reloadData;

Discussion

This must be called at least once after dataSource has been set in order for the view to gather any presentable information.

This method is cheap because we only fetch new information about the currently displayed pages. If the number of pages shrinks then the current center page index will be decreased accordingly.

dequeueReusablePageWithIdentifier:

Dequeues a reusable page from the set of recycled pages.

- (UIView<NIPagingScrollViewPage>*)dequeueReusablePageWithIdentifier:(NSString *)identifier;

Discussion

If no pages have been recycled for the given identifier then this will return nil. In this case it is your responsibility to create a new page.

centerPageView

The current center page view.

- (UIView<NIPagingScrollViewPage>*)centerPageView;

Discussion

If no pages exist then this will return nil.

hasNext

Returns YES if there is a next page.

- (BOOL)hasNext;

hasPrevious

Returns YES if there is a previous page.

- (BOOL)hasPrevious;

moveToNextAnimated:

Move to the next page if there is one.

- (void)moveToNextAnimated:(BOOL)animated;

moveToPreviousAnimated:

Move to the previous page if there is one.

- (void)moveToPreviousAnimated:(BOOL)animated;

moveToPageAtIndex:animated:updateVisiblePagesWhileScrolling:

Move to the given page index with optional animation and option to enable page updates while scrolling.

- (BOOL)moveToPageAtIndex:(NSInteger)pageIndex animated:(BOOL)animated updateVisiblePagesWhileScrolling:(BOOL)updateVisiblePagesWhileScrolling;

Discussion

NOTE: Passing YES for moveToPageAtIndex:animated:updateVisiblePagesWhileScrolling will cause every page from the present page to the destination page to be loaded. This has the potential to cause choppy animations.

Parameters

updateVisiblePagesWhileScrolling

If YES, will query the data source for any pages that become visible while the animation occurs.

Returns

NO if a page change animation is already in effect and we couldn't change the page again.

moveToPageAtIndex:animated:

Move to the given page index with optional animation.

- (BOOL)moveToPageAtIndex:(NSInteger)pageIndex animated:(BOOL)animated;

Discussion

Returns

NO if a page change animation is already in effect and we couldn't change the page again.

willRotateToInterfaceOrientation:duration:

Stores the current state of the scroll view in preparation for rotation.

- (void)willRotateToInterfaceOrientation:(UIInterfaceOrientation)toInterfaceOrientation duration:(NSTimeInterval)duration;

Discussion

This must be called in conjunction with willAnimateRotationToInterfaceOrientation:duration: in the methods by the same name from the view controller containing this view.

willAnimateRotationToInterfaceOrientation:duration:

Updates the frame of the scroll view while maintaining the current visible page's state.

- (void)willAnimateRotationToInterfaceOrientation:(UIInterfaceOrientation)toInterfaceOrientation duration:(NSTimeInterval)duration;

photoScrollViewDidDoubleTapToZoom:didZoomIn:

The user has double-tapped the photo to zoom either in or out.

- (void)photoScrollViewDidDoubleTapToZoom:(NIPhotoScrollView *)photoScrollView didZoomIn:(BOOL)didZoomIn;

Discussion

Parameters

photoScrollView	The photo scroll view that was tapped.
didZoomIn	YES if the photo was zoomed in. NO if the photo was zoomed out.