Image Box

• Download demo - 28 KB
• Download source - 194.8 KB

Introduction

Imaging Box is an advanced image control for Windows Form applications, it’s just like the famous PictureBox with even more amazing features. This control allows to show images with advanced zoom options like stretch with aspect ratio, custom zoom ratio and zoom point. For example, you can make the control show image stretched with aspect ratio only if the image bounds are larger than the control bounds. Also, with extra render options like Interpolation mode and Compositing quality, hence this control renders using GDI+ directly and is built as a custom control and is not based on picture box, and make it as customizable as needed for developers and users. It also supports animated images (GIF) with the availability to zoom, stretch, etc. It also supports Right-to-Left by adjusting the vertical scroll bar.

Background

When you develop an application that requires the display of images in high quality with advanced features, and an imaging control is needed with features that normal PictureBox control don't provide like Aspect ratio stretch; ImageBox can solve that problem with even more advanced features like rendering filters.

Using the Code

ImageBox is just a Windows Forms Control, thus, using it within your forms application is as simple as adding other controls when you design the form.

All you need to do is to include the ImageBox.dll (or ImageBox project) into your project as reference, then the ImageBox control should be listed in the Toolbox in Visual Studio’s form designer.

After that, change the Image property to view the image you like. For example:

// A method that opens image file and displays it in the Imaging Box
void OpenImageFile(string path)
        {
            try
            {
// this.imageBox1 is the instance of the Imaging Box control …
               this.imageBox1.Image = Image.FromFile(path);// that’s it !
            }
            catch (FileNotFoundException)
            {
                MessageBox.Show("File:\n" + path + "\nwas not found!");
            }
       // Handle other exceptions here …
        }...

Don’t forget that you can use the Visual Studio forms designer to explore and change the options of this control in the properties box. The properties are:

• InterpolationMode: The interpolation mode that will be used for rendering the image
• CompositingQuality: The compositing quality that will be used for rendering the image
• ScrollMode: The scroll mode to use in scrolling, it can be:
  • Never: Never show scroll bars
  • Automatic: Show scroll bars if image is larger than viewer
  • Always: Always show scroll bars
• ZoomPoint: Zoom point which is used to zoom around while applying zoom. The coordinates in use are control coordinates.

  This is actually a very handy property and one of the main reasons I started this ImageBox control. You can use this property to apply zoom on a certain location of the image, like if you want to zoom on the eye of someone's face. In this case, ImageBox will move ViewPort so that zoom point never moves while zooming.

• StretchMode: The stretch mode, it can be:
  • KeepAspectRatio: Keep aspect ratio of the image
  • StretchToViewerRatio: Stretch the image to a new size where the image touches all sides of the viewer
• ZoomMode: The zoom style used for new images. Can be:
  • None: No zoom, use the image as it is
  • ZoomIfLarger: Zooms the image in if it was larger than the viewer
  • TouchViewerFromInside: Zooms the image in or out so that the image touches the viewer from inside
  • TocuhViewerFromOutside: Zooms the image in or out so that the image touches the viewer from outside
• ZoomRatio: The zoom ratio. ImageBox supports negative zoom ratios. In this case, image will be mirrored. Try it in the demo program.
• UseDefaultImageOnNull: Gets or sets whether to display a default image if 'Image' property was null.
• Image: Gets or sets image to be displayed.
• DefaultImage: Get or set the default image to display when the 'Image' property is null.

Also, there are some hidden properties that could be changed in code (ImageRectangle, ViewPortRectangle and ViewPortLocation), these properties are used internally for rendering.

The events are:

• ImageChanged: Raised when the Image value is changed
• ZoomRatioChanged: Raised when the ZoomRatio value is changed
• ZoomModeChanged: Raised when the ZoomMode value is changed
• StretchModeChanged: Raised when the StretchMode value is changed
• ViewPortLocationChanged: Raised when the ViewPortLocation value is changed
• InterpolationModeChanged: Raised when the InterpolationMode value is changed
• CompositingQualityChanged: Raised when the CompositingQuality value is changed

ImageBox.dll also has a very helpful helper class: ImageHelper.

This helper class provides extension methods to Image, Rectangle and Size to apply zoom.

The demo project source makes a good example of how to use this control and all its features. It is actually a full preview program that can replace 'Preview' in Windows.

You can open or drop an image over it and navigate the folder in which the image is located while allowing you to custom render the image.

Few Words About the Design

• ImageBox paint method is very simple and will take _ImageToDraw and _ImageToDrawRect to draw the image in.
• _ImageToDraw will be selected from _Image or _DefaultImage depending on the value of the property ImageBox.UseDefaultImageOnNull
• _ImageToDrawRect is exposed to external code as the property ImageBox.ImageRectangle. You can apply any kind of stretch and zoom to this property and the image will be rendered accordingly.
• Internally, setting ImageBox.ImageRectangle will invoke methods to adjust scroll bars and update ViewPort as needed.
• ImageBox.ZoomRatio property will produce a new rectangle and set it in ImageBox.ImageRectangle.
• ImageBox.StretchMode will take _ImageToDraw and produces a stretched rectangle _StretchedImageRect.
• ImageBox.ZoomMode uses _StretchedImageRect and calculates the appropriate zoom ratio, then applies it.

Supporting Negative Zoom

ImageBox.cs provides a conditional compiling variable PREVENT_REVERSED_IMAGE.

In case you don't want to allow negative values for zoom, only compile the project with true value and code will raise exceptions in the case of using negative zoom or reversed images.

Supporting reversed images and negative values for zoom requires extra minor steps to draw the image. This will not actually produce any significant performance issues, however, if you wish to disable support for negative zoom, use this variable.

Points of Interest

The Image Box Control is simply another picture box with customizable zooming features and fast performance. It’s actually used in Emulators Organizer <http: emusorganizer="" projects="" sourceforge.net=""> application (maybe not this version of the control, depending on latest updates of the application) and proves its usability and stability.

Updated:

Ver 1.0.1

Fixed: Exception when changing ZoomMode in desgin mode: Added a check before excuting ApplyZoomMode

Many thanks for 'larclap'  for pointing out the bug.

Added: Support of command line in DemoViewer

Added: Switch Zoom Mode button: Fast Switch zoom mode between None and the last zoom mode.

Ver 1.0.2

Fixed: Exception when minimizing the window that contains the ImageBox control.