WPF › Pan And Zoom Provider › ZoomPanControl

ZoomPanControl

class.NET 6 / 8 / 10.NET Framework 4.8Binarymission.WPF.Controls.ContentControls

A custom class that provides zoom and pan features for any FrameworkElement.

public class ZoomPanControl : ContentControl

Inherits from / implements: ContentControl

Remarks

The view is held in this class as three numbers - a scale and an X and Y offset, all in device-independent pixels of the control's own coordinate space - and the transform on the content follows them. It is deliberately not the other way round: reading the scale back off a running animation gives a value half way to somewhere, and two mouse-wheel notches in quick succession then compound the half-way value instead of the value the user asked for.

Members at a glance

`ZoomPanControl`	Creates a zoom and pan control.
`AutomaticZoomOutKey`	Gets or sets the `Key` that will be enable automatic zooming out, when the user hits that specific Key. By default this key is Escape key.
`FitZoomLevel`	Gets the scale at which the whole of the content fits inside the viewport, or 1 if the size of either is not yet known.
`IsAutomaticZoomingoutByKeypressEnabled`	Gets or sets whether the user will be able to zoom out in full (if he is in zoomed in mode currently) by hitting a specified key (Escape key by default).
`IsInitialViewFitted`	Gets or sets whether the control shows the whole of its content, scaled to fit the viewport, when it is first laid out and whenever its content is replaced.
`IsPanningEnabled`	Gets or sets as to whether the control should support pan as well as zoom or just zoom.
`ZoomInKeyboardKey`	Gets or sets the Keyboard key to perform "Zoom In" function.
`ZoomLevel`	Gets or sets the scale currently applied to the content, where 1 is 1:1.
`ZoomMaximumDepth`	Gets or sets the maximum zoom you would want the Zooming service to support.
`ZoomMinimumDepth`	Gets or sets the minimum zoom you would want the Zooming service to support.
`ZoomOutKeyboardKey`	Gets or sets the Keyboard key to perform "Zoom In" function.
`ZoomStep`	Gets or sets the zoom factor for zooming the serviced target object - i.e. the Content.
`OnApplyTemplate`	Called once the control template has been applied, which is where the named parts of the template first become reachable.
`OnContentChanged`	Called when the content is replaced, so that the new content gets the transform and the opening view rather than inheriting the view the previous content was left in.
`ResetView`	Returns the view to the state the control opens in - the fitted view, or 1:1 if `IsInitialViewFitted` is false .
`ZoomToFit`	Scales the content so that all of it is visible, and centres it in the viewport.
`AutomaticZoomOutKeyProperty`	Identifies the `AutomaticZoomOutKey` dependency property.
`IsAutomaticZoomingoutByKeypressEnabledProperty`	Identifies the `IsAutomaticZoomingoutByKeypressEnabled` dependency property.
`IsInitialViewFittedProperty`	Identifies the `IsInitialViewFitted` dependency property.
`IsPanningEnabledProperty`	Identifies the `IsPanningEnabled` dependency property.
`ZoomInKeyboardKeyProperty`	Identifies the `ZoomInKeyboardKey` dependency property.
`ZoomMaximumDepthProperty`	Identifies the `ZoomMaximumDepth` dependency property.
`ZoomMinimumDepthProperty`	Identifies the `ZoomMinimumDepth` dependency property.
`ZoomOutKeyboardKeyProperty`	Identifies the `ZoomOutKeyboardKey` dependency property.
`ZoomStepProperty`	Identifies the `ZoomStep` dependency property.

Constructors

ZoomPanControl

public ZoomPanControl()

Creates a zoom and pan control.

Properties

AutomaticZoomOutKey

public Key AutomaticZoomOutKey

Gets or sets the Key that will be enable automatic zooming out, when the user hits that specific Key. By default this key is Escape key.

FitZoomLevel

public double FitZoomLevel

Gets the scale at which the whole of the content fits inside the viewport, or 1 if the size of either is not yet known.

This is the number a "reset" or "fit" button in a host application should show and use; ZoomToFit applies it. The control's own zoom-out key uses it too, so that the key and the button cannot disagree.

IsAutomaticZoomingoutByKeypressEnabled

public bool IsAutomaticZoomingoutByKeypressEnabled

Gets or sets whether the user will be able to zoom out in full (if he is in zoomed in mode currently) by hitting a specified key (Escape key by default).

IsInitialViewFitted

