Loading repository data…
nicklockwood / repository
A simple, highly customisable, data-driven 3D carousel for iOS and Mac OS
A transparent discovery signal based on current public GitHub metadata.
This score does not audit code, security, maintainers, documentation quality, or suitability. Verify the repository and its current documentation before adoption.
iCarousel is a class designed to simplify the implementation of various types of carousel (paged, scrolling views) on iPhone, iPad and Mac OS. iCarousel implements a number of common effects such as cylindrical, flat and "CoverFlow" style carousels, as well as providing hooks to implement your own bespoke effects. Unlike many other "CoverFlow" libraries, iCarousel can work with any kind of view, not just images, so it is ideal for presenting paged data in a fluid and impressive way in your app. It also makes it extremely easy to swap between different carousel effects with minimal code changes.
NOTE: 'Supported' means that the library has been tested with this version. 'Compatible' means that the library should work on this OS version (i.e. it doesn't rely on any unavailable SDK features) but is no longer being tested for compatibility and may require tweaking or bug fixes to run correctly.
As of version 1.8, iCarousel requires ARC. If you wish to use iCarousel in a non-ARC project, just add the -fobjc-arc compiler flag to the iCarousel.m class. To do this, go to the Build Phases tab in your target settings, open the Compile Sources group, double-click iCarousel.m in the list and type -fobjc-arc into the popover.
If you wish to convert your whole project to ARC, comment out the #error line in iCarousel.m, then run the Edit > Refactor > Convert to Objective-C ARC... tool in Xcode and make sure all files that you wish to use ARC for (including iCarousel.m) are checked.
iCarousel is derived from UIView and - as with all UIKit components - it should only be accessed from the main thread. You may wish to use threads for loading or updating carousel contents or items, but always ensure that once your content has loaded, you switch back to the main thread before updating the carousel.
To use the iCarousel class in an app, just drag the iCarousel class files (demo files and assets are not needed) into your project and add the QuartzCore framework. You can also install it using Cocoapods in the normal way.
iCarousel is now compatible with the Chameleon iOS-to-Mac conversion library (https://github.com/BigZaphod/Chameleon). To use iCarousel with Chameleon, add USING_CHAMELEON to your project's preprocessor macros. Check out the Chameleon Demo example project for how to port your iOS iCarousel app to Mac OS using Chameleon - the example demonstrates how to run the No Nib iPhone example on Mac OS using Chameleon. Note that tap-to-center doesn't currently work, and scrolling must be done using a two-fingered scroll gesture, not click-and-drag (both of these are due to features/limitations of the Chameleon UIGestureRecognizer implementation).
iCarousel supports the following built-in display types:
You can also implement your own bespoke carousel styles using iCarouselTypeCustom and the carousel:itemTransformForOffset:baseTransform: delegate method.
NOTE: The difference between iCarouselTypeCoverFlow and iCarouselTypeCoverFlow2 types is quite subtle, however the logic for iCarouselTypeCoverFlow2 is substantially more complex. If you flick the carousel they are basically identical, but if you drag the carousel slowly with your finger the difference should be apparent. iCarouselTypeCoverFlow2 is designed to simulate the standard Apple CoverFlow effect as closely as possible and may change subtly in future in the interests of that goal.
The iCarousel has the following properties (note: for Mac OS, substitute NSView for UIView when using properties):
@property (nonatomic, weak) IBOutlet id<iCarouselDataSource> dataSource;
An object that supports the iCarouselDataSource protocol and can provide views to populate the carousel.
@property (nonatomic, weak) IBOutlet id<iCarouselDelegate> delegate;
An object that supports the iCarouselDelegate protocol and can respond to carousel events and layout requests.
@property (nonatomic, assign) iCarouselType type;
Used to switch the carousel display type (see above for details).
@property (nonatomic, assign) CGFloat perspective;
Used to tweak the perspective foreshortening effect for the various 3D carousel views. Should be a negative value, less than 0 and greater than -0.01. Values outside of this range will yield very strange results. The default is -1/500, or -0.005;
@property (nonatomic, assign) CGSize contentOffset;
This property is used to adjust the offset of the carousel item views relative to the center of the carousel. It defaults to CGSizeZero, meaning that the carousel items are centered. Changing this value moves the carousel items without changing their perspective, i.e. the vanishing point moves with the carousel items, so if you move the carousel items down, it does not appear as if you are looking down on the carousel.
@property (nonatomic, assign) CGSize viewpointOffset;
This property is used to adjust the user viewpoint relative to the carousel items. It has the opposite effect to adjusting the contentOffset, i.e. if you move the viewpoint up then the carousel appears to move down. Unlike the contentOffset, moving the viewpoint also changes the perspective vanishing point relative to the carousel items, so if you move the viewpoint up, it will appear as if you are looking down on the carousel.
@property (nonatomic, assign) CGFloat decelerationRate;
The rate at which the carousel decelerates when flicked. Higher values mean slower deceleration. The default value is 0.95. Values should be in the range 0.0 (carousel stops immediately when released) to 1.0 (carousel continues indefinitely without slowing down, unless it reaches the end).
@property (nonatomic, assign) BOOL bounces;
Sets whether the carousel should bounce past the end and return, or stop dead. Note that this has no effect on carousel types that are designed to wrap, or where the carouselShouldWrap delegate method returns YES.
@property (nonatomic, assign) CGFloat bounceDistance;
The maximum distance that a non-wrapped carousel will bounce when it overshoots the end. This is measured in multiples of the itemWidth, so a value of 1.0 would means the carousel will bounce by one whole item width, a value of 0.5 would be half an item's width, and so on. The default value is 1.0;
@property (nonatomic, assign, getter = isScrollEnabled) BOOL scrollEnabled;
Enables and disables user scrolling of the carousel. The carousel can still be scrolled programmatically if this property is set to NO.
@property (nonatomic, readonly, getter = isWrapEnabled) BOOL wrapEnabled;
Returns YES if wrapping is enabled and NO if it isn't. This property is read only. If you wish to override the default value, implement the carousel:valueForOption:withDefault: delegate method and return a value for iCarouselOptionWrap.
@property (nonatomic, assign, getter = isPagingEnabled) BOOL pagingEnabled;
Enables and disables paging. When paging is enabled, the carousel will stop at each item view as the user scrolls, much like the pagingEnabled property of a UIScrollView.
@property (nonatomic, readonly) NSInteger numberOfItems;
The number of items in the carousel (read only). To set this, implement the numberOfItemsInCarousel: dataSource method. Note that not all of these item views will be loaded or visible at a given point in time - the carousel loads item views on demand as it scrolls.
@property (nonatomic, readonly) NSInteger numberOfPlaceholders;
The number of placeholder views to display in the carousel (read only). To set this, implement the numberOfPlaceholdersInCarousel: dataSource method.
@property (nonatomic, readonly) NSInteger numberOfVisibleItems;
The maximum number of carousel item views to be displayed concurrently on screen (read only). This property is important for performance optimisation, and is calculated automatically based on the carousel type and view frame. If you wish to override the default value, implement the carousel:valueForOption:withDefault: delegate method and return a value for iCarouselOptionVisibleItems.
@property (nonatomic, strong, readonly) NSArray *indexesForVisibleItems;
An array containing the indexes of all item views currently loaded and visible in the carousel, including placeholder views. The array contains NSNumber objects whose integer values match the indexes of the views. The indexes for item views start at zero and match the indexes passed to the dataSource to load the view, however the indexes for any visible placeholder views will either be negative (less than zero) or greater than or equal to numberOfItems. Indexes for placeholder views in this array do not equate to the placeholder view index used with the dataSource.
@property (nonatomic, strong, readonly) NSArray *visibleItemViews;
An array of all the item views currently displayed in the carousel (read only). This includes any visible placeholder views. The indexes of views in this array do not match the item indexes, however the order of these views matches the order of the visibleItemIndexes array property, i.e. you can get the item index of a given view in this array by retrieving the equivalent object from the visibleItemIndexes array (or, you can just use the indexOfItemView: method, which is much easier).
@property (nonatomic, strong, readonly) UIView *contentView;
The view containing the carousel item views. You can add subviews to this view if you want to intersperse them with the carousel items. If you want a view to appear in front or behind all of the carousel items, you should add it directly to the iCarousel view itself instead. Note that the order of views inside the contentView is subject to frequent and undocumented change whilst the app is running. Any views added to the contentView should have their userInteractionEnabled property set to NO to prevent conflicts with iCarousel's touch event handling.
@property (nonatomic, assign) CGFloat scrollOffset;
This is the current scroll offset of the carousel in multiples of the itemWidth. This value, rounded to the nearest integer, is the currentItemIndex value. You can use this value to position other screen elements while the carousel is in motion. The value can also be set if you wish to scroll the carousel to a particular offset programmatically. This may be useful if you wish to disable the built-in gesture handling and provide your own implementation.
@property (nonatomic,
Selected from shared topics, language and repository description—not editorial ratings.
tonystone /
TraceLog is a highly configurable, flexible, portable, and simple to use debug logging system for Swift and Objective-C applications running on Linux, macOS, iOS, watchOS, and tvOS.
60/100 health