.. 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.BitmapBundle:

==========================================================================================================================================
|phoenix_title|  **wx.BitmapBundle**
==========================================================================================================================================

Contains representations of the same bitmap in different resolutions.          

This class generalizes :ref:`wx.Bitmap`  for applications supporting multiple DPIs and allows to operate with multiple versions of the same bitmap, in the sizes appropriate to the currently used display resolution, as a single unit. Notably, an entire :ref:`wx.BitmapBundle`  can be passed to functions such as :meth:`wx.ToolBar.AddTool`   to allow toolbar to select the best available bitmap to be shown. 

Objects of this class are typically created by the application and then passed to wxWidgets functions, but not used by the application itself. Currently bitmap bundles can be created from:  

More functions for creating bitmap bundles will be added in the future. 

Objects of :ref:`wx.BitmapBundle`  class have value-like semantics, i.e. they can be copied around freely (and cheaply) and don't need to be allocated on the heap. However they usually are created using static factory functions (known as "pseudo-constructors") such as :meth:`~wx.BitmapBundle.FromBitmaps`  instead of using the real constructors. 

Example of using this class to initialize a toolbar in a frame constructor: ::

        # In __init__ for a wx.Frame
        ...
        toolBar = self.CreateToolBar()
        bitmaps = [ wx.Bitmap('open_32x32.png'),
                    wx.Bitmap('open_32x32.png'),
                    wx.Bitmap('open_32x32.png') ]
        toolBar.AddTool(wx.ID_OPEN, wx.BitmapBundle.FromBitmaps(bitmaps))



The code shown above will use 32 pixel bitmap in normal ``DPI``, 64 pixel bitmap in "high ``DPI``", i.e. pixel-doubling or 200% resolution, and 48 pixel bitmap in 150% resolution. For all the other resolutions, the best matching bitmap will be created dynamically from the best available match, e.g. for 175% resolution, 64 pixel bitmap will be rescaled to 56 pixels. 

Of course, this code relies on actually having the resources with the corresponding names (i.e.  ``open_NxN`` ) in MSW .rc file or Mac application bundle and   ``open_NxN_png``   arrays being defined in the program code, e.g. by including a file generated with   ``bin2c``   (see  ``BITMAP_PNG_FROM_DATA``), on the other platforms. 

For the platforms with resources support, you can also create the bundle from the bitmaps defined in the resources, which has the advantage of not having to explicitly list all the bitmaps, e.g. the code above becomes ::

    # RC resources are not supported in wxPython

and will load all resources called  ``open`` ,   ``open_2x`` ,   ``open_1_5x``   etc (at least the first one of them must be available). See also  ``BITMAP_BUNDLE_2``  macro which can avoid the need to check for ``HAS_IMAGE_RESOURCES`` explicitly in the code in a common case of having only 2 embedded resources (for standard and high ``DPI``). See also :meth:`~wx.BitmapBundle.FromSVGResource`. 

Also note that the existing code using :ref:`wx.Bitmap`  is compatible with the functions taking :ref:`wx.BitmapBundle`  in wxWidgets 3.1.6 and later because bitmaps are implicitly convertible to the objects of this class, so just passing :ref:`wx.Bitmap`  to the functions taking :ref:`wx.BitmapBundle`  continues to work and if high resolution versions of bitmap are not (yet) available for the other toolbar tools, single bitmaps can continue to be used instead. 





         



.. versionadded:: 4.1/wxWidgets-3.1.6  
     







|

|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>BitmapBundle</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.BitmapBundle_inheritance.png" alt="Inheritance diagram of BitmapBundle" 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.BitmapBundle.html" title="wx.BitmapBundle" alt="" coords="5,5,143,35"/> </map> 
   </p>
   </div>

|


