AGW Logo

agw_title thumbnailctrl

ThumbnailCtrl is a widget that can be used to display a series of images in a “thumbnail” format.

description Description

ThumbnailCtrl is a widget that can be used to display a series of images in a “thumbnail” format; it mimics, for example, the windows explorer behavior when you select the “view thumbnails” option. Basically, by specifying a folder that contains some image files, the files in the folder are displayed as miniature versions of the actual images in a wx.ScrolledWindow.

The code is partly based on wxVillaLib, a wxWidgets implementation of this control. However, ThumbnailCtrl wouldn’t have been so fast and complete without the suggestions and hints from Peter Damoc. So, if he accepts the mention, this control is his as much as mine.

usage Usage

Usage example:

import os

import wx
import wx.lib.agw.thumbnailctrl as TC

class MyFrame(wx.Frame):

    def __init__(self, parent):

        wx.Frame.__init__(self, parent, -1, "ThumbnailCtrl Demo")

        panel = wx.Panel(self)

        sizer = wx.BoxSizer(wx.VERTICAL)

        thumbnail = TC.ThumbnailCtrl(panel, imagehandler=TC.NativeImageHandler)
        sizer.Add(thumbnail, 1, wx.EXPAND | wx.ALL, 10)


# our normal wxApp-derived class, as usual

app = wx.PySimpleApp()

frame = MyFrame(None)


This code snippet can be downloaded, see this example script.


Some of the AGW snippets of code in the documentation use images and external files (to create bitmaps or access external data). As these files are not provided in these snippets, you should make the approriate modifications to the code to actually run it.

settings Methods and Settings

With ThumbnailCtrl you can:

  • Create different thumbnail outlines (none, images only, full, etc...);
  • Highlight thumbnails on mouse hovering;
  • Show/hide file names below thumbnails;
  • Change thumbnail caption font;
  • Zoom in/out thumbnails (done via Ctrl key + mouse wheel or with + and - chars, with zoom factor value customizable);
  • Rotate thumbnails with these specifications:
    1. d key rotates 90 degrees clockwise;
    2. s key rotates 90 degrees counter-clockwise;
    3. a key rotates 180 degrees.
  • Delete files/thumbnails (via the del key);
  • Drag and drop thumbnails from ThumbnailCtrl to whatever application you want;
  • Use local (when at least one thumbnail is selected) or global (no need for thumbnail selection) popup menus;
  • Show/hide a wx.ComboBox at the top of ThumbnailCtrl: this combobox contains working directory information and it has history entries;
  • possibility to show tooltips on thumbnails, which display file information (like file name, size, last modification date and thumbnail size).


Using highlight thumbnails on mouse hovering may be slow on slower computers.

styles Window Styles

No particular window styles are available for this class.

events Events Processing

This class processes the following events:

Events processing for thumbnailctrl
Event Name Description
EVT_THUMBNAILS_CAPTION_CHANGED The thumbnail caption has been changed. Not used at present.
EVT_THUMBNAILS_DCLICK The user has double-clicked on a thumbnail.
EVT_THUMBNAILS_POINTED The mouse cursor is hovering over a thumbnail.
EVT_THUMBNAILS_SEL_CHANGED The user has changed the selected thumbnail.
EVT_THUMBNAILS_THUMB_CHANGED The thumbnail of an image has changed. Used internally.

license License And Version

ThumbnailCtrl is distributed under the wxPython license.

Latest revision: Andrea Gavana @ 17 Aug 2011, 15.00 GMT

Version 0.9

Module author: Andrea Gavana <>

hierarchy Inheritance Diagram

Inheritance diagram for module: thumbnailctrl

Inheritance diagram of thumbnailctrl.NativeImageHandler, thumbnailctrl.PILImageHandler, thumbnailctrl.ScrolledThumbnail, thumbnailctrl.Thumb, thumbnailctrl.ThumbnailCtrl, thumbnailctrl.ThumbnailEvent

svn_main SVN Revisions

A graphical representation of the SVN commits in the last year.

Click on any date in the picture to jump to that particular revision page, containing information about committers, log messages and SVN diffs.


Revision Graph For thumbnailctrl

2to3 Python 3 Issues (via 2to3)

No issues have been detected by