path: root/lib/wx/doc/src/wx.xml

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<title>wx</title>
<prepared></prepared>
<responsible></responsible>
<docno>1</docno>
<approved></approved>
<checked></checked>
<date></date>
<rev>A</rev>
<file>wx.xml</file></header>
<module>wx</module>
<modulesummary>A port of wxWidgets.</modulesummary>
<description>
<p>A port of <url href="http://www.wxwidgets.org/">wxWidgets</url>.</p>
 
  <p>This is the base api of <url href="http://www.wxwidgets.org/">wxWidgets</url>.  
This module contains functions for  
starting and stopping the wx-server, as well as  other utility functions.</p>
 
  <p>wxWidgets is object oriented, and not functional. Thus, in wxErlang a  
module represents a class, and the object created by this class  
has an own type, wxCLASS().  This module represents the base  
class, and all other wxMODULE's are sub-classes of this class.</p>
 
  <p>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(...).</p>
 
  <p>Sub class modules inherit (non static) functions from their parents.  
The inherited functions are not documented in the sub-classes.</p>
 
  <p>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 <seeerl marker="wxEvtHandler">wxEvtHandler</seeerl>.</p>
 
  <p>The following classes are implemented directly as erlang types: <br/>
  wxPoint={x,y},wxSize={w,h},wxRect={x,y,w,h},wxColour={r,g,b [,a]},
  wxString=<seeerl marker="stdlib:unicode#type-chardata">unicode:chardata()</seeerl>,  
wxGBPosition={r,c},wxGBSpan={rs,cs},wxGridCellCoords={r,c}.</p>
 
  <p>wxWidgets uses a process specific environment, which is created by
  <seemfa marker="wx#new/0">wx:new/0</seemfa>.  To be able to use the environment from other
  processes, call <seemfa marker="#get_env/0">get_env/0</seemfa> to retrieve the environment and
  <seemfa marker="#set_env/1">set_env/1</seemfa> to assign the environment in the other process.</p>
 
  <p>Global (classless) functions are located in the wx_misc module.</p></description>
<section><title>DATA TYPES</title><marker id="types"/>

<taglist>
<tag><marker id="type-wx_colour"/>wx_colour() = {R::byte(), G::byte(), B::byte()} | <seeerl marker="#type-wx_colour4">wx_colour4()</seeerl></tag>
<item><p/> </item>
<tag><marker id="type-wx_colour4"/>wx_colour4() = {R::byte(), G::byte(), B::byte(), A::byte()}</tag>
<item><p/> </item>
<tag><marker id="type-wx_datetime"/>wx_datetime() = {{Year::integer(), Month::integer(), Day::integer()}, {Hour::integer(), Minute::integer(), Second::integer()}}</tag>
<item><p/>
<p>  In Local Timezone</p>
</item>
<tag><marker id="type-wx_enum"/>wx_enum() = integer()</tag>
<item><p/>
<p>  Constant defined in wx.hrl</p>
</item>
<tag><marker id="type-wx_env"/>wx_env() = #wx_env{}</tag>
<item><p/>
<p>  Opaque process environment</p>
</item>
<tag><marker id="type-wx_memory"/>wx_memory() = binary() | #wx_mem{}</tag>
<item><p/>
<p>  Opaque memory reference</p>
</item>
<tag><marker id="type-wx_object"/>wx_object() = #wx_ref{}</tag>
<item><p/>
<p>  Opaque object reference</p>
</item>
<tag><marker id="type-wx_wxHtmlLinkInfo"/>wx_wxHtmlLinkInfo() = #wxHtmlLinkInfo{href=<seeerl marker="unicode#type-chardata">unicode:chardata()</seeerl>, target=<seeerl marker="unicode#type-chardata">unicode:chardata()</seeerl>}</tag>
<item><p/> </item>
<tag><marker id="type-wx_wxMouseState"/>wx_wxMouseState() = #wxMouseState{x=integer(), y=integer(), leftDown=boolean(), middleDown=boolean(), rightDown=boolean(), controlDown=boolean(), shiftDown=boolean(), altDown=boolean(), metaDown=boolean(), cmdDown=boolean()}</tag>
<item><p/>
<p>  See #wxMouseState{} defined in wx.hrl</p>
</item>
</taglist></section>
<funcs>
<func>
<name since="">parent_class(X1) -&gt; term()
</name>
<fsummary> </fsummary>

