Using the Trajectory List Box 3D node

Use the Trajectory List Box 3D node to create scrollable lists of items arranged along a trajectory. Kanzi Studio comes with a several types of trajectories you can use. When you need a different type of trajectory, you can create a spline trajectory in a third-party tool and import it to your Kanzi Studio project. See Trajectories.

The items in a Trajectory List Box 3D node appear in the order you add them to the Trajectory List Box 3D node. To select an item in a Trajectory List Box 3D node click or tap the item.

The size of the trajectory defines the interactive area for click and drag gestures. If the trajectory is too small, users will not be able to select the items in the Trajectory List Box 3D node. To avoid this, make sure the trajectory is large enough. See Trajectories.

Note that items in all list box nodes (Grid List Box nodes and Trajectory List Box 3D node) are not its child nodes, even though in Kanzi Studio it seems so when you add items to a list box. Because list box items are not child nodes of a list box, you cannot refer to these items from outside of a list box using paths or aliases. If you need to refer from a list box item to an object outside of a list box, use bindings and aliases. See Binding to properties outside of a Trajectory List Box 3D node and Navigating to Page nodes from a Trajectory List Box 3D node.

Trajectory List Box 3D node is an interactive version of the Trajectory Layout nodes. See Using the Trajectory Layout nodes.

Creating a Trajectory List Box 3D node

To create a Trajectory List Box 3D node:

1. In the Project press Alt and right-click the node where you want to create a Trajectory List Box 3D node and select Trajectory List Box 3D.
   Note that you can create the Trajectory List Box 3D node only inside 3D nodes.
   Tip To see the trajectory, in the Preview click to enter the Analyze mode, right-click , and select Debug objects.
   
2. In the Project add items to the Trajectory List Box 3D node.
   For example, add several Sphere nodes.
   As you add items, the Trajectory List Box 3D node arranges them along the trajectory used by the Trajectory List Box 3D node.
   To browse the items in a Trajectory List Box 3D node, in the Preview click and drag the items in the Trajectory List Box 3D node.
3. (Optional) Kanzi Studio creates and uses a circle trajectory by default. You can use an angle, arc, circle, ellipse, line, rectangle, spiral, spline, or a trapezoid trajectory. See Trajectories.

Fine tuning the mechanics of a Trajectory List Box 3D node

You can fine tune the mechanics of a list box. You can set the list box to:

• Bring the selected item to the center of the list box. To set the list box to bring the item to the center of the list box object when a user clicks or taps the item, set the Selection Behavior property to Bring Center. Use the Cursor Offset property to set the direction in which selection moves the items in the list box. Use the Cursor Offset property to set the direction in which selection moves the items in the list box.
  
• Show items from the beginning after reaching the last item. To start showing the items in a Trajectory List Box 3D from the beginning after reaching the last item, enable the Looping property.
  
• Use either x or y axis for scrolling the items in the list box. To set the scrolling axis, add and set the Scroll Axis property. For example, to set the list box so that users scroll along the y axis to browse the list box items, set the Scroll Axis property values X to 0 and Y to 1.

• Change the appearance of the items based on their location on the trajectory. To set how the items look at different points on the trajectory, use the Item Area Begin and Item Area End properties. You use the Item Area Begin and Item Area End properties to set the value of the Visible Amount In Parent property, which sets shaders to change the appearance of an item based on the location of that object in the list box.
  For example, if you use the Visible Amount In Parent property to gradually change the visibility of an item, set the Item Area Begin property to a larger value and the Item Area End property to a smaller value. This way you limit the area where that item is visible.

Binding to properties outside of a Trajectory List Box 3D node

Use an alias when you want to bind a property of a list box item to a property of a node outside of the list box.

For example, if you have a Grid List Box 3D or a Trajectory List Box 3D node with a Text Block 3D node item and want to set the Text property value of the Text Block 3D node to a value of an Empty Node 3D node property that is not in the list box:

1. In the Project press Alt and right-click the nodes that contain the property to which you want to bind and select Alias. See Using aliases.
   For example, create an alias for the Empty Node 3D node.
2. In the Dictionaries make sure that the aliases you created are in the resource dictionary that the list box node can access.
   For example, place all aliases to the resource dictionary of the Screen node, or create a resource dictionary in the list box node and place the aliases to that resource dictionary. See Using resource dictionaries.
