Scroll View

SmartUI Dialog Behavior operation and ACEs.

ScrollViews are excellent wrappers for large UI containers. It is a complex composite component that inherits its features directly from a Container. It is particularly useful on devices with a reduced viewport, such as mobile phones, and also clips objects and their interactions to the viewport area of the ScrollView.

Structure of a Scrollview Component

Scrollviews are composed of the following parts:

1. A scrollview container, the Scrollview behavior itself.
2. A content Container; it must always be a smartui container. The content container is mandatory.
3. A vertical and a horizontal scrollbar for displacing. Both scrollbars are optional.

At all times, the coordinates of the content are calculated from the bounding quad. This means the origin point is not relevant for calculating the bounds where the content can be displaced. Rotating the content has no effect on the bounding quad; it just results in occupying a larger area for the calculations.

The content container can have any type of object in its hierarchy. Child objects don't have to use a Smart UI behavior. 🎉

The way a ScrollView works is by masking all the objects inside the content container. This process requires you to use ScrollViews in a single, separate layer for each ScrollView. Nevertheless, to semi-automate this process, ScrollViews can create a dynamic layer on top of the one holding the component to render the content.

All the content is then masked to render within the ScrollView container. To mask the child objects, the ScrollView changes each child's blend mode to source-atop rendering, thereby enabling the content layer's transparency and force-own-texture properties. The layer configuration, creation, and disposal are automatically handled by the plugin. If the ScrollView object is destroyed, the dynamic layer is removed instantly.

Dynamic layers do not support 3D layers. If you want to render the ScrollView in a 3D layer, you have to manually set it up and arrange the objects' Z-Elevation to render correctly. Make sure the 3D layer's draw order is set to Z-Order.

ScrollViews generate a dynamic layer to render the content by default. You can turn this feature off to adjust it to your needs. This is useful when you want the view to render the content in a 3D layer. In that case, place the ScrollView in a separate 3D layer, and manually enable the transparency and force-own-texture properties.

By design, ScrollView does not arrange the scrollbars automatically; you will have to place them manually, keeping in mind the conditions below.

Component composition recommended layout.

For the horizontal scrollbar, the minimum value is placed at the left-most edge of the bar, and subsequent increments will push the bar to the right-most edge, to be consistent with the ScrollView orientation. The preferred angle for this component should be 0º.

For the vertical scrollbar, the minimum value is placed at the top of the bar, and subsequent increments will push the bar downwards. The preferred angle for this component should be 90º.

⚠️ Rendering Limitations ⚠️

Construct doesn't have the capability to create additional viewports or cameras to render different sections of a scene. To work within this limitation using only built-in and official features, the Scrollview utilizes a dedicated layer for content. This means you will need to manually manage rendering if you want objects to appear above the Scrollview, such as additional dialog windows that overlap and cover parts of it.

Construct is also limited in rendering HTML and texture-like objects within the same layer, as they scale differently and may cause unwanted behavior. Unfortunately, this issue cannot be resolved by addons without hacking the engine. To avoid odd behaviors, it is recommended to use texture-only objects within the same layer. However, the Text plugin can still be used effectively.

Rendering in 3D

To use the ScrollView in a 3D layer, you must set it up manually and make some small adjustments to the content container.

You will use two 3D layers to compose your ScrollView. The bottom-most layer (Layer 0) will hold the scrollbars that control the ScrollView. This layer uses a normal rendering mode. Next, place the ScrollView component and the content component with its objects in the next layer (Layer 1). This layer must have the Force Own Texture and Transparency attributes enabled. Notice that the content container and all its children are not at the same Z-Elevation level; they must be one Z-Elevation level above the ScrollView container level to render correctly. Both layers must use Z-Order-based rendering to work correctly.

3D layer configuration

Objects arrangement for a 3D scrollview

You can also embed a 3D ScrollView in a Dialog. For that, the Dialog object must be in the same layer as the scrollbars and must be the parent of the ScrollView container

📺 Video Demo

3D scrollview demo

Basic Setup - Tutorial Video

Properties

