←Select platform

Zoom Method (ImageViewer)

Summary

Zooms or changes the size mode of the view.

Syntax

C++

public virtual void Zoom( 
   ControlSizeMode sizeMode, 
   double zoomValue, 
   LeadPoint origin 
)

Public Overridable Sub Zoom( 
   ByVal sizeMode As ControlSizeMode, 
   ByVal zoomValue As Double, 
   ByVal origin As LeadPoint 
)

public:  
   virtual void Zoom( 
      ControlSizeMode^ sizeMode, 
      double zoomValue, 
      LeadPoint^ origin 
   )

Parameters

sizeMode

The size mode to use.

zoomValue

The desired zoom value. This must be a value greater than 0. A value of 1.0 equals 100 percent zoom, a value of 0.5 equals to 50 percent, a value of 1.5 equals 150 percent zoom and so on.

The value must be greater than or equal to the current MinimumScaleFactor value and less than or equal to the current MaximumScaleFactor value.

origin

The origin of the zoom operation.

Remarks

The "view" size is calculated by UpdateTransform and stored in ViewSize. It is controlled by the current ViewLayout as follows:

View layout	Description
ImageViewerSingleViewLayout	The view size is the size of the current ActiveItem, a fit page operation will fit the active item inside the viewer, a fit width operation will fit the width of the active item inside the viewer and so on.
ImageViewerVerticalViewLayout	The view size is dependant on the value of Columns, for example, if the column count is 0, then the view layout will try to fit as much items in the viewer horizontally as possible before moving to the next row. If the column count is any other number, then the view will fill the columns with that exact number of items before moving to the next row. The width of the view is maximum total width of the items in any column, the height of the view is the total height of all the rows.
ImageViewerHorizontalViewLayout	The view size is dependant on the value of Rows, for example, if the row count is 0, then the view layout will try to fit as much items in the viewer vertically as possible before moving to the next row. If the column count is any other number, then the view will fill the rows with that exact number of items before moving to the next column. The height of the view is maximum total height of the items in any row, the width of the view is the total width of all the columns.

The following factors affect the current zoom value of the view:

The size mode (SizeMode), (whether it is none, fit, fit width, fit height or stretch).
The current scale factor (ScaleFactor). A value of 1 means no scaling 100 percent), a value of 0.5 means 50 percent, 1.5 means 150 percent, 2 means 200 percent and so forth
The aspect ratio correction (AspectRatioCorrection). Use this value to manually stretch the view vertically.

A combination of the above will result in an actual x and y zoom value (they will be different if the size mode is ControlSizeMode.Stretch for example). These values can always be obtained by reading the value of the read-only XScaleFactor and YScaleFactor. If stretch size mode is not used in your application, then Use ScaleFactor which is a helper property that returns the maximum of x, y scale factors (which are equal in all cases but stretch).

For example, to fit the view in the current viewer area, use the following: sizeMode = ControlSizeMode.Fit and zoomValue = 1. The viewer might zoom the view out to make it fit if the size is greater than the control size. Hence, the actual scale factor (will be stored in ScaleFactor after the method returns ) is not 1, but a value less than 1. Since the viewer has to zoom the total image out.

Examples:

To zoom the viewer in and out, obtain the current scale factor and multiply it by the increment or decrement value. For example, to zoom the viewer in by 200% (makes it twice as big), use:

// Multiply the current scale factor by two 
viewer.Zoom(ControlSizeMode.None, viewer.ScaleFactor * 2.0, viewer.DefaultZoomOrigin);

The following zooms the viewer out by 50% (makes it half as big)

// Multiply the current scale factor by half 
viewer.Zoom(ControlSizeMode.None, viewer.ScaleFactor * 0.5, viewer.DefaultZoomOrigin);

To zoom the viewer in by 50% (makes it one and half times bigger), use:

// Multiply the current scale factor by one and a half 
viewer.Zoom(ControlSizeMode.None, viewer.ScaleFactor * 1.5, viewer.DefaultZoomOrigin);