<desc><marker id="parent_class-1"/>
 </desc></func>
<func>
<name since="">new() -&gt; <seeerl marker="#type-wx_object">wx_object()</seeerl></name>
<fsummary>Starts a wx server.</fsummary>

<desc><marker id="new-0"/>

<p>Starts a wx server.</p>
</desc></func>
<func>
<name since="">new(Options::[Option]) -&gt; <seeerl marker="#type-wx_object">wx_object()</seeerl></name>
<fsummary>Starts a wx server.</fsummary>
<type>
<v>Option = {debug, list() | atom()} | {silent_start, boolean()}</v></type>
<desc><marker id="new-1"/>

<p>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.</p>
</desc></func>
<func>
<name since="">destroy() -&gt; ok</name>
<fsummary>Stops a wx server.</fsummary>

<desc><marker id="destroy-0"/>

<p>Stops a wx server.</p>
</desc></func>
<func>
<name since="">get_env() -&gt; <seeerl marker="#type-wx_env">wx_env()</seeerl></name>
<fsummary>Gets this process's current wx environment.</fsummary>

<desc><marker id="get_env-0"/>

<p>Gets this process's current wx environment.
  Can be sent to other processes to allow them use this process wx environment.</p>
<p><em>See also:</em> <seemfa marker="#set_env/1">set_env/1</seemfa>.</p>
</desc></func>
<func>
<name since="">set_env(Wx_env::<seeerl marker="#type-wx_env">wx_env()</seeerl>) -&gt; ok</name>
<fsummary>Sets the process wx environment, allows this process to use
  another process wx environment.</fsummary>

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

<p>Sets the process wx environment, allows this process to use
  another process wx environment.</p>
</desc></func>
<func>
<name since="">subscribe_events() -&gt; ok</name>
<fsummary>Adds the calling process to the list of of processes that are
listening to wx application events.</fsummary>

<desc><marker id="subscribe_events-0"/>
<p>
  Adds the calling process to the list of of processes that are listening to
  wx application events.
</p>

<p>
  At the moment these are all MacOSX specific events corresponding to
  <c>MacNewFile()</c>
  and friends from wxWidgets
  <url href="https://docs.wxwidgets.org/trunk/classwx_app.html">wxApp</url>:
</p>

<list>
  <item>
    <p><c>{new_file, ""}</c></p>
  </item>
  <item>
    <p><c>{open_file, Filename}</c></p>
  </item>
  <item>
    <p><c>{print_file, Filename}</c></p>
  </item>
  <item>
    <p><c>{open_url, Url}</c></p>
  </item>
  <item>
    <p><c>{reopen_app, ""}</c></p>
  </item>
</list>

<p>
  The call always returns ok but will have sent any already received
  events to the calling process.
</p>
</desc></func>
<func>
<name since="">null() -&gt; <seeerl marker="#type-wx_object">wx_object()</seeerl></name>
<fsummary>Returns the null object.</fsummary>

<desc><marker id="null-0"/>

<p>Returns the null object</p>
</desc></func>
<func>
<name since="">is_null(Wx_ref::<seeerl marker="#type-wx_object">wx_object()</seeerl>) -&gt; boolean()</name>
<fsummary>Returns true if object is null, false otherwise.</fsummary>

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

<p>Returns true if object is null, false otherwise</p>
</desc></func>
<func>
<name since="">equal(Wx_ref::<seeerl marker="#type-wx_object">wx_object()</seeerl>, X2::<seeerl marker="#type-wx_object">wx_object()</seeerl>) -&gt; boolean()</name>
<fsummary>Returns true if both arguments references the same object, false otherwise.</fsummary>

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

<p>Returns true if both arguments references the same object, false otherwise</p>
</desc></func>
<func>
<name since="">getObjectType(Wx_ref::<seeerl marker="#type-wx_object">wx_object()</seeerl>) -&gt; atom()</name>
<fsummary>Returns the object type.</fsummary>

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

<p>Returns the object type</p>
</desc></func>
<func>
<name since="">typeCast(Old::<seeerl marker="#type-wx_object">wx_object()</seeerl>, NewType::atom()) -&gt; <seeerl marker="#type-wx_object">wx_object()</seeerl></name>
<fsummary>Casts the object to class NewType.</fsummary>

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

