wxBitmap(3erl)

📦
version 25.3.2.8 · 5 versions
, in ubuntu noble

💅 wxBitmap(3erl) — the Erlang module definition, but make it make sense ✨

Okay bestie, welcome to wxBitmap(3erl), aka the page where we talk about the bitmap class and why it's lowkey iconic. Let's get into it 🫶

🌸 NAME 🌸

wxBitmap — literally just the functions for the wxBitmap class, no cap 💖

🎀 DESCRIPTION 🎀

So this class encapsulates the concept of a platform-dependent bitmap. It can be monochrome, or colour, or colour with alpha channel support — it's giving range, honestly 👑

If you need direct access to the bitmap data instead of going through drawing to it using wxMemoryDC, you need to use the wxPixelData (not implemented in wx) class. And that comes in two flavours, bestie:

  • wxNativePixelData — for RGB bitmaps
  • wxAlphaPixelData — for bitmaps with an additionally alpha channel

Also heads up: many wxBitmap functions take a type parameter, which is a value of the ?wxBitmapType enumeration. The validity of those values depends on the platform where your program is running and from the wxWidgets configuration. If all possible wxWidgets settings are used:

And in addition, wxBitmap can load and save all formats that wxImage can — see wxImage for more info. Of course, you must have loaded the wxImage handlers (see ?wxInitAllImageHandlers() and wxImage::AddHandler (not implemented in wx)). Note that all available wxBitmapHandlers for a given wxWidgets port are automatically loaded at startup, so you won't need to use wxBitmap::AddHandler (not implemented in wx). Slay, one less thing to do 🙈

More on the difference between wxImage and wxBitmap, because this is the part where it gets juicy: wxImage is just a buffer of RGB bytes with an optional buffer for the alpha bytes. It is all generic, platform independent and image file format independent code. It includes generic code for scaling, resizing, clipping, and other manipulations of the image data. OTOH, wxBitmap is intended to be a wrapper of whatever is the native image format that is quickest/easiest to draw to a DC or to be the target of the drawing operations performed on a wxMemoryDC. By splitting the responsibilities between wxImage/wxBitmap like this, then it's easier to use generic code shared by all platforms and image types for generic operations, and platform specific code where performance or compatibility is needed. It's giving "you do you, I'll do me" in the healthiest way possible 💅

Predefined objects (include wx.hrl): ?wxNullBitmap — she's the main character of empty bitmaps, periodt 💀

See: Overview bitmap, Overview bitmap, wxDC:blit/6, wxIcon, wxCursor, wxMemoryDC, wxImage, wxPixelData (not implemented in wx)

wxWidgets docs: wxBitmap

🦋 DATA TYPES 🦋

  • wxBitmap() = wx:wx_object() — that's the whole type, bestie, short and sweet 🍓

✨ EXPORTS ✨

Exports o'clock, bestie 💅 — this is every function this module puts on the menu, with the signatures kept exactly as they are so you can scream “no cap” while copying them.

  • new() -> wxBitmap() — default constructor, the “no thoughts, head empty” bitmap. It constructs a bitmap object with no data; an assignment or another member function such as create/4 or loadFile/3 must be called subsequently.
  • new(Name) -> wxBitmap(), new(Sz) -> wxBitmap(), new(Img) -> wxBitmap() — the Name, Sz, and Img overloads. For the Img one, the type is Img = wxImage:wxImage() | wxBitmap:wxBitmap().
  • new(Width, Height) -> wxBitmap(), new(Name, Height :: [Option]) -> wxBitmap(), new(Sz, Height :: [Option]) -> wxBitmap(), new(Img, Height :: [Option]) -> wxBitmap() — the image-powered constructor crew 🦋.

Types: Img = wxImage:wxImage(); Option = {depth, integer()}.

Creates this bitmap object from the given image.

This has to be done to actually display an image as you cannot draw an image directly on a window.

The resulting bitmap will use the provided colour depth (or that of the current system if depth is ?wxBITMAP_SCREEN_DEPTH) which entails that a colour reduction may take place.

