View thumbnails in WinForms

In This Topic

ThumbnailViewer is a WinForms control designed to display thumbnails of associated image collection.

ThumbnailViewer can work separately

ThumbnailViewer creates own image collection
associated image collection can be accessed with the ImageViewerBase.Images property
image collection can be navigated with the ImageViewerBase.FocusedIndex property
thumbnail is added/updated/removed if image is added/updated/removed from associatedimage collection

ThumbnailViewer can work as a "slave viewer" of another ImageViewer or ThumbnailViewer

link between viewers can be set with the ImageViewerBase.MasterViewer property of the slave viewer
slave viewer uses image collection of the master viewer
shared image collection can be accessed with the ImageViewerBase.Images property of master or slave viewer
image collection can be navigated with the ImageViewerBase.FocusedIndex property of master or slave viewer
ImageViewerBase.FocusedIndex properties of master and slave viewer are changed synchronously
image is added/updated/removed in image viewer if image is added/updated/removed from associatedimage collection

Here is C#/VB.NET code that shows how to load images to ImageViewer, link an ImageViewer with ThumbnailViewer, invert the first image in the image collection - the image in ImageViewer and the thumbnail in ThumbnailViewer will be inverted:

imageViewer1.Images.Add("myimages.tif");
thumbnailViewer1.MasterViewer = imageViewer1;
imageViewer1.Images[0].Invert();

VB.NET

imageViewer1.Images.Add("myimages.tif")
thumbnailViewer1.MasterViewer = imageViewer1
imageViewer1.Images(0).Invert()

Thumbnail size

Thumbnails have 2 sizes:

"physical size" - size of bitmap associated with thumbnail
"visible size" - size of bitmap associated with thumbnail after scaling

"Physical size" of thumbnails can be set with the ThumbnailViewer.ThumbnailSize property.The minimum "physical size" of thumbnail is 32x32 pixels, the maximum "physical size" of thumbnail is 1024x1024 pixels.

"Visible size" of thumbnails can be set with the ThumbnailViewer.ThumbnailScale property. "Visible size" is calculated as multiplication of "physical size" and scaling factor.
Here is a list of scaling factors:

Smallest - visible size is 0.5 of the physical size
Small - visible size is 0.75 of the physical size
Normal - visible size is equal to the physical size
Large - visible size is 1.5 of the physical size

2 blocks of memory can be allocated for thumbnails:

"Memory for original thumbnails" is a memory block for thumbnails with ThumbnailViewer.ThumbnailSize
"Memory for scaled thumbnails" is a memory for scaled thumbnails if ThumbnailViewer.ThumbnailScaleis not equal "Normal"

Old thumbnails will be destroyed (used memory will be freed) and new thumbnails will be created (new "memory for original thumbnails" will be allocated) when ThumbnailViewer.ThumbnailSize is changed.

Existing thumbnails are scaled when ThumbnailViewer.ThumbnailScale is changed, "memory for scaled thumbnails" is allocated if ThumbnailViewer.ThumbnailScale is not equal "Normal".

Important: Do not use large size of thumbnails if this is not necessary.

Thumbnail appearance and caption

Define thumbnail appearance using properties

The ThumbnailAppearance class allows to define the thumbnail appearance (back color, border color, border style and border width of thumbnail) using the properties.

ThumbnailViewer has properties, which allow to define the "standard" thumbnail appearances:

ThumbnailViewer.ThumbnailAppearance property - gets or sets the appearance of the "normal" thumbnail
ThumbnailViewer.FocusedThumbnailAppearance property - gets or sets the appearance of the thumbnail when thumbnail has focus
ThumbnailViewer.SelectedThumbnailAppearance property - gets or sets the appearance of the thumbnail when user selects thumbnail
ThumbnailViewer.HoveredThumbnailAppearance property - gets or sets the appearance of the thumbnail when mouse hovers thumbnail
ThumbnailViewer.NotReadyThumbnailAppearance property - gets or sets the appearance of not ready thumbnail

Also ThumbnailViewer allows to set the thumbnail appearance on the fly. For doing this is necessary to subscribe to the ThumbnailViewer.ThumbnailAppearanceSelected event and change the thumbnail appearance in the event handler.

