wx.BitmapBundle¶

Contains representations of the same bitmap in different resolutions.

This class generalizes 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 wx.BitmapBundle can be passed to functions such as 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: 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 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 bitmap with the “best” matching size will be used, where “best” is deemed to be the bitmap with the closest size if it can be used without scaling (so that in this example the 64px bitmap will be used at 175% resolution because it typically looks much better than either downscaling it or upscaling the 48px bitmap to 56px) or, if there is no bitmap with close enough size, a bitmap upscaled by an integer scaling factor is used. Note that custom bitmap bundles can use a different algorithm for selecting the best match by overriding wx.BitmapBundleImpl.GetPreferredBitmapSizeAtScale .

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

Also note that the existing code using wx.Bitmap is compatible with the functions taking wx.BitmapBundle in wxWidgets 3.1.6 and later because bitmaps are implicitly convertible to the objects of this class, so just passing wx.Bitmap to the functions taking 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.

Added in version 4.1/wxWidgets-3.1.6.

Class Hierarchy¶

Inheritance diagram for class BitmapBundle:

Methods Summary¶

`__init__`	Default constructor constructs an empty bundle.
`Clear`	Clear the existing bundle contents.
`FromBitmap`	Create a bundle from a single bitmap.
`FromBitmaps`	Create a bundle from the given collection of bitmaps.
`FromFiles`	Create a bundle from bitmaps stored as files.
`FromIconBundle`	Create a bundle from an icon bundle.
`FromImage`	Create a bundle from a single image.
`FromImpl`	Create a bundle from a custom bitmap bundle implementation.
`FromResources`	Create a bundle from the bitmaps in the application resources.
`FromSVG`	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
`FromSVGFile`	Create a bundle from the `SVG` image loaded from the given file.
`FromSVGResource`	Create a bundle from the `SVG` image loaded from an application resource.
`GetBitmap`	Get bitmap of the specified size, creating a new bitmap from the closest available size by rescaling it if necessary.
`GetBitmapFor`	Get bitmap of the size appropriate for the `DPI` scaling used by the given window.
`GetDefaultSize`	Get the size of the bitmap represented by this bundle in default resolution or, equivalently, at 100% scaling.
`GetIcon`	Get icon of the specified size.
`GetIconFor`	Get icon of the size appropriate for the `DPI` scaling used by the given window.
`GetPreferredBitmapSizeAtScale`	Get the size that would be best to use for this bundle at the given `DPI` scaling factor.
`GetPreferredBitmapSizeFor`	Get the size that would be best to use for this bundle at the `DPI` scaling factor used by the given window.
`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.
`IsOk`	Check if bitmap bundle is non-empty.
`IsSameAs`	Check if the two bundles refer to the same object.

Properties Summary¶

DefaultSize

See GetDefaultSize

Class API¶

class wx.BitmapBundle(object)¶

Possible constructors:

BitmapBundle() -> None

BitmapBundle(bitmap) -> None

BitmapBundle(icon) -> None

BitmapBundle(image) -> None

BitmapBundle(other) -> None

Contains representations of the same bitmap in different resolutions.

Methods¶

__init__(self, *args, **kw)¶

Overloaded Implementations:

__init__ (self)

Default constructor constructs an empty bundle.

An empty bundle can’t be used for anything, but can be assigned something else later.

Return type:: None

__init__ (self, bitmap)

Conversion constructor from a single bitmap.

This constructor does the same thing as FromBitmap and only exists for interoperability with the existing code using wx.Bitmap.

Parameters:: bitmap (wx.Bitmap)
Return type:: None

__init__ (self, icon)

Conversion constructor from a single icon.

This constructor does the same thing as FromBitmap and only exists for interoperability with the existing code using wx.Icon.

Parameters:: icon (wx.Icon)
Return type:: None

__init__ (self, image)

Conversion constructor from a single image.

Similarly to the constructor from wx.Bitmap, this constructor only exists for interoperability with the existing code using wx.Image and can be replaced with more readable FromImage in the new code.

Parameters:: image (wx.Image)
Return type:: None

__init__ (self, other)

Copy constructor creates a copy of another bundle.

Parameters:: other (wx.BitmapBundle)
Return type:: None

Clear(self)¶

Clear the existing bundle contents.

After calling this function IsOk returns False.

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

Return type:: None

Added in version 4.1/wxWidgets-3.1.7.

static FromBitmap(bitmap)¶

Create a bundle from a single bitmap.

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

If bitmap is invalid, empty bundle is returned.

Parameters:: bitmap (wx.Bitmap)
Return type:: wx.BitmapBundle

static FromBitmaps(*args, **kw)¶

Overloaded Implementations:

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.

Parameters:: bitmaps (Vector)
Return type:: wx.BitmapBundle

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.

Parameters:

bitmap1 (wx.Bitmap)
bitmap2 (wx.Bitmap)

Return type:

wx.BitmapBundle

static FromFiles(*args, **kw)¶

Overloaded Implementations:

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”

Parameters:

path (string) – Path of the directory containing the files
filename (string) – Bitmap’s filename without any scale suffix
extension (string) – File extension, without leading dot ( png by default)

Return type:

wx.BitmapBundle

FromFiles (fullpathname)

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

Parameters:: fullpathname (string)
Return type:: wx.BitmapBundle

static FromIconBundle(iconBundle)¶

Create a bundle from an icon bundle.

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

Parameters:: iconBundle (wx.IconBundle)
Return type:: wx.BitmapBundle

Added in version 4.1/wxWidgets-3.1.7.

static FromImage(image)¶

Create a bundle from a single image.

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

If image is invalid, empty bundle is returned.

Parameters:: image (wx.Image)
Return type:: wx.BitmapBundle

static 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 wx.BitmapBundleImpl.

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

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

Parameters:: name (string)
Return type:: wx.BitmapBundle

Properties¶

DefaultSize¶: See GetDefaultSize

wx.BitmapBundle¶

Class Hierarchy¶

Methods Summary¶

Properties Summary¶

Class API¶

Methods¶

Properties¶

Table of Contents

This Page