wx_object(3)

📦
version 29.0.6 · 3 versions
, in ubuntu stonking

💖 wx_object(3) 💖

Erlang Module Definition bestie, and today we're decoding wx_object, the generic wx object behaviour. buckle up, it's giving ✨architecture✨ and it's lowkey iconic.

🌸 NAME 🌸

wx_object — the generic wx object behaviour. yeah that's it, that's the whole name, she's simple and she knows it 💅

🦋 DESCRIPTION 🦋

okay so THIS is a behaviour module, and what it does is let you "sub class" wx objects. how does it work? it works like a regular gen_server module — like, exactly that energy — and it creates a server per object. one object, one server, no sharing, main character energy 🫶

⚠️ NOTE: Currently no form of inheritance is implemented. bestie. do not go looking for inheritance. she's not there. 💀

So your user module should export:

  • init(Args) — should return {wxWindow, State} | {wxWindow, State, Timeout} | ignore | {stop, Reason}

Asynchronous window event handling, bestie:

  • handle_event(#wx{}, State) — should return {noreply, State} | {noreply, State, Timeout} | {stop, Reason, State}

Your user module can export these callback functions too:

  • handle_call(Msg, {From, Tag}, State) — should return {reply, Reply, State} | {reply, Reply, State, Timeout} | {noreply, State} | {noreply, State, Timeout} | {stop, Reason, Reply, State}
  • handle_cast(Msg, State) — should return {noreply, State} | {noreply, State, Timeout} | {stop, Reason, State}
💀 If the above are not exported but called, the wx_object process will crash. no cap. not a vibe check you want to fail.

The user module can also export:

  • handle_info(Info, State) — where Info is a message, e.g. {'EXIT', P, R}, {nodedown, N}, ... and it should return {noreply, State} | {noreply, State, Timeout} | {stop, Reason, State}

If a message is sent to the wx_object process when handle_info is not exported, the message will be dropped and ignored. like, straight up ghosted 🙈

When stop is returned in one of the functions above with Reason = normal | shutdown | Term, terminate(State) is called. it lets the user module clean up, and fr fr it is always called when the server terminates or when wx_object() in the driver is deleted. and if the Parent process terminates, the Module:terminate/2 function is called: terminate(Reason, State)

🌈 Example 🌈

-module(myDialog).
-export([new/2, show/1, destroy/1]).  %% API
-export([init/1, handle_call/3, handle_event/2,
         handle_info/2, code_change/3, terminate/2]).
         new/2, showModal/1, destroy/1]).  %% Callbacks

%% Client API
new(Parent, Msg) ->
   wx_object:start(?MODULE, [Parent,Id], []).

show(Dialog) ->
   wx_object:call(Dialog, show_modal).

destroy(Dialog) ->
   wx_object:call(Dialog, destroy).

%% Server Implementation ala gen_server
init([Parent, Str]) ->
   Dialog = wxDialog:new(Parent, 42, "Testing", []),
   ...
   wxDialog:connect(Dialog, command_button_clicked),
   {Dialog, MyState}.

