.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2017 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc

.. module:: wx.lib.agw.thumbnailctrl

.. currentmodule:: wx.lib.agw.thumbnailctrl

.. highlight:: python



.. _wx.lib.agw.thumbnailctrl:

==========================================================================================================================================
|phoenix_title|  **wx.lib.agw.thumbnailctrl**
==========================================================================================================================================

:class:`~wx.lib.agw.thumbnailctrl.ThumbnailCtrl` is a widget that can be used to display a series of images in
a "thumbnail" format.


Description
===========

:class:`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 :class:`ScrolledWindow`.

The code is partly based on `wxVillaLib`, a wxWidgets implementation of this
control. However, :class:`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 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)

            thumbnail.ShowDir(os.getcwd())
            panel.SetSizer(sizer)


    # our normal wxApp-derived class, as usual

    app = wx.App(0)

    frame = MyFrame(None)
    app.SetTopWindow(frame)
    frame.Show()

    app.MainLoop()



Methods and Settings
====================

With :class:`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:

  a) ``d`` key rotates 90 degrees clockwise;
  b) ``s`` key rotates 90 degrees counter-clockwise;
  c) ``a`` key rotates 180 degrees.

- Delete files/thumbnails (via the ``del`` key);
- Drag and drop thumbnails from :class:`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 :class:`ComboBox` at the top of :class:`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).


:note: 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:

================================== ==================================================
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 And Version
===================

:class:`ThumbnailCtrl` is distributed under the wxPython license.

Latest revision: Andrea Gavana @ 27 Dec 2012, 21.00 GMT

Version 0.9


|function_summary| Functions Summary
====================================

================================================================================ ================================================================================
:func:`~wx.lib.agw.thumbnailctrl.getDataBL`                                      Return the second part of the shadow dropped behind thumbnails.
:func:`~wx.lib.agw.thumbnailctrl.getDataSH`                                      Return the first part of the shadow dropped behind thumbnails.
:func:`~wx.lib.agw.thumbnailctrl.getDataTR`                                      Return the third part of the shadow dropped behind thumbnails.
:func:`~wx.lib.agw.thumbnailctrl.GetMondrianBitmap`                              Returns a default image placeholder as a :class:`wx.Bitmap`.
:func:`~wx.lib.agw.thumbnailctrl.GetMondrianData`                                Returns a default image placeholder as a decompressed stream of characters.
:func:`~wx.lib.agw.thumbnailctrl.GetMondrianImage`                               Returns a default image placeholder as a :class:`wx.Image`.
:func:`~wx.lib.agw.thumbnailctrl.getShadow`                                      Creates a shadow behind every thumbnail.
:func:`~wx.lib.agw.thumbnailctrl.KeyThumb`                                       Return the key to be used for sorting???
:func:`~wx.lib.agw.thumbnailctrl.opj`                                            Convert paths to the platform-specific separator.
:func:`~wx.lib.agw.thumbnailctrl.SortFiles`                                      Sort files in alphabetical order.
================================================================================ ================================================================================


|


|class_summary| Classes Summary
===============================

================================================================================ ================================================================================
:ref:`~wx.lib.agw.thumbnailctrl.NativeImageHandler`                              This image handler loads and manipulates the thumbnails with the help of
:ref:`~wx.lib.agw.thumbnailctrl.PILImageHandler`                                 This image handler loads and manipulates the thumbnails with the help
:ref:`~wx.lib.agw.thumbnailctrl.ScrolledThumbnail`                               This is the main class implementation of :class:`ThumbnailCtrl`.
:ref:`~wx.lib.agw.thumbnailctrl.Thumb`                                           This is an auxiliary class, to handle single thumbnail information for every thumb.
:ref:`~wx.lib.agw.thumbnailctrl.ThumbnailCtrl`                                   :class:`ThumbnailCtrl` is a widget that can be used to display a series of images in
:ref:`~wx.lib.agw.thumbnailctrl.ThumbnailEvent`                                  This class is used to send events when a thumbnail is hovered, selected,
================================================================================ ================================================================================


|


.. toctree::
   :maxdepth: 1
   :hidden:

   wx.lib.agw.thumbnailctrl.NativeImageHandler
   wx.lib.agw.thumbnailctrl.PILImageHandler
   wx.lib.agw.thumbnailctrl.ScrolledThumbnail
   wx.lib.agw.thumbnailctrl.Thumb
   wx.lib.agw.thumbnailctrl.ThumbnailCtrl
   wx.lib.agw.thumbnailctrl.ThumbnailEvent





Functions
------------

.. function:: getDataBL()

   Return the second part of the shadow dropped behind thumbnails. 


.. function:: getDataSH()

   Return the first part of the shadow dropped behind thumbnails. 


.. function:: getDataTR()

   Return the third part of the shadow dropped behind thumbnails. 


.. function:: GetMondrianBitmap()

   Returns a default image placeholder as a :class:`wx.Bitmap`. 


.. function:: GetMondrianData()

   Returns a default image placeholder as a decompressed stream of characters. 


.. function:: GetMondrianImage()

   Returns a default image placeholder as a :class:`wx.Image`. 


.. function:: getShadow()

   Creates a shadow behind every thumbnail. 


.. function:: KeyThumb(item)

   Return the key to be used for sorting???


.. function:: opj(path)

   Convert paths to the platform-specific separator.
   
   :param `path`: the path to convert.


.. function:: SortFiles(items, sorteditems, filenames)

   Sort files in alphabetical order.
   
   :param `sorteditems`: a list of :class:`Thumb` objects;
   :param `filenames`: a list of image filenames.