|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~wx.BitmapBundle.__init__`                                                Default constructor constructs an empty bundle.
:meth:`~wx.BitmapBundle.Clear`                                                   Clear the existing bundle contents.
:meth:`~wx.BitmapBundle.FromBitmap`                                              Create a bundle from a single bitmap.
:meth:`~wx.BitmapBundle.FromBitmaps`                                             Create a bundle from the given collection of bitmaps.
:meth:`~wx.BitmapBundle.FromFiles`                                               Create a bundle from bitmaps stored as files.
:meth:`~wx.BitmapBundle.FromIconBundle`                                          Create a bundle from an icon bundle.
:meth:`~wx.BitmapBundle.FromImage`                                               Create a bundle from a single image.
:meth:`~wx.BitmapBundle.FromImpl`                                                Create a bundle from a custom bitmap bundle implementation.
:meth:`~wx.BitmapBundle.FromResources`                                           Create a bundle from the bitmaps in the application resources.
:meth:`~wx.BitmapBundle.FromSVG`                                                 
:meth:`~wx.BitmapBundle.FromSVGFile`                                             Create a bundle from the ``SVG`` image loaded from the given file.
:meth:`~wx.BitmapBundle.FromSVGResource`                                         Create a bundle from the ``SVG`` image loaded from an application resource.
:meth:`~wx.BitmapBundle.GetBitmap`                                               Get bitmap of the specified size, creating a new bitmap from the closest available size by rescaling it if necessary.
:meth:`~wx.BitmapBundle.GetBitmapFor`                                            Get bitmap of the size appropriate for the ``DPI`` scaling used by the given window.
:meth:`~wx.BitmapBundle.GetDefaultSize`                                          Get the size of the bitmap represented by this bundle in default resolution or, equivalently, at 100% scaling.
:meth:`~wx.BitmapBundle.GetIcon`                                                 Get icon of the specified size.
:meth:`~wx.BitmapBundle.GetIconFor`                                              Get icon of the size appropriate for the ``DPI`` scaling used by the given window.
:meth:`~wx.BitmapBundle.GetPreferredBitmapSizeAtScale`                           Get the size that would be best to use for this bundle at the given ``DPI`` scaling factor.
:meth:`~wx.BitmapBundle.GetPreferredBitmapSizeFor`                               Get the size that would be best to use for this bundle at the ``DPI`` scaling factor used by the given window.
:meth:`~wx.BitmapBundle.GetPreferredLogicalSizeFor`                              Get the size that would be best to use for this bundle at the ``DPI`` scaling factor used by the given window in logical size.
:meth:`~wx.BitmapBundle.IsOk`                                                    Check if bitmap bundle is non-empty.
:meth:`~wx.BitmapBundle.IsSameAs`                                                Check if the two bundles refer to the same object.
================================================================================ ================================================================================


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~wx.BitmapBundle.DefaultSize`                                             See :meth:`~wx.BitmapBundle.GetDefaultSize`
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: wx.BitmapBundle(object)

   **Possible constructors**::

       BitmapBundle()
       
       BitmapBundle(bitmap)
       
       BitmapBundle(icon)
       
       BitmapBundle(image)
       
       BitmapBundle(other)
       
   
   Contains representations of the same bitmap in different resolutions.



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



      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self)`
      
      Default constructor constructs an empty bundle.                  
      
      An empty bundle can't be used for anything, but can be assigned something else later.                   
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, bitmap)`
      
      Conversion constructor from a single bitmap.                  
      
      This constructor does the same thing as :meth:`FromBitmap`   and only exists for interoperability with the existing code using :ref:`wx.Bitmap`.                  
      
      
      :param `bitmap`: 
      :type `bitmap`: wx.Bitmap
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, icon)`
      
      Conversion constructor from a single icon.                  
      
      This constructor does the same thing as :meth:`FromBitmap`   and only exists for interoperability with the existing code using :ref:`wx.Icon`.                  
      
      
      :param `icon`: 
      :type `icon`: wx.Icon
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, image)`
      
      Conversion constructor from a single image.                  
      
      Similarly to the constructor from :ref:`wx.Bitmap`, this constructor only exists for interoperability with the existing code using :ref:`wx.Image`  and can be replaced with more readable :meth:`FromImage`   in the new code.                  
      
      
      :param `image`: 
      :type `image`: wx.Image
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, other)`
      
      Copy constructor creates a copy of another bundle.                  
      
      
      :param `other`: 
      :type `other`: wx.BitmapBundle
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: Clear(self)

      Clear the existing bundle contents.                  

      After calling this function :meth:`IsOk`   returns ``False``. 

      This is the same as assigning a default-constructed bitmap bundle to this object but slightly more explicit. 

                 



      .. versionadded:: 4.1/wxWidgets-3.1.7  
     








   .. staticmethod:: FromBitmap(bitmap)

      Create a bundle from a single bitmap.                  

      This is only useful for compatibility with the existing code using :ref:`wx.Bitmap`. 

      If `bitmap`  is invalid, empty bundle is returned.                  


      :param `bitmap`: 
      :type `bitmap`: wx.Bitmap




      :rtype: :ref:`wx.BitmapBundle`








   .. staticmethod:: FromBitmaps(*args, **kw)



      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **FromBitmaps** `(bitmaps)`
      
      Create a bundle from the given collection of bitmaps.                  
      
      If the `bitmaps`  vector is empty, an invalid, empty bundle is returned, otherwise initialize the bundle with all the bitmaps in this vector which must be themselves valid.                  
      
      
      :param `bitmaps`: 
      :type `bitmaps`: Vector
      
      
      
      
      :rtype: :ref:`wx.BitmapBundle`
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **FromBitmaps** `(bitmap1, bitmap2)`
      
      
      
      This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.                  
      
      
      :param `bitmap1`: 
      :type `bitmap1`: wx.Bitmap
      :param `bitmap2`: 
      :type `bitmap2`: wx.Bitmap
      
      
      
      
      :rtype: :ref:`wx.BitmapBundle`
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. staticmethod:: FromFiles(*args, **kw)



      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **FromFiles** `(path, filename, extension="png")`
      
      Create a bundle from bitmaps stored as files.                  
      
      Looking in `path`  for files using `filename`  as prefix and potentionally a suffix with scale, e.g. "_2x" or "@2x" 
      
      
      
      
      :param `path`: Path of the directory containing the files   
      :type `path`: string
      :param `filename`: Bitmap's filename without any scale suffix   
      :type `filename`: string
      :param `extension`: File extension, without leading dot ( ``png``   by default)    
      :type `extension`: string
      
      
      
      
      
      
      
      
      
      
      :rtype: :ref:`wx.BitmapBundle`
      
      
      
                        
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **FromFiles** `(fullpathname)`
      
      
      
      This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.                  
      
      
      :param `fullpathname`: 
      :type `fullpathname`: string
      
      
      
      
      :rtype: :ref:`wx.BitmapBundle`
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. staticmethod:: FromIconBundle(iconBundle)

      Create a bundle from an icon bundle.                  

      If `iconBundle`  is invalid or empty, empty bundle is returned. 

                


      :param `iconBundle`: 
      :type `iconBundle`: wx.IconBundle




      :rtype: :ref:`wx.BitmapBundle`







      .. versionadded:: 4.1/wxWidgets-3.1.7  
     








   .. staticmethod:: FromImage(image)

      Create a bundle from a single image.                  

      This is only useful for compatibility with the existing code using :ref:`wx.Image`. 

      If `image`  is invalid, empty bundle is returned.                  


      :param `image`: 
      :type `image`: wx.Image




      :rtype: :ref:`wx.BitmapBundle`








   .. staticmethod:: FromImpl(impl)

      Create a bundle from a custom bitmap bundle implementation.                  

      This function can be used to create bundles implementing custom logic for creating the bitmaps, e.g. creating them on the fly rather than using predefined bitmaps. 

      See :ref:`wx.BitmapBundleImpl`. 




      :param `impl`: A valid, i.e. non-null, pointer. This function takes ownership of it, so the caller must  `not`  call DecRef() on it.   
      :type `impl`: wx.BitmapBundleImpl






      :rtype: :ref:`wx.BitmapBundle`



                  





   .. staticmethod:: FromResources(name)

      Create a bundle from the bitmaps in the application resources.                  

      This function can only be used on the platforms supporting storing bitmaps in resources, and currently only works under MSW and MacOS and returns an empty bundle on the other platforms. 

      Under MSW, for this function to create a valid bundle, you must have  ``RCDATA``   resource with the given  `name`  in your application resource file (with the extension `name`  as prefix and suffix with the scale, e.g. "_2x" or "_1_5x" (for 150% ``DPI``) will be also loaded as part of the bundle. 

                


      :param `name`: 
      :type `name`: string




      :rtype: :ref:`wx.BitmapBundle`







      .. seealso:: :meth:`FromSVGResource`     








   .. staticmethod:: FromSVG(data, sizeDef)



      This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.                  


      :param `data`: 
      :type `data`: int
      :param `sizeDef`: 
      :type `sizeDef`: wx.Size




      :rtype: :ref:`wx.BitmapBundle`








   .. staticmethod:: FromSVGFile(path, sizeDef)

      Create a bundle from the ``SVG`` image loaded from the given file.                  

      This function loads the ``SVG`` data from the given `path`  and calls :meth:`FromSVG`   with it. As it is just a wrapper for :meth:`FromSVG` , please see that function documentation for more information about ``SVG`` support. 




      :param `path`: Path to the ``SVG`` file. Notice that it should a local file, not an URL.   
      :type `path`: string
      :param `sizeDef`: The default size to return from :meth:`GetDefaultSize`   for this bundle.   
      :type `sizeDef`: wx.Size








      :rtype: :ref:`wx.BitmapBundle`



                  





   .. staticmethod:: FromSVGResource(name, sizeDef)

      Create a bundle from the ``SVG`` image loaded from an application resource.                  

      Available only on the platforms supporting images in resources, i.e., MSW and MacOS. 




      :param `name`: On MSW, it must be a resource with  ``RT_RCDATA``   type. On MacOS, it must be a file with an extension "svg" placed in the "Resources" subdirectory of the application bundle.    
      :type `name`: string
      :param `sizeDef`: The default size to return from :meth:`GetDefaultSize`   for this bundle.  
      :type `sizeDef`: wx.Size








      :rtype: :ref:`wx.BitmapBundle`



                  



      .. seealso:: :meth:`FromResources` , :meth:`FromSVGFile`     








   .. method:: GetBitmap(self, size)

      Get bitmap of the specified size, creating a new bitmap from the closest available size by rescaling it if necessary.                  

      This function is mostly used by wxWidgets itself and not the application. As all bitmaps created by it dynamically are currently cached, avoid calling it for many different sizes if you do use it, as this will create many bitmaps that will never be deleted and will consume resources until the application termination. 




      :param `size`: The size of the bitmap to return, in physical pixels. If this parameter is DefaultSize, default bundle size is used.   
      :type `size`: wx.Size






      :rtype: :ref:`wx.Bitmap`



                  





   .. method:: GetBitmapFor(self, window)

      Get bitmap of the size appropriate for the ``DPI`` scaling used by the given window.                  

      This helper function simply combines :meth:`GetPreferredBitmapSizeFor`   and :meth:`GetBitmap` , i.e. it returns a (normally unscaled) bitmap from the bundle of the closest size to the size that should be used at the ``DPI`` scaling of the provided window. 




      :param `window`: Non-null and fully created window.   
      :type `window`: wx.Window






      :rtype: :ref:`wx.Bitmap`



                  





   .. method:: GetDefaultSize(self)

      Get the size of the bitmap represented by this bundle in default resolution or, equivalently, at 100% scaling.                  

      When creating the bundle from a number of bitmaps, this will be just the size of the smallest bitmap in it. 

      Note that this function is mostly used by wxWidgets itself and not the application.                  

      :rtype: :ref:`wx.Size`








   .. method:: GetIcon(self, size)

      Get icon of the specified size.                  

      This is just a convenient wrapper for :meth:`GetBitmap`   and simply converts the returned bitmap to :ref:`wx.Icon`.                  


      :param `size`: 
      :type `size`: wx.Size




      :rtype: :ref:`wx.Icon`








   .. method:: GetIconFor(self, window)

      Get icon of the size appropriate for the ``DPI`` scaling used by the given window.                  

      This is similar to :meth:`GetBitmapFor` , but returns a :ref:`wx.Icon`, as :meth:`GetIcon`   does. 




      :param `window`: Non-null and fully created window.   
      :type `window`: wx.Window






      :rtype: :ref:`wx.Icon`



                  





   .. method:: GetPreferredBitmapSizeAtScale(self, scale)

      Get the size that would be best to use for this bundle at the given ``DPI`` scaling factor.                  

      For bundles containing some number of the fixed-size bitmaps, this function returns the size of an existing bitmap closest to the ideal size at the given scale, i.e. :meth:`GetDefaultSize`   multiplied by `scale`. 

      Passing a size returned by this function to :meth:`GetBitmap`   ensures that bitmap doesn't need to be rescaled, which typically significantly lowers its quality.                  


      :param `scale`: 
      :type `scale`: float




      :rtype: :ref:`wx.Size`








   .. method:: GetPreferredBitmapSizeFor(self, window)

      Get the size that would be best to use for this bundle at the ``DPI`` scaling factor used by the given window.                  

      This is just a convenient wrapper for :meth:`GetPreferredBitmapSizeAtScale`   calling that function with the result of :meth:`wx.Window.GetDPIScaleFactor` . 




      :param `window`: Non-null and fully created window.   
      :type `window`: wx.Window






      :rtype: :ref:`wx.Size`



                  





   .. method:: GetPreferredLogicalSizeFor(self, window)

      Get the size that would be best to use for this bundle at the ``DPI`` scaling factor used by the given window in logical size.                  

      This is just call :meth:`GetPreferredBitmapSizeAtScale`   with the result of :meth:`wx.Window.GetDPIScaleFactor`   and convert returned value with :meth:`wx.Window.FromPhys` . 




      :param `window`: Non-null and fully created window.   
      :type `window`: wx.Window






      :rtype: :ref:`wx.Size`



                  





   .. method:: IsOk(self)

      Check if bitmap bundle is non-empty.                  

      Return ``True`` if the bundle contains any bitmaps or ``False`` if it is empty.                  

      :rtype: `bool`








   .. method:: IsSameAs(self, other)

      Check if the two bundles refer to the same object.                  

      Bundles are considered to be same only if they actually use the same underlying object, i.e. are copies of each other. If the two bundles were independently constructed, they're `not`  considered to be the same, even if they were created from the same bitmap.                  


      :param `other`: 
      :type `other`: wx.BitmapBundle




      :rtype: `bool`








   .. attribute:: DefaultSize

      See :meth:`~wx.BitmapBundle.GetDefaultSize`