On Windows, if there is a palette present (set with SetPalette), it will be used when creating the wxBitmap (most useful in 8-bit display mode). On other platforms, the palette is currently ignored.

  • new(Bits, Width, Height) -> wxBitmap(), new(Width, Height, Height :: [Option]) -> wxBitmap() — fresh bitmap, new you ✨.

Types: Width = Height = integer(); Option = {depth, integer()}.

Creates a new bitmap.

A depth of ?wxBITMAP_SCREEN_DEPTH indicates the depth of the current screen or visual.

Some platforms only support 1 for monochrome and ?wxBITMAP_SCREEN_DEPTH for the current colour setting.

A depth of 32 including an alpha channel is supported under MSW, Mac and GTK+.

  • new(Bits, Width, Height, Options :: [Option]) -> wxBitmap() — bitmap from raw bits, very demure, very mindful 🎀.

Types: Bits = binary(); Width = Height = integer(); Option = {depth, integer()}.

Creates a bitmap from the given array bits.

You should only use this function for monochrome bitmaps (depth 1) in portable programs: in this case the bits parameter should contain an XBM image.

For other bit depths, the behaviour is platform dependent: under Windows, the data is passed without any changes to the underlying CreateBitmap() API. Under other platforms, only monochrome bitmaps may be created using this constructor and wxImage should be used for creating colour bitmaps from static data.

  • destroy(This :: wxBitmap()) -> ok — okay, the page takes a little side-quest here 😭. It starts with cursor-constructor text: “Creates bitmap corresponding to the given cursor.” This can be useful to display a cursor as it cannot be drawn directly on a window. This constructor only exists in wxMSW and wxGTK (where it is implemented for GTK+ 2.8 or later) only. Then it pivots to Since: 3.1.0 Destructor. See overview_refcount_destruct for more info.

If the application omits to delete the bitmap explicitly, the bitmap will be destroyed automatically by wxWidgets when the application exits.

Warning: Do not delete a bitmap that is selected into a memory device context.
  • convertToImage(This) -> wxImage:wxImage() — glow-up from bitmap to image 💖.

Types: This = wxBitmap().

Creates an image from a platform-dependent bitmap.

This preserves mask information so that bitmaps and images can be converted back and forth without loss in that respect.

  • copyFromIcon(This, Icon) -> boolean() — icon to bitmap, slay 🫶.

Types: This = wxBitmap(); Icon = wxIcon:wxIcon().

Creates the bitmap from an icon.

  • create(This, Sz) -> boolean() — the size-based create.

Types: This = wxBitmap(); Sz = {W :: integer(), H :: integer()}.

  • create(This, Width, Height) -> boolean(), create(This, Sz, Height :: [Option]) -> boolean() — more create energy, same icon behavior.

Types: This = wxBitmap(); Sz = {W :: integer(), H :: integer()}; Option = {depth, integer()}.

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

  • create(This, Width, Height, Options :: [Option]) -> boolean() — listed as its own overload.
  • create(This, Width, Height, Dc) -> boolean() — create with a DC, inheriting the magnification factor ✨.

Types: This = wxBitmap(); Width = Height = integer(); Dc = wxDC:wxDC().

Create a bitmap compatible with the given DC, inheriting its magnification factor.

Return: true if the creation was successful.

Since: 3.1.0

  • getDepth(This) -> integer() — tells you the colour depth, no cap.

Types: This = wxBitmap().

Gets the colour depth of the bitmap.

A value of 1 indicates a monochrome bitmap.

  • getHeight(This) -> integer() — height check, but make it pixels 📏.

Types: This = wxBitmap().

Gets the height of the bitmap in pixels.

See: getWidth/1, GetSize() (not implemented in wx).

  • getPalette(This) -> wxPalette:wxPalette() — palette reveal 🌈.

Types: This = wxBitmap().

Gets the associated palette (if any) which may have been loaded from a file or set for the bitmap.

See: wxPalette.

  • getMask(This) -> wxMask:wxMask() — mask check, very mysterious 💅.

