#include <wx/bmpbndl.h>

Detailed Description

Contains representations of the same bitmap in different resolutions.

This class generalizes wxBitmap 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 wxBitmapBundle can be passed to functions such as wxToolBar::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:

- A vector of bitmaps, of any provenance.
- An SVG (as memory block, file, or resource) which will be rasterized at required resolutions.
- A custom bitmap source using wxBitmapBundleImpl.
- A single wxBitmap or wxImage for backwards compatibility.

Objects of wxBitmapBundle 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:

MyFrame::MyFrame()
    : wxFrame(nullptr, wxID_ANY, "My frame")
{
    ...
    wxToolBar* toolBar = CreateToolBar();
 
    wxVector<wxBitmap> bitmaps;
    bitmaps.push_back(wxBITMAP_PNG(open_32x32));
    bitmaps.push_back(wxBITMAP_PNG(open_48x48));
    bitmaps.push_back(wxBITMAP_PNG(open_64x64));
 
    toolBar->AddTool(wxID_OPEN, "Open", wxBitmapBundle::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 wxBitmapBundleImpl::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 wxBITMAP_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

#ifdef wxHAS_IMAGE_RESOURCES
    toolBar->AddTool(wxID_OPEN, "Open", wxBitmapBundle::FromResources("open"));
#else
    ... same code as shown above ...
#endif

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 wxBITMAP_BUNDLE_2() macro which can avoid the need to check for wxHAS_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 wxBitmap is compatible with the functions taking wxBitmapBundle in wxWidgets 3.1.6 and later because bitmaps are implicitly convertible to the objects of this class, so just passing wxBitmap to the functions taking wxBitmapBundle 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.

Library: wxCore

Category: Graphics Device Interface (GDI)

Since: 3.1.6

Public Member Functions
	wxBitmapBundle ()
	Default constructor constructs an empty bundle. More...

	wxBitmapBundle (const wxBitmap &bitmap)
	Conversion constructor from a single bitmap. More...

	wxBitmapBundle (const wxIcon &icon)
	Conversion constructor from a single icon. More...

	wxBitmapBundle (const wxImage &image)
	Conversion constructor from a single image. More...

	wxBitmapBundle (const char const xpm)
	Conversion constructor from XPM data. More...

	wxBitmapBundle (const wxBitmapBundle &other)
	Copy constructor creates a copy of another bundle. More...

wxBitmapBundle &	operator= (const wxBitmapBundle &other)
	Assignment operator makes this bundle a copy of another bundle. More...

void	Clear ()
	Clear the existing bundle contents. More...

bool	IsOk () const
	Check if bitmap bundle is non-empty. More...

wxSize	GetDefaultSize () const
	Get the size of the bitmap represented by this bundle in default resolution or, equivalently, at 100% scaling. More...

wxSize	GetPreferredBitmapSizeAtScale (double scale) const
	Get the size that would be best to use for this bundle at the given DPI scaling factor. More...

wxSize	GetPreferredBitmapSizeFor (const wxWindow *window) const
	Get the size that would be best to use for this bundle at the DPI scaling factor used by the given window. More...

wxSize	GetPreferredLogicalSizeFor (const wxWindow *window) const
	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. More...

wxBitmap	GetBitmap (const wxSize &size) const
	Get bitmap of the specified size, creating a new bitmap from the closest available size by rescaling it if necessary. More...

wxBitmap	GetBitmapFor (const wxWindow *window) const
	Get bitmap of the size appropriate for the DPI scaling used by the given window. More...

wxIcon	GetIcon (const wxSize &size) const
	Get icon of the specified size. More...

wxIcon	GetIconFor (const wxWindow *window) const
	Get icon of the size appropriate for the DPI scaling used by the given window. More...

bool	IsSameAs (const wxBitmapBundle &other) const
	Check if the two bundles refer to the same object. More...

Static Public Member Functions
static wxBitmapBundle	FromBitmaps (const wxVector< wxBitmap > &bitmaps)
	Create a bundle from the given collection of bitmaps. More...

static wxBitmapBundle	FromBitmaps (const wxBitmap &bitmap1, const wxBitmap &bitmap2)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...

static wxBitmapBundle	FromBitmap (const wxBitmap &bitmap)
	Create a bundle from a single bitmap. More...

static wxBitmapBundle	FromIconBundle (const wxIconBundle &iconBundle)
	Create a bundle from an icon bundle. More...

static wxBitmapBundle	FromImage (const wxImage &image)
	Create a bundle from a single image. More...

static wxBitmapBundle	FromImpl (wxBitmapBundleImpl *impl)
	Create a bundle from a custom bitmap bundle implementation. More...

static wxBitmapBundle	FromResources (const wxString &name)
	Create a bundle from the bitmaps in the application resources. More...

static wxBitmapBundle	FromFiles (const wxString &path, const wxString &filename, const wxString &extension="png")
	Create a bundle from bitmaps stored as files. More...

static wxBitmapBundle	FromFiles (const wxString &fullpathname)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...

static wxBitmapBundle	FromSVG (char *data, const wxSize &sizeDef)
	Create a bundle from the SVG image. More...

static wxBitmapBundle	FromSVG (const char *data, const wxSize &sizeDef)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...

static wxBitmapBundle	FromSVG (const wxByte *data, size_t len, const wxSize &sizeDef)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...

static wxBitmapBundle	FromSVGFile (const wxString &path, const wxSize &sizeDef)
	Create a bundle from the SVG image loaded from the given file. More...

static wxBitmapBundle	FromSVGResource (const wxString &name, const wxSize &sizeDef)
	Create a bundle from the SVG image loaded from an application resource. More...

Constructor & Destructor Documentation

◆ wxBitmapBundle() [1/6]

wxBitmapBundle::wxBitmapBundle ( )

Default constructor constructs an empty bundle.

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

◆ wxBitmapBundle() [2/6]

wxBitmapBundle::wxBitmapBundle ( const wxBitmap & 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 wxBitmap.

◆ wxBitmapBundle() [3/6]

wxBitmapBundle::wxBitmapBundle ( const wxIcon & 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 wxIcon.

◆ wxBitmapBundle() [4/6]

wxBitmapBundle::wxBitmapBundle ( const wxImage & image )

Conversion constructor from a single image.

Similarly to the constructor from wxBitmap, this constructor only exists for interoperability with the existing code using wxImage and can be replaced with more readable FromImage() in the new code.

◆ wxBitmapBundle() [5/6]

wxBitmapBundle::wxBitmapBundle ( const char *const * xpm )

Conversion constructor from XPM data.

This constructor overload exists only for compatibility with the existing code passing XPM data (e.g. foo_xpm after including foo.xpm) directly to the functions expecting a bitmap. Don't use it in the new code, as it is likely to be deprecated in the future.

Since: 3.2.0

◆ wxBitmapBundle() [6/6]

wxBitmapBundle::wxBitmapBundle ( const wxBitmapBundle & other )

Copy constructor creates a copy of another bundle.

Member Function Documentation

◆ Clear()

void wxBitmapBundle::Clear ( )

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.

Since: 3.1.7

◆ FromBitmap()

static wxBitmapBundle wxBitmapBundle::FromBitmap ( const wxBitmap & bitmap )

static

Create a bundle from a single bitmap.

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

If bitmap is invalid, empty bundle is returned.

◆ FromBitmaps() [1/2]

static wxBitmapBundle wxBitmapBundle::FromBitmaps	(	const wxBitmap &	bitmap1,
		const wxBitmap &	bitmap2
	)

static

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

◆ FromBitmaps() [2/2]

static wxBitmapBundle wxBitmapBundle::FromBitmaps ( const wxVector< wxBitmap > & bitmaps )

static

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.

◆ FromFiles() [1/2]

static wxBitmapBundle wxBitmapBundle::FromFiles ( const wxString & fullpathname )

static

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

◆ FromFiles() [2/2]

static wxBitmapBundle wxBitmapBundle::FromFiles	(	const wxString &	path,
		const wxString &	filename,
		const wxString &	extension = `"png"`
	)

static

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	Path of the directory containing the files
filename	Bitmap's filename without any scale suffix
extension	File extension, without leading dot (`png` by default)

◆ FromIconBundle()

static wxBitmapBundle wxBitmapBundle::FromIconBundle ( const wxIconBundle & iconBundle )

static

Create a bundle from an icon bundle.

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

Since: 3.1.7

◆ FromImage()

static wxBitmapBundle wxBitmapBundle::FromImage ( const wxImage & image )

static

Create a bundle from a single image.

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

If image is invalid, empty bundle is returned.

◆ FromImpl()

static wxBitmapBundle wxBitmapBundle::FromImpl ( wxBitmapBundleImpl * impl )

static

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

Parameters

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

◆ FromResources()

static wxBitmapBundle wxBitmapBundle::FromResources ( const wxString & name )

static

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 .rc) containing PNG file, and any other resources using 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.

See also: FromSVGResource()

◆ FromSVG() [1/3]

static wxBitmapBundle wxBitmapBundle::FromSVG	(	char *	data,
		const wxSize &	sizeDef
	)

static

Create a bundle from the SVG image.

Please note that the current implementation uses NanoSVG library (https://github.com/memononen/nanosvg) for parsing and rasterizing SVG images which imposes the following limitations:

Text elements are not supported at all (see note for workaround).
SVG 1.1 filters are not supported.
Embedded images are not supported (see note for workaround).

These limitations will be relaxed in the future wxWidgets versions.

Please also note that this method is only available in the ports providing raw bitmap access via wxPixelData. This is the case for all tier-1 ports, but not all of them, check if wxHAS_SVG is defined before using this method if for maximum portability.

Parameters

data This data may, or not, have the XML document preamble, i.e. it can start either with "<?xml" processing instruction or directly with svg tag. For NUL-terminated string, two overloads of this function, taking const and non-const data, are provided: as the current implementation modifies the data while parsing, using the non-const variant is more efficient, as it avoids making copy of the data, but the data is consumed by it and can't be reused any more. For non-NUL-terminated data, the third overload, taking an extra parameter explicitly specifying the length of the input data, must be used.

sizeDef The default size to return from GetDefaultSize() for this bundle. As SVG images usually don't have any natural default size, it should be provided when creating the bundle.

Note: Converting text objects to path objects will allow them to be rasterized as expected. This can be done in an SVG editor such as Inkscape. (In Inkscape, select a text object and choose "Object to Path" from the "Path" menu.)
Converting embedded images to paths from an SVG editor will allow them to be rasterized. For example, selecting "Trace Bitmap" from the "Path" menu in Inkscape can perform this. This is only recommended for simple images, however, as more complex images may not rasterize well.

◆ FromSVG() [2/3]

static wxBitmapBundle wxBitmapBundle::FromSVG	(	const char *	data,
		const wxSize &	sizeDef
	)

static

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

◆ FromSVG() [3/3]

static wxBitmapBundle wxBitmapBundle::FromSVG	(	const wxByte *	data,
		size_t	len,
		const wxSize &	sizeDef
	)

static

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

◆ FromSVGFile()

static wxBitmapBundle wxBitmapBundle::FromSVGFile	(	const wxString &	path,
		const wxSize &	sizeDef
	)

static

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

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

Parameters

path	Path to the SVG file. Notice that it should a local file, not an URL.
sizeDef	The default size to return from GetDefaultSize() for this bundle.

◆ FromSVGResource()

static wxBitmapBundle wxBitmapBundle::FromSVGResource	(	const wxString &	name,
		const wxSize &	sizeDef
	)

static

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.

Parameters

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.
sizeDef	The default size to return from GetDefaultSize() for this bundle.

See also: FromResources(), FromSVGFile()

◆ GetBitmap()

wxBitmap wxBitmapBundle::GetBitmap ( const wxSize & size ) const

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.

Parameters

size	The size of the bitmap to return, in physical pixels. If this parameter is wxDefaultSize, default bundle size is used.

◆ GetBitmapFor()

wxBitmap wxBitmapBundle::GetBitmapFor ( const wxWindow * window ) const

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

This helper function simply combines GetPreferredBitmapSizeFor() and 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.

Parameters

window Non-null and fully created window.

◆ GetDefaultSize()

wxSize wxBitmapBundle::GetDefaultSize ( ) const

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.

◆ GetIcon()

wxIcon wxBitmapBundle::GetIcon ( const wxSize & size ) const

Get icon of the specified size.

This is just a convenient wrapper for GetBitmap() and simply converts the returned bitmap to wxIcon.

◆ GetIconFor()

wxIcon wxBitmapBundle::GetIconFor ( const wxWindow * window ) const

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

This is similar to GetBitmapFor(), but returns a wxIcon, as GetIcon() does.

Parameters

window Non-null and fully created window.

◆ GetPreferredBitmapSizeAtScale()

wxSize wxBitmapBundle::GetPreferredBitmapSizeAtScale ( double scale ) const

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. GetDefaultSize() multiplied by scale.

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

◆ GetPreferredBitmapSizeFor()

wxSize wxBitmapBundle::GetPreferredBitmapSizeFor ( const wxWindow * window ) const

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 GetPreferredBitmapSizeAtScale() calling that function with the result of wxWindow::GetDPIScaleFactor().

Parameters

window Non-null and fully created window.

◆ GetPreferredLogicalSizeFor()

wxSize wxBitmapBundle::GetPreferredLogicalSizeFor ( const wxWindow * window ) const

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 GetPreferredBitmapSizeAtScale() with the result of wxWindow::GetDPIScaleFactor() and convert returned value with wxWindow::FromPhys().

Parameters

window Non-null and fully created window.

◆ IsOk()

bool wxBitmapBundle::IsOk ( ) const

Check if bitmap bundle is non-empty.

Return true if the bundle contains any bitmaps or false if it is empty.

◆ IsSameAs()

bool wxBitmapBundle::IsSameAs ( const wxBitmapBundle & other ) const

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.

◆ operator=()

wxBitmapBundle& wxBitmapBundle::operator= ( const wxBitmapBundle & other )

Assignment operator makes this bundle a copy of another bundle.

Detailed Description

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

◆ wxBitmapBundle() [1/6]

◆ wxBitmapBundle() [2/6]

◆ wxBitmapBundle() [3/6]

◆ wxBitmapBundle() [4/6]

◆ wxBitmapBundle() [5/6]

◆ wxBitmapBundle() [6/6]

Member Function Documentation

◆ Clear()

◆ FromBitmap()

◆ FromBitmaps() [1/2]

◆ FromBitmaps() [2/2]

◆ FromFiles() [1/2]

◆ FromFiles() [2/2]

◆ FromIconBundle()

◆ FromImage()

◆ FromImpl()

◆ FromResources()

◆ FromSVG() [1/3]

◆ FromSVG() [2/3]

◆ FromSVG() [3/3]

◆ FromSVGFile()

◆ FromSVGResource()

◆ GetBitmap()

◆ GetBitmapFor()

◆ GetDefaultSize()

◆ GetIcon()

◆ GetIconFor()

◆ GetPreferredBitmapSizeAtScale()

◆ GetPreferredBitmapSizeFor()

◆ GetPreferredLogicalSizeFor()

◆ IsOk()

◆ IsSameAs()

◆ operator=()