Crystal Image Toolkit: thumbnail image control and picture viewing.

#region gnu_license
/*
    Crystal Controls - C# control library containing the following tools:
        CrystalControl - base class
        CrystalGradientControl - a control that can either have a gradient background or be totally transparent.
        CrystalLabel - a homegrown label that can have a gradient or transparent background.
        CrystalPanel - a panel that can have a gradient or transparent background.
        CrystalTrackBar - a homegrown trackbar that can have a gradient or transparent background.
        CrystalToolStripTrackBar - a host for CrystalTrackBar that allows it to work in a ToolStrip.
        
        CrystalImageGridView - a control that hosts thumbnail images in a virtual grid.
        CrystalImageGridModel - a data model that holds a collection of CrystalImageItems
                                to feed to CrystalImageGridView.
        CrystalImageItem - a class that describes an Image file.
        CrystalThumbnailer - provides thumbnailing methods for images.

        CrystalCollector - a base class for a controller that links 
                            CrystalImageGridView to the CrystalImageGridModel.
        CrystalFileCollector - a controller that works on disk-based Image files.
        CrystalDesignCollector - a controller that works in Visual Studio toolbox designer.
        CrystalMemoryCollector - a controller that can be used to add images from memory.
        CrystalMemoryZipCollector - a controller that accesses images in zip files by streaming them into memory.
        CrystalZipCollector - a controller that accesses images in zip files by unpacking them.
        CrystalRarCollector - a controller that accesses images in rar files by unpacking them.

        CrystalPictureBox - a picture box control, derived from CrystalGradientControl.
        CrystalPictureShow - a control for viewing images and processing slideshows.
        CrystalComicShow - a control for viewing comic-book images in the CDisplay format.
 
    Copyright (C) 2006, 2008 Richard Guion
    Attilan Software Factory: http://www.attilan.com
    Contact: richard@attilan.com

   Version 1.0.0
        This is a work in progress: USE AT YOUR OWN RISK!  Interfaces/Methods may change!
 
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2.1 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 */
#endregion

using System;
using System.ComponentModel;
using System.Drawing;
using System.Windows.Forms;

namespace Attilan.Crystal.Controls
{
    /// <summary>
    /// A Crystal Image collector variant that displays images held in memory.
    /// By using a memory collector, you are taking responsibility to load full and
    /// thumbnail images inside the collection of CrystalImageItems manually.
    /// </summary>
    [ToolboxItem(false)]
    public class CrystalMemoryCollector : CrystalCollector
    {
        #region Method Implementation

        /// <summary>
        /// Loads the full image and places it into the CrystalImageItem object.
        /// </summary>
        /// <param name="ImageFullPath">The location of the image.</param>
        /// <returns>Image if successful, null if an error occurred.</returns>
        public override Image LoadImage(string ImageFullPath)
        {
            return null;
        }

        /// <summary>
        /// Loads the full image and places it into the CrystalImageItem object.
        /// </summary>
        /// <param name="imageItem">The CrystalImageItem object with the Image information.</param>
        /// <returns>True if successful, false if an error occurred.</returns>
        public override bool LoadImage(ref CrystalImageItem imageItem)
        {
            return (imageItem.FullImage != null);
        }

        /// <summary>
        /// Loads the thumbnail image and places it into the CrystalImageItem object.
        /// </summary>
        /// <param name="imageItem">The CrystalImageItem object with the Image information.</param>
        /// <returns>True if successful, false if an error occurred.</returns>
        public override bool LoadThumbnailImage(ref CrystalImageItem imageItem)
        {
            if ((imageItem == null) || (imageItem.ThumbnailImage == null))
                return false;

            if (imageItem.ThumbnailImage != null)
            {
                // Just use the thumbnail image already loaded.
                return true;
            }
            else
            {
                // Generate a thumbnail image based on the full image.
                Image thumbImage = Thumbnailer.Generate(imageItem.FullImage, imageItem.ImageRect.Size);

                if (thumbImage != null)
                {
                    imageItem.ThumbnailImage = thumbImage;
                    return true;
                }
            }

            return false;
        }

        /// <summary>
        /// CollectImages does almost nothing in a memory collector.
        /// The caller should use AddImage or AddImageItem to manually add a series of image
        /// item objects before calling CollectImages with this type of collector.
        /// </summary>
        /// <returns></returns>
        public override bool CollectImages()
        {
            if (GridModel != null)
            {
                UpdateGrid();
            }

            return true;
        }

        /// <summary>
        /// Collects the images at the group item's location into the model and then tells the view to display them.
        /// </summary>
        /// <param name="groupItem">CrystalGroupItem containing location to collect images from.</param>
        /// <returns>True if images collected, false otherwise.</returns>
        public override bool CollectImages(CrystalGroupItem groupItem)
        {
            return false;
        }

        /// <summary>
        /// Purges the collection of images that belongs to this object.
        /// </summary>
        public override void PurgeImages()
        {
            _gridModel = null;

            if (GridView != null)
            {
                UpdateResizeVirtualGrid();
            }

            GC.Collect();
        }

        /// <summary>
        /// Stops the image collection operation.  Kills any background threads operating on images.
        /// </summary>
        public override void StopCollection()
        {
            // Do nothing.
            // Don't have to stop in the designer.
        }

        /// <summary>
        /// Collects a thumbnail for a single image item.
        /// </summary>
        /// <param name="crystalImage">Image item from which a thumbnail image will be collected.</param>
        /// <param name="overwriteExisting">True means regenerate the thumbnail if one already exists.</param>
        /// <returns>True if a thumbnail was generated, false otherwise.</returns>
        public override bool CollectThumbnailImage(ref CrystalImageItem crystalImage, bool overwriteExisting)
        {
            return false;
        }

        /// <summary>
        /// Default Constructor.
        /// </summary>
        public CrystalMemoryCollector()
        {
            Thumbnailer = new CrystalThumbnailer();
            Thumbnailer.ThumbLocationRoot = Application.UserAppDataPath;
        }

        #endregion
    }
}