ItemsControl Overview

Overview

Table of contents

• Drawing
• Panning
• Zooming
• Scrolling
• Scrolling, Panning and Zooming limitation
• Selecting items
• Snapping to grid
• Customize

Drawing

As the canvas is the ItemsHost of RichItemsControl, items can be drawn by adding them to the ItemsSource.

Whenever an item is added to the ItemsSource:

• if the Height and Width are set, then the item is directly drawn at the specified position(Top and Left properties);
• if the Height or Width is not set, then you can click and hold the left mouse button to draw the added item;

Note: If you add multiple items once the same behavior applies, and you can draw them one by one for those with the Height and Width not set.

Panning

Panning is done by holding the Space key and left click. The panning key which by default is 'Space' can be changed by setting the PanningKey dependency property to another Key.

Note: It can be programmatically changed by setting the Offset dependency property.

While panning, the IsPanning dependency property will be set to true and the Viewport and AppliedTransform dependency properties will be updated.

Automatic panning is also enabled by default and can be disabled by setting the DisableAutoPanning dependency property to true. The behavior is to pan the viewport when selecting or dragging a selection or drawing an element near the edges of the viewport.

The auto panning speed can be changed using the AutoPanSpeed dependency property.

Default values:

• Offset: [0, 0]
• DisableAutoPanning: false
• AutoPanSpeed: 10 pixels per tick
• AutoPanningTickRate: 1 millisecond

Zooming

Zooming is done by pressing CTRL + to zoom in or CTRL - to zoom out and mouse wheel, it can be disabled by setting the DisableZoom dependency property to true.

Note: It can be programmatically changed by setting the Scale dependency property to a value between MinScale and MaxScale.

By setting the ZoomKey dependency property the default key for zooming action is overwritten.

While zooming the Zooming routed event is raised.

Default values:

• Scale: 1
• MinScale: 0.1
• MaxScale: 2

Scrolling

Scrolling works as for the usual ScrollViewer, but the scrollbars appear only when any element has left the Viewport.

Note: Actions like Pan, Zoom or Move influences Scrolling.

It can be customized by setting ScrollFactor dependency property which tells how fast the moving of viewport and ScrollBar is done. It can be disabled by setting DisableScroll dependency property to true.

While scrolling or doing any other action that modifies the Viewport the Scrolling routed event will be raised.

Default values:

• ScrollFactor: 10

Scrolling, Panning and Zooming limitation

Scrolling, Panning and Zooming can be limited using the ExtentSize property which tells the maximum VerticalOffset and HorizontalOffset and the maximum ExtentHeight and ExtentWidth. The other property, EnableNegativeScrolling stops the scroll or the pan or the zoom if a negative value for VerticalOffset has been reached.

Note: ExtentHeight could be maximum ExtentSize.Height * 2 when scroll is in both ways for example.

Default values:

• ExtentSize: Size.Empty
• EnableNegativeScrolling: true

Selecting

Selecting items is done by holding the left mouse button and moving the mouse. When a selection operation is in progress, the IsSelecting dependency property is set to true and the SelectionRectangle dependency property is updated with each move.

Note: SelectedItems dependency property holds the currently selected items.

Default values:

• RealTimeSelectionEnabled: false

Note: See also Performance page.

Snapping

When EnableGrid and EnableSnapping are set to true after drawing or moving an element on canvas it will be snapped relative to the position of the selected item.

Default values:

• GridSpacing: 10
• EnableGrid: false
• EnableSnapping: false

Customize

You can customize different parts of the library by setting those dependency properties:

GridStyle - change the style of the background grid

Data Type: Drawing

Default value:

<GeometryDrawing x:Key="GridStyle"
                 Geometry="M0,0 L0,1 0.03,1 0.03,0.03 1,0.03 1,0 Z"
                 Brush="Red" />

SelectionRectangleStyle - change the style of selection rectangle used when Selecting

Data Type: Style

Default value:

<Style x:Key="SelectionRectangleStyle"
       TargetType="Rectangle">
        <Setter Property="Stroke"
                Value="DodgerBlue" />
        <Setter Property="StrokeThickness"
                Value="1" />
        <Setter Property="Fill">
            <Setter.Value>
                <SolidColorBrush Opacity="0.1"
                                 Color="DodgerBlue" />
            </Setter.Value>
        </Setter>
</Style>