.. wxPython Phoenix documentation

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

   Copyright: (c) 2011-2018 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 :ref:`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`, :ref:`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.png" alt="Inheritance diagram of ImageHandler" usemap="#dummy" class="inheritance"/></center>
   </div>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.Object.html" title="wx.Object" alt="" coords="29,5,111,35"/> <area shape="rect" id="node2" href="wx.ImageHandler.html" title="wx.ImageHandler" alt="" coords="5,83,136,112"/> </map> 
   </p>

|


|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 a image from a stream, putting the resulting data into `image`.
:meth:`~wx.ImageHandler.SaveFile`                                                Saves a 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()
       
   
   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.                   





   .. method:: CanRead(self, *args, **kw)



      |overload| Overloaded Implementations:

      **~~~**

      
      **CanRead** `(self, stream)`
      
      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`
      
      
      
      
      
      
      
      **~~~**

      
      **CanRead** `(self, filename)`
      
      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`
      
      
      
      
      
      
      
      **~~~**






   .. method:: DoCanRead(self, stream)

      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)

      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 of strings`







      .. versionadded:: 2.9.0 
     








   .. method:: GetExtension(self)

      Gets the preferred file extension associated with this handler.                  

                

      :rtype: `string`







      .. seealso:: :meth:`GetAltExtensions`     








   .. method:: GetImageCount(self, stream)

      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: `string`








   .. method:: GetName(self)

      Gets the name of this handler.                  

      :rtype: `string`








   .. method:: GetType(self)

      Gets the image type associated with this handler.                  

      :rtype: :ref:`wx.BitmapType`








   .. method:: LoadFile(self, image, stream, verbose=True, index=-1)

      Loads a 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, stream, verbose=True)

      Saves a 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)

      Sets the alternative file extensions associated with this handler.                  




      :param `extensions`: Array of file extensions.  
      :type `extensions`: list of strings




                  



      .. versionadded:: 2.9.0 
     







      .. seealso:: :meth:`SetExtension`   








   .. method:: SetExtension(self, extension)

      Sets the preferred file extension associated with this handler.                  




      :param `extension`: File extension without leading dot.  
      :type `extension`: string




                  



      .. seealso:: :meth:`SetAltExtensions`     








   .. method:: SetMimeType(self, mimetype)

      Sets the handler MIME type.                  




      :param `mimetype`: Handler MIME type.   
      :type `mimetype`: string




                  





   .. method:: SetName(self, name)

      Sets the handler name.                  




      :param `name`: Handler name.   
      :type `name`: string




                  





   .. method:: SetType(self, type)

      Sets the bitmap type for the handler.                  




      :param `type`: 
      :type `type`: wx.BitmapType




      The bitmap type.  

                  





   .. 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`