releases/2.5.4releases/2.0.0releases/2.1.0releases/2.2.0releases/2.3.0releases/2.4.0releases/2.5.0releases/2.5.1releases/2.5.2releases/2.5.3
  • Features and Architecture
  • API Documentation

We've moved!

Starting from MRTK 2.6, we are publishing both conceptual docs and API references on docs.microsoft.com. For conceptual docs, please visit our new landing page. For API references, please visit the MRTK-Unity section of the dot net API explorer. Existing content will remain here but will not be updated further.

  • Features and Architecture
  • Feature Overviews
  • UX Building Blocks
  • Scrolling Object Collection
Search Results for

    Show / Hide Table of Contents
    • Welcome to MRTK
      • Installation Guide
      • Configuration
        • Using the Unity Package Manager
        • MRTK configuration dialog
        • Getting started with MRTK and XR SDK
      • Updates and Deployment
        • Updating from earlier versions
        • Upgrading from HTK
        • Building and Deploying MRTK
      • Packages and Release Notes
        • Release Notes
        • MRTK Packages
      • Performance and Best Practices
        • Performance
        • Hologram Stabilization
        • Using MRTK in large projects
    • Architecture
      • Overview
      • Framework and Runtime
      • Input System
        • Terminology
        • Core System
        • Controllers, Pointers, and Focus
      • Systems, Extension Services and Data Providers
    • Feature Overviews
      • Boundary System
        • Boundary System Overview
        • Configuring the Boundary Visualization
      • Camera System
        • Camera System Overview
        • Camera Settings Providers
          • Windows Mixed Reality Camera Settings
          • Unity AR Camera Settings [Experimental]
          • Creating a camera settings provider
      • Cross Platform Support
        • Configure MRTK for iOS and Android
        • Configure MRTK for Leap Motion Hand Tracking
        • Configure MRTK for Oculus Quest
      • Detecting Platform Capabilities
      • Diagnostics System
        • Diagnostics System Overview
        • Configuring the Diagnostics System
        • Using the Visual Profiler
      • Extension Services
        • Extension Service Creation Wizard
        • Scene Transition Service Overview
        • Hand Physics Service Overview
      • Input System
        • Input Overview
        • Input Actions
        • Input Events
        • Input Providers
          • Input Providers Overview
          • Creating an input data provider
        • Controllers
        • Eyes
          • Overview
          • Getting Started
          • Access Data via Code
          • Validate Tracking Calibration
        • Gaze
        • Gestures
        • Hands
        • How to Add Near Interaction
        • In-Editor Input Simulation
        • Pointers
        • Voice Input
          • Dictation
          • Speech (Command and Control)
      • Multi Scene System
        • Multi Scene System Overview
        • Scene Types
        • Content Scene Loading
        • Monitoring Content Loading
        • Lighting Scene Operations
      • Packaging
        • MRTK Packages
        • MRTK Modularization
      • Profiles
        • Profiles Overview
        • Configuration Guide
      • Rendering
        • MRTK Standard Shader
        • Material Instance Overview
        • Hover Light Overview
        • Proximity Light Overview
        • Clipping Primitive Overview
      • Services
        • What makes a mixed reality feature
        • What are the MixedRealityServiceRegistry and IMixedRealityServiceRegistrar
        • Extension services
      • Spatial Awareness System
        • Spatial Awareness Overview
        • Spatial Observers
          • Configuring Observers for Device
          • Configuring Observers for Editor
          • Controlling Observers via Code
          • Creating a custom Observer
      • Teleport System Overview
      • Tools
        • Dependency Window
        • Extension Service Creation Wizard
        • Holographic Remoting
        • Input Animation Recording
          • Input Animation File Format Specification
        • Migration Window
        • Optimize Window
        • Runtime tools
          • Controller Mapping tool
          • InputFeatureUsage tool
          • MixedRealityInteractionMapping tool
      • UX Building Blocks
        • Toolbox Window
        • Button
        • Bounds Control
        • Object Manipulator
        • Constraint Manager
        • Slate
        • System Keyboard
        • Interactable
        • Interactive Element
        • Solvers
          • Tap to Place
        • Object Collection
        • Scrolling Object Collection
        • Tooltips
        • Slider
        • Hand Menu
        • Near Menu
        • App Bar
        • Rigged Hand Visualizer
        • Fingertip Visualization
        • Progress Indicator
        • Dialog
        • Hand Coach
        • Pulse Shader
        • Dock Control [Experimental]
        • HoloLens Keyboard Helpers [Experimental]
        • Elastic System [Experimental]
        • Bounding Box [Obsolete]
        • Manipulation Handler [Obsolete]
      • Example Scenes
        • Examples Hub
        • Hand Interaction Example
        • Eye Tracking Interaction Example
    • Contributing
      • Contributing Overview
      • Coding Guidelines
      • Writing and Running Tests
      • Writing Documentation
      • Pull Requests
      • Experimental Features
      • Breaking Changes
      • How to use DocFX
    • Planning
      • Roadmap
    • Notice
    • Authors

    Scrolling object collection

    Scrolling object collection

    The MRTK scrolling object collection is an UX component that enables scrolling of 3D content through a contained viewable area. The scrolling movement can be triggered by near or far input interaction and by discrete pagination. It supports both interactive and non-interactive objects.

    Getting started with the scrolling object collection

    Setting up the scene

    1. Create a new unity scene.
    2. Add MRTK to the scene by navigating to the Mixed Reality Toolkit > Add to Scene and Configure.

    Setting up the scrolling object

    1. Create an empty game object in the scene and change its position to (0, 0, 1).

    2. Add a scrolling object collection component to the game object.

      When the scrolling object collection is added, a box collider and a near interaction touchable component will be automatically attached to the root game object. These components allow the scroll object to listen to near and far interaction input events, like a pointer touch or click.

      The MRTK scrolling object collection has two important elements that are created as child game objects under the root scrolling object hierarchy:

      • Container - All scrolling content objects must be children of the container game object.
      • Clipping bounds - If scrolling content masking is enabled, the clipping bounds element ensures that only the scrollable content inside its boundaries is visible. The clipping bounds game object has two components: a disabled box collider and a clipping box.

    Scrolling object collection elements

    Adding content to the scrolling object

    The scrolling object collection can be combined with a grid object collection to layout content in a grid of aligned elements that have uniform size and spacing.

    1. Create an empty game object as a child of the scroll container.
    2. Add a grid object collection component to the game object.
    3. For a vertical single column scroll, in the inspector tab, configure the grid object collection as follow:
      • Num columns: 1
      • Layout: column then row
      • Anchor: upper left
    4. Change the cell width and height according to the dimensions of the content objects.
    5. Add the content objects as children of the grid object.
    6. Press update collection.

    Grid layout

    Important

    Any scrolling content object material must use the MRTK standard shader in order for the clipping effect on the viewable area to work properly.

    Note

    If scrolling content masking is enabled, the scrolling object collection will add a material instance component to any content objects that have a renderer attached. This component is used to manage instanced materials lifetime and improve memory performance.

    Configuring the scrolling viewable area

    1. For vertical scrolling through a single column of objects, in the inspector tab, configure the scrolling object collection as follow:
      • Cells per tier: 1
      • Choose the number of tiers per page according to the desired number of visible rows
    2. Change the page cell width, height and depth according to the dimensions of the content objects.

    Notice how the content objects lying outside the scrolling viewable area are now disabled, while objects intersecting the scroll wireframe might be partially masked by the clipping primitive.

    Viewable area

    Testing the scrolling object collection in the editor

    1. Press play and hold the space bar to show an input simulation hand.
    2. Move the hand until the scrolling collider or any scrolling interactive content is in focus and trigger the scrolling movement by clicking and dragging up and down with the left mouse.

    Controlling the scrolling object from code

    The MRTK scrolling object collection exposes a few public methods that allow moving the scrolling container by snapping its position according to the pagination properties configuration.

    An example of how to access the scrolling object collection pagination interface is available to use under the MRTK/Examples/Demos/ScrollingObjectCollection/Scripts folder. The scrollable pagination example script can be linked to any existing scrolling object collection in the scene. The script can then be referenced by scene components exposing Unity events (e.g, MRTK button).

    public class ScrollablePagination : MonoBehaviour
    {
        [SerializeField]
        private ScrollingObjectCollection scrollView;
    
        public void ScrollByTier(int amount)
        {
            scrollView.MoveByTiers(amount);
        }       
    }
    

    Scrolling object collection properties:

    General
    Scroll direction The direction in which content should scroll.
    Pagination
    Cells per tier Number of cells in a row on up-down scroll view or number of cells in a column on left-right scroll view.
    Tiers per page Number of visible tiers in the scrolling area.
    Page cell Dimensions of the pagination cell.
    Advanced settings
    Mask edit mode Edit modes for defining the clipping box masking boundaries. Choose 'Auto' to automatically use pagination values. Choose 'Manual' for enabling direct manipulation of the clipping box object.
    Collider edit mode Edit modes for defining the scroll interaction collider boundaries. Choose 'Auto' to automatically use pagination values. Choose 'Manual' for enabling direct manipulation of the collider.
    Can scroll Enables/disables scrolling with near/far interaction.
    Use on pre render Toggles whether the scrollingObjectCollection will use the Camera OnPreRender event to manage content visibility.
    Pagination curve Animation curve for pagination.
    Animation length The amount of time (in seconds) the PaginationCurve will take to evaluate.
    Hand delta scroll threshold The distance, in meters, the current pointer can travel along the scroll direction before triggering a scroll drag.
    Front touch distance Distance, in meters, to position a local xy plane used to verify if a touch interaction started in the front of the scroll view.
    Release threshold Withdraw amount, in meters, from the scroll boundaries needed to transition from touch engaged to released.
    Velocity
    Type of velocity The desired type of velocity falloff for the scroller.
    Velocity multiplier Amount of (extra) velocity to be applied to scroller.
    Velocity dampen Amount of falloff applied to the velocity.
    Bounce multiplier Multiplier to add more bounce to the overscroll of a list when using falloff per frame or falloff per item.
    Debug options
    Mask enabled Visibility mode of scroll content. Default value will mask all objects outside of the scroll viewable area.
    Show threshold planes If true, the editor will render the touch release threshold planes around the scroll boundaries.
    Debug pagination Use this section to debug the scroll pagination during runtime.
    Events
    On click Event triggered when the scroll background collider or any of its interactive content receives a click.
    On touch started Event triggered when the scroll background collider or any of its interactive content receives a near interaction touch.
    On touch ended Event triggered when an active touch interaction is terminated by having the near interaction pointer crossing one of the release threshold planes.
    On momentum started Event triggered when the scroll container starts moving by interaction, velocity fallofff or pagination.
    On momentum ended Event triggered when the scroll container stops moving by interaction, velocity fallofff or pagination.

    Scrolling example scene

    ScrollingObjectCollection.unity example scene consists of 3 scrollable examples, each one with a different velocity falloff configuration. The example scene can be found under the MRTK/Examples/Demos/ScrollingObjectCollection/Scenes folder.

    Scrolling object collection example scene

    Scrolling example prefabs

    For convenience, two scrolling object collection prefabs are available to use. The example prefabs can be found under the MRTK/Examples/Demos/ScrollingObjectCollection/Prefabs folder.

    Scrolling object collection prefabs

    See also

    • Clipping Primitive
    • Material Instance
    • Standard Shader
    • Object collection
    • Improve this Doc
    In This Article
    • Getting started with the scrolling object collection
      • Setting up the scene
      • Setting up the scrolling object
      • Adding content to the scrolling object
      • Configuring the scrolling viewable area
      • Testing the scrolling object collection in the editor
    • Controlling the scrolling object from code
    • Scrolling object collection properties:
    • Scrolling example scene
    • Scrolling example prefabs
    • See also
    Back to top Generated by DocFX