Skip to main content
Version: 5.x

Image Carousel

Image Carousel is a rotary UI element that enables the selection of one item between many. To select items users can swipe to rotate the carousel or tap on an icon.

Adding the component to a scene

The Image Carousel component can be downloaded from the Asset Library.

Once downloaded it can be added to a Scene Object that has a Screen Transform.

Adding items

Items are added to the carousel by adding to the "Images" input array. Click on “Add Value” and select or drag a texture to the newly created field. (Items can be also added through a script using the API, see Full API section below)

Defining touch area

The carousel responds to touch events inside the bounds of its containing Screen Transform, editing these bounds will determine the touch area for the component.

The carousel can be also modified to have a vertical orientation (or any diagonal orientation) by rotating the containing Scene Object. Item images can then be straightened using "Item Rotation" input (under “Advanced”).

Responding to selection events

Responding to selection events can be done in one of two ways - registering for the onSelectionUpdate event or setting the callback input fields.

Method 1: Register for "onSelectionUpdate" event

The carousel component has an event called "onSelectionUpdate" that is triggered whenever a selection is made. Scripts can register for this event in the following way.

Create a new script with the following code:

//@input Component.ScriptComponent carousel

script.carousel.onSelectionUpdate.add(function (i, tex) {
print('selected index: ' + i);
print('selected icon texture: ' + tex);
});

Add the script to your scene and use the inspector panel to set the "carousel" input field to reference the carousel component in the scene.

Method 2: Set callback input fields

Create a new script and define the following function:

// Image Carousel callback example

script.onCarouselSelection = function (i, tex) {
print('selected index: ' + i);
print('selected icon texture: ' + tex);
};

In the Carousel CC, set the input fields under "On Item Set Call":

  1. Script: Set to the newly created script (the script should be in the scene).

  2. Function Name: Set to the name of the function that should be called when a selection is made ("onCarouselSelection" in this example).

Inputs

The Image Carousel Custom Component provides various input parameters to customize its look and feel. See below the full list of inputs:

Input NameDescription
ImagesArray of textures, will be used as the icons of the items
On Item Set CallDefines the callback to call when selection is made (See "Respond to selection events" section above)
Visible ItemsSet the number of visible items (3 or 5)
Item SizeThe size of the items
Carousel RadiusThe radius (spread) of the carousel
OpacityThe opacity of the items
Background ColorThe color to use for the background of the carousel (default is transparent)
Ring MarginThe distance between the selection ring and the selected item
Item RotationInternal rotation of the item images
Render OrderRender order of this UI (higher value will render later in the scene, leave at 0 to render in the same order as the containing Scene Object)
Touch SensitivitySets swipe sensitivity, higher value is more sensitive
Magnet ForceThe magnitude of the force that centers the carousel on the closest item. Used for the animation
Inertia ForceThe inertia magnitude on quick swipes
Delay CallbackCan be used to set a delay from the time of selection until the selection event is called

Full API

Events

onSelectionUpdate(index, texture)

'index' is the index of the item in the carousel

'texture' is the texture of the icon that was selected

* Registering for the event from another script:

script.carouselCC.onSelectionUpdate.add(function(index, texture) {...});

Functions

size(): int
Returns the number of items in the carousel

setSelected(int index, bool animate): void
Select item at index, animate to position if animate is true

getSelected(): int
Returns the currently selected item index, or -1 if the carousel is empty

getCentered(): int
Returns item index closest to center (works while dragging/animating too)
May be different the currently selected item while rotating the carousel

add(Texture image): int
Add an item to the end of the carousel with image
Returns the new image index

remove(int index): bool
Remove image at index, returns false if index is out of bounds

setImage(int index, Texture image): bool
Set image at index, returns false if index is out of bounds

getImage(int index): Texture
Returns the image texture for index, or null if index is out of bounds

getSelectedImage(): Texture
Returns the currently selected image texture, or null is the carousel is empty

setLocked(int index, bool locked): void
Show/Hide a lock badge on the icon

getLocked(int index): bool
Get lock badge state for icon index

setData(int index, Object data) : void
Set private data associated with this icon

getData(int index): Object
Get private data associated with this icon

enableInteraction(): void
Enable touch interaction

disableInteraction(): void
Disable touch interaction

show(): void
Show carousel (fade in animation)

hide(): void
Hide carousel (fade out animation)

isVisible(): bool
Returns visibility

Example

Here’s an example script that calls some of the carousel API functions

//@input Component.ScriptComponent carousel

//@input Asset.Texture[] icons

// Add items to the carousel

for (let i in script.icons) {
script.carousel.add(script.icons[i]);
}

// Set currently selected item
script.carousel.setSelected(1);

// Get currently selected item
print('Selected index: ' + script.carousel.getSelected());
Was this page helpful?
Yes
No

AI-Powered Search