In This Article

View Manipulation

The ZoomContentControl offers numerous way to manipulate the view, both interactively and programmatically. This topic covers these aspects of the control.

Screenshot

Zooming

The content displayed by the ZoomContentControl will be scaled by ZoomLevel, along both the X and Y axes. There are several ways to interactively and programmatically adjust the zoom level.

Minimum/Maximum Zoom Level

The ZoomLevel is restricted to the range defined by the MinZoomLevel and MaxZoomLevel properties. Both of these properties must be greater than zero, and the MaxZoomLevel must be larger than or equal to the MinZoomLevel.

If the zoom level is set to the value outside of this range, it will be coerced to fall within the range.

Zoom Level Stops

The ZoomLevelStops property is used by several of the helper methods listed below to incrementally increase or decrease ZoomLevel. When specified, the ZoomLevel will be incremented or decremented to the next stop value. This allows the zoom in and out commands/methods to follow a predefined set of zoom levels (e.g., 10%, 25%, 33%, 50%, 75%, 100%, 200%, 300%, etc.).

Note

If an appropriate stop value cannot be found, then the minimum or maximum zoom level will be used, based on whether the user is zooming in or out.

By default, this property is set to null which indicates that the ZoomStep (described below) should be used.

Zoom Step

As an alternative to the zoom level stops, the ZoomStep property can provide a fixed value that derives exponential zoom level stop power increments.

If one or more zoom level stops are specified in the ZoomLevelStops collection, then the ZoomStep property is not used.

Helper Methods

There are several methods that can be used to adjust the zoom level, which include:

Member Description

CenterAndZoomInToPoint Method

Centers the view to the specified point and zooms the content in using ZoomLevelStops or ZoomStep.

If no point is specified, then the view will be centered to the current mouse position.

CenterAndZoomOutFromPoint Method

Centers the view to the specified point and zooms the content out using ZoomLevelStops or ZoomStep.

If no point is specified, then the view will be centered to the current mouse position.

ResetView Method

Resets the view to the DefaultZoomLevel and DefaultCenterPoint.

StartZoomDrag Method

Starts a zoom-drag operation, where the user can zoom-in by moving the mouse up and zoom-out by moving the mouse down.

The left, right, or middle mouse button must be pressed when this method is called. Once the operation is started, the end-user can zoom the content until the mouse button is released.

StartZoomIn Method

Starts a zoom-in operation, where the user can continuously zoom-in by holding the mouse button down.

The left, right, or middle mouse button must be pressed when this method is called. Once the operation is started, the end-user can continuously zoom-in the content until the mouse button is released.

StartZoomOut Method

Starts a zoom-out operation, where the user can continuously zoom-out by holding the mouse button down.

The left, right, or middle mouse button must be pressed when this method is called. Once the operation is started, the end-user can continuously zoom-out the content until the mouse button is released.

StartZoomToRegion Method

Starts a zoom-to-region operation, where the user can draw a rectangle over the content to indicate the desired region.

The left, right, or middle mouse button must be pressed when this method is called. Once the operation is started, the end-user can draw a rectangle over the content until the mouse button is released.

ZoomIn Method

Zooms the content in using ZoomLevelStops or ZoomIn.

ZoomInToPoint Method

Zooms the content in using ZoomLevelStops or ZoomStep with the specific point as an anchor.

If no point is specified, then the current mouse position will be used.

ZoomOut Method

Zooms the content out using ZoomLevelStops or ZoomStep.

ZoomOutFromPoint Method

Zooms the content out using ZoomLevelStops or ZoomStep with the specific point as an anchor.

If no point is specified, then the current mouse position will be used.

ZoomToFit Method

Zooms the content so that it fits with-in the bounds of the control and centers the view.

Various overloads can be used to zoom-to-fit horizontally and/or vertically, and optionally center the view.

Panning

The content displayed by the ZoomContentControl can be scrolled (or panned) in any direction. There are several ways to interactively and programmatically adjust the pan offsets.

Center Point

The CenterPoint property is used to track the current pan offsets. The center point is relative the content, not the ZoomContentControl control. Therefore, a point of 0,0 would indicate that the top-left corner of the content should be centered in the view.