public bool IsInitialViewFitted

Gets or sets whether the control shows the whole of its content, scaled to fit the viewport, when it is first laid out and whenever its content is replaced.

A zoom control that opens at 1:1 on content larger than its viewport shows the user a sharp, complete-looking picture with no visible reason to touch it. Opening on the whole sheet - readable structure, unreadable detail - makes zooming in the obvious next move. Set this to false to open at 1:1 instead.

IsPanningEnabled

public bool IsPanningEnabled

Gets or sets as to whether the control should support pan as well as zoom or just zoom.

By default, panning is enabled.

ZoomInKeyboardKey

public Key ZoomInKeyboardKey

Gets or sets the Keyboard key to perform "Zoom In" function.

By default, this is set to Up (Arrow Up) key.

ZoomLevel

public double ZoomLevel

Gets or sets the scale currently applied to the content, where 1 is 1:1.

Setting this zooms about the centre of the viewport, which is what a zoom box or a zoom slider in a host application wants. The value is clamped to ZoomMinimumDepth and ZoomMaximumDepth.

ZoomMaximumDepth

public double ZoomMaximumDepth

Gets or sets the maximum zoom you would want the Zooming service to support.

ZoomMinimumDepth

public double ZoomMinimumDepth

Gets or sets the minimum zoom you would want the Zooming service to support.

Values at or below zero are treated as 0.01, because a scale of zero cannot be inverted and a negative scale mirrors the content.

ZoomOutKeyboardKey

public Key ZoomOutKeyboardKey

Gets or sets the Keyboard key to perform "Zoom In" function.

By default, this is set to Down (Arrow Down) key.

ZoomStep

public double ZoomStep

Gets or sets the zoom factor for zooming the serviced target object - i.e. the Content.

This factor will determine how much of zoom to apply for every mouse wheel move unit of zoom attempt by the user. It is read two ways, because both readings are natural and only one of them can be right for a given value. A value greater than 1 is a multiplier: 1.4 magnifies by 40% per wheel notch. A value of 1 or less is a fraction: 0.15 also magnifies, by 15% per notch. Taking a value below 1 literally as a multiplier would shrink the content when the user scrolls up and magnify it when they scroll down, which is not a setting anybody chooses deliberately.

Methods

OnApplyTemplate

public override void OnApplyTemplate()

Called once the control template has been applied, which is where the named parts of the template first become reachable.

OnContentChanged

protected override void OnContentChanged(object oldContent, object newContent)

Called when the content is replaced, so that the new content gets the transform and the opening view rather than inheriting the view the previous content was left in.

oldContent: The content being replaced.
newContent: The content replacing it.

ResetView

public void ResetView()

Returns the view to the state the control opens in - the fitted view, or 1:1 if IsInitialViewFitted is false .

ZoomToFit

public void ZoomToFit()

Scales the content so that all of it is visible, and centres it in the viewport.

Fields

AutomaticZoomOutKeyProperty

public static readonly DependencyProperty AutomaticZoomOutKeyProperty

Identifies the AutomaticZoomOutKey dependency property.

IsAutomaticZoomingoutByKeypressEnabledProperty

public static readonly DependencyProperty IsAutomaticZoomingoutByKeypressEnabledProperty

Identifies the IsAutomaticZoomingoutByKeypressEnabled dependency property.

IsInitialViewFittedProperty

public static readonly DependencyProperty IsInitialViewFittedProperty

Identifies the IsInitialViewFitted dependency property.

IsPanningEnabledProperty

public static readonly DependencyProperty IsPanningEnabledProperty

Identifies the IsPanningEnabled dependency property.

ZoomInKeyboardKeyProperty

public static readonly DependencyProperty ZoomInKeyboardKeyProperty

Identifies the ZoomInKeyboardKey dependency property.

ZoomMaximumDepthProperty

public static readonly DependencyProperty ZoomMaximumDepthProperty

Identifies the ZoomMaximumDepth dependency property.

ZoomMinimumDepthProperty

public static readonly DependencyProperty ZoomMinimumDepthProperty

Identifies the ZoomMinimumDepth dependency property.

ZoomOutKeyboardKeyProperty

public static readonly DependencyProperty ZoomOutKeyboardKeyProperty

Identifies the ZoomOutKeyboardKey dependency property.

ZoomStepProperty

public static readonly DependencyProperty ZoomStepProperty

Identifies the ZoomStep dependency property.