Class: Wx::BitmapBundle

Inherits:
Object
  • Object
show all
Defined in:
lib/wx/doc/gen/bitmap.rb

Overview

Note:

This class is untracked and should not be derived from nor instances extended!

Contains representations of the same bitmap in different resolutions.

This class generalizes 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 BitmapBundle can be passed to functions such as ToolBar#add_tool 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 BitmapBundleImpl. - A single Bitmap or Image for backwards compatibility. Objects of 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 BitmapBundle.from_bitmaps instead of using the real constructors.

class MyFrame < Wx::Frame
    
    def initialize
      super(nil, Wx::ID_ANY, "My frame")
      # ...
      tool_bar = create_toolBar
   
      bitmaps = [
          Wx::Bitmap(:open_32x32, Wx::BitmapType::BITMAP_TYPE_PNG),
          Wx::Bitmap(:open_48x48, Wx::BitmapType::BITMAP_TYPE_PNG),
          Wx::Bitmap(:open_64x64, Wx::BitmapType::BITMAP_TYPE_PNG)
        ]
 
      tool_bar.add_tool(Wx::ID_OPEN, "Open", Wx::BitmapBundle.from_bitmaps(bitmaps))
    end

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#get_preferred_bitmap_size_at_scale. 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.

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

Category: Graphics Device Interface (GDI)

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Wx::BitmapBundle #initialize(bitmap) ⇒ Wx::BitmapBundle #initialize(icon) ⇒ Wx::BitmapBundle #initialize(image) ⇒ Wx::BitmapBundle #initialize(other) ⇒ Wx::BitmapBundle

Returns a new instance of BitmapBundle.

Overloads:

  • #initialize ⇒ Wx::BitmapBundle

    Default constructor constructs an empty bundle.

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

  • #initialize(bitmap) ⇒ Wx::BitmapBundle

    Conversion constructor from a single bitmap.

    This constructor does the same thing as from_bitmap and only exists for interoperability with the existing code using Wx::Bitmap.

    Parameters:

  • #initialize(icon) ⇒ Wx::BitmapBundle

    Conversion constructor from a single icon.

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

    Parameters:

  • #initialize(image) ⇒ Wx::BitmapBundle

    Conversion constructor from a single image.

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

    Parameters:

  • #initialize(other) ⇒ Wx::BitmapBundle

    Copy constructor creates a copy of another bundle.

    Parameters:



480
 
# File 'lib/wx/doc/gen/bitmap.rb', line 480

def initialize(*args) end

Class Method Details

.from_bitmap(bitmap) ⇒ Wx::BitmapBundle

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:

Returns:



588
 
# File 'lib/wx/doc/gen/bitmap.rb', line 588

def self.from_bitmap(bitmap) end

.self.from_bitmaps(bitmaps) ⇒ Wx::BitmapBundle .self.from_bitmaps(bitmap1, bitmap2) ⇒ Wx::BitmapBundle

Overloads:

  • .self.from_bitmaps(bitmaps) ⇒ Wx::BitmapBundle

    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:

    Returns:

  • .self.from_bitmaps(bitmap1, bitmap2) ⇒ Wx::BitmapBundle

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

    Parameters:

    Returns:



580
 
# File 'lib/wx/doc/gen/bitmap.rb', line 580

def self.from_bitmaps(*args) end

.self.from_files(path, filename, extension = ("PNG")) ⇒ Wx::BitmapBundle .self.from_files(fullpathname) ⇒ Wx::BitmapBundle

Overloads:

  • .self.from_files(path, filename, extension = ("PNG")) ⇒ Wx::BitmapBundle

    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) (defaults to: ("PNG")) —

      File extension, without leading dot (png by default)

    Returns:

  • .self.from_files(fullpathname) ⇒ Wx::BitmapBundle

    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)

    Returns:



617
 
# File 'lib/wx/doc/gen/bitmap.rb', line 617

def self.from_files(*args) end

.from_icon_bundle(iconBundle) ⇒ Wx::BitmapBundle

Create a bundle from an icon bundle.

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

Parameters:

Returns:



595
 
# File 'lib/wx/doc/gen/bitmap.rb', line 595

def self.from_icon_bundle(iconBundle) end

.from_image(image) ⇒ Wx::BitmapBundle

Create a bundle from a single image.

This is only useful for compatibility with the existing code using Image. If image is invalid, empty bundle is returned.

Parameters:

Returns:



603
 
# File 'lib/wx/doc/gen/bitmap.rb', line 603

def self.from_image(image) end

