wx(3)

👑 NAME 👑

wx — a port of wxWidgets. That's it, that's the whole name section, bestie. This page ships as wx(3) in the Erlang module docs, version wx 2.6, courtesy of Ericsson AB. 💅

---

✨ DESCRIPTION ✨

okay so first things first: this is the base api of wxWidgets. This module is where you get the functions that start and stop the wx-server, plus a bunch of other little utility functions. The essentials, the main character functions, if you will. 🌟

Big vibe check: wxWidgets is object oriented, and not functional. So in Wx, a module represents a class, and the object made by that class has its own type, wxCLASS(). This module right here represents the base class, and literally every other wxMODULE out there is a sub-class of this one. It's giving founder energy. 🫶

Objects of a class get created with wxCLASS:new(...) and yeeted out of existence with wxCLASS:destroy(). Member functions get called like wxCLASS:member(Object, ...) — not like C++ does it with Object.member(...). Different syntax, same dreams.

Sub class modules inherit (non static) functions from their parents. And heads up: the inherited functions are not documented in the sub-classes. So don't go looking for them there, they're just vibing invisibly. 🙈

This erlang port of wxWidgets tries to be a one-to-one mapping with the original wxWidgets library. Some things are different though, because the optional arguments use property lists and can be in any order. And the main difference is the event handling, which is different from the original library. Go see wxEvtHandler for that whole situation. iykyk.

The following classes are implemented directly as erlang types: wxPoint={x,y}, wxSize={w,h}, wxRect={x,y,w,h}, wxColour={r,g,b [,a]}, wxString=unicode:chardata(), wxGBPosition={r,c}, wxGBSpan={rs,cs}, wxGridCellCoords={r,c}.

Also: wxWidgets uses a process specific environment, and that's created by wx:new/0. If you wanna use that environment from other processes, call get_env/0 to retrieve the environment and set_env/1 to assign the environment in the other process. Sharing is caring. 💖

Global (classless) functions are located in the wx_misc module. Slay.

🌸 DATA TYPES 🌸

(these are the quick lil ones listed up in the description, before the fancy formal section)

• wx_colour() = {R::byte(), G::byte(), B::byte()} | wx_colour4()
• wx_colour4() = {R::byte(), G::byte(), B::byte(), A::byte()}
• wx_datetime() = {{Year::integer(), Month::integer(), Day::integer()}, {Hour::integer(), Minute::integer(), Second::integer()}} — in Local Timezone 🕰️
• wx_enum() = integer() — a Constant defined in wx.hrl
• wx_env() = #wx_env{} — Opaque process environment
• wx_memory() = binary() | #wx_mem{} — Opaque memory reference
• wx_object() = #wx_ref{} — Opaque object reference
• wx_wxHtmlLinkInfo() = #wxHtmlLinkInfo{href=unicode:chardata(), target=unicode:chardata()}
• wx_wxMouseState() = #wxMouseState{x=integer(), y=integer(), leftDown=boolean(), middleDown=boolean(), rightDown=boolean(), controlDown=boolean(), shiftDown=boolean(), altDown=boolean(), metaDown=boolean(), cmdDown=boolean()} — See #wxMouseState{} defined in wx.hrl

---

🦋 DATA TYPES 🦋

aight, here's the formal, dressed-up version of the same crew:

wx_colour()

{R :: byte(), G :: byte(), B :: byte()} | wx_colour4().

wx_colour4()

{R :: byte(), G :: byte(), B :: byte(), A :: byte()}.

wx_datetime()

{{Year :: integer(), Month :: integer(), Day :: integer()},
 {Hour :: integer(), Minute :: integer(), Second :: integer()}}.

wx_enum()

integer().

wx_env()

#wx_env{}.

wx_memory()

binary() | #wx_mem{}.

wx_object()

#wx_ref{}.

wx_wxHtmlLinkInfo()

#wxHtmlLinkInfo{}.

wx_wxMouseState()

#wxMouseState{}.

---

🎀 FUNCTIONS 🎀

batch(function()) -> term().

