{"id":19712569,"url":"https://github.com/evgenyneu/auk","last_synced_at":"2025-04-05T18:11:19.357Z","repository":{"id":33712170,"uuid":"37365668","full_name":"evgenyneu/Auk","owner":"evgenyneu","description":"An image slideshow for iOS written in Swift.","archived":false,"fork":false,"pushed_at":"2023-10-12T06:12:39.000Z","size":11079,"stargazers_count":278,"open_issues_count":23,"forks_count":44,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-03-29T17:11:20.013Z","etag":null,"topics":["image","slideshow","swift"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evgenyneu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-06-13T09:28:58.000Z","updated_at":"2024-10-29T16:20:01.000Z","dependencies_parsed_at":"2024-06-18T22:49:52.802Z","dependency_job_id":"9604188d-ec93-4d97-99a9-5210e07b8245","html_url":"https://github.com/evgenyneu/Auk","commit_stats":{"total_commits":500,"total_committers":5,"mean_commits":100.0,"dds":"0.10999999999999999","last_synced_commit":"b4d6ebbfacb6f8853ca1f1fd251dff1eab38c20b"},"previous_names":[],"tags_count":49,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evgenyneu%2FAuk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evgenyneu%2FAuk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evgenyneu%2FAuk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evgenyneu%2FAuk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evgenyneu","download_url":"https://codeload.github.com/evgenyneu/Auk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247378149,"owners_count":20929297,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["image","slideshow","swift"],"created_at":"2024-11-11T22:17:38.981Z","updated_at":"2025-04-05T18:11:19.336Z","avatar_url":"https://github.com/evgenyneu.png","language":"Swift","readme":"# Auk, an image slideshow for iOS / Swift\n\n[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)\n[![CocoaPods Version](https://img.shields.io/cocoapods/v/Auk.svg?style=flat)](http://cocoadocs.org/docsets/Auk)\n[![Swift Package Manager compatible](https://img.shields.io/badge/Swift%20Package%20Manager-compatible-brightgreen.svg)](https://github.com/apple/swift-package-manager)\n[![License](https://img.shields.io/cocoapods/l/Auk.svg?style=flat)](LICENSE)\n[![Platform](https://img.shields.io/cocoapods/p/Auk.svg?style=flat)](http://cocoadocs.org/docsets/Auk)\n\nThis is an iOS library that shows an image carousel with a page indicator. Users can scroll through local and remote images or watch them scroll automatically.\n\n```Swift\n  scrollView.auk.show(url: \"https://bit.ly/auk_image\")\n  scrollView.auk.show(url: \"https://bit.ly/moa_image\")\n\n  if let image = UIImage(named: \"local_bird.jpg\") {\n    scrollView.auk.show(image: image)\n  }\n```\n\n* Uses Auto Layout and supports animated transition during screen orientation change.\n* Allows to specify placeholder and error images for remote sources.\n* Includes caching and logging for remote images.\n* Supports right-to-left languages.\n* Allows to specify accessiblity labels for the images.\n* Includes ability to simulate and verify image download in unit tests.\n\n\n\u003cimg src='https://raw.githubusercontent.com/evgenyneu/Auk/master/Graphics/Screenshots/auk_paged_image_scroller_ios.jpg' alt='Great Auks by John Gerrard Keulemans' width='382'\u003e\n\n*Drawing of the great auk by John Gerrard Keulemans, circa 1900. Source: [Wikimedia Commons](https://en.wikipedia.org/wiki/Great_auk).*\n\n\n\n## Setup\n\nThere are multiple ways you can add Auk to your Xcode project.\n\n#### Add source (iOS 7+)\n\nSimply add two files to your project:\n\n1. Moa image downloader [MoaDistrib.swift](https://github.com/evgenyneu/moa/blob/master/Distrib/MoaDistrib.swift).\n2. Auk image slideshow [AukDistrib.swift](https://github.com/evgenyneu/Auk/blob/master/Distrib/AukDistrib.swift).\n\n#### Setup with Carthage (iOS 8+)\n\n1. Add `github \"evgenyneu/Auk\" ~\u003e 11.0` to your Cartfile.\n2. Run `carthage update`.\n3. Add `moa` and `Auk` frameworks into your project.\n\n#### Setup with CocoaPods (iOS 8+)\n\nIf you are using CocoaPods add this text to your Podfile and run `pod install`.\n\n    use_frameworks!\n    target 'Your target name'\n    pod 'moa', '~\u003e 12.0'\n    pod 'Auk', '~\u003e 11.0'\n\n\n#### Setup with Swift Package Manager\n\n* In Xcode 11+ select *File \u003e Packages \u003e Add Package Dependency...*.\n* Enter **Auk** project's URL: https://github.com/evgenyneu/Auk.git\n\n\n### Legacy Swift versions\n\nSetup a [previous version](https://github.com/evgenyneu/Auk/wiki/Legacy-Swift-versions) of the library if you use an older version of Swift.\n\n\n\n## Usage\n\n1. Add `import Auk` to your source code ((unless you used the file setup method)).\n1. Add a scroll view to the storyboard and create an outlet property `scrollView` in your view controller.\n1. Clear the **Adjust Scroll View Insets** checkbox in the *Attribute Inspector* of your view controller.\n\n\u003cimg src='https://raw.githubusercontent.com/evgenyneu/Auk/master/Graphics/Screenshots/adjust_table_view_insets.png' width='463' alt='Clear \"Adjust Scroll View Insets\" in your View Controller.'\u003e\n\nAuk extends UIScrollView class by creating the `auk` property.\n\n```Swift\n// Show remote images\nscrollView.auk.show(url: \"https://bit.ly/auk_image\")\nscrollView.auk.show(url: \"https://bit.ly/moa_image\")\n\n// Show local image\nif let image = UIImage(named: \"bird.jpg\") {\n  scrollView.auk.show(image: image)\n}\n\n// Return the number of pages in the scroll view\nscrollView.auk.numberOfPages\n\n// Get the index of the current page or nil if there are no pages\nscrollView.auk.currentPageIndex\n\n// Return currently displayed images\nscrollView.auk.images\n```\n\n#### Scrolling from code\n\n```Swift\n// Scroll to page\nscrollView.auk.scrollToPage(atIndex: 2, animated: true)\n\n// Scroll to the next page\nscrollView.auk.scrollToNextPage()\n\n// Scroll to the previous page\nscrollView.auk.scrollToPreviousPage()\n```\n\n#### Auto scrolling\n\n```Swift\n// Scroll images automatically with the interval of 3 seconds\nscrollView.auk.startAutoScroll(delaySeconds: 3)\n\n// Stop auto-scrolling of the images\nscrollView.auk.stopAutoScroll()\n```\n\nNote that auto scrolling stops when the user starts scrolling manually.\n\n#### Accessibility\n\nOne can pass an image description when calling the `show` methods. This description will be spoken by the device in accessibility mode for the current image on screen.\n\n```Swift\n// Supply accessibility label for the image\nscrollView.auk.show(url: \"https://bit.ly/auk_image\", accessibilityLabel: \"Picture of a great auk.\")\n```\n\n#### Removing pages\n\n```Swift\n// Remove a page at given index\nscrollView.auk.removePage(atIndex: 0, animated: true, completion: {})\n\n// Remove the currently shown page\nscrollView.auk.removeCurrentPage(animated: true, completion: {})\n\n// Remove all pages\nscrollView.auk.removeAll()\n```\n\n\n#### Updating pages\n\nOne can change existing image by calling `updateAt` methods and supplying the page index.\n\n```Swift\n// Replace the image on a given page with a remote image.\n// The current image is replaced after the new image has finished downloading.\nscrollView.auk.updatePage(atIndex: 0, url: \"https://bit.ly/moa_image\")\n\n// Replace the image on a given page with a local image.\nif let image = UIImage(named: \"bird.jpg\") {\n  scrollView.auk.updatePage(atIndex: 1, image: image)\n}\n```\n\n\n## Loading images from insecure HTTP hosts\n\nIf your remote image URLs are not *https* you will need to [add an exception](http://evgenii.com/blog/loading-data-from-non-secure-hosts-in-ios9-with-nsurlsession/) to the **Info.plist** file. This will allow the App Transport Security to load the images from insecure HTTP hosts.\n\n## Configuration\n\nUse the `auk.settings` property to configure behavior and appearance of the scroll view **before showing the images**. See the [configuration manual](https://github.com/evgenyneu/Auk/wiki/Auk-configuration) for the complete list of configuration options.\n\n```Swift\n// Make the images fill entire page\nscrollView.auk.settings.contentMode = .scaleAspectFill\n\n// Set background color of page indicator\nscrollView.auk.settings.pageControl.backgroundColor = UIColor.gray.withAlphaComponent(0.3)\n\n// Show placeholder image while remote image is being downloaded.\nscrollView.auk.settings.placeholderImage = UIImage(named: \"placeholder.jpg\")\n\n// Show an image AFTER specifying the settings\nscrollView.auk.show(url: \"https://bit.ly/auk_image\")\n```\n\n## Preloading remote images\n\nBy default remote images are loaded after they become visible to user. One can ask the library to preload remote images  by setting the property `preloadRemoteImagesAround`.\n\n```Swift\n// Set the property before showing remote images\nscrollView.auk.settings.preloadRemoteImagesAround = 1\n\n// Add remote images. The first two images will start loading simultaneously.\nscrollView.auk.show(url: \"https://bit.ly/auk_image\")\nscrollView.auk.show(url: \"https://bit.ly/moa_image\")\n\n// The third image will start loading when the user scrolls to the second page.\nscrollView.auk.show(url: \"https://bit.ly/auks_at_home\")\n```\n\nThe `preloadRemoteImagesAround` property defines the number of remote images to preload around the current page. For example, if `preloadRemoteImagesAround = 2` and we are viewing the first page it will preload images on the second and third pages. If we are viewing 5th page then it will preload images on pages 3, 4, 6 and 7 (unless they are already loaded). The default value is 0.\n\nNote that images are loaded all at the same time, therefore, using large values for `preloadRemoteImagesAround` may result in the first image being delayed on slow networks because the limited bandwidth will be shared by many image downloads.\n\n## Size change animation\n\nRead [size animation](https://github.com/evgenyneu/Auk/wiki/Size-animation) manual if you need to animate the scroll view during device orientation change.\n\n\n## Image caching\n\nAuk uses [moa image downloader](https://github.com/evgenyneu/moa) for getting remote images. You can configure its caching settings by changing the `Moa.settings.cache.requestCachePolicy` property. Add `import moa` to your source code if you used Carthage or CocoaPods setup methods.\n\n\n```Swift\nimport moa // for Carthage and CocoaPods\n\n// ...\n\n// By default images are cached according to their response HTTP headers.\nMoa.settings.cache.requestCachePolicy = .useProtocolCachePolicy\n\n// Use local cache regardless of response HTTP headers.\nMoa.settings.cache.requestCachePolicy = .returnCacheDataElseLoad\n```\n\nNote: [moa image downloader](https://github.com/evgenyneu/moa) offers other features including request logging and HTTP settings.\n\n## Logging\n\nIf you want to know when the remote images are being loaded you can log the network activity to console, as shown in the following example. Please refer to the [moa logging manual](https://github.com/evgenyneu/moa/wiki/Logging-with-Moa) for more information.\n\n```Swift\nimport moa // for Carthage and CocoaPods\n\n// ...\n\n// Log to console\nMoa.logger = MoaConsoleLogger\n\n// Show an existing image\nscrollView.auk.show(url: \"https://bit.ly/auk_image\")\n\n// Attempt to show a missing image\nscrollView.auk.show(url: \"https://bit.ly/missing_auk.jpg\")\n```\n\n\u003cimg src='https://raw.githubusercontent.com/evgenyneu/Auk/master/Graphics/Screenshots/auk_swift_slideshow_logging_console_2.png' alt='Log Auk remove image download to console' width='506'\u003e\n\n## Remote image unit testing\n\nOne can simulate and verify remote image download in your unit tests. Please refer to the [moa unit testing manual](https://github.com/evgenyneu/moa/wiki/Unit-testing-with-Moa) for more information. Add `import moa` to your source code if you used Carthage or CocoaPods setup methods.\n\n\n```Swift\n// Autorespond with the given image\nMoaSimulator.autorespondWithImage(\"www.site.com\", image: UIImage(named: \"35px.jpg\")!)\n```\n\n## Respond to image tap\n\nHere is what you need to do to add an image tap handler to the scroll view.\n\n1. In the Storyboard drag a *Tap Gesture Recognizer* into your scroll view.\n1. Show assistant editor with your view controller code.\n1. Do the control-drag from the tap gesture recognizer in the storyboard into your view controller code.\n1. A dialog will appear, change the *Connection* to *action* and enter the name of the method.\n1. This method will be called when the scroll view is tapped. Use the `auk.currentPageIndex` property of your scroll view to get the index of the current page.\n\n## Detect page scrolling\n\nYou can run some code when the scroll view is being scrolled by using `UIScrollViewDelegate`. See the [detect page scrolling manual](https://github.com/evgenyneu/Auk/wiki/Detect-page-scrolling) for details.\n\n## Using Auk from Objective-C\n\n[This manual](https://github.com/evgenyneu/Auk/wiki/Using-Auk-in-Objective-C-project) describes how to use Auk in Objective-C apps.\n\n\n## Common problems\n\n### Page control is not visible\n\nMake sure the scrollView is added to the view tree *before* you call the `show` method. Otherwise the page control will not be created. Quick check:\n\n```Swift\nprint(scrollView.superview) // should not be `nil`\nscrollView.auk.show(url: \"https://bit.ly/auk_image\")\n```\n\nThe page control is added to the superview of the scroll view when the `show` method is called. That's why page control is not created when the scroll view has no superview.\n\nIf `scrollView.superview` is `nil` then you may need to move that code that shows the images to the `viewDidAppear` method.\n\n### Remote images are not loading\n\nOne can [turn on the logger](#logging) to see the network activity in the Xcode console and find the problem with image download.\n\n### Page control is not changing / second remote image is not shown\n\nIf you are assigning the scroll view delegate please make sure it is done **before** showing the images.\n\n```Swift\n// Assign the delegate BEFORE showing the images\nscrollView.delegate = self\n\nscrollView.auk.show(url: \"https://bit.ly/auk_image\")\nscrollView.auk.show(url: \"https://bit.ly/moa_image\")\n```\n\n\n## Demo app\n\nThe project includes a demo iOS app.\n\n\u003cimg src='https://raw.githubusercontent.com/evgenyneu/Auk/master/Graphics/Screenshots/auk_demo_ios_app_2.jpg' width='414' alt='Auk pages scroll view demo iOS app'\u003e\n\n\n## Alternative solutions\n\nHere is a list of other image slideshow libraries for iOS.\n\n\n* [kimar/KIImagePager](https://github.com/kimar/KIImagePager)\n* [kirualex/KASlideShow](https://github.com/kirualex/KASlideShow)\n* [nicklockwood/iCarousel](https://github.com/nicklockwood/iCarousel)\n* [nicklockwood/SwipeView](https://github.com/nicklockwood/SwipeView)\n* [paritsohraval100/PJR-ScrollView-Slider](https://github.com/paritsohraval100/PJR-ScrollView-Slider)\n* [zvonicek/ImageSlideshow](https://github.com/zvonicek/ImageSlideshow)\n\n\n## Thanks 👍\n\n* [eyaldar](https://github.com/eyaldar) added `updatePage` method.\n* [Valpertui](https://github.com/Valpertui) added `removePage` and `removeCurrentPage` methods.\n\n## Image credits\n\n* The Great Auk drawing by John James Audubon, 1827-1838. Source: [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:341_Great_Auk.jpg).\n* Great auk with juvenile drawing by John Gerrard Keulemans, circa 1900. Source: [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Great_auk_with_juvenile.jpg).\n* The Great Auk drawing from Popular Science Monthly Volume 62, 1902-1903. Source: [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:PSM_V62_D510_The_great_auk.png).\n* Great Auk egg, U. S. National Museum, in a book by Arthur Cleveland Bent, 1919. Source: [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Great_Auk_Egg_Bent.jpg).\n* Only known illustration of a Great Auk frawn from life by Olaus Wormius, 1655. Source: [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Wormius%27_Great_Auk.jpg).\n* The Great Auks at Home, oil on canvas by John Gerrard Keulemans. Source: [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Pinguinus.jpg).\n* Alca impennis by John Gould: The Birds of Europe, vol. 5 pl. 55, 19th century. Source: [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Alca_Impennis_by_John_Gould.jpg).\n* Great Auks in summer and winter plumage by John Gerrard Keulemans, before 1912. Source: [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Keulemans-GreatAuk.jpg).\n\n\n## License\n\nAuk is released under the [MIT License](LICENSE).\n\n## Feedback is welcome\n\nIf you notice any issue, got stuck or just want to chat feel free to create an issue. I will be happy to help you.\n\n## •ᴥ•\n\nThis code is dedicated to the [great auk](https://en.wikipedia.org/wiki/Great_auk), a flightless bird that became extinct in the mid-19th century.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevgenyneu%2Fauk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevgenyneu%2Fauk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevgenyneu%2Fauk/lists"}