Define thumbnail caption using properties

The ThumbnailCaption class allows to define the thumbnail caption: caption format or custom text, padding, anchor, text font, text color.
Here is C#/VB.NET code that shows how to customize the thumbnail caption using ThumbnailCaption.CaptionFormatted event:

/// <summary>
/// Sets the custom thumbnail caption.
/// </summary>
/// <param name="thumbnailViewer">The thumbnail viewer.</param>
public static void SetCustomThumbnailCaption(Vintasoft.Imaging.UI.ThumbnailViewer thumbnailViewer)
{
    thumbnailViewer.ThumbnailCaption.CaptionFormatted += ThumbnailCaption_CaptionFormatted;
    thumbnailViewer.ThumbnailCaption.IsVisible = true;
}

/// <summary>
/// Handles the CaptionFormatted event of the ThumbnailCaption.
/// </summary>
/// <param name="sender">The source of the event.</param>
/// <param name="e">The <see cref="Vintasoft.Imaging.UI.ThumbnailCaptionFormattedEventArgs"/> instance containing the event data.</param>
private static void ThumbnailCaption_CaptionFormatted(object sender, Vintasoft.Imaging.UI.ThumbnailCaptionFormattedEventArgs e)
{
    Vintasoft.Imaging.VintasoftImage image = e.Thumbnail.Source;
    int imageIndex = e.ThumbnailViewer.Images.IndexOf(image);
    if (e.ThumbnailViewer.SelectedIndices.Contains(imageIndex))
    {
        e.Caption = "Selected";
    }
    else
    {
        e.Caption = string.Format("{0}, page {1}", System.IO.Path.GetFileName(image.SourceInfo.Filename), image.SourceInfo.PageIndex + 1);
    }
}

VB.NET

''' <summary>
''' Sets the custom thumbnail caption.
''' </summary>
''' <param name="thumbnailViewer">The thumbnail viewer.</param>
Public Shared Sub SetCustomThumbnailCaption(thumbnailViewer As Vintasoft.Imaging.UI.ThumbnailViewer)
    AddHandler thumbnailViewer.ThumbnailCaption.CaptionFormatted, AddressOf ThumbnailCaption_CaptionFormatted
    thumbnailViewer.ThumbnailCaption.IsVisible = True
End Sub