Batches all wx commands used in the fun. It improves performance of the command processing by grabbing the wxWidgets thread so that no event processing will be done before the complete batch of commands is invoked. Efficiency queen. 👑

See also: foldl/3, foldr/3, foreach/2, map/2.

create_memory(Size :: integer()) -> wx_memory().

Creates a memory area (of Size in bytes) which can be used by an external library (i.e. opengl). It is up to the client to keep a reference to this object so it does not get garbage collected by erlang while still in use by the external library.

⚠️ bestie listen to me: this is far from erlang's intentional usage and can crash the erlang emulator. Use it carefully. fr fr.

debug(Level | [Level]) -> ok when Level :: none | verbose | trace | driver | integer().

Sets debug level. If debug level is 'verbose' or 'trace' each call is printed on console. If Level is 'driver' each allocated object and deletion is printed on the console. Maximum yapping mode, activated. 🗣️

demo() -> ok | {error, atom()}.

Starts a Wx demo if examples directory exists and is compiled.

destroy() -> ok.

Stops a wx server. bye bestie 👋

equal(Ref1 :: wx_object(), Ref2 :: wx_object()) -> boolean().

Returns true if both arguments references the same object, false otherwise.

foldl(function(), term(), list()) -> term().

Behaves like lists:foldl/3 but batches wx commands. See batch/1.

foldr(function(), term(), list()) -> term().

Behaves like lists:foldr/3 but batches wx commands. See batch/1.

foreach(function(), list()) -> ok.

Behaves like lists:foreach/2 but batches wx commands. See batch/1.

getObjectType(Wx_ref :: wx_object()) -> atom().

Returns the object type. 🔍

get_env() -> wx_env().

Gets this process's current wx environment. Can be sent to other processes to allow them use this process wx environment. Sharing the vibe across processes, iconic. ✨

See also: set_env/1.

get_memory_bin(Wx_mem :: wx_memory()) -> binary().

Returns the memory area as a binary.

is_null(Wx_ref :: wx_object()) -> boolean().

Returns true if object is null, false otherwise.

map(function(), list()) -> list().

Behaves like lists:map/2 but batches wx commands. See batch/1.

new() -> wx_object().

Starts a wx server. ✨ the beginning ✨

new([Option]) -> wx_object() when Option :: {debug, list() | atom()} | {silent_start, boolean()}.

Starts a wx server.

Option may be {debug, Level}, see debug/1. Or {silent_start, Bool}, which causes error messages at startup to be suppressed. The latter can be used as a silent test of whether wx is properly installed or not. Sneaky little diagnostic moment, we love to see it. 🕵️

null() -> wx_object().

Returns the null object.

parent_class(Wx_ref :: wx_object()) -> boolean().

(no description on this one bestie, it's just out here existing 🫥)

release_memory(Wx_mem :: wx_memory()) -> ok.

Releases the memory retained by retain_memory/1.

retain_memory(Wx_mem :: wx_memory()) -> ok.

Saves the memory from deletion until release_memory/1 is called. If release_memory/1 is not called the memory will not be garbage collected. 💀

set_env(Wx_env :: wx_env()) -> ok.

Sets the process wx environment, allows this process to use another process wx environment.

subscribe_events() -> ok.

Adds the calling process to the list of of processes that are listening to wx application events.

At the moment these are all MacOSX specific events corresponding to MacNewFile() and friends from wxWidgets wxApp:

• {new_file, ""}
• {open_file, Filename}
• {print_file, Filename}
• {open_url, Url}
• {reopen_app, ""}

The call always returns ok but will have sent any already received events to the calling process.

typeCast(wx_object(), atom()) -> wx_object().

Casts the object to class NewType. It is needed when using functions like wxWindow:findWindow/2, which returns a generic wxObject type. glow up for your objects 💅

---

aaaand that's the whole page, bestie!! 🎉 this absolute icon of a manual page comes to you from Ericsson AB, version wx 2.6, filed under wx(3). go forth and start your wx server. periodt. 💖✨🦋