diff options
Diffstat (limited to 'lib/wx/src/wx.erl')
| -rw-r--r-- | lib/wx/src/wx.erl | 162 |
1 files changed, 85 insertions, 77 deletions
diff --git a/lib/wx/src/wx.erl b/lib/wx/src/wx.erl index 9d76f3bc42..7d62305048 100644 --- a/lib/wx/src/wx.erl +++ b/lib/wx/src/wx.erl @@ -1,46 +1,46 @@ %% %% %CopyrightBegin% -%% -%% Copyright Ericsson AB 2008-2010. All Rights Reserved. -%% +%% +%% Copyright Ericsson AB 2008-2012. All Rights Reserved. +%% %% The contents of this file are subject to the Erlang Public License, %% Version 1.1, (the "License"); you may not use this file except in %% compliance with the License. You should have received a copy of the %% Erlang Public License along with this software. If not, it can be %% retrieved online at http://www.erlang.org/. -%% +%% %% Software distributed under the License is distributed on an "AS IS" %% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See %% the License for the specific language governing rights and limitations %% under the License. -%% +%% %% %CopyrightEnd% %%%------------------------------------------------------------------- %%% File : wx.erl %%% Author : Dan Gudmundsson <[email protected]> -%%% Description : +%%% Description : %%% %%% Created : 22 Feb 2007 by Dan Gudmundsson <[email protected]> %%%------------------------------------------------------------------- %% @doc A port of <a href="http://www.wxwidgets.org/">wxWidgets</a>. -%% +%% %% This is the base api of <a href="http://www.wxwidgets.org/">wxWidgets</a>. -%% This module contains functions for +%% This module contains functions for %% starting and stopping the wx-server, as well as other utility functions. %% %% 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. -%% -%% Objects of a class are created with wxCLASS:new(...) and destroyed with +%% +%% 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(...). -%% +%% %% Sub class modules inherit (non static) functions from their parents. %% The inherited functions are not documented in the sub-classes. -%% +%% %% 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 @@ -49,7 +49,7 @@ %% %% 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={@link //stdlib/unicode:charlist()}, +%% wxString={@link //stdlib/unicode:chardata()}, %% wxGBPosition={r,c},wxGBSpan={rs,cs},wxGridCellCoords={r,c}. %% %% wxWidgets uses a process specific environment, which is created by @@ -59,42 +59,50 @@ %% %% Global (classless) functions are located in the wx_misc module. -%% @type wxObject(). Opaque object -%% @type wx_env(). Wx process environment -%% @type wx_mem(). Wx memory area -%% @type colour(). A 3 or 4 tuple: {R,G,B,A} or as argument {R,G,B} is also accepted -%% where each colour channel is a an integer between 0-255. -%% @type datetime(). {{Year,Month,Day}, {Hour,Minute,Second}} in local timezone. -%% @type mouseState(). See #wxMouseState{} defined in wx.hrl - - -module(wx). -export([parent_class/1, new/0, new/1, destroy/0, get_env/0,set_env/1, debug/1, batch/1,foreach/2,map/2,foldl/3,foldr/3, - getObjectType/1, typeCast/2, + getObjectType/1, typeCast/2, null/0, is_null/1]). -export([create_memory/1, get_memory_bin/1, retain_memory/1, release_memory/1]). - -export([demo/0]). +-export_type([wx_object/0, wx_env/0, wx_memory/0]). +-export_type([wx_colour/0, wx_colour4/0, wx_datetime/0, + wx_enum/0, wx_wxMouseState/0, wx_wxHtmlLinkInfo/0]). + -include("wxe.hrl"). +-include("../include/wx.hrl"). + +-type wx_object() :: #wx_ref{}. %% Opaque object reference +-type wx_env() :: #wx_env{}. %% Opaque process environment +-type wx_memory() :: binary() | #wx_mem{}. %% Opaque memory reference + +-type wx_colour4() :: {R::byte(),G::byte(),B::byte(), A::byte()}. +-type wx_colour() :: {R::byte(),G::byte(),B::byte()} | wx_colour4(). + +-type wx_datetime() :: {{Year::integer(),Month::integer(),Day::integer()}, + {Hour::integer(),Minute::integer(),Second::integer()}}. %% In Local Timezone + +-type wx_wxMouseState() :: #wxMouseState{}. %% See #wxMouseState{} defined in wx.hrl +-type wx_enum() :: integer(). %% Constant defined in wx.hrl +-type wx_wxHtmlLinkInfo() :: #wxHtmlLinkInfo{}. -%% @hidden parent_class(_) -> true. %% Let the null pointers be sent down. -%% @spec () -> wxObject() %% @doc Starts a wx server. +-spec new() -> wx_object(). new() -> new([]). -%% @spec ([Option]) -> wxObject() -%% @doc Starts a wx server. +%% @doc Starts a wx server. %% Option may be {debug, Level}, see debug/1. +-spec new([Option]) -> wx_object() when Option :: {debug, list() | atom()}. new(Options) when is_list(Options) -> #wx_env{port=Port} = wxe_server:start(), put(opengl_port, Port), @@ -102,130 +110,129 @@ new(Options) when is_list(Options) -> debug(Debug), null(). -%% @spec () -> ok %% @doc Stops a wx server. +-spec destroy() -> ok. destroy() -> wxe_server:stop(), erase(?WXE_IDENTIFIER), ok. -%% @spec () -> wx_env() %% @doc Gets this process's current wx environment. %% Can be sent to other processes to allow them use this process wx environment. %% @see set_env/1 +-spec get_env() -> wx_env(). get_env() -> case get(?WXE_IDENTIFIER) of undefined -> erlang:error({wxe,unknown_port}); Env = #wx_env{} -> Env end. -%% @spec (wx_env()) -> ok %% @doc Sets the process wx environment, allows this process to use %% another process wx environment. +-spec set_env(wx_env()) -> ok. set_env(#wx_env{sv=Pid, port=Port} = Env) -> - put(?WXE_IDENTIFIER, Env), + put(?WXE_IDENTIFIER, Env), put(opengl_port, Port), %% wxe_util:cast(?REGISTER_PID, <<>>), wxe_server:register_me(Pid), ok. -%% @spec () -> wxObject() %% @doc Returns the null object +-spec null() -> wx_object(). null() -> #wx_ref{ref=0, type=wx}. -%% @spec (wxObject()) -> boolean() %% @doc Returns true if object is null, false otherwise +-spec is_null(wx_object()) -> boolean(). is_null(#wx_ref{ref=NULL}) -> NULL =:= 0. -%% @spec (wxObject()) -> atom() %% @doc Returns the object type +-spec getObjectType(wx_object()) -> atom(). getObjectType(#wx_ref{type=Type}) -> Type. -%% @spec (wxObject(), atom()) -> wxObject() %% @doc Casts the object to class NewType. -%% It is needed when using functions like wxWindow:findWindow/2, which +%% It is needed when using functions like wxWindow:findWindow/2, which %% returns a generic wxObject type. +-spec typeCast(wx_object(), atom()) -> wx_object(). typeCast(Old=#wx_ref{}, NewType) when is_atom(NewType) -> Old#wx_ref{type=NewType}. -%% @spec (function()) -> term() %% @doc 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. -%% +%% %% @see map/2 %% @see foreach/2 %% @see foldl/3 %% @see foldr/3 +-spec batch(function()) -> term(). batch(Fun) -> ok = wxe_util:cast(?BATCH_BEGIN, <<>>), try Fun() - catch + catch error:W -> erlang:exit({W, erlang:get_stacktrace()}); throw:W -> erlang:throw(W); exit:W -> erlang:exit(W) - after + after ok = wxe_util:cast(?BATCH_END, <<>>) end. -%% @spec (function(), list()) -> ok -%% @doc Behaves like {@link //stdlib/lists:foreach/2} but batches wx commands. See {@link batch/1}. +%% @doc Behaves like {@link //stdlib/lists:foreach/2} but batches wx commands. See {@link batch/1}. +-spec foreach(function(), list()) -> ok. foreach(Fun, List) -> ok = wxe_util:cast(?BATCH_BEGIN, <<>>), try lists:foreach(Fun, List) - catch + catch error:W -> erlang:exit({W, erlang:get_stacktrace()}); throw:W -> erlang:throw(W); exit:W -> erlang:exit(W) - after + after ok = wxe_util:cast(?BATCH_END, <<>>) end. -%% @spec (function(), list()) -> list() -%% @doc Behaves like {@link //stdlib/lists:map/2} but batches wx commands. See {@link batch/1}. +%% @doc Behaves like {@link //stdlib/lists:map/2} but batches wx commands. See {@link batch/1}. +-spec map(function(), list()) -> list(). map(Fun, List) -> ok = wxe_util:cast(?BATCH_BEGIN, <<>>), try lists:map(Fun, List) - catch + catch error:W -> erlang:exit({W, erlang:get_stacktrace()}); throw:W -> erlang:throw(W); exit:W -> erlang:exit(W) - after + after ok = wxe_util:cast(?BATCH_END, <<>>) end. -%% @spec (function(), term(), list()) -> term() -%% @doc Behaves like {@link //stdlib/lists:foldl/3} but batches wx commands. See {@link batch/1}. +%% @doc Behaves like {@link //stdlib/lists:foldl/3} but batches wx commands. See {@link batch/1}. +-spec foldl(function(), term(), list()) -> term(). foldl(Fun, Acc, List) -> ok = wxe_util:cast(?BATCH_BEGIN, <<>>), try lists:foldl(Fun, Acc, List) - catch + catch error:W -> erlang:exit({W, erlang:get_stacktrace()}); throw:W -> erlang:throw(W); exit:W -> erlang:exit(W) - after + after ok = wxe_util:cast(?BATCH_END, <<>>) end. -%% @spec (function(), term(), list()) -> term() -%% @doc Behaves like {@link //stdlib/lists:foldr/3} but batches wx commands. See {@link batch/1}. +%% @doc Behaves like {@link //stdlib/lists:foldr/3} but batches wx commands. See {@link batch/1}. +-spec foldr(function(), term(), list()) -> term(). foldr(Fun, Acc, List) -> ok = wxe_util:cast(?BATCH_BEGIN, <<>>), try lists:foldr(Fun, Acc, List) - catch + catch error:W -> erlang:exit({W, erlang:get_stacktrace()}); throw:W -> erlang:throw(W); exit:W -> erlang:exit(W) - after + after ok = wxe_util:cast(?BATCH_END, <<>>) end. -define(MIN_BIN_SIZE, 64). %% Current emulator min off heap size -%% @spec (integer()) -> wx_memory() %% @doc 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 @@ -233,22 +240,23 @@ foldr(Fun, Acc, List) -> %% %% This is far from erlang's intentional usage and can crash the erlang emulator. %% Use it carefully. +-spec create_memory(integer()) -> wx_memory(). create_memory(Size) when Size > ?MIN_BIN_SIZE -> #wx_mem{bin = <<0:(Size*8)>>, size = Size}; create_memory(Size) -> #wx_mem{bin = <<0:((?MIN_BIN_SIZE+1)*8)>>, size = Size}. -%% @spec (wx_memory()) -> binary() %% @doc Returns the memory area as a binary. +-spec get_memory_bin(wx_memory()) -> binary(). get_memory_bin(#wx_mem{bin=Bin, size=Size}) when Size > ?MIN_BIN_SIZE -> Bin; get_memory_bin(#wx_mem{bin=Bin, size=Size}) -> <<WithCorrectSize:Size/binary, _/binary>> = Bin, WithCorrectSize. -%% @spec (wx_memory()) -> ok %% @doc 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. +-spec retain_memory(wx_memory()) -> ok. retain_memory(#wx_mem{bin=Bin}) -> wxe_util:send_bin(Bin), ok = wxe_util:cast(?WXE_BIN_INCR, <<>>); @@ -260,30 +268,29 @@ retain_memory(Bin) when is_binary(Bin) -> wxe_util:send_bin(Bin), ok = wxe_util:cast(?WXE_BIN_INCR, <<>>). +-spec release_memory(wx_memory()) -> ok. release_memory(#wx_mem{bin=Bin}) -> wxe_util:send_bin(Bin), ok = wxe_util:cast(?WXE_BIN_DECR, <<>>); release_memory(Bin) when is_binary(Bin) -> wxe_util:send_bin(Bin), ok = wxe_util:cast(?WXE_BIN_DECR, <<>>). - - - -%% @spec (Level::term()) -> ok -%% Level = none | verbose | trace | driver | [Level] -%% @doc Sets debug level. If debug level is verbose or trace -%% each call is printed on console. If Level is driver each allocated +%% @doc 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. +-spec debug(Level | [Level]) -> ok + when Level :: none | verbose | trace | driver | integer(). + debug(none) -> debug(0); debug(verbose) -> debug(1); debug(trace) -> debug(2); debug(driver) -> debug(16); debug([]) -> debug(0); -debug(List) when is_list(List) -> - {Drv,Erl} = - lists:foldl(fun(verbose, {Drv,_Erl}) -> +debug(List) when is_list(List) -> + {Drv,Erl} = + lists:foldl(fun(verbose, {Drv,_Erl}) -> {Drv,1}; (trace, {Drv,_Erl}) -> {Drv,2}; @@ -295,28 +302,29 @@ debug(Level) when is_integer(Level) -> case get(?WXE_IDENTIFIER) of undefined -> erlang:error({wxe,unknown_port}); #wx_env{debug=Old} when Old =:= Level -> ok; - Env = #wx_env{sv=Server, port=Port, debug=Old} -> - if + Env = #wx_env{sv=Server, port=Port, debug=Old} -> + if Old > 16, Level > 16 -> ok; Old < 16, Level < 16 -> ok; true -> erlang:port_call(Port,?WXE_DEBUG_DRIVER, [Level bsr 4]) - end, + end, put(?WXE_IDENTIFIER, Env#wx_env{debug=Level}), wxe_server:set_debug(Server,Level), ok end. -%% @spec () -> ok %% @doc Starts a wxErlang demo if examples directory exists and is compiled +-spec demo() -> ok | {error, atom()}. demo() -> Priv = code:priv_dir(wx), Demo = filename:join([filename:dirname(Priv),examples,demo]), Mod = list_to_atom("demo"), %% Fool xref tests case file:set_cwd(Demo) of - ok -> - apply(Mod, start, []); + ok -> + apply(Mod, start, []), + ok; _ -> {error, no_demo_dir} end. - + |