''' <summary>
''' Handles the CaptionFormatted event of the ThumbnailCaption.
''' </summary>
''' <param name="sender">The source of the event.</param>
''' <param name="e">The <see cref="Vintasoft.Imaging.UI.ThumbnailCaptionFormattedEventArgs"/> instance containing the event data.</param>
Private Shared Sub ThumbnailCaption_CaptionFormatted(sender As Object, e As Vintasoft.Imaging.UI.ThumbnailCaptionFormattedEventArgs)
    Dim image As Vintasoft.Imaging.VintasoftImage = e.Thumbnail.Source
    Dim imageIndex As Integer = e.ThumbnailViewer.Images.IndexOf(image)
    If e.ThumbnailViewer.SelectedIndices.Contains(imageIndex) Then
        e.Caption = "Selected"
    Else
        e.Caption = String.Format("{0}, page {1}", System.IO.Path.GetFileName(image.SourceInfo.Filename), image.SourceInfo.PageIndex + 1)
    End If
End Sub

The ThumbnailViewer.ThumbnailCaption property allows to get or set caption of thumbnail in thumbnail viewer.

Draw the thumbnail in thumbnail viewer

If you cannot define the thumbnail appearance or caption using properties, you can use the low-level functionality - the ThumbnailViewer.ThumbnailPainting and ThumbnailViewer.ThumbnailPainted events, i.e. draw graphics under thumbnail in handler of ThumbnailViewer.ThumbnailPainting event and/or draw graphics over thumbnail in handler of ThumbnailViewer.ThumbnailPainted event.

Examples

'Thumbnail Viewer Demo' and 'Simple Demos' projects show how to create thumbnail viewers with custom appearances.

Tooltip of thumbnails

ThumbnailViewer allows to show tooltips for thumbnails.

Tooltips can be generated automatically

set value of the ThumbnailViewer.ThumbnailAutoToolTip property to true
set value of the tooltip prefix for all thumbnails using ThumbnailViewer.ThumbnailAutoToolTipPrefix property

Also tooltips can be specified manually

set value of the ThumbnailViewer.ThumbnailAutoToolTip property to false
set tooltip for thumbnail using the Thumbnail.ToolTip property

Thumbnail viewer events

ThumbnailViewer can raise the following events:

ThumbnailViewer.ThumbnailsLoadingProgress - occurs when the loading progress of thumbnails is changed
ThumbnailViewer.ThumbnailLoading - occurs when thumbnail is loading
ThumbnailViewer.ThumbnailLoadingProgress - occurs when the loading progress of thumbnail is changed
ThumbnailViewer.ThumbnailLoaded - occurs when thumbnail is loaded
ThumbnailViewer.ThumbnailLoadingException - occurs when thumbnail is not loaded because of error
ThumbnailViewer.ThumbnailPainting - occurs when thumbnail is painting
ThumbnailViewer.ThumbnailPainted - occurs when thumbnail is painted
ThumbnailViewer.ThumbnailAdded - occurs when thumbnail is added to thumbnail viewer

Thumbnail rendering

ThumbnailViewer can render thumbnails in multiple threads. Count of rendering threads can be get/set using the ThumbnailViewer.ThumbnailRenderingThreadCount property. By default ThumbnailViewer renders thumbnails in a single thread.

All thumbnails are generated by default. ThumbnailViewer.GenerateOnlyVisibleThumbnails property allows to generate only visible thumbnails, this can be necessary for slow computers.

Context menus of thumbnail viewer

The ThumbnailViewer.ContextMenuStrip property allows to set the context menu, which is associated with the thumbnail viewer.

The ThumbnailViewer.ThumbnailContextMenuStrip property allows to set the context menu, which is associated with a single thumbnail. The ThumbnailViewer.DisableThumbnailContextMenu property allows to disable the context menu for a single thumbnail.

Hot keys of thumbnail viewer

ThumbnailViewer has hot keys:

Ctrl+C - copies image of selected thumbnail to clipboard
Ctrl+X - copies image of selected thumbnail to clipboard and removes image from associated image collection
Ctrl+V - inserts image from clipboard as image of selected thumbnail
Del - deletes selected thumbnails and images from associated image collection
Ctrl+A - selects all thumbnails

Hot keys can be enabled/disabled with the ImageViewerBase.ShortcutCopy, ImageViewerBase.ShortcutCut, ImageViewerBase.ShortcutInsert, ImageViewerBase.ShortcutDelete, ImageViewerBase.ShortcutSelectAll properties.
Behaviour of hot keys can be overriden with the ImageViewerBase.DoCopy, ImageViewerBase.DoCut, ImageViewerBase.DoInsert, ImageViewerBase.DoDelete, ImageViewerBase.DoSelectAll methods.

Select multiple thumbnail in thumbnail viewer

ThumbnailViewer allows to select several thumbnails at the same time, indices of selected thumbnails can be accessed with the ThumbnailViewer.SelectedIndices property.

ThumbnailViewer.SelectedIndices is a "snapshot" of indices collection (read only) of allocated thumbnails. If you work with a copy of the collection, you must note that the ThumbnailViewer.SelectedIndices property could be changed depending on the user's actions and your copy may become irrelevant.

Drag-and-drop thumbnails in thumbnail viewer

ThumbnailViewer allows to drag-and-drop thumbnails. In order to drag the thumbnail, just hover your cursor on it, hold left mouse button and pull the cursor to the desired position. Thumbnails drag-and-drop process changes their indexes in the ImageViewerBase.Images collection, which means that indexes in the ThumbnailViewer.SelectedIndices collection will change too. That's why we do not recommend using a copy of this collection.

Drag-and-drop feature can be enabled/disabled with the ThumbnailViewer.AllowDrop or ThumbnailViewer.AllowDrag properties.

Send Feedback