Add documentation to demo programs.

demo/agw/ScrolledThumbnail.py

@@ -22,6 +22,35 @@ sys.path.append(os.path.split(dirName)[0])
 from ThumbDemoConfig import ThumbDemoConfig
 
 class ScrolledThumbnailDemo (ThumbDemoConfig):
+    """Demo program for ScrolledThumbnail widget.
+
+    :class:`ScrolledThumbnail` provides a scrollable window containing
+    thumbnail images.  These thumbnails are provided to the widget in
+    an array of :class:`Thumb` objects.  The images can be selected,
+    resized, or rotated.  Optionally, tooltips can provide information
+    about the image file or popups can be displayed when a thumbnail is
+    selected.
+
+    The included :class:`Thumb` supports image files like JPEG, GIF, or
+    PNG, using either native Python or PIL functions.  This class can
+    be extended by the user to support other types, for example, to
+    provide a thumbnail of a TXT or PDF file.
+
+    :class:`ScrolledThumbnail` is based on :class:`ThumbnailCtrl`, with
+    the difference that the latter is essentially an image browser
+    application, performing file operations as well as filtering and
+    sorting image files.  :class:`ScrolledThumbnail` contains only the
+    support for displaying thumbnail images in a scrolling window, with
+    generating thumbnails, reading files, and other operations which
+    are not related to displaying the thumbnail to either the user of
+    the class (e.g., this demo), or to support classes such as
+    :class:`Thumb`.
+
+    For full documentation, see the comments in agw/scrolledthumbnail.py.
+
+    This class extends the common code in ThumbDemoConfig to work with
+    the :class:`ScrolledThumbnail` widget.
+    """
 
     def __init__(self, parent, log):
 
@@ -39,10 +68,16 @@ class ScrolledThumbnailDemo (ThumbDemoConfig):
         super().__init__ (parent, log, name=name, about=msg)
 
 
+    # Create a ScrolledThumbnail panel in the left side of the splitter.
     def SetScroll(self):
         self.scroll = ScrolledThumbnail(self.splitter, -1, size=(400,300))
 
 
+    # Display a directory of images in the ScrolledThumbnail window.
+    # Read each file name, filter by desired type (jpg, gif, png) and
+    # create a Thumb (including specifying image support class).  Add
+    # this to the array 'thumbs' and pass to ScrolledThumbnail widget
+    # for display.
     def ShowDir(self, dir):
         files = os.listdir(dir)
         thumbs = []

demo/agw/ThumbDemoConfig.py

@@ -12,6 +12,23 @@ from wx.lib.agw.scrolledthumbnail import (ScrolledThumbnail,
                                           EVT_THUMBNAILS_DCLICK)
 
 class ThumbDemoConfig(wx.Frame):
+    """ScrolledThumbnail or ThumbnailCtrl demo common code
+
+    This class contains code common to both the ScrolledThumbnail and
+    the ThumbnailCtrl demos.  It is extended by both of these demos to
+    address the differences in invoking :class:`ScrolledThumbnail`
+    or :class:`ThumbnailCtrl` widgets.
+
+    This class creates a SplitterWindow with the left half containing
+    the widget being demoed and the right half containing a number of
+    controls which set or change operation of the widget.  In most
+    this simply involves passing the user-specified value to the
+    widget.
+
+    For information about what setting does, as well as other settings,
+    set the documentation for :class:`ScrolledThumbnail` or
+    :class:`ThumbnailCtrl`.
+    """
 
     def __init__(self, parent, log, name, about):
 
@@ -33,12 +50,15 @@ class ThumbDemoConfig(wx.Frame):
 
         self.SetMenuBar(self.CreateMenuBar())
 
+        # Create SplitterWindow with panels for widget and controls.
         self.splitter = wx.SplitterWindow(self, -1, style=wx.CLIP_CHILDREN |
                                      wx.SP_3D | wx.WANTS_CHARS | wx.SP_LIVE_UPDATE)
         self.panel = wx.Panel(self.splitter, -1)
 
         sizer = wx.BoxSizer(wx.HORIZONTAL)
 
+        # Call SetScroll() to create thumbnail widget.
+        # This is provided by each of the two demos.
         self.SetScroll()
 
         self.log = log
@@ -78,6 +98,7 @@ class ThumbDemoConfig(wx.Frame):
         self.panel.SetSizer(sizer)
         sizer.Layout()
 
+
         self.Bind(wx.EVT_RADIOBUTTON, self.OnChangeOutline, self.radiostyle1)
         self.Bind(wx.EVT_RADIOBUTTON, self.OnChangeOutline, self.radiostyle2)
         self.Bind(wx.EVT_RADIOBUTTON, self.OnChangeOutline, self.radiostyle3)
