.. include:: headings.inc .. _ImageHandler: ========================================================================================================================================== |phoenix_title| **ImageHandler** ========================================================================================================================================== This is the base class for implementing image file loading/saving, and image creation from data. It is used within :ref:`Image` and is not normally seen by the application. If you wish to extend the capabilities of :ref:`Image`, derive a class from :ref:`ImageHandler` and add the handler using :meth:`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 ` in the :ref:`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. JPEGHandler uses libjpeg created by ``IJG``.) .. seealso:: :ref:`Image`, :func:`InitAllImageHandlers` | |class_hierarchy| Inheritance Diagram ===================================== Inheritance diagram for class **ImageHandler** .. raw:: html

Inheritance diagram of ImageHandler

| |method_summary| Methods Summary ================================ ================================================================================ ================================================================================ :meth:`~ImageHandler.__init__` Default constructor. :meth:`~ImageHandler.CanRead` Returns ``True`` if this handler supports the image format contained in the given stream. :meth:`~ImageHandler.DoCanRead` Called to test if this handler can read an image from the given stream. :meth:`~ImageHandler.DoGetImageCount` Called to get the number of images available in a multi-image file type, if supported. :meth:`~ImageHandler.GetAltExtensions` Returns the other file extensions associated with this handler. :meth:`~ImageHandler.GetExtension` Gets the preferred file extension associated with this handler. :meth:`~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:`~ImageHandler.GetMimeType` Gets the ``MIME`` type associated with this handler. :meth:`~ImageHandler.GetName` Gets the name of this handler. :meth:`~ImageHandler.GetType` Gets the image type associated with this handler. :meth:`~ImageHandler.LoadFile` Loads a image from a stream, putting the resulting data into `image`. :meth:`~ImageHandler.SaveFile` Saves a image in the output stream. :meth:`~ImageHandler.SetAltExtensions` Sets the alternative file extensions associated with this handler. :meth:`~ImageHandler.SetExtension` Sets the preferred file extension associated with this handler. :meth:`~ImageHandler.SetMimeType` Sets the handler ``MIME`` type. :meth:`~ImageHandler.SetName` Sets the handler name. ================================================================================ ================================================================================ | |property_summary| Properties Summary ===================================== ================================================================================ ================================================================================ :attr:`~ImageHandler.AltExtensions` See :meth:`~ImageHandler.GetAltExtensions` and :meth:`~ImageHandler.SetAltExtensions` :attr:`~ImageHandler.Extension` See :meth:`~ImageHandler.GetExtension` and :meth:`~ImageHandler.SetExtension` :attr:`~ImageHandler.MimeType` See :meth:`~ImageHandler.GetMimeType` and :meth:`~ImageHandler.SetMimeType` :attr:`~ImageHandler.Name` See :meth:`~ImageHandler.GetName` and :meth:`~ImageHandler.SetName` :attr:`~ImageHandler.Type` See :meth:`~ImageHandler.GetType` ================================================================================ ================================================================================ | |api| Class API =============== .. class:: ImageHandler(Object) This is the base class for implementing image file loading/saving, and image creation from data. **Possible constructors**:: ImageHandler() .. 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:`StreamBase.IsSeekable` ). :param `stream`: :type `stream`: 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:`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`: 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`: 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:`StreamBase.IsSeekable` ). :type `stream`: 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:`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`: Image :param `stream`: Opened input stream for reading image data. :type `stream`: 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:`Image.LoadFile` , :meth:`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`: Image :param `stream`: Opened output stream for writing the data. :type `stream`: 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:`Image.LoadFile` , :meth:`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 .. attribute:: AltExtensions See :meth:`~ImageHandler.GetAltExtensions` and :meth:`~ImageHandler.SetAltExtensions` .. attribute:: Extension See :meth:`~ImageHandler.GetExtension` and :meth:`~ImageHandler.SetExtension` .. attribute:: MimeType See :meth:`~ImageHandler.GetMimeType` and :meth:`~ImageHandler.SetMimeType` .. attribute:: Name See :meth:`~ImageHandler.GetName` and :meth:`~ImageHandler.SetName` .. attribute:: Type See :meth:`~ImageHandler.GetType`