Types: This = wxBitmap().

Gets the associated mask (if any) which may have been loaded from a file or set for the bitmap.

See: setMask/2, wxMask.

  • getWidth(This) -> integer() — width check, also in pixels.

Types: This = wxBitmap().

Gets the width of the bitmap in pixels.

See: getHeight/1, GetSize() (not implemented in wx).

  • getSubBitmap(This, Rect) -> wxBitmap() — crop that bitmap, but keep the details intact ✂️.

Types:

This = wxBitmap()
Rect =
    {X :: integer(),
     Y :: integer(),
     W :: integer(),
     H :: integer()}

Returns a sub bitmap of the current one as long as the rect belongs entirely to the bitmap.

This function preserves bit depth and mask information.

  • loadFile(This, Name) -> boolean() — load from file, basic bestie version.

Types: This = wxBitmap(); Name = unicode:chardata().

  • loadFile(This, Name, Options :: [Option]) -> boolean() — load from file or resource, with options 🍓.

Types: This = wxBitmap(); Name = unicode:chardata(); Option = {type, wx:wx_enum()}.

Loads a bitmap from a file or resource.

Return: true if the operation succeeded, false otherwise.

Remark: A palette may be associated with the bitmap if one exists (especially for colour Windows bitmaps), and if the code supports it. You can check if one has been created by using the getPalette/1 member.

See: saveFile/4.

  • ok(This) -> boolean() — quick vibe check 👀.

Types: This = wxBitmap().

See: isOk/1.

  • isOk(This) -> boolean() — true if the bitmap data is actually present, periodt.

Types: This = wxBitmap().

Returns true if bitmap data is present.

  • saveFile(This, Name, Type) -> boolean() — save that bitmap, main character energy 👑.

Types: This = wxBitmap(); Name = unicode:chardata(); Type = wx:wx_enum().

  • saveFile(This, Name, Type, Options :: [Option]) -> boolean() — save with extra palette options 🎨.

Types: This = wxBitmap(); Name = unicode:chardata(); Type = wx:wx_enum(); Option = {palette, wxPalette:wxPalette()}.

Saves a bitmap in the named file.

Return: true if the operation succeeded, false otherwise.

Remark: Depending on how wxWidgets has been configured, not all formats may be available.

See: loadFile/3.

  • setDepth(This, Depth) -> ok — deprecated, bestie, read the warning 😭.

Types: This = wxBitmap(); Depth = integer().

Deprecated: This function is deprecated since version 3.1.2, dimensions and depth can only be set at construction time.

Sets the depth member (does not affect the bitmap data).

  • setHeight(This, Height) -> ok — also deprecated, also only sets the member.

Types: This = wxBitmap(); Height = integer().

Deprecated: This function is deprecated since version 3.1.2, dimensions and depth can only be set at construction time.

Sets the height member (does not affect the bitmap data).

  • setMask(This, Mask) -> ok — mask time, very mysterious, very owned by the bitmap 🫶.

Types: This = wxBitmap(); Mask = wxMask:wxMask().

Sets the mask for this bitmap.

Remark: The bitmap object owns the mask once this has been called.

Note: A mask can be set also for bitmap with an alpha channel but doing so under wxMSW is not recommended because performance of drawing such bitmap is not very good.

See: getMask/1, wxMask.

  • setPalette(This, Palette) -> ok — palette assigned, except GTK+ said not today.

Types: This = wxBitmap(); Palette = wxPalette:wxPalette().

Sets the associated palette.

(Not implemented under GTK+).

See: wxPalette.

  • setWidth(This, Width) -> ok — deprecated width setter, still only touches the member.

Types: This = wxBitmap(); Width = integer().

Deprecated: This function is deprecated since version 3.1.2, dimensions and depth can only be set at construction time.

Sets the width member (does not affect the bitmap data).

That’s the whole export list, bestie — go make something iconic 🌈. The footer’s source/version stamp is wxWidgets team / wx 2.2.2.1 / wxBitmap(3erl) 🎀. Mwah 💋.

📦 where this page comes from