wxArtProvider(3erl)

🌸 NAME 🌸

wxArtProvider — functions for the wxArtProvider class. This is the wxArtProvider(3erl) page from the Erlang Module Definition manual, bestie. 💅

✨ DESCRIPTION ✨

Okay so the wxArtProvider class is the glow-up tool for customizing how a wxWidgets application looks. 🎀

When wxWidgets needs to show an icon or a bitmap — like in the standard file dialog — it does not use a hard-coded resource. Nope. It asks wxArtProvider for it instead. It's giving “plug in your own wxArtProvider class and replace standard art with your own version” energy, and it's honestly slay. 🦋

All you need to do is derive a class from wxArtProvider, override either its wxArtProvider::CreateBitmap() (not implemented in wx) and/or its wxArtProvider::CreateIconBundle() (not implemented in wx) methods, and register the provider with wxArtProvider::Push() (not implemented in wx):

If you need bitmap images (of the same artwork) that should display at different sizes, you should probably consider overriding wxArtProvider::CreateIconBundle (not implemented in wx) and supplying icon bundles that contain different bitmap sizes. ✨

There's another way to take advantage of this class too: use it in your code and use platform native icons as provided by getBitmap/2 or getIcon/2. 👑

🎨 Identifying art resources 🎨

Every bitmap and icon bundle is known to wxArtProvider under a unique ID, and that ID is what's used when requesting a resource from it. The ID is represented by the ?wxArtID type and can have one of these predefined values (you can see the bitmaps represented by these constants in page_samples_artprov):

Additionally, any string recognized by custom art providers registered using wxArtProvider::Push (not implemented in wx) may be used.

Note: When running under GTK+ 2, GTK+ stock item IDs (e.g. "gtk-cdrom") may be used as well. For a list of the GTK+ stock items, please refer to the GTK+ documentation page. It's also possible to load icons from the current icon theme by specifying their name (without extension and directory components). Icon themes recognized by GTK+ follow the freedesktop.org Icon Themes specification. And heads up: themes are not guaranteed to contain all icons, so wxArtProvider may return ?wxNullBitmap or ?wxNullIcon. The default theme is typically installed in /usr/share/icons/hicolor. 💀

🫶 Clients 🫶

The client is the entity that calls wxArtProvider's getBitmap/2 or getIcon/2 function. It's represented by the wxClientID type and can have one of these values:

Client ID serves as a hint to wxArtProvider that's supposed to help it choose the best-looking bitmap. For example, it's often desirable to use slightly different icons in menus and toolbars even though they represent the same action (e.g. wxART_FILE_OPEN). But remember: this is really only a hint for wxArtProvider — it's common that getBitmap/2 returns an identical bitmap for different client values! 😭

See: Examples, wxArtProvider, usage; stock ID list

wxWidgets docs: wxArtProvider

🎀 DATA TYPES 🎀

Only one data type here, and it's short and sweet:

wxArtProvider() = wx:wx_object()

🔥 EXPORTS 🔥

getBitmap(Id) -> wxBitmap:wxBitmap()

Types:

Id = unicode:chardata()

This is the one-arg version — you pass an Id, and that's the whole request. 💖

getBitmap(Id, Options :: [Option]) -> wxBitmap:wxBitmap()

Types:

Id = unicode:chardata()
Option =
    {client, unicode:chardata()} |
    {size, {W :: integer(), H :: integer()}}

Query registered providers for a bitmap with the given ID. In other words: “hey registered providers, do y'all recognize this ID?” No cap, that's the whole ask.

Return: The bitmap if one of the registered providers recognizes the ID; otherwise it's wxNullBitmap.

getIcon(Id) -> wxIcon:wxIcon()

Types:

Id = unicode:chardata()

The one-arg icon flavor. 🎀

getIcon(Id, Options :: [Option]) -> wxIcon:wxIcon()

Types:

Id = unicode:chardata()
Option =
    {client, unicode:chardata()} |
    {size, {W :: integer(), H :: integer()}}

Same as getBitmap/2, but it returns a wxIcon object (or ?wxNullIcon on failure). Iconic, literally. 🦋

---

💖 source/version check: wxWidgets team · wx 2.2.2.1 · page wxArtProvider(3erl) — date? the footer didn't list one, so I'm not inventing it, bestie. That's the whole manual page, periodt. 🫶