Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/haruma-k/fancycarouselview
Carousel View for Unity uGUI using Fancy Scroll View.
https://github.com/haruma-k/fancycarouselview
carouselview scrollview ugui unity
Last synced: 6 days ago
JSON representation
Carousel View for Unity uGUI using Fancy Scroll View.
- Host: GitHub
- URL: https://github.com/haruma-k/fancycarouselview
- Owner: Haruma-K
- License: mit
- Created: 2021-10-05T00:59:27.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2023-08-16T10:10:42.000Z (over 1 year ago)
- Last Synced: 2024-12-13T10:44:40.003Z (13 days ago)
- Topics: carouselview, scrollview, ugui, unity
- Language: C#
- Homepage:
- Size: 551 KB
- Stars: 247
- Watchers: 4
- Forks: 19
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
Fancy Carousel View
[](LICENSE.md)
[日本語ドキュメント(Japanese Documents Available)](README_JA.md)
Carousel View for Unity uGUI using Fancy Scroll View.
## Table of Contents
- [Features](#features)
- [Demo](#demo)
- [Setup](#setup)
- [Requirement](#requirement)
- [Install](#install)
- [Basic Usage](#basic-usage)
- [Create data for the cells](#create-data-for-the-cells)
- [Create the cell view](#create-the-cell-view)
- [Create the carousel view](#create-the-carousel-view)
- [Initialize the carousel view](#initialize-the-carousel-view)
- [Advanced Usage](#advanced-usage)
- [Understand the properties of the Carousel View](#understand-the-properties-of-the-carousel-view)
- [Use the progress View](#use-the-progress-view)
- [Custom cell movements](#custom-cell-movements)
- [Use with scroll view](#use-with-scroll-view)
- [License](#license)
## Features
* You can create the Carousel View in a few simple steps.
* High performance because cells that are not needed for display are reused.
* Supports vertical and horizontal scrolling.
* The movement of the carousel and each parameters can be customized in detail.
## Demo
1. Clone this repository.
2. Open and play the following scene.
* https://github.com/Haruma-K/FancyCarouselView/blob/master/Assets/Demo/Scenes/CarouselDemo.unity
## Setup
#### Requirement
Unity 2019.4 or higher.
#### Install
The Fancy Carousel View uses the Fancy Scroll View as a low layer implementation.
So you need to install both of them.
1. Open the Package Manager from Window > Package Manager
2. "+" button > Add package from git URL
3. Enter the following to install Fancy Scroll View
* https://github.com/setchi/FancyScrollView.git#upm
4. Enter the following to install Fancy Carousel View
* https://github.com/Haruma-K/FancyCarouselView.git?path=/Assets/FancyCarouselView
Or, open Packages/manifest.json and add the following to the dependencies block.
```json
{
"dependencies": {
"jp.setchi.fancyscrollview": "https://github.com/setchi/FancyScrollView.git#upm",
"com.harumak.fancycarouselview": "https://github.com/Haruma-K/FancyCarouselView.git?path=/Assets/FancyCarouselView"
}
}
```
If you want to set the target version, specify it like follow.
* https://github.com/Haruma-K/FancyCarouselView.git?path=/Assets/FancyCarouselView#1.0.0
## Basic Usage
#### Create data for the cells
First, create data for each of the cells that are elements of the carousel view.
In the following example, defines the key to load cell background texture and the string that is displayed in the cell.
```cs
public class DemoData
{
public string SpriteResourceKey { get; }
public string Text { get; }
public DemoData(string spriteResourceKey, string text)
{
SpriteResourceKey = spriteResourceKey;
Text = text;
}
}
```
#### Create the cell view
Next, create the view of the cell.
As the following, inherit from the `CarouselCell` class and write the process of updating the view in the `Refresh` method.
```cs
using FancyCarouselView.Runtime.Scripts;
using UnityEngine;
using UnityEngine.UI;
public class DemoCarouselCell : CarouselCell
{
[SerializeField] private Image _image = default;
[SerializeField] private Text _text = default;
protected override void Refresh(DemoData data)
{
_image.sprite = Resources.Load(data.SpriteResourceKey);
_text.text = data.Text;
}
}
```
Attach this script to a GameObject and create a prefab of the cell.
#### Create the carousel view
Next, create the carousel view.
Create a class that inherits from the `CarouselView` class with the data and the cell class described above as the generic.
```cs
using FancyCarouselView.Runtime.Scripts;
public class DemoCarouselView : CarouselView
{
}
```
Attach it to a GameObject under Canvas.
Adjust the size of the carousel view with the size of RectTransform, and adjust the size per cell with `Cell Size` property of `CarouselView`.
Also, assign the prefab created in the previous section to the `Cell Prefab` property.
#### Initialize the carousel view
Finally, pass the data using the `CarouselView.Setup` method, and the carousel view will be displayed.
```cs
using System.Linq;
using UnityEngine;
namespace Demo.Scripts
{
public class Demo : MonoBehaviour
{
[SerializeField] private DemoCarouselView _carouselView = default;
[SerializeField, Range(1, 3)] private int _bannerCount = 3;
private void Start()
{
var items = Enumerable.Range(0, _bannerCount)
.Select(i =>
{
var spriteResourceKey = $"tex_demo_banner_{i:D2}";
var text = $"Demo Banner {i:D2}";
return new DemoData(spriteResourceKey, text);
})
.ToArray();
_carouselView.Setup(items);
}
}
}
```
## Advanced Usage
#### Understand the properties of the Carousel View
The description of each property in the Carousel View inspector is as follows.
Property NameDescription
Cell ContainerRectTransform representing the area of the carousel view.
Cells outside this area will be hidden and be reused.
Cell PrefabPrefab of the cell.
Cell SizeSize of the cell.
Cell SpacingSpacing between cells.
Snap Animation DurataionSeconds of the snap animation.
Snap Animation TypeEasing type of the snap animation.
Auto ScrollingIf true, scroll automatically at regular intervals.
IntervalAuto scrolling interval in seconds。
Inverse DirectionIf true, reverse the direction of the auto scrolling.
Scroll DirectionDirection of the scrolling.
LoopIf true, loop when reaches the end.
DraggableDragable or not.
Progress ViewView that represents the progress. See below for details.
ClickableIf true, you can click progress view to scroll to the element at the clicked index.
#### Use the progress View
Fancy Carousel View supports the progress view representing the carousel progress.
You can use the simple dot progress view by the following steps.
1. Instantiate `pfb_default_carousel_progress_view.prefab` in a scene.
2. Assign 1. to the Progress View property of the Carousel View.
`DotCarouselProgressView` derived from `CarouselProgressView` is attached to the Prefab above.
If you implement your own class that derived from `CarouselProgressView` or `ClickableCarouselProgressView`, you can create a progress view that behaves as you wish.
If you want to change only the color or size of the dot while using `DotCarouselProgressView`, you can do so by replacing only the Progress Element Prefab in the Inspector of `DotCarouselProgressView`.
#### Custom cell movements
You can override `CarouselCell.OnPositionUpdated` to implement your own cell movement.
The following is an example of a custom cell movements.
```cs
protected override void OnPositionUpdated(float position)
{
base.OnPositionUpdated(position);
var trans = transform;
var pos = position * 2.0f - 1.0f;
var absPos = Mathf.Abs(pos);
var cellPosZ = Mathf.Lerp(0.0f, 120.0f, absPos);
trans.localPosition = new Vector3(trans.localPosition.x, trans.localPosition.y, cellPosZ);
trans.rotation = Quaternion.AngleAxis(pos * -20.0f, Vector3.up);
}
```
#### Use with scroll view
When you use the carousel view as the content of the scroll view, the carousel view blocks the dragging of the scroll view according to the Unity specification.
In other words, dragging the carousel view will not scroll the scroll view.
In such a case, attach the `Scroll Event Propagator` component to the Carousel View GameObject.
This component will propagate drag events to the parent `ScrollRect` properly.
As a result, the scroll view and carousel view will work properly as shown below.
## License
This software is released under the MIT License.
You are free to use it within the scope of the license.
However, the following copyright and license notices are required for use.
* [LICENSE.md](LICENSE.md)
And this software is implemented on the assumption that the following software is installed (not included).
* [FancyScrollView](https://github.com/setchi/FancyScrollView)
See [Third Party Notices.md](Third%20Party%20Notices.md) for details on the license of this software.