And to zoom the viewer out by 25% (make it quarter of the size)

// Multiply the current scale factor by quarter 
viewer.Zoom(ControlSizeMode.None, viewer.ScaleFactor * 0.25, viewer.DefaultZoomOrigin);

You can also use a different size mode. For example, to fit the whole view into the current viewer use:

viewer.Zoom(ControlSizeMode.Fit, 1.0, viewer.DefaultZoomOrigin);

As you can see, we passed 1.0 (or 100%) as the scale factor because the viewer will calculate the actual scaling values needed to perform "Fit". Similarly the following will fit the view width to take the whole viewer horizontal space while maintaining the aspect ratio:

viewer.Zoom(ControlSizeMode.FitWidth, 1.0, viewer.DefaultZoomOrigin);

All the ControlSizeMode's support fitting to the desired size and then applying a zoom, so:

viewer.Zoom(ControlSizeMode.Fit, 2.0, viewer.DefaultZoomOrigin);

Will fit the view into the available viewer space and then zooms it by 2.

All the size modes listed above maintain the aspect ratio of the view. And hence, the values of XScaleFactor and YScaleFactor will be the same. However, when you want to fit the view into the control area extending to fill each direction, you use:

viewer.Zoom(ControlSizeMode.Stretch, 1.0, viewer.DefaultZoomOrigin);

And this will almost always result in different values for XScaleFactor and YScaleFactor.

zoomValue must be a value between MinimumScaleFactor and MaximumScaleFactor. The default values can be changed to support smaller or larger legal scale factor values. However, since Zoom is called by other parts of the framework (for example, the ImageViewerPanZoomInteractiveMode), a default cut-off value is needed so the viewer does not zoom outside user-controlled values. Passing a zoomValue value outside the minimum and maximum range will have no affect and will be ignored.

Anytime you change ScaleFactor or SizeMode by calling Zoom, the control will re-calculate the transformation matrices and view layout required to place and render the view and items as requested on the viewer by internally calling UpdateTransform. The view transformation matrix will be stored in ViewTransform while the matrices for the items and their images can be updated using GetItemTransform or GetItemImageTransform.

The value of sizeMode will be stored in by the viewer internally (in SizeMode) and the viewer will automatically re-calculates the desired view size when the size of the viewer changes.

Generally, you might use the ImageViewer control to display images in two ways:

An application that sets the size mode to a value and leave it, such as ControlSizeMode.None, ControlSizeMode.Fit or ControlSizeMode.Stretch. An example of this would be an application that displays thumbnails or a static image. In other words, the application will not have zoom in/out functionality for the viewer.
An application that requires zooming as well as optionally changing the size mode. An example of this would be a document viewer application.

For the first types of applications, call Zoom once with the desired size mode and a zoom value of 1.0. The size mode is stored by the viewer and will be applied whenever the viewer control size changes. For the second type of applications, call Zoom as many times as desired with the necessary information. These application typically has a zoom in/out button as well as optionally a way to set the size mode. As well as taking care of the update issue, the Zoom method also allows you to specify the zoom operation origin. The DefaultZoomOrigin can be used for most cases. This is defined by the values of ViewHorizontalAlignment and ViewVerticalAlignment. For example, when ViewHorizontalAlignment is ControlAlignment.Near, the X value of the zoom origin is the left edge of the view. With ControlAlignment.Center it is at the center of the view width. Finally with ControlAlignment.Near it is at the right edge of the view. The zoom origin works similarly with ViewVerticalAlignment and using the view top, middle and bottom edges. The ImageViewerPanZoomInteractiveMode and ImageViewerZoomAtInteractiveMode modes use this method to perform their actions. For more information refer to Image Viewer Appearance, Image Viewer Transformation, Image Viewer Bounds and Transform, Image Viewer Layouts and Image Viewer Rendering.

Example

