Crystal Image Toolkit: thumbnail image control and picture viewing.

• Download source code - 4.7 MB

Introduction

Back in 2006, I started working on Windows Forms applications in C#. I encountered a series of projects where I needed to display thumbnail images in a form control, but I needed to make the background, border, and text elements customizable. I developed a series of controls called the Crystal Image Toolkit that has allowed me to build applications that display both thumbnails and full images.

I probably shouldn't have named this Crystal, as people wrongly associate it with Crystal Reports. I had chosen the name because of a Marvel comics character. I was also thinking of Crystal Clear images, or maybe that song, Crystal Blue Persuasion. Or maybe, I'm just a nut!

Using the code

I will show you how to quickly add an image thumbnail control to your Windows Forms application.

First of all, download the Crystal Image Toolkit from the link above. Compile the code using the solution that I provided, which takes care of the toolkit and all the demo examples.

Create a new Windows Forms application in Visual Studio. In the Visual Studio toolbox, add a new tab called Crystal Image Toolkit (to separate it from Crystal Reports), and add the controls found in CrystalToolkit.dll.

Select the control called “CrystalImageGridView”. This is the control that displays the thumbnail images. Drag this control onto your new Form.

Now, go to the Properties window, with “crystalImageGridView1” selected. Change the Dock property to Fill. Change the Orientation property to Vertical.

After you set the properties, the image grid control should look like this:

The blue borders simply give you an idea of what the image items will look like in the selected state. The broken image bitmap is just a placeholder. At runtime, your images will be placed inside this blue rectangle. Yes, you can change many other properties, including the border color, background color, and so on. But for now, let’s accept the defaults.

Let’s write a little bit of code. Go to the Events tab, double click on Load, and generate the event on the Form. Now that you are in Form1.cs, let’s add this field at the top of the Form class:

/// <summary>
/// CrystalCollector object, assists in retrieving image files in a specified folder.
/// </summary>
private CrystalCollector _theCollector = null;

The CrystalCollector object is the controller in this framework.

The collector works with the CrystalImageGridView and the CrystalImageGridModel. It finds image files set in the ImageLocation property, creates objects to mirror those files as CrystalImageItem objects, and places those within the model. The collector spawns a background thread to start thumb-nailing the image items; this thread sends events to the view to tell it when an image thumbnail is available. That is what happens behind the scenes, but here in this simple example, you only need to add this method to your Form:

private void InitCollector()
{
     _theCollector =
      CrystalCollectorFactory.DefaultFactory.CreateCollector
      (CrystalCollectorType.CrystalFileCollector);
     // Add the CrystalImageGridView object to the collector.
     // The collector will work with the view to draw the images.
     _theCollector.SetupView(crystalImageGridView1);
     // Optional:
     // Set an initial folder to collect images.
     // If no folder is set, collector starts at MyPictures 
     // in WinXP or Pictures folder in Vista
     //CrystalCollectorFactory.DefaultFactory.InitCollectorSource
         //("c:\\myImages", _theCollector);
     // Tell CrystalFileCollector to collect the images in the 
     // ImageLocation folder.
     _theCollector.CollectImages();
}
private void Form1_Load(object sender, EventArgs e)
{
     InitCollector();
}
protected override void OnFormClosing(FormClosingEventArgs e)
{
     if (_theCollector != null)
     {
      _theCollector.StopCollection();
     }
     base.OnFormClosing(e);
}

InitCollector creates the collector object using a factory. The type it chooses is a file-based collector. You could just create a new CrystalFileCollector yourself, but it is better to use the Factory. This can be used to track down objects getting created/destroyed later.

Once the collector has been created, we call SetupView, passing in the CrystalImageGridView object that we dropped onto the Form. This must be done before we gather any images. The collector creates a CrystalImageGridModel object and links up the view to it. The model must know about certain view properties, which affects how the image items will be displayed.

CollectImages is called at the end, which tells the collector to look at the ImageLocation and start gathering data about the images found there. In this case, we did not set the ImageLocation—the default is set to your Pictures folder (on Vista) or MyPictures folder (in WinXP). If you want to initialize another ImageLocation, use the code I commented out above the call to CollectImages.