@@ -99,6 +120,7 @@ class ThumbDemoConfig(wx.Frame):
         self.scroll.Bind(EVT_THUMBNAILS_POINTED, self.OnPointed)
         self.scroll.Bind(EVT_THUMBNAILS_DCLICK, self.OnDClick)
 
+        # Add thumbnail widget and control panel to SplitterWindow.
         self.splitter.SplitVertically(self.scroll, self.panel, 300)
 
         self.splitter.SetMinimumPaneSize(140)
@@ -112,6 +134,7 @@ class ThumbDemoConfig(wx.Frame):
 
 
     def DoLayout(self):
+        """Layout controls."""
 
         splitsizer = wx.BoxSizer(wx.VERTICAL)
         optionsizer = wx.StaticBoxSizer(self.optionsizer_staticbox, wx.VERTICAL)

demo/agw/ThumbnailCtrl.py

@@ -1,5 +1,8 @@
 #!/usr/bin/env python
 
+# ThumbnailCtrl Demo  Michael Eager @ 2020 Oct 23
+# Adapted from ThumbnailCtrl Demo Andrea Gavana @ 10 Dec 2005
+
 import wx
 import os
 
@@ -21,6 +24,29 @@ from ThumbDemoConfig import ThumbDemoConfig
 
 
 class ThumbnailCtrlDemo(ThumbDemoConfig):
+    """Demo program for ThumbnailCtrl widget.
+
+    :class:`ThumbnailCtrl` provides an image browser widget in a
+    scrollable window containing thumbnail images.  The class reads
+    the specified directory, filters by image type, and create
+    thumbnail images.  The images can be selected, resized, or rotated.
+    Files can be deleted.  Optionally, tooltips can provide information
+    about the image file or popups can be displayed when a thumbnail is
+    selected.
+
+    The included :class:`Thumb` supports image files like JPEG, GIF, or
+    PNG, using either native Python or PIL functions.
+
+    :class:`ScrolledThumbnail` is used by :class:`ThumbnailCtrl`, to
+    provide the scrolling thumbnail window.  Many of the methods of
+    :class:`ThumbnailCtrl` are actually delegated to
+    :class:`ScrolledThumbnail`.
+
+    For full documentation, see the comments in agw/thumbnailctrl.py.
+
+    This class extends the common code in ThumbDemoConfig to work with
+    the :class:`ThumbnailCtrl` widget.
+    """
 
     def __init__(self, parent, log):
 
@@ -37,11 +63,15 @@ class ThumbnailCtrlDemo(ThumbDemoConfig):
         super().__init__ (parent, log, name=name, about=msg)
 
 
+    # Create ThumbnailCtrl in the left side of the splitter window.
+    # Default:  Use native image handling functions, edit to use PIL.
+    # Call ThumbnailCtrl:ShowDir() to read directory and display images.
     def SetScroll(self):
 
         self.scroll = TC.ThumbnailCtrl(self.splitter, -1, imagehandler=TC.NativeImageHandler)
         #scroll = TC.ThumbnailCtrl(self.splitter, -1, imagehandler=TC.PILImageHandler)
 
+        # Display file names with thumbnails.
         self.scroll.ShowFileNames()
         if os.path.isdir("../bitmaps"):
             self.scroll.ShowDir(os.path.normpath(os.getcwd() + "/../bitmaps"))
@@ -49,20 +79,17 @@ class ThumbnailCtrlDemo(ThumbDemoConfig):
             self.scroll.ShowDir(os.getcwd())
 
 
+    # Following three functions override dummy functions in ThumbDemoConfig
+    # to add checkbox for displaying folder path in ThumbnailCtrl widget.
     def DoComboCheckbox(self):
         self.showcombo = wx.CheckBox(self.panel, -1, "Show folder combobox")
 
-
     def DoBindCombo(self):
         self.Bind(wx.EVT_CHECKBOX, self.OnShowComboBox, self.showcombo)
 
     def DoAddCombo(self, customsizer):
         customsizer.Add(self.showcombo, 0, wx.LEFT|wx.BOTTOM|wx.ADJUST_MINSIZE, 3)
 
-    def ShowDir(self, dir):
-        self.scroll.ShowDir(dir)
-
-
     def OnShowComboBox(self, event):
 
         if self.showcombo.GetValue() == 1:
@@ -74,6 +101,9 @@ class ThumbnailCtrlDemo(ThumbDemoConfig):
 
         event.Skip()
 
+    def ShowDir(self, dir):
+        self.scroll.ShowDir(dir)
+
 
 #---------------------------------------------------------------------------