This example will implement a zoom operation similar to popular document viewers such as Adobe Acrobat Reader.

using Leadtools; 
using Leadtools.Controls; 
using Leadtools.Codecs; 
using Leadtools.Drawing; 
using LeadtoolsExamples.Common; 
using Leadtools.ImageProcessing; 
using Leadtools.ImageProcessing.Color; 
 
public void ImageViewerZoom_Example() 
{ 
   // Create the form that holds the ImageViewer 
   new MyForm2().ShowDialog(); 
} 
 
class MyForm2 : Form 
{ 
   public MyForm2() 
   { 
      this.Size = new Size(800, 800); 
   } 
 
   // LEADTOOLS ImageViewer to be used with this example 
   private ImageViewer _imageViewer; 
   // Ratio to use when the user zooms in or out. Change this if another value is needed, 
   // for example, 2.0 will zoom the viewer in by 200% and out by 50% each time 
   private const double _zoomRatio = 1.2; 
 
   protected override void OnLoad(EventArgs e) 
   { 
      // Create a panel to the top 
      var panel = new Panel(); 
      panel.Dock = DockStyle.Top; 
      panel.BorderStyle = BorderStyle.FixedSingle; 
      this.Controls.Add(panel); 
 
      // Add a combo box for the zoom values 
      var zoomComboBox = new ComboBox(); 
      zoomComboBox.Name = "zoomComboBox"; 
      zoomComboBox.Location = new Point(8, 8); 
      zoomComboBox.DropDownStyle = ComboBoxStyle.DropDown; 
 
      // Add default zoom values 
      zoomComboBox.Items.AddRange(new string[] 
      { 
         "10%", "25%", "50%", "75%", "100%", "125%", "200%", "400%", "800%", 
         "1600%", "2400%", "3200%", "6400%", "Actual Size", "Fit Page", "Fit Width", "Fit Height" 
      }); 
      panel.Controls.Add(zoomComboBox); 
 
      // Add zoom in and out buttons 
      var zoomInButton = new Button(); 
      zoomInButton.Text = "+"; 
      zoomInButton.Location = new Point(zoomComboBox.Right + 8, zoomComboBox.Top - 1); 
      panel.Controls.Add(zoomInButton); 
      var zoomOutButton = new Button(); 
      zoomOutButton.Text = "-"; 
      zoomOutButton.Location = new Point(zoomInButton.Right + 2, zoomComboBox.Top - 1); 
      panel.Controls.Add(zoomOutButton); 
 
      // Create the image viewer taking the rest of the form 
      _imageViewer = new ImageViewer(); 
      _imageViewer.Dock = DockStyle.Fill; 
      _imageViewer.ViewBorderThickness = 1; 
      this.Controls.Add(_imageViewer); 
      _imageViewer.BringToFront(); 
 
      // Set UseDpi to true to view the image at its original resolution 
      _imageViewer.UseDpi = true; 
 
      // Add Pan/Zoom interactive mode 
      // Click and drag to pan, CTRL-Click and drag to zoom in and out 
      _imageViewer.DefaultInteractiveMode = new ImageViewerPanZoomInteractiveMode(); 
 
      // Initialize the zoom system 
      InitZoom(zoomComboBox, zoomInButton, zoomOutButton); 
 
      // Load an image 
      using (var codecs = new RasterCodecs()) 
         _imageViewer.Image = codecs.Load(Path.Combine(ImagesPath.Path, "Ocr1.tif")); 
 
      base.OnLoad(e); 
   } 
 
   private void UpdateZoomValueFromView() 
   { 
      // Get the current scale factor from the viewer and set it in the zoom combo box 
      var percentage = _imageViewer.ScaleFactor * 100.0; 
      var zoomComboBox = this.Controls.Find("zoomComboBox", true)[0] as ComboBox; 
      zoomComboBox.Text = percentage.ToString("F1") + "%"; 
   } 
 
