Lay out items along a path

Article
10/10/2017

You can display a list of items along a path by using the PathListBox control. The path can be any element and can be of any size or shape. Once you have created your list, you can add PathListItems explicitly, or add a data source from the Data panel. Because a PathListBox is a type of ListBox, you can modify a PathListBox in the same ways in which you can modify a standard ListBox.

ListBoxItems along an elliptical layout path

Layout path list items displayed Orientation: None

You can create a layout path in two ways: you can add a PathListBox from the Assets panel, and then add a reference to a path to the PathListBox; or you can create a path or an object on the artboard, right-click the object, point to Path, and then select Make Layout Path.

To add a path to a PathListBox

In the Assets panel, expand Controls, click PathListBox. Draw a PathListBox on the artboard.
Do one of the following:
- In the Tools panel, select the ****Pen ****tool and draw a path on the artboard.
- Add an object from the Assets panel.
With the PathListBox selected, in the Layout Paths category in the Properties panel, click ****Artboard Element Picker ****, and then click the object that you just created to create a reference to the object in the LayoutPath list in the Layout path category of the Properties panel.

Note

You cannot use a child of a PathListBox as a LayoutPath.

Tip

You can add multiple layout paths to a PathListBox.

To create a PathListBox from a path

Do one of the following:
- In the Tools panel, select the ****Pen ****tool and draw a path on the artboard.
- Add an object from the Assets panel.
Right-click the path or object, click Path, and then click Make Layout Path.

To add sample data to a PathListBox

In the Data panel, click ****Create sample data ****, and then click New Sample Data. Click OK.
Drag Collection onto the PathListBox.

Tip

You can change the way the properties of the sample data collection are rendered by editing the ItemTemplate of the PathListBox. Right-click the PathListBox, click Edit Additional Templates, then click Edit Generated Items (ItemTemplate), and then click Edit Current.

Modify the layout path

After you have added the path to the list of layout paths, you can modify the display of the items on the path in the Properties panel. You can modify the order of the items displayed, the number of items displayed, the orientation of the items on the path, and the distribution of the items along the path.

StartItemIndex and WrapItems apply to all the layout paths in the selected PathListBox. The properties in the box in the Layout Paths category are a list-details view and apply only to the path selected in the LayoutPaths list. To change the options for an individual path, select the path in the LayoutPaths list before changing the properties that you want.

To modify the StartItemIndex

In the Layout Paths category of the Properties panel, in the StartItemIndex text box, type the number of the StartItemIndex that you want to use.

Tip

The StartItemIndex identifies the first item in the list to be displayed along the path. The StartItemIndex for the first item in the list is 0, for the second item is 1, for the third item is 2, and so on. If you want the first item on the list to be displayed, leave the StartItemIndex at 0. If you want the third item in the list to appear at the beginning of the path, change the StartItemIndex to 2.

To modify the item wrapping

When StartItemIndex is greater than 0, you can enable WrapItems to make sure that all items in your collection are displayed. If you want the list to continue with the first item on the list after it reaches the end of the list, in the Layout Paths category of the Properties panel, select the WrapItems check box. If you want the list to end when it reaches the last item on the list, clear the WrapItems check box.

To modify the distribution of items along the path

In the Distribution box, choose one of the following:
- ****Even ****Distributes items evenly along the path.
- ****Padded ****Distributes items along the path based on their size and the Padding property.

To modify the capacity of the layout path

To change the number of items displayed along the layout path, change the number in the Capacity box. For example, if the capacity is 5, up to 5 items will appear on the list. A capacity of Auto represents the number of items divided by the number of paths. For example, Auto will display all items in the list for a single path. If there are two paths, the items will be divided equally between the two paths.

To modify the padding between objects

If the Distribution of the layout path is set to Padded, you can specify the padding that you want between objects on the path in the Padding box. To change the padding, click inside the Padding box, and use the UP ARROW and DOWN ARROW keys, or type a number directly in the box.

Tip

You can also click inside the field and rotate the mouse wheel to change the value.

To modify the orientation of objects on the layout path

To maintain a standard up-to-down, left-to-right orientation of objects on the path, in the Orientation list, select ****None ****. To orient the objects according to the variations on the path, in the Orientation list, select ****OrientToPath ****.

Orientation: None

Orientation: OrientToPath

To modify the starting point of the list

You can start a list anywhere along a path by using the Start option based on a percentage. For example, to start the list one-quarter of the way along the path, type 25 in the Start box.

To modify the span of the list

You can modify the span of a list along a path by using the Span option. For example, if you want the list to span 50% of the path, type 50 into the Span box.

The Span box can be used in conjunction with the Start box. For example, if you want the span of the list to be 50%, but you want the list to start halfway through the path, type 50 in the Start box, and type 50 in the Span box.

Tip

You can create interesting effects by animating the Start and Span properties of a layout path.

Tip

When you animate points of a path in a storyboard, the items of the PathListBox will automatically update their position.

To modify the fill behavior

In the FillBehavior box, choose one of the following:
- **NoOverlap **If your layout path is an open path and you want to animate the Start property, select NoOverlap from the FillBehavior drop-down list. This reduces the effective span used to lay items out along the path, allowing enough room to animate Start without the items on the path overlapping when the list items return to the beginning of the layout path.
- **FullSpan **Select FullSpan from the FillBehavior drop-down list to make sure that the entire span of the layout path is used. For example, if you have selected Even in the Distribution drop-down list and FullSpan in the FillBehavior drop-down list when working with an open path, an item will appear at the beginning and at the end of the path.

Try it: Lay out text along a path

You can lay out any user interface (UI) element along a path, and then style the element according to your needs. In the following example, a TextBlock is added to the artboard. Then, it is data-bound to the PathListBox. Next, it is styled to create more visual interest.

To lay out text along a path

On the Assets panel, click Shapes, and then click Pie. Draw a Pie shape on the artboard.
Right-click the Pie shape, click Path, and then click Make Layout Path.
On the Tools panel, click ****TextBlock ****. Draw a TextBlock on the artboard and add some text to it.
In the Objects and Timeline panel, click PathListBox. In the Common Properties category of the Properties panel, click Advanced options (next to ItemSource), and then click Data Binding.

Tip

You can locate ItemSource quickly by typing ItemSource into the Search box in the Properties panel.
In the Create Data Binding dialog box, click Element Property. In the Scene elements pane, click TextBlock.
In the Show drop-down list under the Properties pane, select All Properties.
In the Properties pane, select Text: (String). Click OK.

You can now style the text in the TextBlock to add visual interest.

An example of a PathListBox displaying a TextBlock