wx(3erl)

💖 NAME 💖

wx — A port of wxWidgets.

Manual-name check: this is the wx(3erl) page, a.k.a. the Erlang Module Definition. Hiii bestie, welcome to the base-class page. 🫶

✨ DESCRIPTION ✨

Okay so: this is a port of wxWidgets, and it's the base api of wxWidgets. This module has the functions for starting and stopping the wx-server, plus other utility functions. Slay. 💅

wxWidgets is object oriented, and not functional. So in wxErlang a module represents a class, and the object created by this class has its own type, wxCLASS(). This module represents the base class, and all other wxMODULE's are sub-classes of this class. Periodt.

Objects of a class are created with wxCLASS:new(...) and destroyed with wxCLASS:destroy(). Member functions are called with wxCLASS:member(Object, ...) instead of as in C++ Object.member(...). Not me explaining C++ syntax in an Erlang manpage, but here we are. 😭

Sub class modules inherit (non static) functions from their parents. The inherited functions are not documented in the sub-classes. So don't go looking for them there, bestie.

This erlang port of wxWidgets tries to be a one-to-one mapping with the original wxWidgets library. Some things are different though, as the optional arguments use property lists and can be in any order. The main difference is the event handling, which is different from the original library. See wxEvtHandler. 👑

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

wxWidgets uses a process specific environment, which is created by wx:new/0. To be able to use the environment from other processes, call get_env/0 to retrieve the environment and set_env/1 to assign the environment in the other process. Iconic process-env behavior, honestly. 🌈

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

---

🌈 DATA TYPES 🌈

• 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():

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.

• ```erlang wx_wxHtmlLinkInfo() = #wxHtmlLinkInfo{href=unicode:chardata(), target=unicode:chardata()}:

- ```erlang
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.

---

🎀 EXPORTS 🎀

• parent_class(X1) -> term() — that's the whole vibe. No extra notes in the original, bestie.
• new() -> wx_object() — starts a wx server. ✨
• new(Options::[Option]) -> wx_object() — starts a wx server.
  • Types:
    • Option = {debug, list() | atom()} | {silent_start, boolean()}

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. Lowkey useful. 🫶

• destroy() -> ok — stops a wx server.
• 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.

See also: set_env/1.

• 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. (Yes, "of of" is in the original. I'm just the messenger. 💀)

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.

• null() -> wx_object() — returns the null object.
• is_null(Wx_ref::wx_object()) -> boolean() — returns true if object is null, false otherwise.
• equal(Wx_ref::wx_object(), X2::wx_object()) -> boolean() — returns true if both arguments references the same object, false otherwise.
• getObjectType(Wx_ref::wx_object()) -> atom() — returns the object type.
• typeCast(Old::wx_object(), NewType::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.
• batch(Fun::function()) -> term() — batches all wx commands used in the fun. 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.

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

• foreach(Fun::function(), List::list()) -> ok — behaves like lists:foreach/2 but batches wx commands. See batch/1.
• map(Fun::function(), List::list()) -> list() — behaves like lists:map/2 but batches wx commands. See batch/1.
• foldl(Fun::function(), Acc::term(), List::list()) -> term() — behaves like lists:foldl/3 but batches wx commands. See batch/1.
• foldr(Fun::function(), Acc::term(), List::list()) -> term() — behaves like lists:foldr/3 but batches wx commands. See batch/1.
• 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: this is far from erlang's intentional usage and can crash the erlang emulator. Use it carefully. No cap. 💀

• get_memory_bin(Wx_mem::wx_memory()) -> binary() — returns the memory area as a binary.
• 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.
• release_memory(Wx_mem::wx_memory()) -> ok — no description in the original, just the signature. 🎀
• debug(Debug::Level | [Level]) -> ok — sets debug level.
  • Types:
    • Level = none | verbose | trace | driver | integer()

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.

• demo() -> ok | {error, atom()} — starts a wxErlang demo if examples directory exists and is compiled.

---

🦋 AUTHORS 🦋

<>

Mysterious. Iconic. No notes. 💅

---

Sign-off time, bestie: this page is rockin' the wx 2.2.2.1 source/version tag and the wx(3erl) manual name. The original footer doesn't show a date, so I'm not inventing one — we respect the facts in this group chat. 🫶✨