.. wxPython Phoenix documentation
This file was generated by Phoenix's sphinx generator and associated
tools, do not edit by hand.
Copyright: (c) 2011-2020 by Total Control Software
License: wxWindows License
.. include:: headings.inc
.. _wx.ImageHandler:
==========================================================================================================================================
|phoenix_title| **wx.ImageHandler**
==========================================================================================================================================
This is the base class for implementing image file loading/saving, and image creation from data.
It is used within :ref:`wx.Image` and is not normally seen by the application.
If you wish to extend the capabilities of :ref:`wx.Image`, derive a class from :ref:`wx.ImageHandler` and add the handler using :meth:`wx.Image.AddHandler` in your application initialization.
Note that all ImageHandlers provided by wxWidgets are part of the `Core` library. For details about the default handlers, please see the section :ref:`Available image handlers <wx.Image>` in the :ref:`wx.Image` class documentation.
|phoenix_title| Note (Legal Issue)
==================================
This software is based in part on the work of the Independent ``JPEG`` Group. (Applies when wxWidgets is linked with ``JPEG`` support. :ref:`wx.JPEGHandler` uses libjpeg created by ``IJG``.)
.. seealso:: :ref:`wx.Image`, `wx.InitAllImageHandlers`
|
|class_hierarchy| Class Hierarchy
=================================
.. raw:: html
<div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
<img id="toggleBlock-trigger" src="_static/images/closed.png"/>
Inheritance diagram for class <strong>ImageHandler</strong>:
</div>
<div id="toggleBlock-summary" style="display:block;"></div>
<div id="toggleBlock-content" style="display:none;">
<p class="graphviz">
<center><img src="_static/images/inheritance/wx.ImageHandler_inheritance.svg" alt="Inheritance diagram of ImageHandler" usemap="#dummy" class="inheritance"/></center>
<script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
<map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.ImageHandler.html" title="This is the base class for implementing image file loading/saving, and image creation from data." alt="" coords="5,82,159,111"/> <area shape="rect" id="node2" href="wx.Object.html" title="This is the root class of many of the wxWidgets classes." alt="" coords="33,5,132,34"/> </map>
</p>
</div>
|
|sub_classes| Known Subclasses
==============================
:ref:`wx.GIFHandler`, :ref:`wx.IFFHandler`, :ref:`wx.JPEGHandler`, :ref:`wx.PCXHandler`, :ref:`wx.PNGHandler`, :ref:`wx.PNMHandler`, :ref:`wx.TGAHandler`, :ref:`wx.TIFFHandler`, :ref:`wx.XPMHandler`
|
|method_summary| Methods Summary
================================
================================================================================ ================================================================================
:meth:`~wx.ImageHandler.__init__` Default constructor.
:meth:`~wx.ImageHandler.CanRead` Returns ``True`` if this handler supports the image format contained in the given stream.
:meth:`~wx.ImageHandler.DoCanRead` Called to test if this handler can read an image from the given stream.
:meth:`~wx.ImageHandler.DoGetImageCount` Called to get the number of images available in a multi-image file type, if supported.
:meth:`~wx.ImageHandler.GetAltExtensions` Returns the other file extensions associated with this handler.
:meth:`~wx.ImageHandler.GetExtension` Gets the preferred file extension associated with this handler.
:meth:`~wx.ImageHandler.GetImageCount` If the image file contains more than one image and the image handler is capable of retrieving these individually, this function will return the number of available images.
:meth:`~wx.ImageHandler.GetMimeType` Gets the MIME type associated with this handler.
:meth:`~wx.ImageHandler.GetName` Gets the name of this handler.
:meth:`~wx.ImageHandler.GetType` Gets the image type associated with this handler.
:meth:`~wx.ImageHandler.LoadFile` Loads an image from a stream, putting the resulting data into `image`.
:meth:`~wx.ImageHandler.SaveFile` Saves an image in the output stream.
:meth:`~wx.ImageHandler.SetAltExtensions` Sets the alternative file extensions associated with this handler.
:meth:`~wx.ImageHandler.SetExtension` Sets the preferred file extension associated with this handler.
:meth:`~wx.ImageHandler.SetMimeType` Sets the handler MIME type.
:meth:`~wx.ImageHandler.SetName` Sets the handler name.
:meth:`~wx.ImageHandler.SetType` Sets the bitmap type for the handler.
================================================================================ ================================================================================
|
|property_summary| Properties Summary
=====================================
================================================================================ ================================================================================
:attr:`~wx.ImageHandler.AltExtensions` See :meth:`~wx.ImageHandler.GetAltExtensions` and :meth:`~wx.ImageHandler.SetAltExtensions`
:attr:`~wx.ImageHandler.Extension` See :meth:`~wx.ImageHandler.GetExtension` and :meth:`~wx.ImageHandler.SetExtension`
:attr:`~wx.ImageHandler.MimeType` See :meth:`~wx.ImageHandler.GetMimeType` and :meth:`~wx.ImageHandler.SetMimeType`
:attr:`~wx.ImageHandler.Name` See :meth:`~wx.ImageHandler.GetName` and :meth:`~wx.ImageHandler.SetName`
:attr:`~wx.ImageHandler.Type` See :meth:`~wx.ImageHandler.GetType` and :meth:`~wx.ImageHandler.SetType`
================================================================================ ================================================================================
|
|api| Class API
===============
.. class:: wx.ImageHandler(Object)
**Possible constructors**::
ImageHandler() -> None
This is the base class for implementing image file loading/saving, and
image creation from data.
.. method:: __init__(self)
Default constructor.
In your own default constructor, initialise the members m_name, m_extension and m_type.
:rtype: `None`
.. method:: CanRead(self, *args, **kw)
|overload| **Overloaded Implementations:**
:html:`<hr class="overloadsep" /><br />`
**CanRead** `(self, stream : InputStream)`
Returns ``True`` if this handler supports the image format contained in the given stream.
This function doesn't modify the current stream position (because it restores the original position before returning; this however requires the stream to be seekable; see :meth:`wx.StreamBase.IsSeekable` ).
:param `stream`:
:type `stream`: wx.InputStream
:rtype: `bool`
:html:`<hr class="overloadsep" /><br />`
**CanRead** `(self, filename : str)`
Returns ``True`` if this handler supports the image format contained in the file with the given name.
This function doesn't modify the current stream position (because it restores the original position before returning; this however requires the stream to be seekable; see :meth:`wx.StreamBase.IsSeekable` ).
:param `filename`:
:type `filename`: string
:rtype: `bool`
:html:`<hr class="overloadsep" /><br />`
.. method:: DoCanRead(self, stream : InputStream)
Called to test if this handler can read an image from the given stream.
``NOTE``: this function is allowed to change the current stream position since CallDoCanRead() will take care of restoring it later
:param `stream`:
:type `stream`: wx.InputStream
:rtype: `bool`
.. method:: DoGetImageCount(self, stream : InputStream)
Called to get the number of images available in a multi-image file type, if supported.
``NOTE``: this function is allowed to change the current stream position since :meth:`GetImageCount` will take care of restoring it later
:param `stream`:
:type `stream`: wx.InputStream
:rtype: `int`
.. method:: GetAltExtensions(self)
Returns the other file extensions associated with this handler.
The preferred extension for this handler is returned by :meth:`GetExtension` .
:rtype: `List[str]`
.. versionadded:: 2.9.0
.. method:: GetExtension(self)
Gets the preferred file extension associated with this handler.
:rtype: `str`
.. seealso:: :meth:`GetAltExtensions`
.. method:: GetImageCount(self, stream : InputStream)
If the image file contains more than one image and the image handler is capable of retrieving these individually, this function will return the number of available images.
:param `stream`: Opened input stream for reading image data. This function doesn't modify the current stream position (because it restores the original position before returning; this however requires the stream to be seekable; see :meth:`wx.StreamBase.IsSeekable` ).
:type `stream`: wx.InputStream
:rtype: `int`
:returns:
Number of available images. For most image handlers, this is 1 (exceptions are ``TIFF`` and ``ICO`` formats as well as animated GIFs for which this function returns the number of frames in the animation).
.. method:: GetMimeType(self)
Gets the MIME type associated with this handler.
:rtype: `str`
.. method:: GetName(self)
Gets the name of this handler.
:rtype: `str`
.. method:: GetType(self)
Gets the image type associated with this handler.
:rtype: :ref:`wx.BitmapType`
.. method:: LoadFile(self, image : Image, stream : InputStream, verbose: bool=True, index: int=-1)
Loads an image from a stream, putting the resulting data into `image`.
If the image file contains more than one image and the image handler is capable of retrieving these individually, `index` indicates which image to read from the stream.
:param `image`: The image object which is to be affected by this operation.
:type `image`: wx.Image
:param `stream`: Opened input stream for reading image data.
:type `stream`: wx.InputStream
:param `verbose`: If set to ``True``, errors reported by the image handler will produce LogMessages.
:type `verbose`: bool
:param `index`: The index of the image in the file (starting from zero).
:type `index`: int
:rtype: `bool`
:returns:
``True`` if the operation succeeded, ``False`` otherwise.
.. seealso:: :meth:`wx.Image.LoadFile` , :meth:`wx.Image.SaveFile` , :meth:`SaveFile`
.. method:: SaveFile(self, image : Image, stream : OutputStream, verbose: bool=True)
Saves an image in the output stream.
:param `image`: The image object which is to be affected by this operation.
:type `image`: wx.Image
:param `stream`: Opened output stream for writing the data.
:type `stream`: wx.OutputStream
:param `verbose`: If set to ``True``, errors reported by the image handler will produce LogMessages.
:type `verbose`: bool
:rtype: `bool`
:returns:
``True`` if the operation succeeded, ``False`` otherwise.
.. seealso:: :meth:`wx.Image.LoadFile` , :meth:`wx.Image.SaveFile` , :meth:`LoadFile`
.. method:: SetAltExtensions(self, extensions : List[str])
Sets the alternative file extensions associated with this handler.
:param `extensions`: Array of file extensions.
:type `extensions`: list of strings
:rtype: `None`
.. versionadded:: 2.9.0
.. seealso:: :meth:`SetExtension`
.. method:: SetExtension(self, extension : str)
Sets the preferred file extension associated with this handler.
:param `extension`: File extension without leading dot.
:type `extension`: string
:rtype: `None`
.. seealso:: :meth:`SetAltExtensions`
.. method:: SetMimeType(self, mimetype : str)
Sets the handler MIME type.
:param `mimetype`: Handler MIME type.
:type `mimetype`: string
:rtype: `None`
.. method:: SetName(self, name : str)
Sets the handler name.
:param `name`: Handler name.
:type `name`: string
:rtype: `None`
.. method:: SetType(self, type : BitmapType)
Sets the bitmap type for the handler.
:param `type`: The bitmap type.
:type `type`: wx.BitmapType
:rtype: `None`
.. attribute:: AltExtensions
See :meth:`~wx.ImageHandler.GetAltExtensions` and :meth:`~wx.ImageHandler.SetAltExtensions`
.. attribute:: Extension
See :meth:`~wx.ImageHandler.GetExtension` and :meth:`~wx.ImageHandler.SetExtension`
.. attribute:: MimeType
See :meth:`~wx.ImageHandler.GetMimeType` and :meth:`~wx.ImageHandler.SetMimeType`
.. attribute:: Name
See :meth:`~wx.ImageHandler.GetName` and :meth:`~wx.ImageHandler.SetName`
.. attribute:: Type
See :meth:`~wx.ImageHandler.GetType` and :meth:`~wx.ImageHandler.SetType`