   private void InitZoom(ComboBox zoomComboBox, Button zoomInButton, Button zoomOutButton) 
   { 
      // Add support for user typing the zoom value in the combo box directly 
      zoomComboBox.LostFocus += (sender, e) => 
      { 
         // When the user moves away from the combo box, make sure it has a valid value 
         UpdateZoomValueFromView(); 
      }; 
 
      zoomComboBox.KeyPress += (sender, e) => 
      { 
         // Check if the finished editing by pressing Enter 
         if (e.KeyChar == (char)Keys.Return) 
         { 
            // Yes, get the new value 
            var value = zoomComboBox.Text.Trim(); 
            if (!string.IsNullOrEmpty(value)) 
            { 
               // Remove the % sign if present 
               if (value.EndsWith("%")) 
                  value = value.Remove(value.Length - 1, 1).Trim(); 
 
               // Try to parse the new zoom value 
               double percentage; 
               if (double.TryParse(value, out percentage)) 
               { 
                  // Valid value, zoom the viewer 
                  _imageViewer.Zoom(ControlSizeMode.None, percentage / 100.0, _imageViewer.DefaultZoomOrigin); 
               } 
 
               // And update the combo box from this value (in case we set a value not in the min/max range) 
               UpdateZoomValueFromView(); 
            } 
         } 
      }; 
 
      zoomComboBox.SelectedIndexChanged += (sender, e) => 
      { 
         // Get the value from the combo box 
         var value = zoomComboBox.Text.Trim(); 
         switch (value) 
         { 
            case "Actual Size": 
               _imageViewer.Zoom(ControlSizeMode.ActualSize, 1, _imageViewer.DefaultZoomOrigin); 
               break; 
 
            case "Fit Page": 
               _imageViewer.Zoom(ControlSizeMode.FitAlways, 1, _imageViewer.DefaultZoomOrigin); 
               break; 
 
            case "Fit Width": 
               _imageViewer.Zoom(ControlSizeMode.FitWidth, 1, _imageViewer.DefaultZoomOrigin); 
               break; 
 
            case "Fit Height": 
               _imageViewer.Zoom(ControlSizeMode.FitHeight, 1, _imageViewer.DefaultZoomOrigin); 
               break; 
 
            default: 
               if (!string.IsNullOrEmpty(value)) 
               { 
                  // A percentage, use it 
                  var percentage = double.Parse(value.Substring(0, value.Length - 1)); 
                  _imageViewer.Zoom(ControlSizeMode.None, percentage / 100.0, _imageViewer.DefaultZoomOrigin); 
               } 
               break; 
         } 
      }; 
 
      // For zoom in button, use current ScaleFactor multiplied by the ratio 
      zoomInButton.Click += (sender, e) => 
      { 
         _imageViewer.Zoom(ControlSizeMode.None, _imageViewer.ScaleFactor * _zoomRatio, _imageViewer.DefaultZoomOrigin); 
      }; 
 
      // For zoom out button, use current ScaleFactor divided by the ratio 
      zoomOutButton.Click += (sender, e) => 
      { 
         _imageViewer.Zoom(ControlSizeMode.None, _imageViewer.ScaleFactor / _zoomRatio, _imageViewer.DefaultZoomOrigin); 
      }; 
 
      // Also update the value from the viewer when the transform changed, this happens if the user selects a fit mode, 
      // such as fit width or fit page. The viewer will change the scale factor accordingly and we need to update it 
      // in our combo box 
      // This also takes care of Pan/Zoom interactive mode updating the scale fatcor 
      _imageViewer.TransformChanged += (sender, e) => 
      { 
         UpdateZoomValueFromView(); 
      }; 
 
      // Get the value from the viewer into the combo box 
      UpdateZoomValueFromView(); 
   } 
}

Imports Leadtools 
Imports Leadtools.Controls 
Imports Leadtools.Codecs 
Imports Leadtools.Drawing 
Imports Leadtools.ImageProcessing 
Imports Leadtools.ImageProcessing.Color 
Imports LeadtoolsControlsExamples.LeadtoolsExamples.Common 
 