handle_call(show, _From, State) ->
   wxDialog:show(State#state.win),
   {reply, ok, State};
...
handle_event(#wx{}, State) ->
   io:format("Users clicked button~n",[]),
   {noreply, State};
...

📦 DATA TYPES 📦

  • request_id() = term()
  • server_ref() = wx:wx_object() | atom() | pid()

✨ DATA TYPES ✨

the big one. here's event(), and she is LONG, and every single variant is here because I do not skip, I do not summarise, I do not gatekeep 🎀

event() ::
          wxActivateEvent:wxActivate() |
          wxAuiManagerEvent:wxAuiManager() |
          wxAuiNotebookEvent:wxAuiNotebook() |
          wxBookCtrlEvent:wxBookCtrl() |
          wxCalendarEvent:wxCalendar() |
          wxChildFocusEvent:wxChildFocus() |
          wxClipboardTextEvent:wxClipboardText() |
          wxCloseEvent:wxClose() |
          wxColourPickerEvent:wxColourPicker() |
          wxCommandEvent:wxCommand() |
          wxContextMenuEvent:wxContextMenu() |
          wxDateEvent:wxDate() |
          wxDisplayChangedEvent:wxDisplayChanged() |
          wxDropFilesEvent:wxDropFiles() |
          wxEraseEvent:wxErase() |
          wxFileDirPickerEvent:wxFileDirPicker() |
          wxFocusEvent:wxFocus() |
          wxFontPickerEvent:wxFontPicker() |
          wxGridEvent:wxGrid() |
          wxHelpEvent:wxHelp() |
          wxHtmlLinkEvent:wxHtmlLink() |
          wxIconizeEvent:wxIconize() |
          wxIdleEvent:wxIdle() |
          wxInitDialogEvent:wxInitDialog() |
          wxJoystickEvent:wxJoystick() |
          wxKeyEvent:wxKey() |
          wxListEvent:wxList() |
          wxMaximizeEvent:wxMaximize() |
          wxMenuEvent:wxMenu() |
          wxMouseCaptureChangedEvent:wxMouseCaptureChanged() |
          wxMouseCaptureLostEvent:wxMouseCaptureLost() |
          wxMouseEvent:wxMouse() |
          wxMoveEvent:wxMove() |
          wxNavigationKeyEvent:wxNavigationKey() |
          wxPaintEvent:wxPaint() |
          wxPaletteChangedEvent:wxPaletteChanged() |
          wxQueryNewPaletteEvent:wxQueryNewPalette() |
          wxSashEvent:wxSash() |
          wxScrollEvent:wxScroll() |
          wxScrollWinEvent:wxScrollWin() |
          wxSetCursorEvent:wxSetCursor() |
          wxShowEvent:wxShow() |
          wxSizeEvent:wxSize() |
          wxSpinEvent:wxSpin() |
          wxSplitterEvent:wxSplitter() |
          wxStyledTextEvent:wxStyledText() |
          wxSysColourChangedEvent:wxSysColourChanged() |
          wxTaskBarIconEvent:wxTaskBarIcon() |
          wxTreeEvent:wxTree() |
          wxUpdateUIEvent:wxUpdateUI() |
          wxWebViewEvent:wxWebView() |
          wxWindowCreateEvent:wxWindowCreate() |
          wxWindowDestroyEvent:wxWindowDestroy().

request_id() :: term().

server_ref() :: Obj :: wx:wx_object() | atom() | pid().

💅 FUNCTIONS 💅

call

  • call(Obj, Request) -> term() — when Obj :: wx:wx_object() | atom() | pid(), Request :: term(). Make a call to a wx_object server. the call waits until it gets a result. invokes handle_call(Request, From, State) in the server 🫶
  • call(Obj, Request, Timeout) -> term() — when Obj :: wx:wx_object() | atom() | pid(), Request :: term(), Timeout :: integer(). Make a call to a wx_object server with a timeout. invokes handle_call(Request, From, State) in the server. so like, this one has a time limit bestie, it's not gonna wait forever ✨

cast

  • cast(Obj, Request) -> ok — when Obj :: wx:wx_object() | atom() | pid(), Request :: term(). Make a cast to a wx_object server. invokes handle_cast(Request, State) in the server. she returns ok and moves on, no waiting, that's the whole point 💅

check_response

  • check_response(Msg :: term(), Key :: request_id()) -> {reply, Reply :: term()} | false | {error, {term(), server_ref()}} — check if a received message was a reply to a RequestId 👑

get_pid

  • get_pid(Obj) -> pid() — when Obj :: wx:wx_object() | atom() | pid(). get the pid of the object handle 🎀

reply

  • reply({pid(), Tag :: term()}, Reply :: term()) -> pid() — get the pid of the object handle. (yeah, the docs literally say the exact same sentence as get_pid right above. i'm just the messenger bestie, i am not fixing it, that's what it says 😭)

send_request

  • send_request(Obj, Request :: term()) -> request_id() — when Obj :: wx:wx_object() | atom() | pid(). make a send_request to a generic server, and return a RequestId which can/should be used with wait_response/[1|2]. invokes handle_call(Request, From, State) in the server. 🦋

set_pid

  • set_pid(Obj, Pid :: pid()) -> wx:wx_object() — when Obj :: wx:wx_object() | atom() | pid(). sets the controlling process of the object handle 🔥

start

  • start(Name, Mod, Args, Options) -> wxWindow:wxWindow() | {error, term()} — when Name :: {local, atom()}, Mod :: atom(), Args :: term(), Flag :: trace | log | {logfile, string()} | statistics | debug, Options :: [{timeout, timeout()} | {debug, [Flag]}]. starts a generic wx_object server and invokes Mod:init(Args) in the new process ✨
  • start_link(Mod, Args, Options) -> wxWindow:wxWindow() | {error, term()} — when Mod :: atom(), Args :: term(), Flag :: trace | log | {logfile, string()} | statistics | debug, Options :: [{timeout, timeout()} | {debug, [Flag]}]. starts a generic wx_object server and invokes Mod:init(Args) in the new process 🫶
  • start_link(Name, Mod, Args, Options) -> wxWindow:wxWindow() | {error, term()} — when Name :: {local, atom()}, Mod :: atom(), Args :: term(), Flag :: trace | log | {logfile, string()} | statistics | debug, Options :: [{timeout, timeout()} | {debug, [Flag]}]. starts a generic wx_object server and invokes Mod:init(Args) in the new process 🌈

stop

  • stop(Obj) -> ok — when Obj :: wx:wx_object() | atom() | pid(). stops a generic wx_object server with reason 'normal'. invokes terminate(Reason,State) in the server. the call waits until the process is terminated. if the process does not exist, an exception is raised 💀
  • stop(Obj, Reason, Timeout) -> ok — when Obj :: wx:wx_object() | atom() | pid(), Reason :: term(), Timeout :: timeout(). stops a generic wx_object server with the given Reason. invokes terminate(Reason,State) in the server. the call waits until the process is terminated. if the call times out, or if the process does not exist, an exception is raised. so yeah, hold onto your socks 🧦

wait_response

  • wait_response(RequestId :: request_id()) -> {reply, Reply :: term()} | {error, {term(), server_ref()}} — wait infinitely for a reply from a generic server. she has all the time in the world ✨
  • wait_response(Key :: request_id(), Timeout :: timeout()) -> {reply, Reply :: term()} | timeout | {error, {term(), server_ref()}} — wait 'timeout' for a reply from a generic server ⏰ (and yeah, timeout can be an actual returned value, it's right there in the return type 👀)

🎀 CALLBACKS 🎀

this section exists, it's in the source, and it has literally nothing in it. it's giving mystery, it's giving silence, it's giving the callback docs live up in the DESCRIPTION instead. anyway, here it is, in order, because I keep everything 🫶

that's the whole page bestie!! no notes, ate, periodt 👑

Ericsson AB · wx 2.6 · wx_object(3) — that's the little footer at the bottom of the page, considered mentioned, mwah 💖

📦 where this page comes from