.from_svg(data, sizeDef) ⇒ Wx::BitmapBundle

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

Parameters:

  • data (String)
  • sizeDef (Array(Integer, Integer), Wx::Size)

Returns:



623
 
# File 'lib/wx/doc/gen/bitmap.rb', line 623

def self.from_svg(data, sizeDef) end

.from_svg_file(path, sizeDef) ⇒ Wx::BitmapBundle

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

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

Parameters:

  • path (String) —

    Path to the SVG file. Notice that it should a local file, not an URL.

  • sizeDef (Array(Integer, Integer), Wx::Size) —

    The default size to return from #get_default_size for this bundle.

Returns:



631
 
# File 'lib/wx/doc/gen/bitmap.rb', line 631

def self.from_svg_file(path, sizeDef) end

Instance Method Details

#clear ⇒ void

This method returns an undefined value.

Clear the existing bundle contents.

After calling this function #is_ok returns false. This is the same as assigning a default-constructed bitmap bundle to this object but slightly more explicit.



487
 
# File 'lib/wx/doc/gen/bitmap.rb', line 487

def clear; end

#get_bitmap(size) ⇒ Wx::Bitmap Also known as: bitmap

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 (Array(Integer, Integer), Wx::Size) —

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

Returns:



534
 
# File 'lib/wx/doc/gen/bitmap.rb', line 534

def get_bitmap(size) end

#get_bitmap_for(window) ⇒ Wx::Bitmap Also known as: bitmap_for

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

This helper function simply combines #get_preferred_bitmap_size_for and #get_bitmap, 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 (Wx::Window) —

    Non-null and fully created window.

Returns:



542
 
# File 'lib/wx/doc/gen/bitmap.rb', line 542

def get_bitmap_for(window) end

#get_default_size ⇒ Wx::Size Also known as: default_size

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.

Returns:



501
 
# File 'lib/wx/doc/gen/bitmap.rb', line 501

def get_default_size; end

#get_icon(size) ⇒ Wx::Icon Also known as: icon

Get icon of the specified size.

This is just a convenient wrapper for #get_bitmap and simply converts the returned bitmap to Icon.

Parameters:

  • size (Array(Integer, Integer), Wx::Size)

Returns:



550
 
# File 'lib/wx/doc/gen/bitmap.rb', line 550

def get_icon(size) end

#get_icon_for(window) ⇒ Wx::Icon Also known as: icon_for

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

This is similar to #get_bitmap_for, but returns a Icon, as #get_icon does.

Parameters:

  • window (Wx::Window) —

    Non-null and fully created window.

Returns:



558
 
# File 'lib/wx/doc/gen/bitmap.rb', line 558

def get_icon_for(window) end

#get_preferred_bitmap_size_at_scale(scale) ⇒ Wx::Size Also known as: preferred_bitmap_size_at_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. #get_default_size multiplied by scale. Passing a size returned by this function to #get_bitmap ensures that bitmap doesn’t need to be rescaled, which typically significantly lowers its quality.

Parameters:

  • scale (Float)

Returns:



510
 
# File 'lib/wx/doc/gen/bitmap.rb', line 510

def get_preferred_bitmap_size_at_scale(scale) end

#get_preferred_bitmap_size_for(window) ⇒ Wx::Size Also known as: preferred_bitmap_size_for

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 #get_preferred_bitmap_size_at_scale calling that function with the result of Window#get_dpi_scale_factor.

Parameters:

  • window (Wx::Window) —

    Non-null and fully created window.

Returns:



518
 
# File 'lib/wx/doc/gen/bitmap.rb', line 518

def get_preferred_bitmap_size_for(window) end

#get_preferred_logical_size_for(window) ⇒ Wx::Size Also known as: preferred_logical_size_for

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 #get_preferred_bitmap_size_at_scale with the result of Window#get_dpi_scale_factor and convert returned value with Window#from_phys.

Parameters:

  • window (Wx::Window) —

    Non-null and fully created window.

Returns:



526
 
# File 'lib/wx/doc/gen/bitmap.rb', line 526

def get_preferred_logical_size_for(window) end

#is_ok ⇒ Boolean Also known as: ok?

Check if bitmap bundle is non-empty.

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

Returns:

  • (Boolean) 


493
 
# File 'lib/wx/doc/gen/bitmap.rb', line 493

def is_ok; end

#is_same_as(other) ⇒ Boolean Also known as: same_as?

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.

Parameters:

Returns:

  • (Boolean) 


566
 
# File 'lib/wx/doc/gen/bitmap.rb', line 566

def is_same_as(other) end