The size of the content can be obtained from the ChildSize property. If the center point falls outside of this range, it will be coerced to fall within the range.

The resolved coerced value (that is the current true center point) is available from the CenterPointResolved property.

Horizontal/Vertical Steps

The HorizontalScrollLineStep, HorizontalScrollPageStep, VerticalScrollLineStep, and VerticalScrollPageStep properties are used by several of the helper methods listed below to incrementally increase or decrease the X or Y values of the CenterPoint.

These steps values are specified using a Unit, which can represent a fixed number of pixels or a percentage of the visible area. For example, a value of Unit.Percentage(100) would scroll the view one full page either horizontally or vertically, assuming the content is large enough to allow scrolling.

Helper Methods

There are several methods that can be used to adjust the zoom level, which include:

Member Description

CenterAndZoomInToPoint Method

Centers the view to the specified point and zooms the content in by the ZoomStep value.

If no point is specified, then the view will be centered to the current mouse position.

CenterAndZoomOutFromPoint Method

Centers the view to the specified point and zooms the content out by the ZoomStep value.

If no point is specified, then the view will be centered to the current mouse position.

CenterToPoint Method

Centers the view to the specified point.

If no point is specified, then the view will be centered to the current mouse position.

CenterView Method

Centers the content in the view horizontally and/or vertically.

LineDown Method

Scrolls the content down by VerticalScrollLineStep, with an optional factor (which is multipled by the step value).

LineLeft Method

Scrolls the content left by HorizontalScrollLineStep, with an optional factor (which is multipled by the step value).

LineRight Method

Scrolls the content right by HorizontalScrollLineStep, with an optional factor (which is multipled by the step value).

LineUp Method

Scrolls the content up by VerticalScrollLineStep, with an optional factor (which is multipled by the step value).

PageDown Method

Scrolls the content down by VerticalScrollPageStep, with an optional factor (which is multipled by the step value).

PageLeft Method

Scrolls the content left by HorizontalScrollPageStep, with an optional factor (which is multipled by the step value).

PageRight Method

Scrolls the content right by HorizontalScrollPageStep, with an optional factor (which is multipled by the step value).

PageUp Method

Scrolls the content up by VerticalScrollPageStep, with an optional factor (which is multipled by the step value).

Pan Method

Pans the view by the specified x and y offsets.

ResetView Method

Resets the view to the DefaultZoomLevel and DefaultCenterPoint.

StartPanDrag Method

Starts a pan-drag operation, where the user can move the content along with the mouse.

The left, right, or middle mouse button must be pressed when this method is called. Once the operation is started, the end-user can pan the content until the mouse button is released.

Virtual Space

When the content can be fully displayed (either horizontally, vertically, or both) in the ZoomContentControl then it is centered, and the view cannot be panned. Additionally, the content must always be aligned to the edges of the view. For example, the left edge of the content cannot be scrolled to the right of the left edge of the view.

By setting IsVirtualSpaceEnabled to true, then any part of the content can be centered into the view. This setting adds "virtual space" around the control to allow, which increases the scrollable area.

Mouse Behavior

The mouse behavior of the ZoomContentControl can be customized by updating the InputBindings collection.

See the Input Bindings topic for more information.

Supported Commands

The commands supported by the ZoomContentControl are defined by the ZoomContentControlCommands static class.

Note

Several of the commands in ZoomContentControlCommands return a command that is defined elsewhere. For example, the LineDown command returns the command defined by ScrollBar.LineDownCommand. This makes it easier to find the supported commands.

The following table describes the various commands:

Member Description

CenterAndZoomInToPoint Property

Centers the view to the point specified as the command parameter and zooms the content in using ZoomLevelStops or ZoomStep.

If no point is specified, then the view will be centered to the current mouse position.

CenterAndZoomOutFromPoint Property

Centers the view to the point specified as the command parameter and zooms the content out using ZoomLevelStops or ZoomStep.

If no point is specified, then the view will be centered to the current mouse position.

CenterToPoint Property

Centers the view to the point specified as the command parameter.

If no point is specified, then the view will be centered to the current mouse position.

LineDown Property