<TestMethod> 
Public Sub ImageViewerZoom_Example() 
   ' Create the form that holds the ImageViewer 
   CType(New MyForm2(), MyForm2).ShowDialog() 
End Sub 
 
Private Class MyForm2 : Inherits Form 
   Public Sub New() 
      Me.Size = New Size(800, 800) 
   End Sub 
 
   ' LEADTOOLS ImageViewer to be used with this example 
   Private _imageViewer As ImageViewer 
   ' Ratio to use when the user zooms in or out. Change this if another value is needed, 
   ' for example, 2.0 will zoom the viewer in by 200% and out by 50% each time 
   Private Const _zoomRatio As Double = 1.2 
 
   Protected Overrides Sub OnLoad(ByVal e As EventArgs) 
      ' Create a panel to the top 
      Dim panel As New Panel() 
      panel.Dock = DockStyle.Top 
      panel.BorderStyle = BorderStyle.FixedSingle 
      Me.Controls.Add(panel) 
 
      ' Add a combo box for the zoom values 
      Dim zoomComboBox As New ComboBox() 
      zoomComboBox.Name = "zoomComboBox" 
      zoomComboBox.Location = New Point(8, 8) 
      zoomComboBox.DropDownStyle = ComboBoxStyle.DropDown 
 
      ' Add default zoom values 
      zoomComboBox.Items.AddRange(New String() {"10%", "25%", "50%", "75%", "100%", "125%", 
                                                "200%", "400%", "800%", "1600%", "2400%", 
                                                "3200%", "6400%", "Actual Size", "Fit Page", "Fit Width", "Fit Height"}) 
      panel.Controls.Add(zoomComboBox) 
 
      ' Add zoom in and out buttons 
      Dim zoomInButton As New Button() 
      zoomInButton.Text = "+" 
      zoomInButton.Location = New Point(zoomComboBox.Right + 8, zoomComboBox.Top - 1) 
      panel.Controls.Add(zoomInButton) 
      Dim zoomOutButton As New Button() 
      zoomOutButton.Text = "-" 
      zoomOutButton.Location = New Point(zoomInButton.Right + 2, zoomComboBox.Top - 1) 
      panel.Controls.Add(zoomOutButton) 
 
      ' Create the image viewer taking the rest of the form 
      _imageViewer = New ImageViewer() 
      _imageViewer.Dock = DockStyle.Fill 
      _imageViewer.ViewBorderThickness = 1 
      Me.Controls.Add(_imageViewer) 
      _imageViewer.BringToFront() 
 
      ' Set UseDpi to true to view the image at its original resolution 
      _imageViewer.UseDpi = True 
 
      ' Add Pan/Zoom interactive mode 
      ' Click and drag to pan, CTRL-Click and drag to zoom in and out 
      _imageViewer.DefaultInteractiveMode = New ImageViewerPanZoomInteractiveMode() 
 
      ' Initialize the zoom system 
      InitZoom(zoomComboBox, zoomInButton, zoomOutButton) 
 
      ' Load an image 
      Using codecs As New RasterCodecs() 
         _imageViewer.Image = codecs.Load(Path.Combine(ImagesPath.Path, "Ocr1.tif")) 
      End Using 
 
      MyBase.OnLoad(e) 
   End Sub 
 
   Private Sub UpdateZoomValueFromView() 
      ' Get the current scale factor from the viewer and set it in the zoom combo box 
      Dim percentage As Double = _imageViewer.ScaleFactor * 100.0 
      Dim zoomComboBox As ComboBox = TryCast(Me.Controls.Find("zoomComboBox", True)(0), ComboBox) 
      zoomComboBox.Text = percentage.ToString("F1") & "%" 
   End Sub 
 
   Private Sub InitZoom(ByVal zoomComboBox As ComboBox, ByVal zoomInButton As Button, ByVal zoomOutButton As Button) 
      ' Add support for user typing the zoom value in the combo box directly 
      AddHandler zoomComboBox.LostFocus, 
         Sub(sender, e) 
            ' When the user moves away from the combo box, make sure it has a valid value 
            UpdateZoomValueFromView() 
         End Sub 
 
      AddHandler zoomComboBox.KeyPress, 
         Sub(sender, e) 
            ' Check if the finished editing by pressing Enter 
            If e.KeyChar = ChrW(Keys.Return) Then 
               ' Yes, get the new value 
               Dim value As String = zoomComboBox.Text.Trim() 
               If (Not String.IsNullOrEmpty(value)) Then 
                  ' Remove the % sign if present 
                  If value.EndsWith("%") Then 
                     value = value.Remove(value.Length - 1, 1).Trim() 
                  End If 
 
                  ' Try to parse the new zoom value 
                  Dim percentage As Double 
                  If Double.TryParse(value, percentage) Then 
                     ' Valid value, zoom the viewer 
                     _imageViewer.Zoom(ControlSizeMode.None, percentage / 100.0, _imageViewer.DefaultZoomOrigin) 
                  End If 
 
                  ' And update the combo box from this value (in case we set a value not in the min/max range) 
                  UpdateZoomValueFromView() 
               End If 
            End If 
         End Sub 
 
      AddHandler zoomComboBox.SelectedIndexChanged, 
         Sub(sender, e) 
            ' Get the value from the combo box 
            Dim value As String = zoomComboBox.Text.Trim() 
            Select Case value 
               Case "Actual Size" 
                  _imageViewer.Zoom(ControlSizeMode.ActualSize, 1, _imageViewer.DefaultZoomOrigin) 
 
               Case "Fit Page" 
                  _imageViewer.Zoom(ControlSizeMode.FitAlways, 1, _imageViewer.DefaultZoomOrigin) 
 
               Case "Fit Width" 
                  _imageViewer.Zoom(ControlSizeMode.FitWidth, 1, _imageViewer.DefaultZoomOrigin) 
 
               Case "Fit Height" 
                  _imageViewer.Zoom(ControlSizeMode.FitHeight, 1, _imageViewer.DefaultZoomOrigin) 
 
               Case Else 
                  If (Not String.IsNullOrEmpty(value)) Then 
                     ' A percentage, use it 
                     Dim percentage As Double = Double.Parse(value.Substring(0, value.Length - 1)) 
                     _imageViewer.Zoom(ControlSizeMode.None, percentage / 100.0, _imageViewer.DefaultZoomOrigin) 
                  End If 
            End Select 
         End Sub 
 
      ' For zoom in button, use current ScaleFactor multiplied by the ratio 
      AddHandler zoomInButton.Click, 
         Sub(sender, e) 
            _imageViewer.Zoom(ControlSizeMode.None, _imageViewer.ScaleFactor * _zoomRatio, _imageViewer.DefaultZoomOrigin) 
         End Sub 
 
      ' For zoom out button, use current ScaleFactor divided by the ratio 
      AddHandler zoomOutButton.Click, 
         Sub(sender, e) 
            _imageViewer.Zoom(ControlSizeMode.None, _imageViewer.ScaleFactor / _zoomRatio, _imageViewer.DefaultZoomOrigin) 
         End Sub 
 
      ' Also update the value from the viewer when the transform changed, this happens if the user selects a fit mode, 
      ' such as fit width or fit page. The viewer will change the scale factor accordingly and we need to update it 
      ' in our combo box 
      ' This also takes care of Pan/Zoom interactive mode updating the scale factor 
      AddHandler _imageViewer.TransformChanged, 
         Sub(sender, e) 
            UpdateZoomValueFromView() 
         End Sub 
 
      ' Get the value from the viewer into the combo box 
      UpdateZoomValueFromView() 
   End Sub 
End Class