Fully document PIL.ImageWin

PIL/ImageWin.py

@@ -20,44 +20,49 @@
 import warnings
 from PIL import Image
 
-##
-# The <b>ImageWin</b> module contains support to create and display
-# images under Windows 95/98, NT, 2000 and later.
 
 class HDC:
+    """
+    Wraps a HDC integer. The resulting object can be passed to the
+    :py:meth:`~PIL.ImageWin.Dib.draw` and :py:meth:`~PIL.ImageWin.Dib.expose`
+    methods.
+    """
     def __init__(self, dc):
         self.dc = dc
     def __int__(self):
         return self.dc
 
 class HWND:
+    """
+    Wraps a HWND integer. The resulting object can be passed to the
+    :py:meth:`~PIL.ImageWin.Dib.draw` and :py:meth:`~PIL.ImageWin.Dib.expose`
+    methods, instead of a DC.
+    """
     def __init__(self, wnd):
         self.wnd = wnd
     def __int__(self):
         return self.wnd
 
-##
-# Create a Windows bitmap with the given mode and size.  The mode can
-# be one of "1", "L", "P", or "RGB".
-#
-# If the display requires a palette, this constructor creates a
-# suitable palette and associates it with the image. For an "L" image,
-# 128 greylevels are allocated. For an "RGB" image, a 6x6x6 colour
-# cube is used, together with 20 greylevels.
-#
-# To make sure that palettes work properly under Windows, you must
-# call the <b>palette</b> method upon certain events from Windows.
 
 class Dib:
+    """
+    A Windows bitmap with the given mode and size.  The mode can be one of "1",
+    "L", "P", or "RGB".
 
-    ##
+    If the display requires a palette, this constructor creates a suitable
-    # Create Windows bitmap.
+    palette and associates it with the image. For an "L" image, 128 greylevels
-    #
+    are allocated. For an "RGB" image, a 6x6x6 colour cube is used, together
-    # @param image Either a PIL image, or a mode string.  If a
+    with 20 greylevels.
-    #    mode string is used, a size must also be given.  The
+
-    #    mode can be one of "1", "L", "P", or "RGB".
+    To make sure that palettes work properly under Windows, you must call the
-    # @param size If the first argument is a mode string, this
+    **palette** method upon certain events from Windows.
-    #    defines the size of the image.
+
+    :param image: Either a PIL image, or a mode string. If a mode string is
+                  used, a size must also be given.  The mode can be one of "1",
+                  "L", "P", or "RGB".
+    :param size: If the first argument is a mode string, this
+                 defines the size of the image.
+    """
 
     def __init__(self, image, size=None):
         if hasattr(image, "mode") and hasattr(image, "size"):
@@ -74,15 +79,15 @@ class Dib:
         if image:
             self.paste(image)
 
-    ##
-    # Copy the bitmap contents to a device context.
-    #
-    # @param handle Device context (HDC), cast to a Python integer,
-    #    or a HDC or HWND instance.  In PythonWin, you can use the
-    #    <b>GetHandleAttrib</b> method of the <b>CDC</b> class to get
-    #    a suitable handle.
 
     def expose(self, handle):
+        """
+        Copy the bitmap contents to a device context.
+
+        :param handle: Device context (HDC), cast to a Python integer, or a HDC
+                       or HWND instance.  In PythonWin, you can use the
+                       :py:meth:`CDC.GetHandleAttrib` to get a suitable handle.
+        """
         if isinstance(handle, HWND):
             dc = self.image.getdc(handle)
             try:
@@ -94,6 +99,15 @@ class Dib:
         return result
 
     def draw(self, handle, dst, src=None):
+        """
+        Same as expose, but allows you to specify where to draw the image, and
+        what part of it to draw.
+
+        The destination and source areas are given as 4-tuple rectangles. If
+        the source is omitted, the entire image is copied. If the source and
+        the destination have different sizes, the image is resized as
+        necessary.
+        """
         if not src:
             src = (0,0) + self.size
         if isinstance(handle, HWND):
@@ -106,22 +120,22 @@ class Dib:
             result = self.image.draw(handle, dst, src)
         return result
 
