Carousel

Creates an empty carousel, with the arrow-key commands ready and white lighting.

Add items, then set SelectedIndex to bring one to the front.

Gets or sets the perspective camera the carousel is viewed through, to change the viewpoint, the distance or the field of view.

Move the camera nearer (a smaller Z) to make the carousel larger, raise it (a larger Y) to look down on the ring, or narrow the PerspectiveCamera.FieldOfView to flatten the perspective. CarouselViewport3DCamera, if set, takes precedence when the template is applied.

<car:Carousel.Camera>
    <PerspectiveCamera Position="0,2,5" LookDirection="0,-2,-5" UpDirection="0,1,0" FieldOfView="50" />
</car:Carousel.Camera>

Gets or sets the colour of the light the carousel's items are lit by.

The light is even and comes from everywhere, so it tints and darkens every item alike: a grey light dims the carousel, a warm one gives it a cast. It does not light the Control.Background.

Gets or sets the camera the carousel is viewed through, of any kind – for example an OrthographicCamera for a flat view without perspective.

When both this and Camera are set, this one is used when the template is applied; after that, the one set most recently is in effect. Setting either back to null leaves the camera in use unchanged.

Gets or sets how far the item at the front is brought forward, towards the viewer.

A larger value makes the front item appear larger, as it comes closer to the camera; too large and it passes the camera and disappears. To make the whole carousel larger or smaller, move the Camera instead.

Gets or sets how far the items that are not at the front are pushed back, away from the viewer.

A larger gap sets the front item further apart from the rest, so it stands out more; 0 leaves every item on the circle itself.

Gets or sets how far apart the items stand round the circle, which also sets the circle's size.

The circle's circumference is this distance times the number of items, so the ring grows as items are added. Small values overlap the items behind the front one like a fanned deck; values around the width of an item spread them out side by side.

Gets or sets whether each item is drawn with a mirror-image reflection beneath it, fading to transparent, as though standing on a glossy floor.

The carousel draws the reflection itself, so it works for any item and any item template. Reflections suit a dark Control.Background.

Changing the property rebuilds every item. If the carousel has no ItemsControl.ItemTemplate of its own, or has the template keyed CarouselControlResources.CarouselItemReflectionEnabledTemplateKey, it is given the template keyed CarouselControlResources.CarouselItemTemplateKey at the same time; a template of your own is left alone.

Gets or sets the size each item is drawn at before it is placed in 3D, which decides its shape and its sharpness.

Each item is laid out at this size, as though in a window of its own, and the picture is then put on a panel one unit tall in 3D. So the ratio of width to height is the shape of every panel, and the size itself is the resolution: larger sizes stay sharp when the item is close to the camera. How large an item appears on screen is set by the camera and the carousel's own size, not by this.

Changing it rebuilds every item.

<!-- Portrait book covers. -->
<car:Carousel ItemDimension="200,300" />

Gets or sets how far the items that are not at the front are turned away from the viewer.

The front item always faces the viewer squarely. 0 leaves every item facing forwards, so the ring looks flat; values towards 90 show the others edge-on, so they almost disappear. The carousel turns to the new angle at once.

Gets or sets the position of the item at the front of the carousel, facing the viewer.

Setting it turns the carousel to bring that item forward, over half a second, and raises SelectedIndexChanged. It binds two-way by default, so a view model sees the user's choice. A value set before the control is loaded is applied once it is; a value outside the items is ignored and the carousel does not move.

When items are removed and the index falls past the last item, it moves to the last item.

// Show the last product added.
gallery.SelectedIndex = gallery.Items.Count - 1;

Gets the number of visual children: one once the template has been applied, otherwise none.

Takes an item off the carousel when it is removed, and brings the selection back within the remaining items.

Call the base method when overriding, so the item's 3D panel is removed with it.

Finds the 3D viewport, the item container and the light in the template, and applies the camera and the light colour to them.

A custom template provides a Viewport3D named PART_CarouselViewPort, a ContainerUIElement3D inside it named PART_CarouselItemContainer, an AmbientLight named viewport3DAmbientLight, and a hidden panel with IsItemsHost="True" for the item containers. Any of them may be left out; the features that need it then do nothing.

The camera applied is CarouselViewport3DCamera if set, otherwise Camera, otherwise the carousel's own.

Turns the carousel one item for each notch of the mouse wheel, and gives it keyboard focus.

The event is marked handled only when the carousel actually moved, so at either end of the carousel the wheel goes on to scroll whatever contains it.

Sizes an item's container to ItemDimension and puts the item on the carousel.

Call the base method first when overriding, or the item does not appear.

Occurs when SelectedIndex changes, whether the user turned the carousel or code set the index.

Raised as the carousel starts turning, with the new index already in SelectedIndex. Not raised for changes made before the control is loaded. A value set outside the items still raises it, although the carousel does not move.

gallery.SelectedIndexChanged += (sender, e) =>
{
    Product product = (Product)gallery.Items[gallery.SelectedIndex];
    priceText.Text = product.Price.ToString("C");
};

Identifies the Camera dependency property.

Identifies the CarouselViewport3DAmbientLightColor dependency property.

Identifies the CarouselViewport3DCamera dependency property.

Identifies the DistanceFromCentreToUser dependency property.

Identifies the GapBetweenCurrentDisplayFrontItemAndOthers dependency property.

Identifies the GapBetweenItems dependency property.

Identifies the IsReflectionRenderingEnabled dependency property.

Identifies the ItemDimension dependency property.

Identifies the ItemRenderAngle dependency property.

The command that moves the selection to the previous item; bound to the Left arrow key.

Disabled while the first item (or no item) is selected, so a button using it greys out at the start of the carousel. Give a button the command and the carousel as its CommandTarget, or let it find the carousel through keyboard focus.

The Left arrow key works whenever the carousel has keyboard focus, which it takes when the user clicks it or turns the mouse wheel over it.

<Button Content="Previous" Command="{x:Static car:Carousel.MoveToLeft}" CommandTarget="{Binding ElementName=Gallery}" />

The command that moves the selection to the next item; bound to the Right arrow key.

Disabled while the last item is selected, so a button using it greys out at the end of the carousel. See MoveToLeft for how to use it.

Identifies the SelectedIndex dependency property.