RichCanvas Overview

Table of contents

• Drawing
• Panning
• Zooming
• Scrolling
• Selecting items
• Snapping to grid
• Customize

Drawing

RichCanvas offers a default mechanism that lets you draw items added to its ItemsSource at a desired position using the mouse.

Whenever an item is added to the ItemsSource:

• if the Top, Left, Height and Width are not set, item is drawn using dragging. Top and Left are set relative to mouse click position and its container ScaleTransform; Width and Height are set relative to the dragged distance;
• if the Top and Left are set, but Height and Width`` are not, then the item is drawn at the specified position and WidthandHeight``` set by dragging;
• if everything is set, the item is "drawn" or added at the specified position with the specified size.

Note

If you add multiple items once the same behavior applies, and you can draw them one by one.

If you move the order or remove any items in the collection the same behavior should still apply to the items in the specified order.

After drawing, DrawingEnded routed event is raised passing DrawEndedEventArgs, holding the drawn item's DataContext and mouse position where drawing finished.

Also, DrawingEndedCommand dependency property of type ICommand is invoked, sending the mouse position where drawing finished as a parameter.

Panning

Panning is done by holding the Space key and left click. The panning gesture can be changed by setting RichCanvasGestures.Pan static property.

Note

It can be programmatically changed by setting the ViewportLocation dependency property.

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

Automatic panning is also available and can be enabled by setting EnableAutoPanning 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:

• ViewportLocation: [0, 0]
• EnableAutoPanning: false
• AutoPanSpeed: 1f pixels per tick
• AutoPanningTickRate: 1f millisecond

Zooming

Zooming is done through command bindings by pressing CTRL + to zoom in or CTRL - to zoom out. To modify zoom in or zoom out command bindings gestures, set RichCanvasGestures.ZoomIn or RichCanvasGestures.ZoomOut static properties.

Zooming can also be performed holding CTRL and using mouse wheel. To modify the default CTRL key you can set RichCanvasGestures.ZoomModifierKey static property.

Zooming can be disabled by setting the DisableZoom dependency property to true.

Note

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

While zooming the Zooming routed event is raised.

Default values:

• ViewportZoom: 1d
• MinScale: 0.1d
• MaxScale: 2d
• DisableZoom: false

Scrolling

To enable scrolling, wrap the RichCanvas control inside a ScrollViewer:

<ScrollViewer CanContentScroll="True"
              VerticalScrollBarVisibility="Auto"
              HorizontalScrollBarVisibility="Auto">
    <rc:RichCanvas .../>
</ScrollViewer>

Tip

Setting VerticalScrollBarVisibility and HorizontalScrollBarVisibility to Auto will make the scrollbars visible.

Scrolling sensitivity can be adjusted by setting ScrollFactor dependency property.

Default values:

• ScrollFactor: 10d

Selecting

RichCanvas offers by default both single and multiple selection.

By default, multiple selection is enabled. This can be changed by setting CanSelectMultipleItems dependency property to false.

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.

Selected items can also be set programmatically by binding a collection to the SelectedItems dependency property.

For interaction optimization when having thousands of items, RichCanvas by default doesn't have real-time selection enabled. This means the items contained in the SelectionRectangle will only be selected after the selection operation is finished. This behavior can be changed by setting RealTimeSelectionEnabled to true. now the items will be selected and deselected while you resize the selection rectangle.

When an RichCanvasContainer is selected, its IsSelected dependency property is set to true.

Default values:

• RealTimeSelectionEnabled: false
• CanSelectMultipleItems: true

Snapping & Drawing a grid

When EnableSnapping is set to true after drawing an item or dragging a selection on canvas, items will be snapped relative to the position of the selected item, using GridSpacing dependency property.

To coordinate the snapping visually with a grid you can set the background of RichCanvas control to a DrawingBrush. Basically, you create your DrawingBrush with a GeometryDrawing as Drawing property.

<!--Define the GeometryDrawing that will be passed to the Drawing property of DrawingBrush-->
<GeometryDrawing x:Key="RectangleGridGeometry">
    <GeometryDrawing.Pen>
        <Pen Brush="DodgerBlue"
             Thickness="0.3" />
    </GeometryDrawing.Pen>
    <GeometryDrawing.Geometry>
        <RectangleGeometry Rect="0,0,10,10" />
    </GeometryDrawing.Geometry>
</GeometryDrawing>

<!--Set RichCanvas's Background to a DrawingBrush-->
<rc:RichCanvas.Background>
    <DrawingBrush TileMode="Tile"
                  ViewportUnits="Absolute"
                  Viewport="{Binding GridSpacing, ElementName=name_of_RichCanvas_control, Converter={StaticResource UIntToRectConverter}}"
                  Transform="{Binding AppliedTransform, ElementName=name_of_RichCanvas_control}"
                  Drawing="{StaticResource RectangleGridGeometry}" />
</rc:RichCanvas.Background>

Important

Very important to pass the AppliedTransform property of RichCanvas to the Transform property of DrawingBrush, as well as setting the Viewport property to GridSpacing property of RichCanvas with the exposed UIntToRectConverter.

Default values:

• GridSpacing: 10
• EnableSnapping: false

Customize

Important

Docs about new states design that RichCanvas is relying on, starting with v3.0.0, will be added.

Read v3.0.0 changelog to see added methods and start from there until docs will be updated.

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

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>