Property	Description
Enabled	Enables or Disables the ScrollView and all its children.
Index	Index of the ScrollView within layout. Used for focusing the elements in the sequence order.
Invisible Component	Allows interactions for the component even if the object is invisible.
Focusable	Marks if the component can have the focus.
Automatic-Color	Enables the component to darken a bit when its state is Disabled or when it's focused. Auto-Color is meant to provide a quick identification of the component state. For more specialized customizations, use the component events and disable this check.
Dynamic Layers	Handle the Scrollview components in a dynamic layer.
Name	Unique name string for identifying the selected ScrollView.
Content	A container object that uses the Smart UI Container behavior.
Vertical Scrollbar	Component name of the vertical scrollbar.
Horizontal Scrollbar	Component name of the horizontal scrollbar.
Movement Type	Indicates which axes can be scrolled. When horizontal scrolling is set, the wheel moves along X-axis, otherwise it moves along Y-axis.
Swipe	Indicates if the scrollview supports the swipe gesture.
Inertia	Indicates if intertia is applied when swiping
Wheel Step	Step size in pixels when scrolling using the mouse wheel.

Smart UI ScrollView ACEs

Smart UI ScrollView behavior groups UI components, provides focusing abilities and default interactions to navigate within the ScrollView and its children components that uses Smart UI behaviors, and handles cascading Enabling/Disabling events. It also responds to pointer interactions prioritizing by zIndex.

Actions

---

Set Enabled

Disable/Enable the ScrollView

Parameter	Description
Enabled	Enabled/Disabled

Set Name

Sets the name of the ScrollView.

Parameter	Description
Name	Name of the component

Set Sequence

Sets the sequence index to influence the selection of components.

Parameter	Description
Index	Sequence index value. E.g. Indexes values of 0 are processed before indexes values of 1 and 2.

Set Focusable

Sets the component to be able to receive the focus

Parameter	Description
Focusable	Flag to allow the component to be focused.

Set Focus

Request the focus for this ScrollView

Focus First Element

Request the focus for the first interactable element of the ScrollView.

Focus Last Element

Request the focus for the last interactable element of the ScrollView.

Set Invisible Component

Sets whether the component should be processed when it's invisible. Opacity is not taken in consideration.It doesn't affect the visibility attribute of the object, you are responsible of turning it visible or invisible when needed.

Parameter	Description
Invisible Component	Set if the component processed even if it's invisible: True/False

Scroll To Object

Scrolls the view to the object coordinates ignoring the movement-type restriction.

Parameter	Description
Object	Instance of the object to scroll to

Scroll To Position

Scrolls the view to the given coordinates ignoring the movement-type restriction. Relative coordinates start at the top-left corner of the content object bounding quad. Y-positive downwards, X-positive right.

Parameter	Description
X	Absolute X-Axis coordinate
Y	Absolute Y-Axis coordinate
Coordinates	Coordinate system type

Set Scroll Step

Sets the size in pixels of the step when using the mouse wheel.

Parameter	Description
Step Size	Step size in pixels.

Set Inertia

Sets the component inertia feature enabled or disabled

Parameter	Description
Enabled	Flag to allow the component to use inertia.

Set Swipe

Sets the component swipe gesture support enabled or disabled

Parameter	Description
Enabled	Flag to allow the component to use the swipe gesture.

Set Movement

Indicates which axes can be scrolled. When horizontal scrolling is set, the wheel moves along X-axis, otherwise it moves along Y-axis.

Parameter	Description
Movement Type	Type of scrolling/movemement allowed for the content. Scroll-To-Position and Scroll-To-Object actions ignore movement type.

Conditions

---

Is Enabled

Returns true if the ScrollView is enabled

Is Invisible Component

Returns true if the ScrollView is configured as an invisible component.

Compare Name

Returns true if the component's name equals the parameter

Parameter	Description
Name	Name to compare with the component picked.

Is Focused

Returns true if the ScrollView has the focus

Has Control

True if the ScrollView has the control to navigate over components.

On Focus

Triggered when the ScrollView gets the focus

On Focus Lost

Triggered when the ScrollView loses focus

Is Inertia Enabled

Returns true if the ScrollView inertia feature is enabled

Is Swipe Enabled

Returns true if the ScrollView swipe gesture support is enabled

Expressions

---

Name

Component name

DynamicLayer

Dynamic layer name.

(c) Pixel Perfect Studio 2024