Adding an UICarouselView instance to your iOS apps is easy and straightforward. In the designated view controller, create a new UICarouselView instance with the desired size and add it to the view hierarchy such as shown in the code example below.
The above code will show an empty carousel view in the screen which is not really useful. Let's get some images to show through the step-by-step guide in the following sections.
Binding Data to UICarouselView
UICarouselView is designed to be a multi-purpose slidable container, so it can actually display just anything you desire, in addition to images. Featuring built-in data binding support, you can easily bind a datasource to the carousel view in the same way you bind data to other data controls such as table view and collection view.
Binding a collection of images to the carousel view is simple and straightforward. Consider that you have a simple model with the following definition:
You can easily represent a list of EventImage in a ViewModel by simply utilizing the provided ListViewModelBase<T> class. For more information about built-in ViewModel available in Crosslight, see Selecting a ViewModel Base Class to Get Started.
An example of the ListViewModelBase implementation can be seen below.
For the sake of simplicity, the above example shows how easy it is to define a collection of images and use it as the items source. If you prefer to load the datasource from a web service, you simply need to change the implementation to get the source from the repository. For more information about data access in Crosslight, see Working with Data.
Once you have the ViewModel ready, all you need to do is creating a binding provider that contains the binding information between the ViewModel and the View. See the example below.
The above code is pretty self explanatory. It binds the Items property of the ViewModel to a view named CarouselView. In addition, the item binding description specifies the properties that will be bound to each image in the carousel view. With such minimal definition, you will now see the images show up in the carousel view similar to the illustration below.
For more information about data binding in Crosslight, see Understanding Binding Providers.
In addition to data presentation, UICarouselView also includes support for selection behavior which allows you to capture the current selection as well as programmatically selecting an item through data binding. The control supports the following bindable properties:
Both properties can be bound two-way, so the selection changes at the view level can be easily intercepted in the ViewModel.
The ability to set the selection programmatically is important in certain scenarios where you need to control the active selection from the ViewModel. One of the most common scenarios is to set the initial selection for the carousel view, where the current index is set to the item of which user tapped from the list.
The following code illustrates how to set an initial selection to the control in ViewModel.
For more information about data binding concept in Crosslight, see Understanding Data Binding and MVVM Design Pattern.
Enabling Slide Show
You can easily enable slide show on the carousel view by simply setting the EnableSlideShow property to true. In addition, you can also configure several settings related to the slide show feature such as:
- SlideShowInterval – the slide show interval in milliseconds.
- ImageContentMode – the content scaling mode for the image, applicable when using default template. For slide show scenario, you might want to use ScaleAspectFill content mode to achieve full screen presentation.
Customizing Item Template
By default, UICarouselView provides a built-in template which comprises of an image filling the control's view, and two labels at the bottom of the view. The default template is typically ideal in common scenarios, such as presenting a list of images with a title and a sub title. However, in advanced scenarios, you might want to customize the view template entirely such as providing new controls not available in the default template, or changing the appearance and layout properties completely.
UICarouselView is built with the familiar view template concept similar to other Crosslight iOS controls such as table view and collection view. This lets you easily customize the control's view template through a simple property set, by providing your custom XIB to to the CellTemplate property.
The following code shows how to set a custom view template to the control.
Customizing Page Indicator
You can control the appearance of page indicator in UICarouselView through the following properties:
- ShowPageIndicator – determines whether page indicator should be shown, true by default
- CurrentPageIndicatorColor – the color of the active/current page indicator
- PageIndicatorColor – the color of the inactive/normal page indicator
The following illustration shows the result of current page indicator set to Orange color.
You can quickly get started with the UICarouselView control by downloading the samples from Intersoft Git server here. Prior to running the samples, make sure to set the iOS project as the startup project.