3. Create the binding:
   1. In the Project select the node inside the list box node from which you want to bind to a node outside of the list box node.
   2. In the Properties add the Bindings property and create the binding using the alias to bind to the property in a node outside of the list box node.
      For example, in the Text Block 3D node create a binding to the Empty Node 3D node using the alias you created in the first step. See Bindings expressions reference.
      For example, use this binding expression:

      {#Empty Node 3D/TextBlockConcept.Text}

      
      The Text property in the Text Block 3D node gets the value of the Text property from the Empty Node 3D node.
   3. Click Save.

Navigating to Page nodes from a Trajectory List Box 3D node

Use an alias when you want to navigate to a Page node from a node that is inside a list box node. For example, if you use a Grid List Box or a Trajectory List Box 3D node to create an address book and want to show the content of an address book entry in a Page node.

To navigate to Page nodes from a list box node:

1. In the Project press Alt and right-click each Page node to which you want to navigate to and select Alias.
   Kanzi Studio creates an alias that points to the node from which you created it, and places the alias to the nearest resource dictionary.
   
2. In the Dictionaries make sure that the aliases you created are in the resource dictionary that the list box node can access.
   For example, place all aliases to the resource dictionary of the Screen node, or create a resource dictionary in the list box node and place the aliases to that resource dictionary. See Using resource dictionaries.
   
3. Add and set the Navigate to Page action:
   1. In the Project in the list box node select the node that contains the trigger you want to use to navigate to one of the Page nodes for which you created the alias in the first step.
      
   2. In the Node Components > Triggers section in the trigger you want to use to navigate to the Page node add the Navigate to Page action.
      
   3. In the Navigate to Page settings window set the Item property to the alias of the Page node to which you want to navigate and click Save.
      All aliases start with a # sign.
      

In the Preview when you click the node that contains the Navigate to Page action, you activate the Page node selected in the action.

Trajectory list box example

This example shows the use of the Trajectory List Box 3D node to create an interactive scrollable list of items. The example implements a simple gallery of photos with a selection effect using an animation.

The Trajectory List Box 3D node, its Circle Trajectory, content shown in the Trajectory List Box 3D, and animation that highlights the centered photo are created in Kanzi Studio. The point of time at which a highlight-animation is launched is defined based on the scroll speed and focused item data available from the user input events that the trajectory list box component produces.

The Trajectory List Box 3D node in the example uses these features:

• Scroll Axis. The scroll axis for the trajectory is set to the x axis. The trajectory defines the scroll path.
• Looping. You can clamp the items in the Trajectory List Box 3D node to the defined trajectory start and end or to transition between the start and end positions, as in this example, with the Looping property.
• Trajectory. To use a trajectory for the Trajectory List Box 3D, you need to create it in the Library > Trajectories. You can create circle and line trajectories in Kanzi Studio. To use a spline trajectory, create a spline in a third-party tool, import it, and add the spline as a Spline Trajectory. See Using circle trajectories, Using line trajectories, and Using spline trajectories.
  You can customize the trajectory by adding and setting trajectory properties such as Item Area Begin, Item Area End, Cursor Offset, and Override Distance.
• Selection and focus behavior. Selection and focus events are handled separately. The Item focused event is generated at the moment the user releases the pointer. It contains the information on the item that is brought to the center with the current trajectory movement. The selection message is generated when a user selects an item by clicking or tapping it. You can select the Bring Center selection behavior in Kanzi Studio.
  You can define more actions for the focus and selection events for any member of the Trajectory List Box 3D, or even the trajectory list box component itself, by setting invoked actions for List Box: Item Focused or List Box: Item Selected events.

You can find the example in the <KanziWorkspace>/Examples/Trajectory_list_box directory.

Using the Trajectory List Box 3D node in the API

To create a Trajectory List Box 3D:

// Create a Trajectory List Box 3D named MyListBox.
TrajectoryListBox3DSharedPtr trajectoryListBox = TrajectoryListBox3D::create(domain, "MyListBox");

To set the trajectory you want the list box to use:

// Create a circle trajectory named Circle with radius of 4 device independent units.
TrajectorySharedPtr trajectory = Trajectory::createCircle(Vector3(), Vector3::up(), 0.0f, 4.0f, domain, "Circle");

// Set the list box to use the trajectory.
trajectoryListBox->setTrajectory(trajectory);
// Increase the layout size to cover the whole trajectory.
trajectoryListBox->setWidth(10.0f);
trajectoryListBox->setDepth(10.0f);
trajectoryListBox->setHeight(3.0f);

To add items to the list box:

// Create cube meshes and add them as items of the trajectory list box.
// Items on the trajectory appear in the order you add them to the list.
Model3DSharedPtr item1 = Model3D::createCube(domain, "item1", 1.0f, ThemeRed);
Model3DSharedPtr item2 = Model3D::createCube(domain, "item2", 1.0f, ThemeGreen);
Model3DSharedPtr item3 = Model3D::createCube(domain, "item3", 1.0f, ThemeBlue);
Model3DSharedPtr item4 = Model3D::createCube(domain, "item4", 1.0f, ThemeOrange);
Model3DSharedPtr item5 = Model3D::createCube(domain, "item5", 1.0f, ThemeYellow);
trajectoryListBox->addItem(item1);
trajectoryListBox->addItem(item2);
trajectoryListBox->addItem(item3);
trajectoryListBox->addItem(item4);
trajectoryListBox->addItem(item5);

To make the list box loop:

// Make the list box looping. All items fit to the trajectory so they are positioned evenly.
trajectoryListBox->setLooping(true);

To set selection behavior:

// Make clicking items bring them to the center of the trajectory.
trajectoryListBox->setSelectionBehavior(ListBoxConcept::SelectionBehaviorBringToCenter);
// Change the position where the clicked items are brought to be one quarter from the beginning of the trajectory.
trajectoryListBox->setCursorOffset(0.25f);

For details, see the API reference.

See also

Using the Grid List Box nodes

Using the Trajectory Layout nodes

Using the Trajectory List Box 3D node

Using arc trajectories

Using circle trajectories

Using ellipse trajectories

Using line trajectories

Using rectangle trajectories

Using spiral trajectories

Using spline trajectories

Using trapezoid trajectories

Trajectories

Using bindings

Using the List Box Item Container prefabs

Open topic with navigation