mirror of
https://github.com/python-pillow/Pillow.git
synced 2024-12-24 00:46:16 +03:00
Fully document PIL.ImageWin
This commit is contained in:
parent
4b4f090258
commit
7030e50b36
139
PIL/ImageWin.py
139
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".
|
||||
|
||||
##
|
||||
# Create Windows bitmap.
|
||||
#
|
||||
# @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.
|
||||
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
|
||||
**palette** method upon certain events from Windows.
|
||||
|
||||
: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()
|
||||
|
||||
##
|
||||
|
|
|
@ -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
|
||||
-------------------------
|
||||
|
||||
|
|
29
docs/reference/ImageWin.rst
Normal file
29
docs/reference/ImageWin.rst
Normal file
|
@ -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
|
|
@ -21,4 +21,5 @@ Reference
|
|||
ImageSequence
|
||||
ImageStat
|
||||
ImageTk
|
||||
ImageWin
|
||||
../PIL
|
||||
|
|
Loading…
Reference in New Issue
Block a user