<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<title>wx_object</title>
<prepared></prepared>
<responsible></responsible>
<docno>1</docno>
<approved></approved>
<checked></checked>
<date></date>
<rev>A</rev>
<file>wx_object.xml</file></header>
<module>wx_object</module>
<modulesummary>wx_object - Generic wx object behaviour.</modulesummary>
<description>
<p>wx_object - Generic wx object behaviour</p>
 
  <p>This is a behaviour module that can be used for "sub classing"  
wx objects. It works like a regular gen_server module and creates  
a server per object.</p>
 
  <p>NOTE: Currently no form of inheritance is implemented.</p>
 
 
  <p>The user module should export:</p>
 
    <p>init(Args) should return <br/>      
{wxObject, State} | {wxObject, State, Timeout} |          
ignore | {stop, Reason}</p>
 
    <p>Asynchronous window event handling: <br/>
    handle_event(#wx{}, State)  should return <br/>     
{noreply, State} | {noreply, State, Timeout} | {stop, Reason, State}</p>
 
  <p>The user module can export the following callback functions:</p>
 
    <p>handle_call(Msg, {From, Tag}, State) should return <br/>     
{reply, Reply, State} | {reply, Reply, State, Timeout} |         
{noreply, State} | {noreply, State, Timeout} |         
{stop, Reason, Reply, State}</p>
 
    <p>handle_cast(Msg, State) should return <br/>     
{noreply, State} | {noreply, State, Timeout} |         
{stop, Reason, State}</p>
 
  <p>If the above are not exported but called, the wx_object process will crash.  
The user module can also export:</p>
 
    <p>Info is message e.g. {'EXIT', P, R}, {nodedown, N}, ...  <br/>
    handle_info(Info, State)  should return , ...  <br/>     
{noreply, State} | {noreply, State, Timeout} | {stop, Reason, State}</p>
 
  <p>If a message is sent to the wx_object process when handle_info is not  
exported, the message will be dropped and ignored.</p>
 
    <p>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, it is always called when server terminates or
  when wx_object() in the driver is deleted. If the Parent process
  terminates the Module:terminate/2 function is called. <br/>  
terminate(Reason, State)</p>
 
 
  <p>Example:</p>
 
  <pre>  -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) -&gt;
     wx_object:start(?MODULE, [Parent,Id], []).
 
  show(Dialog) -&gt;
     wx_object:call(Dialog, show_modal).
 
  destroy(Dialog) -&gt;
     wx_object:call(Dialog, destroy).
 
  %% Server Implementation ala gen_server
  init([Parent, Str]) -&gt;
     Dialog = wxDialog:new(Parent, 42, "Testing", []),
     ...
     wxDialog:connect(Dialog, command_button_clicked),
     {Dialog, MyState}.
 
  handle_call(show, _From, State) -&gt;
     wxDialog:show(State#state.win),
     {reply, ok, State};
  ...
  handle_event(#wx{}, State) -&gt;
     io:format("Users clicked button~n",[]),
     {noreply, State};
  ...</pre></description>
<section><title>DATA TYPES</title><marker id="types"/>

<taglist>
<tag><marker id="type-request_id"/>request_id() = term()</tag>
<item><p/> </item>
<tag><marker id="type-server_ref"/>server_ref() = <seeerl marker="wx#type-wx_object">wx:wx_object()</seeerl> | atom() | pid()</tag>
<item><p/> </item>
</taglist></section>
<funcs>
<func>
<name since="">start(Name, Mod, Args, Options) -&gt; <seeerl marker="wxWindow#type-wxWindow">wxWindow:wxWindow()</seeerl> | {error, term()}</name>
<fsummary>Starts a generic wx_object server and invokes Mod:init(Args) in the
  new process.</fsummary>
<type>
<v>Name = {local, atom()}</v><v>Mod = atom()</v><v>Args = term()</v><v>Flag = trace | log | {logfile, string()} | statistics | debug</v><v>Options = [{timeout, timeout()} | {debug, [Flag]}]</v></type>
<desc><marker id="start-4"/>

<p>Starts a generic wx_object server and invokes Mod:init(Args) in the
  new process.</p>
</desc></func>
<func>
<name since="">start_link(Mod, Args, Options) -&gt; <seeerl marker="wxWindow#type-wxWindow">wxWindow:wxWindow()</seeerl> | {error, term()}</name>
<fsummary>Starts a generic wx_object server and invokes Mod:init(Args) in the
  new process.</fsummary>
<type>
<v>Mod = atom()</v><v>Args = term()</v><v>Flag = trace | log | {logfile, string()} | statistics | debug</v><v>Options = [{timeout, timeout()} | {debug, [Flag]}]</v></type>
<desc><marker id="start_link-3"/>

<p>Starts a generic wx_object server and invokes Mod:init(Args) in the
  new process.</p>
</desc></func>
<func>
<name since="">start_link(Name, Mod, Args, Options) -&gt; <seeerl marker="wxWindow#type-wxWindow">wxWindow:wxWindow()</seeerl> | {error, term()}</name>
<fsummary>Starts a generic wx_object server and invokes Mod:init(Args) in the
  new process.</fsummary>
<type>
<v>Name = {local, atom()}</v><v>Mod = atom()</v><v>Args = term()</v><v>Flag = trace | log | {logfile, string()} | statistics | debug</v><v>Options = [{timeout, timeout()} | {debug, [Flag]}]</v></type>
<desc><marker id="start_link-4"/>

<p>Starts a generic wx_object server and invokes Mod:init(Args) in the
  new process.</p>
</desc></func>
<func>
<name since="">stop(Obj) -&gt; ok</name>
<fsummary>Stops a generic wx_object server with reason 'normal'.</fsummary>
<type>
<v>Obj = <seeerl marker="wx#type-wx_object">wx:wx_object()</seeerl> | atom() | pid()</v></type>
<desc><marker id="stop-1"/>

<p>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.</p>
</desc></func>
<func>
<name since="">stop(Obj, Reason, Timeout) -&gt; ok</name>
<fsummary>Stops a generic wx_object server with the given Reason.</fsummary>
<type>
<v>Obj = <seeerl marker="wx#type-wx_object">wx:wx_object()</seeerl> | atom() | pid()</v><v>Reason = term()</v><v>Timeout = timeout()</v></type>
<desc><marker id="stop-3"/>

<p>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.</p>
</desc></func>
<func>
<name since="">call(Obj, Request) -&gt; term()</name>
<fsummary>Make a call to a wx_object server.</fsummary>
<type>
<v>Obj = <seeerl marker="wx#type-wx_object">wx:wx_object()</seeerl> | atom() | pid()</v><v>Request = term()</v></type>
<desc><marker id="call-2"/>

<p>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</p>
</desc></func>
<func>
<name since="">call(Obj, Request, Timeout) -&gt; term()</name>
<fsummary>Make a call to a wx_object server with a timeout.</fsummary>
<type>
<v>Obj = <seeerl marker="wx#type-wx_object">wx:wx_object()</seeerl> | atom() | pid()</v><v>Request = term()</v><v>Timeout = integer()</v></type>
<desc><marker id="call-3"/>

<p>Make a call to a wx_object server with a timeout.
  Invokes handle_call(Request, From, State) in server</p>
</desc></func>
<func>
<name since="">send_request(Obj, Request::term()) -&gt; <seeerl marker="#type-request_id">request_id()</seeerl></name>
<fsummary>Make an send_request to a generic server.</fsummary>
<type>
<v>Obj = <seeerl marker="wx#type-wx_object">wx:wx_object()</seeerl> | atom() | pid()</v></type>
<desc><marker id="send_request-2"/>

<p>Make an 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 server.</p>
</desc></func>
<func>
<name since="">wait_response(RequestId::<seeerl marker="#type-request_id">request_id()</seeerl>) -&gt; {reply, Reply::term()} | {error, {term(), <seeerl marker="#type-server_ref">server_ref()</seeerl>}}</name>
<fsummary>Wait infinitely for a reply from a generic server.</fsummary>

<desc><marker id="wait_response-1"/>

<p>Wait infinitely for a reply from a generic server.</p>
</desc></func>
<func>
<name since="">wait_response(Key::<seeerl marker="#type-request_id">request_id()</seeerl>, Timeout::timeout()) -&gt; {reply, Reply::term()} | timeout | {error, {term(), <seeerl marker="#type-server_ref">server_ref()</seeerl>}}</name>
<fsummary>Wait 'timeout' for a reply from a generic server.</fsummary>

<desc><marker id="wait_response-2"/>

<p>Wait 'timeout' for a reply from a generic server.</p>
</desc></func>
<func>
<name since="">check_response(Msg::term(), Key::<seeerl marker="#type-request_id">request_id()</seeerl>) -&gt; {reply, Reply::term()} | false | {error, {term(), <seeerl marker="#type-server_ref">server_ref()</seeerl>}}</name>
<fsummary>Check if a received message was a reply to a RequestId.</fsummary>

<desc><marker id="check_response-2"/>

<p>Check if a received message was a reply to a RequestId</p>
</desc></func>
<func>
<name since="">cast(Obj, Request) -&gt; ok</name>
<fsummary>Make a cast to a wx_object server.</fsummary>
<type>
<v>Obj = <seeerl marker="wx#type-wx_object">wx:wx_object()</seeerl> | atom() | pid()</v><v>Request = term()</v></type>
<desc><marker id="cast-2"/>

<p>Make a cast to a wx_object server.
  Invokes handle_cast(Request, State) in the server</p>
</desc></func>
<func>
<name since="">get_pid(Obj) -&gt; pid()</name>
<fsummary>Get the pid of the object handle.</fsummary>
<type>
<v>Obj = <seeerl marker="wx#type-wx_object">wx:wx_object()</seeerl> | atom() | pid()</v></type>
<desc><marker id="get_pid-1"/>

<p>Get the pid of the object handle.</p>
</desc></func>
<func>
<name since="">set_pid(Obj, Pid::pid()) -&gt; <seeerl marker="wx#type-wx_object">wx:wx_object()</seeerl></name>
<fsummary>Sets the controlling process of the object handle.</fsummary>
<type>
<v>Obj = <seeerl marker="wx#type-wx_object">wx:wx_object()</seeerl> | atom() | pid()</v></type>
<desc><marker id="set_pid-2"/>

<p>Sets the controlling process of the object handle.</p>
</desc></func>
<func>
<name since="">reply(X1::{pid(), Tag::term()}, Reply::term()) -&gt; pid()</name>
<fsummary>Get the pid of the object handle.</fsummary>

<desc><marker id="reply-2"/>

<p>Get the pid of the object handle.</p>
</desc></func></funcs>

<authors>
<aname> </aname>
<email> </email></authors></erlref>