-    ##
-    # Installs the palette associated with the image in the
-    # given device context.
-    # <p>
-    # This method should be called upon <b>QUERYNEWPALETTE</b>
-    # and <b>PALETTECHANGED</b> events from Windows. If this
-    # method returns a non-zero value, one or more display
-    # palette entries were changed, and the image should be
-    # redrawn.
-    #
-    # @param handle Device context (HDC), cast to a Python integer,
-    #     or an HDC or HWND instance.
-    # @return A true value if one or more entries were changed
-    #    (this indicates that the image should be redrawn).
 
     def query_palette(self, handle):
+        """
+        Installs the palette associated with the image in the given device
+        context.
+
+        This method should be called upon **QUERYNEWPALETTE** and
+        **PALETTECHANGED** events from Windows. If this method returns a
+        non-zero value, one or more display palette entries were changed, and
+        the image should be redrawn.
+
+        :param handle: Device context (HDC), cast to a Python integer, or an
+                       HDC or HWND instance.
+        :return: A true value if one or more entries were changed (this
+                 indicates that the image should be redrawn).
+        """
         if isinstance(handle, HWND):
             handle = self.image.getdc(handle)
             try:
@@ -132,17 +146,18 @@ class Dib:
             result = self.image.query_palette(handle)
         return result
 
-    ##
-    # Paste a PIL image into the bitmap image.
-    #
-    # @param im A PIL image.  The size must match the target region.
-    #    If the mode does not match, the image is converted to the
-    #    mode of the bitmap image.
-    # @param box A 4-tuple defining the left, upper, right, and
-    #    lower pixel coordinate.  If None is given instead of a
-    #    tuple, all of the image is assumed.
 
     def paste(self, im, box=None):
+        """
+        Paste a PIL image into the bitmap image.
+
+        :param im: A PIL image.  The size must match the target region.
+                   If the mode does not match, the image is converted to the
+                   mode of the bitmap image.
+        :param box: A 4-tuple defining the left, upper, right, and
+                    lower pixel coordinate.  If None is given instead of a
+                    tuple, all of the image is assumed.
+        """
         im.load()
         if self.mode != im.mode:
             im = im.convert(self.mode)
@@ -151,21 +166,23 @@ class Dib:
         else:
             self.image.paste(im.im)
 
-    ##
-    # Load display memory contents from byte data.
-    #
-    # @param buffer A buffer containing display data (usually
-    #     data returned from <b>tobytes</b>)
 
     def frombytes(self, buffer):
+        """
+        Load display memory contents from byte data.
+
+        :param buffer: A buffer containing display data (usually
+                       data returned from <b>tobytes</b>)
+        """
         return self.image.frombytes(buffer)
 
-    ##
-    # Copy display memory contents to bytes object.
-    #
-    # @return A bytes object containing display data.
 
     def tobytes(self):
+        """
+        Copy display memory contents to bytes object.
+
+        :return: A bytes object containing display data.
+        """
         return self.image.tobytes()
 
     ##

docs/PIL.rst

@@ -102,14 +102,6 @@ can be found here.
     :undoc-members:
     :show-inheritance:
 
-:mod:`ImageWin` Module
-----------------------
-
-.. automodule:: PIL.ImageWin
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 :mod:`JpegPresets` Module
 -------------------------
 

docs/reference/ImageWin.rst

@@ -0,0 +1,29 @@
+.. py:module:: PIL.ImageWin
+.. py:currentmodule:: PIL.ImageWin
+
+:py:mod:`ImageWin` Module (Windows-only)
+========================================
+
+The :py:mod:`ImageWin` module contains support to create and display images on
+Windows.
+
+ImageWin can be used with PythonWin and other user interface toolkits that
+provide access to Windows device contexts or window handles. For example,
+Tkinter makes the window handle available via the winfo_id method:
+
+.. code-block:: python
+
+    from PIL import ImageWin
+
+    dib = ImageWin.Dib(...)
+
+    hwnd = ImageWin.HWND(widget.winfo_id())
+    dib.draw(hwnd, xy)
+
+
+.. autoclass:: PIL.ImageWin.Dib
+    :members:
+
+
+.. autoclass:: PIL.ImageWin.HDC
+.. autoclass:: PIL.ImageWin.HWND

docs/reference/index.rst

@@ -21,4 +21,5 @@ Reference
    ImageSequence
    ImageStat
    ImageTk
+   ImageWin
    ../PIL