Scrolls the content down by VerticalScrollLineStep, with an optional factor (which is multipled by the step value) specified as the command parameter.

LineLeft Property

Scrolls the content left by HorizontalScrollLineStep, with an optional factor (which is multipled by the step value) specified as the command parameter.

LineRight Property

Scrolls the content right by HorizontalScrollLineStep, with an optional factor (which is multipled by the step value) specified as the command parameter.

LineUp Property

Scrolls the content up by VerticalScrollLineStep, with an optional factor (which is multipled by the step value) specified as the command parameter.

PageDown Property

Scrolls the content down by VerticalScrollPageStep, with an optional factor (which is multipled by the step value) specified as the command parameter.

PageLeft Property

Scrolls the content left by HorizontalScrollPageStep, with an optional factor (which is multipled by the step value) specified as the command parameter.

PageRight Property

Scrolls the content right by HorizontalScrollPageStep, with an optional factor (which is multipled by the step value) specified as the command parameter.

PageUp Property

Scrolls the content up by VerticalScrollPageStep, with an optional factor (which is multipled by the step value) specified as the command parameter.

ResetView Property

Resets the view to the DefaultZoomLevel and DefaultCenterPoint.

StartPanDrag Property

Starts a pan-drag operation, where the user can move the content along with the mouse.

The left, right, or middle mouse button must be pressed when this method is called. Once the operation is started, the end-user can pan the content until the mouse button is released.

StartZoomDrag Property

Starts a zoom-drag operation, where the user can zoom-in by moving the mouse up and zoom-out by moving the mouse down.

The left, right, or middle mouse button must be pressed when this method is called. Once the operation is started, the end-user can zoom the content until the mouse button is released.

StartZoomIn Property

Starts a zoom-in operation, where the user can continuously zoom-in by holding the mouse button down.

The left, right, or middle mouse button must be pressed when this method is called. Once the operation is started, the end-user can continuously zoom-in the content until the mouse button is released.

StartZoomOut Property

Starts a zoom-out operation, where the user can continuously zoom-out by holding the mouse button down.

The left, right, or middle mouse button must be pressed when this method is called. Once the operation is started, the end-user can continuously zoom-out the content until the mouse button is released.

StartZoomToRegion Property

Starts a zoom-to-region operation, where the user can draw a rectangle over the content to indicate the desired region.

The left, right, or middle mouse button must be pressed when this method is called. Once the operation is started, the end-user can draw a rectangle over the content until the mouse button is released.

ZoomIn Property

Zooms the content in using ZoomLevelStops or ZoomIn.

ZoomInToPoint Property

Zooms the content in using ZoomLevelStops or ZoomStep with the point specified as the command parameter as an anchor.

If no point is specified, then the current mouse position will be used.

ZoomOut Property

Zooms the content out using ZoomLevelStops or ZoomStep.

ZoomOutFromPoint Property

Zooms the content out using ZoomLevelStops or ZoomStep with the point specified as the command parameter as an anchor.

If no point is specified, then the current mouse position will be used.

ZoomToFit Property

Zooms the content so that it fits with-in the bounds of the control and centers the view.

An Orientation can be passed as the command parameter to only zoom-to-fit horizontally or vertically.

Scroll Bars

The ZoomContentControl includes a ScrollViewer in the default control template. The visibility of associated scrollbars can be customized using the HorizontalScrollBarVisibility and/or VerticalScrollBarVisibility properties.

Tip

If HorizontalScrollBarVisibility or VerticalScrollBarVisibility is set to ScrollBarVisibility.Auto then the view will "shift" when the scrollbars are shown or hidden (as the viewport size will shrink or grow, respectively).

Batch Updates

By default, the ZoomContentControl will immediately update the display when the zoom level or the center point is changed. Changes can be batched together, so that only a single update is made to the display. To batch changes into a single update, the changes must be wrapped by calls to BeginUpdate and EndUpdate.

The EndUpdate includes an overload that can be used to prevent the changes from being animated.

Animations

ZoomContentControl supports smooth animations when zooming and panning. The duration of the animations are control by the ZoomAnimationDuration and PanAnimationDuration properties, respectively.