<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- Interface Functions</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/gs-1.5.15.1.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>Graphics System (GS)</strong><br><strong>User's Guide</strong><br><small>Version 1.5.15.1</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../../../../doc/js/flipmenu">
<li id="no" title="GS - The Graphics System" expanded="false">GS - The Graphics System<ul>
<li><a href="gs_chapter1.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="gs_chapter1.html#id62365">Introduction</a></li>
<li title="Basic Architecture of GS"><a href="gs_chapter1.html#id61203">Basic Architecture of GS</a></li>
</ul>
</li>
<li id="loadscrollpos" title="Interface Functions" expanded="true">Interface Functions<ul>
<li><a href="gs_chapter2.html">
Top of chapter
</a></li>
<li title="Overview"><a href="gs_chapter2.html#id61459">Overview</a></li>
<li title="A First Example"><a href="gs_chapter2.html#id57477">A First Example</a></li>
<li title="Creating Objects"><a href="gs_chapter2.html#id63683">Creating Objects</a></li>
<li title="Ownership"><a href="gs_chapter2.html#id59961">Ownership</a></li>
<li title="Naming Objects"><a href="gs_chapter2.html#id59975">Naming Objects</a></li>
</ul>
</li>
<li id="no" title="Options" expanded="false">Options<ul>
<li><a href="gs_chapter3.html">
Top of chapter
</a></li>
<li title="The Option Concept"><a href="gs_chapter3.html#id58188">The Option Concept</a></li>
<li title="The Option Tables"><a href="gs_chapter3.html#id64276">The Option Tables</a></li>
<li title="Config-Only Options"><a href="gs_chapter3.html#id64432">Config-Only Options</a></li>
<li title="Read-Only Options"><a href="gs_chapter3.html#id64553">Read-Only Options</a></li>
<li title="Data Types"><a href="gs_chapter3.html#id64674">Data Types</a></li>
</ul>
</li>
<li id="no" title="Events" expanded="false">Events<ul>
<li><a href="gs_chapter4.html">
Top of chapter
</a></li>
<li title="Event Messages"><a href="gs_chapter4.html#id65002">Event Messages</a></li>
<li title="Generic Events"><a href="gs_chapter4.html#id65107">Generic Events</a></li>
<li title="Object Specific Events"><a href="gs_chapter4.html#id65547">Object Specific Events</a></li>
<li title="Matching Events Against Object Identifiers"><a href="gs_chapter4.html#id65664">Matching Events Against Object Identifiers</a></li>
<li title="Matching Events Against Object Names"><a href="gs_chapter4.html#id65689">Matching Events Against Object Names</a></li>
<li title="Matching Events Against the Data Field"><a href="gs_chapter4.html#id65716">Matching Events Against the Data Field</a></li>
<li title="Experimenting with Events"><a href="gs_chapter4.html#id65756">Experimenting with Events</a></li>
</ul>
</li>
<li id="no" title="Fonts" expanded="false">Fonts<ul>
<li><a href="gs_chapter5.html">
Top of chapter
</a></li>
<li title="The Font Model"><a href="gs_chapter5.html#id65831">The Font Model</a></li>
</ul>
</li>
<li id="no" title="Default Values" expanded="false">Default Values<ul>
<li><a href="gs_chapter6.html">
Top of chapter
</a></li>
<li title="The Default Value Model"><a href="gs_chapter6.html#id66044">The Default Value Model</a></li>
</ul>
</li>
<li id="no" title="The Packer" expanded="false">The Packer<ul>
<li><a href="gs_chapter7.html">
Top of chapter
</a></li>
<li title="The Packer"><a href="gs_chapter7.html#id66217">The Packer</a></li>
</ul>
</li>
<li id="no" title="Built-In Objects" expanded="false">Built-In Objects<ul>
<li><a href="gs_chapter8.html">
Top of chapter
</a></li>
<li title="Overview"><a href="gs_chapter8.html#id66484">Overview</a></li>
<li title="Generic Options"><a href="gs_chapter8.html#id66791">Generic Options</a></li>
<li title="Window"><a href="gs_chapter8.html#id67843">Window</a></li>
<li title="Button"><a href="gs_chapter8.html#id68226">Button</a></li>
<li title="Label"><a href="gs_chapter8.html#id68734">Label</a></li>
<li title="Frame"><a href="gs_chapter8.html#id68905">Frame</a></li>
<li title="Entry"><a href="gs_chapter8.html#id69050">Entry</a></li>
<li title="Listbox"><a href="gs_chapter8.html#id69366">Listbox</a></li>
<li title="Canvas"><a href="gs_chapter8.html#id70050">Canvas</a></li>
<li title="Menu"><a href="gs_chapter8.html#id72195">Menu</a></li>
<li title="Grid"><a href="gs_chapter8.html#id80608">Grid</a></li>
<li title="Editor"><a href="gs_chapter8.html#id81434">Editor</a></li>
<li title="Scale"><a href="gs_chapter8.html#id82183">Scale</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>2 Interface Functions</h1>
<h3><a name="id61459">2.1
Overview</a></h3>
<p>The following interface functions are included with the graphics system:</p>
<ul>
<li>
<span class="code">gs:start().</span> This function starts the graphics server and returns its object identifier. If the graphics server has already been started, it returns its original identifier.</li>
<li>
<span class="code">gs:stop().</span> This function stops the graphics server and closes all windows which <span class="code">gs</span> has launched. This function is not the opposite of <span class="code">gs:start/0</span> because <span class="code">gs:stop/1</span> causes all applications to lose the graphics server and the objects created with the <span class="code">gs</span> system.</li>
<li>
<span class="code">gs:create(Objtype, Parent, Options).</span> This function creates a new object of specified <span class="code">Objtype</span> as a child to the specified <span class="code">Parent</span>. It configures the object with <span class="code">Options</span> and returns the identifier for the object, or <span class="code">{error,Reason}</span>.</li>
<li>
<span class="code">gs:create(Objtype, Name, Parent, Options).</span> This function is identical to the previously listed function, except that a <span class="code">Name</span> is specified to reference the object. <span class="code">Name</span> is an atom.</li>
<li>
<span class="code">gs:destroy(IdOrName).</span> This function destroys an object and all its children.</li>
<li>
<span class="code">gs:config(IdOrNeme, Options).</span> This function configures an object with <span class="code">Options</span>. It returns <span class="code">ok</span>, or <span class="code">{error,Reason}</span>.</li>
<li>
<span class="code">gs:read(Id_or_Name, OptionKey).</span> This function reads the value of an object option. It returns the value, or <span class="code">{error,Reason}</span>.</li>
</ul>
<p>The above list contains all the function which are <strong>needed</strong> with the graphics system. For convenience, the following aliases also exist:</p>
<ul>
<li><span class="code">gs:create(Obttype, Parent).</span></li>
<li><span class="code">gs:create(Objtype, Parent, Options).</span></li>
<li><span class="code">gs:create(Objtype, Parent, Option).</span></li>
<li><span class="code">gs:create(Objtype, Name, Parent, Options).</span></li>
<li><span class="code">gs:create(Objtype, Name, Parent, Option).</span></li>
<li><span class="code">gs:Objecttype(Parent).</span></li>
<li><span class="code">gs:Objecttype(Parent,Options).</span></li>
<li><span class="code">gs:Objecttype(Parent, Option).</span></li>
<li><span class="code">gs:Objecttype(Name, Parent, Options).</span></li>
<li><span class="code">gs:Objecttype(Name, Parent, Option).</span></li>
<li><span class="code">gs:config(IdOrName, Option).</span></li>
</ul>
<p>These shorthands can be used as follows:</p>
<ul>
<li><span class="code">gs:window(gs:start(), {map,true}).</span></li>
<li><span class="code">gs:button(W).</span></li>
<li><span class="code">gs:config(B,{label,{text,"Hi!"}}).</span></li>
</ul>
<p>The <span class="code">create_tree/2</span> function is useful for creating a large hierarchy of objects. It has the following syntax: </p>
<div class="example"><pre>
create_tree(ParentId,Tree) -> | {error,Reason}
</pre></div>
<p><span class="code">Tree</span> is a list of <span class="code">Object</span>, and <span class="code">Object</span> is any of the following:</p>
<ul>
<li><span class="code">{ObjectType,Name,Options,Tree}</span></li>
<li><span class="code">{ObjectType,Options,Tree}</span></li>
<li><span class="code">{ObjectType,Options}</span></li>
</ul>
<p>The following example constructs a window which contains two objects, a button and a frame with a label:</p>
<div class="example"><pre>
R = [{window,[{map,true}],
[{button,[{label,{text,"Butt1"}}]},
{frame,[{y,40}],[{label,[{label,{text,"Lbl1"}}]}]}]}],
gs:create_tree(gs:start(),R).
</pre></div>
<h3><a name="id57477">2.2
A First Example</a></h3>
<p>The first action required is to start up the graphics server. This operation returns an identifier for the server process, which registers itself under the name <span class="code">gs</span>. If a graphics server was already started, its identifier is returned. We can now create objects and configure the behavior and appearance of these objects. When all objects are created and configured in a top level window, we map it on the screen to make it visible. The example below shows how to create a window with a button that says "Press Me".</p>
<div class="example"><pre>
-module(ex1).
-copyright('Copyright (c) 1991-97 Ericsson Telecom AB').
-vsn('$Revision: /main/release/2 $ ').
-export([init/0]).
init() ->
S = gs:start(),
%% the parent of a top-level window is the gs server
Win = gs:create(window,S,[{width,200},{height,100}]),
Butt = gs:create(button,Win,[{label, {text,"Press Me"}}]),
gs:config(Win, {map,true}),
loop(Butt).
loop(Butt) ->
receive
{gs, Butt, click, Data, Args} ->
io:format("Hello There~n",[]),
loop(Butt)
end.
</pre></div> <p>The following steps were completed in this code:</p>
<ul>
<li>start a graphics server</li>
<li>create a window of specified width and height</li>
<li>create a button with the text "Press Me"</li>
<li>map the window on the screen</li>
<li>enter the event loop.</li>
</ul>
<p>The event loop is where we receive events from <span class="code">gs</span>. In this case, we want to receive a click event from the button. This event is delivered when the user presses the button.</p>
<a name="gs_fig4"></a>
<img alt="IMAGE MISSING" src="images/ex1.gif"><br>
<em>Figure
2.1:
"Press Me" Button Example</em>
<p>The Erlang <span class="code">gs</span> system includes many examples. All examples in this document can be found in the <span class="code">doc/users_guide/examples/</span> directory. In addition, there is an example directory which contains examples of fractal trees, bouncing balls, a color editor, and a couple of other <span class="code">gs</span> applications.</p>
<h3><a name="id63683">2.3
Creating Objects</a></h3>
<p>You create an object of a specified type with the <span class="code">create/3</span> or the <span class="code">create/4</span> function. The difference is that the <span class="code">create/4</span> function allows you to assign names to the objects. You can then refer to the object instead of using the object identifier. The two forms of the <span class="code">create</span> function look as follows:</p>
<div class="example"><pre>
ObjId = gs:create(Objtype, Parent, Options)
ObjId = gs:create(Objtype, Name, Parent, Options)
</pre></div>
<p>Examples of built-in object types are:</p>
<ul>
<li>window</li>
<li>frame</li>
<li>menu</li>
<li>button</li>
<li>radio button</li>
<li>list box.</li>
</ul>
<p>Objects are created in a hierarchical order. The top level object is the window object which is a container object for most other object types.</p>
<a name="gs_fig5"></a>
<img alt="IMAGE MISSING" src="images/gs1-1-image-4.gif"><br>
<em>Figure
2.2:
Hierarchy of Objects</em>
<p>A frame object is like a sub-window but also a container object which can have children objects.</p>
<p>The <span class="code">create/3</span> or <span class="code">create/4</span> functions return an object identifier, or the tuple <span class="code">{error, Reason}</span>. The object identifier uniquely identifies the object within the system. The object identifier is used to:</p>
<ul>
<li>reconfigure an object</li>
<li>identify events from a particular object.</li>
</ul>
<h3><a name="id59961">2.4
Ownership</a></h3>
<p>The process which creates an object is said to own the object. When a process dies, all objects owned by the process are destroyed. The ownership also means that all events generated by a specific object are delivered to the owner process. The graphics server keeps track of all Erlang processes that create objects. It is therefore able to take appropriate actions if a process should die.</p>
<h3><a name="id59975">2.5
Naming Objects</a></h3>
<p>As shown previously, the <span class="code">create/4</span> function can be used to name objects. The name should be a unique atom which is used to reference the object. The advantage of naming objects is that we do not have to pass object identifiers as arguments to the event loop. Instead, we can use the object name in our code. To name objects in the following example, the code gives the name <span class="code">win1</span> to the window, and <span class="code">b1</span> to the button.</p>
<div class="example"><pre>
-module(ex2).
-copyright('Copyright (c) 1991-97 Ericsson Telecom AB').
-vsn('$Revision: /main/release/2 $ ').
-export([init/0]).
init() ->
S = gs:start(),
gs:create(window,win1,S,[{width,200},{height,100}]),
gs:create(button,b1,win1,[{label, {text,"Press Me"}}]),
gs:config(win1, {map,true}),
loop().
loop() ->
receive
{gs, b1, click, Data, Args} ->
io:format("Hello World!~n",[]),
loop()
end.
</pre></div> <p>The name is <strong>local</strong> for the process which creates the object. This means that the name have a meaning only for one process. Different processes can give different objects the same name. When passing references to objects between processes, the object identifier has to be used because names only has a meaning in a process context. If necessary, the object identifier can be retrieved by reading the <span class="code">id</span> option.</p>
<p>When using distributed Erlang, objects should be named carefully. A named object always refers to an object in the graphics system on the node where it was created. The syntax <span class="code">{Name,Node}</span> should be used when referring to a named object on another node.</p>
<p>The following example receives a canvas object from another node and creates a line named <span class="code">myline1</span> that will appear in the canvas. Also, this example demonstrates how to configure the line using the special syntax.</p>
<div class="example"><pre>
foo() ->
receive
{gs_obj,Canvas,FromNode} -> ok
end,
gs:create(line,myline1,Canvas,[{coords,[{10,10},{20,20}]}]),
gs:config({myline1,FromNode},[{buttonpress,true}]).
</pre></div>
<p>Unnamed objects are transparent. For example, a line object can be created from a canvas on another node and then configured as any other object.</p>
<div class="example"><pre>
bar() ->
receive
{gs_obj,Canvas,_FromNode} -> ok
end,
L = gs:create(line,Canvas,[{coords,[{10,10},{20,20}]}]),
gs:config(L,[{buttonpress,true}]).
</pre></div>
</div>
<div class="footer">
<hr>
<p>Copyright © 1997-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
651
