phoenix_title wx.lib.agw.scrolledthumbnail

ScrolledThumbnail is a widget that can be used to display a series of thumbnails for files in a scrollable window.


ScrolledThumbnail is a widget derived from wx.ScrolledWindow which will display the thumbnail image for a file in a scrollable, resizable window. It supports selecting one or more thumbnails, rotating the thumbnails, displaying information for each thumbnail, and popups for both the window and for individual thumbnails.

The class uses two support classes: Thumb and ImageHandler.

Thumb contains all of the information for a particular thumbnail, including filename, bitmaped thumbnail image, caption, and other data. This class also has methods to perform thumbnail operations such as rotation, highlighting, setting a file name.

ImageHandler provides file/image handling functions, including loading a file and creating an image from it, rotating an image, or highlighting an image.

The implementations of these two classes included in this file support generating thumbnails from supported image files, such as JPEG, GIF, PNG, etc., using either WxPythons native support or the PIL image library. Additional file types can be supported by extending these classes, for example, to provide a thumbnail image for an MP4 file, perhaps the cover photo, an MPEG by providing the image of a title frame, or a PDF by providing an image of the cover page. The images for these files may be generated on the fly by a suitably extended ImageHandler, or may be provided with the instance of Thumb. The list of Thumb instances passed to ScrolledThumbnail may contain different derived classes, as long as each contains the required functions.

NB: Use of ScrolledThumbnail has not been tested with extended classes.

ScrolledThumbnail, Thumb, and ImageHandler, implemented here are derived from the similarly named classes included in agw.ThumbnailCtrl, written by Andrea Gavana. That implementation was tightly integrated as a image file browser application. The current implementation removes dependencies between the several classes and narrows the scope of ScrolledThumbnail to the placement and management of thumbnails within a window.

An updated ThumbnailCtrl which uses this implementation of ScrolledThumbnail, Thumb, and ImageHandler provides all of the previous functionality, which described as 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 ScrolledWindow.

The code in the previous implementation is partly based on wxVillaLib, a wxWidgets implementation of the ThumbnailCtrl control. Andrea Gavana notes that ThumbnailCtrl wouldn’t have been so fast and complete without the suggestions and hints from Peter Damoc.


Usage example:

import os
import wx
from scrolledthumbnail import ScrolledThumbnail, Thumb, NativeImageHandler

class MyFrame(wx.Frame):

    def __init__(self, parent):
        wx.Frame.__init__(self, parent, -1, "ScrolledThumb Demo", size=(400,300))

        self.scroll = ScrolledThumbnail(self, -1, size=(400,300))

    def ShowDir(self, dir):
        dir = os.getcwd()
        files = os.listdir(dir)
        thumbs = []
        for f in files:
            if os.path.splitext(f)[1] in [".jpg", ".gif", ".png"]:
                thumbs.append(Thumb(dir, f, caption=f, imagehandler=NativeImageHandler))

app = wx.App(False)
frame = MyFrame(None)


Methods and Settings

With ScrolledThumbnail 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.

  • Drag and drop thumbnails from ScrolledThumbnail to whatever application you want;

  • Use local (when at least one thumbnail is selected) or global (no need for thumbnail selection) popup menus;

  • 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.

Window Styles

No particular window styles are available for this class.

Events Processing

This class processes the following events:

This class processes the following events:

Event Name



The thumbnail caption has been changed. Not used at present.


The user has double-clicked on a thumbnail.


The mouse cursor is hovering over a thumbnail.


The user has changed the selected thumbnail.


The thumbnail of an image has changed. Used internally.


A character has been typed

License And Version

ScrolledThumbnail is distributed under the wxPython license.

Latest revision: Michael Eager @ 2 Oct 2020

Version 1.0

function_summary Functions Summary


Return the second part of the shadow dropped behind thumbnails.


Return the first part of the shadow dropped behind thumbnails.


Return the third part of the shadow dropped behind thumbnails.


Creates a shadow behind every thumbnail.


Convert paths to the platform-specific separator.

class_summary Classes Summary


This image handler loads and manipulates the thumbnails with the help of


This image handler loads and manipulates the thumbnails with the help


This is the main class implementation of ThumbnailCtrl.


This is an auxiliary class, to handle single thumbnail information for every thumb.


This class is used to send events when a thumbnail is hovered, selected,



Return the second part of the shadow dropped behind thumbnails.


Return the first part of the shadow dropped behind thumbnails.


Return the third part of the shadow dropped behind thumbnails.


Creates a shadow behind every thumbnail.


Convert paths to the platform-specific separator.


path – the path to convert.