Form1_Load calls InitCollector. But, there’s also the override to OnFormClosing, which calls the StopCollector method on the collector object. This call will stop any background threads going on to thumbnail the images.

After you compile this code and execute, you should see the thumbnails for whatever images are in your Pictures folder. Hopefully, they will be images of friends, family, and pets, instead of comic book images!

Play around with this form—you should see that the control responds to resizing events, making the number of image items per row grow or shrink the form. You can do Ctrl-click and Shift-click on image items for multiple selection as well.

Where are these thumbnail images stored? The CrystalThumbnailer object, which does the work of creating them, has a property called ThumbnailLocationRoot. By default, it is your AppData folder, under the name of your Company and Product name.

The collector creates a sub folder here based on the hash number of the original location. It stores the thumbnails here—the largest thumbnail size it needs to display. In these simple demos, the thumbnails will exist permanently. I’ve decided the behavior to retain or erase them is application dependent, and has left the choice up to you.

This is obviously a very simple example, but I have included many sample Form applications in the toolkit:

SimpleImageGridDemo shows a slightly more complex version of this application, by allowing you to open any folder and view the thumbnail images.

ZoomImageGrid shows you how to setup CrystalImageGridView to zoom the thumbnail size up or down. It's a bit of a hack; the thumbnails are stored in their largest possible size, and scaled down according to a property named ZoomFactor.

WaitFormPictureShow demonstrates how to use the CrystalMemoryCollector to load up images directly without having to scan a folder.

HeaderImageGridDemo explains how to put a list of CrystalImageItem objects into a CrystalGroupItem. Group items can be inserted into the model with a special header display that can be collapsed/expanded. Unfortunately, I haven't tested this with ZoomFactor.

PictureShowControllerDemo (above) shows you how to create a more realistic picture viewing application. A split container is used to hold the CrystalImageGridView in Horizontal orientation on the bottom pane. The top pane contains the CrystalPictureShow control, which is used to display images, magnify them, and present slideshows. There’s also a panning window that appears whenever the image is displayed in a non-fit mode.

ComicShowControllerDemo is a specialized image viewer that operates on comic-book files formatted for the CDisplay viewer, with a .CBR or .CBZ extension. You probably have never heard of these, but they are becoming the MP3-like standard for sharing comic books. CBR is really just a RAR file, and CBZ is a ZIP file. The factory will invoke specialized crystal collectors for these formats, unpack the images, and display them.

Points of interest

After I wrote the CrystalImageGridView, naturally, I needed to display a full image, but the PictureBox control wasn't enough. I needed to zoom\magnify the image, add a gradient background effect, get it to work with a panning window, and even do slideshows. I synthesized a lot of code from various articles here on CodeProject, but also from Bob Powell, who has contributed a lot of .NET GDI+ code in various forums. I've tried to credit him in the code for CrystalPictureBox and CrystalPictureShow, wherever possible.

If you run the PictureShowControllerDemo and hit the Slideshow button, you'll see these effects: Fade, Iris, Spin, and Slide.

I've learned a lot by writing this toolkit, but it's far from perfect. The collector only supports one view; I made a serious mistake early on by putting the rectangles for view display inside the model rather than have a separate data structure that the view would access. To fix this, I would have to rewrite a lot of code, but I'm ready to move on to a new project. I'm hoping my source code will benefit other people down the line.

Another improvement that I would have liked to make is to have the background thumbnailer thread be directed by the view. Currently, it thumbnails the images in the sorted order they are displayed in; it would be nicer to behave like Windows Photo Gallery and thumbnail the images viewed at the current scroll location.

There are some other controls here, such as a track bar, gradient panel, etc. I'm not supporting these, but I've left them in the toolkit because the samples make use of them.

History

• Crystal Image Toolkit 1.0.0 - Dec 6, 2008.
• Crystal Image Toolkit 1.0.1 - May 11, 2011: Source has been updated to Visual Studio 2010 and .NET Framework 4.0.