<p>Casts the object to class NewType.
   It is needed when using functions like wxWindow:findWindow/2, which
   returns a generic wxObject type.</p>
</desc></func>
<func>
<name since="">batch(Fun::function()) -&gt; term()</name>
<fsummary>Batches all wx commands
  used in the fun.</fsummary>

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

<p>Batches all <c>wx</c> 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.
 </p>
<p><em>See also:</em> <seemfa marker="#foldl/3">foldl/3</seemfa>, <seemfa marker="#foldr/3">foldr/3</seemfa>, <seemfa marker="#foreach/2">foreach/2</seemfa>, <seemfa marker="#map/2">map/2</seemfa>.</p>
</desc></func>
<func>
<name since="">foreach(Fun::function(), List::list()) -&gt; ok</name>
<fsummary>Behaves like //stdlib/lists:foreach/2 but batches wx commands.</fsummary>

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

<p>Behaves like <seemfa marker="stdlib:lists#foreach/2">lists:foreach/2</seemfa> but batches wx commands. See <seemfa marker="#batch/1">batch/1</seemfa>.</p>
</desc></func>
<func>
<name since="">map(Fun::function(), List::list()) -&gt; list()</name>
<fsummary>Behaves like //stdlib/lists:map/2 but batches wx commands.</fsummary>

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

<p>Behaves like <seemfa marker="stdlib:lists#map/2">lists:map/2</seemfa> but batches wx commands. See <seemfa marker="#batch/1">batch/1</seemfa>.</p>
</desc></func>
<func>
<name since="">foldl(Fun::function(), Acc::term(), List::list()) -&gt; term()</name>
<fsummary>Behaves like //stdlib/lists:foldl/3 but batches wx commands.</fsummary>

<desc><marker id="foldl-3"/>

<p>Behaves like <seemfa marker="stdlib:lists#foldl/3">lists:foldl/3</seemfa> but batches wx commands. See <seemfa marker="#batch/1">batch/1</seemfa>.</p>
</desc></func>
<func>
<name since="">foldr(Fun::function(), Acc::term(), List::list()) -&gt; term()</name>
<fsummary>Behaves like //stdlib/lists:foldr/3 but batches wx commands.</fsummary>

<desc><marker id="foldr-3"/>

<p>Behaves like <seemfa marker="stdlib:lists#foldr/3">lists:foldr/3</seemfa> but batches wx commands. See <seemfa marker="#batch/1">batch/1</seemfa>.</p>
</desc></func>
<func>
<name since="">create_memory(Size::integer()) -&gt; <seeerl marker="#type-wx_memory">wx_memory()</seeerl></name>
<fsummary>Creates a memory area (of Size in bytes) which can be used by an external library (i.e.</fsummary>

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

<p>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.</p>
 
  <p>This is far from erlang's intentional usage and can crash the erlang emulator.
  Use it carefully.</p>
</desc></func>
<func>
<name since="">get_memory_bin(Wx_mem::<seeerl marker="#type-wx_memory">wx_memory()</seeerl>) -&gt; binary()</name>
<fsummary>Returns the memory area as a binary.</fsummary>

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

<p>Returns the memory area as a binary.</p>
</desc></func>
<func>
<name since="">retain_memory(Wx_mem::<seeerl marker="#type-wx_memory">wx_memory()</seeerl>) -&gt; ok</name>
<fsummary>Saves the memory from deletion until release_memory/1 is called.</fsummary>

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

<p>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.</p>
</desc></func>
<func>
<name since="">release_memory(Wx_mem::<seeerl marker="#type-wx_memory">wx_memory()</seeerl>) -&gt; ok</name>
<fsummary> </fsummary>

<desc><marker id="release_memory-1"/>
 </desc></func>
<func>
<name since="">debug(Debug::Level | [Level]) -&gt; ok</name>
<fsummary>Sets debug level.</fsummary>
<type>
<v>Level = none | verbose | trace | driver | integer()</v></type>
<desc><marker id="debug-1"/>

<p>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.</p>
</desc></func>
<func>
<name since="">demo() -&gt; ok | {error, atom()}</name>
<fsummary>Starts a wxErlang demo if examples directory exists and is compiled.</fsummary>

<desc><marker id="demo-0"/>

<p>Starts a wxErlang demo if examples directory exists and is compiled</p>
</desc></func></funcs>

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