Part one of a series of tutorials explaining how to use the Crystal Image Toolkit. In this example, I will show you how to quickly add an image thumbnail control to your Windows Form application.
First of all, download the latest Crystal Image Toolkit from my downloads page. Compile the code using the solution that I provided.
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 the above picture. 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 and double click on the Load event of the Form. Now that you are in Form1.cs, let’s add this field:
1: /// <summary>
2: /// CrystalCollector object, assists in retrieving image files in a specified folder.
3: /// </summary>
4: 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 thumbnailing 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 for your Form:
1: private void InitCollector()
2: {
3: _theCollector =
4: CrystalCollectorFactory.DefaultFactory.CreateCollector(CrystalCollectorType.CrystalFileCollector);
5:
6: // Add the CrystalImageGridView object to the collector.
7: // The collector will work with the view to draw the images.
8: _theCollector.SetupView(crystalImageGridView1);
9:
10: // Optional:
11: // Set an initial folder to collect images.
12: // If no folder is set, collector starts at MyPictures in WinXP or Pictures folder in Vista
13: //CrystalCollectorFactory.DefaultFactory.InitCollectorSource("c:\\myImages", _theCollector);
14:
15: // Tell CrystalFileCollector to collect the images in the ImageLocation folder.
16: _theCollector.CollectImages();
17: }
18:
19: private void Form1_Load(object sender, EventArgs e)
20: {
21: InitCollector();
22: }
23:
24: protected override void OnFormClosing(FormClosingEventArgs e)
25: {
26: if (_theCollector != null)
27: {
28: _theCollector.StopCollection();
29: }
30: base.OnFormClosing(e);
31: }
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.
When you press F5 and run, 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 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.
PictureShowControllerDemo 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.
