<!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 -- Options</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.11.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.11</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#id2252132">Introduction</a></li> <li title="Basic Architecture of GS"><a href="gs_chapter1.html#id2260084">Basic Architecture of GS</a></li> </ul> </li> <li id="no" title="Interface Functions" expanded="false">Interface Functions<ul> <li><a href="gs_chapter2.html"> Top of chapter </a></li> <li title="Overview"><a href="gs_chapter2.html#id2259440">Overview</a></li> <li title="A First Example"><a href="gs_chapter2.html#id2251841">A First Example</a></li> <li title="Creating Objects"><a href="gs_chapter2.html#id2252118">Creating Objects</a></li> <li title="Ownership"><a href="gs_chapter2.html#id2260305">Ownership</a></li> <li title="Naming Objects"><a href="gs_chapter2.html#id2260244">Naming Objects</a></li> </ul> </li> <li id="loadscrollpos" title="Options" expanded="true">Options<ul> <li><a href="gs_chapter3.html"> Top of chapter </a></li> <li title="The Option Concept"><a href="gs_chapter3.html#id2251819">The Option Concept</a></li> <li title="The Option Tables"><a href="gs_chapter3.html#id2257882">The Option Tables</a></li> <li title="Config-Only Options"><a href="gs_chapter3.html#id2259929">Config-Only Options</a></li> <li title="Read-Only Options"><a href="gs_chapter3.html#id2259184">Read-Only Options</a></li> <li title="Data Types"><a href="gs_chapter3.html#id2252729">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#id2261952">Event Messages</a></li> <li title="Generic Events"><a href="gs_chapter4.html#id2262070">Generic Events</a></li> <li title="Object Specific Events"><a href="gs_chapter4.html#id2262547">Object Specific Events</a></li> <li title="Matching Events Against Object Identifiers"><a href="gs_chapter4.html#id2262670">Matching Events Against Object Identifiers</a></li> <li title="Matching Events Against Object Names"><a href="gs_chapter4.html#id2262702">Matching Events Against Object Names</a></li> <li title="Matching Events Against the Data Field"><a href="gs_chapter4.html#id2262738">Matching Events Against the Data Field</a></li> <li title="Experimenting with Events"><a href="gs_chapter4.html#id2262786">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#id2262872">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#id2263109">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#id2263312">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#id2263617">Overview</a></li> <li title="Generic Options"><a href="gs_chapter8.html#id2263936">Generic Options</a></li> <li title="Window"><a href="gs_chapter8.html#id2265010">Window</a></li> <li title="Button"><a href="gs_chapter8.html#id2265386">Button</a></li> <li title="Label"><a href="gs_chapter8.html#id2265947">Label</a></li> <li title="Frame"><a href="gs_chapter8.html#id2266123">Frame</a></li> <li title="Entry"><a href="gs_chapter8.html#id2266272">Entry</a></li> <li title="Listbox"><a href="gs_chapter8.html#id2266609">Listbox</a></li> <li title="Canvas"><a href="gs_chapter8.html#id2267327">Canvas</a></li> <li title="Menu"><a href="gs_chapter8.html#id2269512">Menu</a></li> <li title="Grid"><a href="gs_chapter8.html#id2277494">Grid</a></li> <li title="Editor"><a href="gs_chapter8.html#id2278347">Editor</a></li> <li title="Scale"><a href="gs_chapter8.html#id2279121">Scale</a></li> </ul> </li> </ul> </div></div> <div id="content"> <div class="innertube"> <h1>3 Options</h1> <h3><a name="id2251819">3.1 The Option Concept</a></h3> <p>Each object has a set of options. The options are key-value tuples and the key is an atom. Depending on the option, the value can be any Erlang term. Typical options are: x, y, width, height, text, and color. A list of options should be supplied when an object is created . It is also possible to reconfigure an object with the function <span class="code">gs:config/2</span>. The following example shows one way to create a red button with the text "Press Me" on it:</p> <div class="example"><pre> Butt = gs:create(button,Win, [{x,10},{y,10}]), gs:config(Butt, [{width,50},{height,50},{bg,red}]), gs:config(Butt, [{label, {text,"Press Me"}},{y,20}]), </pre></div> <p>The evaluation order of options is not defined. This implies that the grouping of options shown in the following example is not recommended:</p> <div class="example"><pre> Rect = gs:create(rectangle,Can, [{coords,[{10,10},{20,20}]}, {move,{5,5}}]), </pre></div> <p>After the operation, the rectangle can be at position <span class="code">[{10,10},{20,20}]</span> or <span class="code">[{15,15},{25,25}]</span>. The following example produces a deterministic behaviour:</p> <div class="example"><pre> Rect = gs:create(rectangle,Can,[{coords,[{10,10},{20,20}]}, gs:config(Rect,[{move,{5,5}}]), </pre></div> <p>The value of each option can be read individually with the <span class="code">read/2</span> function as shown in the following example:</p> <div class="example"><pre> Value = gs:read(ObjectId,Option) </pre></div> <p>The next example shows how to read the text and the width options from a button:</p> <div class="example"><pre> Text = gs:read(Butt, text), Width = gs:read(Butt, width), </pre></div> <h3><a name="id2257882">3.2 The Option Tables</a></h3> <p>Each object is described in terms of its options. The options are listed in a table as is shown in the following example:</p> <table border="1" cellpadding="2" cellspacing="0"> <tr> <td align="left" valign="middle"><strong>{Option,Value}</strong></td> <td align="left" valign="middle"><strong>Default</strong></td> <td align="left" valign="middle"><strong>Description</strong></td> </tr> <tr> <td align="left" valign="middle">{fg, Color}</td> <td align="left" valign="middle"><unspec></td> <td align="left" valign="middle">Foreground color of the object</td> </tr> <tr> <td align="left" valign="middle">{map, Bool}</td> <td align="left" valign="middle">false</td> <td align="left" valign="middle">Visibility on the screen</td> </tr> <tr> <td align="left" valign="middle">...</td> <td align="left" valign="middle">...</td> <td align="left" valign="middle">...</td> </tr> </table> <em>Table 3.1: Options</em> <p>The <unspec> default value means that either <span class="code">gs</span> or the back-end provides the default value. For example, the <span class="code">fg</span> option can be used as follows:</p> <div class="example"><pre> Rect = gs:create(rectangle, Window, [{fg, red}]), Color = gs:read(Rect, fg), </pre></div> <h3><a name="id2259929">3.3 Config-Only Options</a></h3> <p>Most options are read/write key-value tuples such as <span class="code">{select,true|false}</span> and <span class="code">{map,true|false</span>, but some options are by nature write-only, or read-only. For example, buttons can flash for a short time and canvas objects can be moved dx, dy. The following table exemplifies some config-only options:</p> <table border="1" cellpadding="2" cellspacing="0"> <tr> <td align="left" valign="middle"><strong>Config-Only</strong></td> <td align="left" valign="middle"><strong>Description</strong></td> </tr> <tr> <td align="left" valign="middle">flash</td> <td align="left" valign="middle">Causes the object to flash for 2 seconds.</td> </tr> <tr> <td align="left" valign="middle">raise</td> <td align="left" valign="middle">Raises the object on top of other overlapping objects.</td> </tr> <tr> <td align="left" valign="middle">{move, {Dx, Dy}}</td> <td align="left" valign="middle">Moves the object relative to its current position.</td> </tr> </table> <em>Table 3.2: Config-Only Options</em> <p><span class="code">gs:config(Button,[flash]),</span> causes the button to flash.</p> <h3><a name="id2259184">3.4 Read-Only Options</a></h3> <p>The opposite of config-only options are read-only options. The following table exemplifies some read-only options:</p> <table border="1" cellpadding="2" cellspacing="0"> <tr> <td align="left" valign="middle"><strong>Read-Only</strong></td> <td align="left" valign="middle"><strong>Return</strong></td> <td align="left" valign="middle"><strong>Description</strong></td> </tr> <tr> <td align="left" valign="middle">size</td> <td align="left" valign="middle">Int</td> <td align="left" valign="middle">The number of items (entries).</td> </tr> <tr> <td align="left" valign="middle">{get, Index}</td> <td align="left" valign="middle">String</td> <td align="left" valign="middle">The entry at index <span class="code">Index</span>.</td> </tr> </table> <em>Table 3.3: Read-Only Options</em> <p><span class="code">EntryString = gs:read(Listbox,{get, Index}),</span> is an example.</p> <h3><a name="id2252729">3.5 Data Types</a></h3> <p>As previously stated, each object is described in terms of its options. This section defines the data types for options.</p> <dl> <dt><strong><strong>Anchor|Align.</strong></strong></dt> <dd><span class="code">n|w|s|e|nw|se|ne|sw|center</span></dd> <dt><strong><strong>Atom.</strong></strong></dt> <dd>An Erlang atom such as <span class="code">myWay</span>.</dd> <dt><strong><strong>Bool.</strong></strong></dt> <dd> <span class="code">true</span> or <span class="code">false</span> </dd> <dt><strong><strong>Color.</strong></strong></dt> <dd> <span class="code">{R,G,B}</span>, or a the predefined name <span class="code">red</span>,<span class="code">green</span>, <span class="code">blue</span>, <span class="code">white</span>, <span class="code">black</span>, <span class="code">grey</span>, or <span class="code">yellow</span>. For example <span class="code">{0,0,0}</span> is black and <span class="code">{255,255,255}</span> is white.</dd> <dt><strong><strong>Cursor.</strong></strong></dt> <dd>A mouse cursor, or any of the following: <span class="code">arrow</span>, <span class="code">busy</span>, <span class="code">cross</span>, <span class="code">hand</span>, <span class="code">help</span>, <span class="code">resize</span>, <span class="code">text</span>, or <span class="code">parent</span>. <span class="code">parent</span> has a special meaning, namely that this object will have the same cursor as its <span class="code">parent</span>.</dd> <dt><strong><strong>FileName.</strong></strong></dt> <dd> <span class="code">FileName</span> is a string. The file name may include a directory path and should point out a file of a suitable type. The path can be either absolute or relative to the directory from where Erlang was started.</dd> <dt><strong><strong>Float.</strong></strong></dt> <dd>Any float, for example 3.1415.</dd> <dt><strong><strong>Font.</strong></strong></dt> <dd>A Font is represented as a two or three tuple:<span class="code">{Family,Size}</span> or <span class="code">{Family,Style,Size}</span>, where <span class="code">Style</span> is <span class="code">bold</span>, <span class="code">italic</span>, or a combination of those in a list. <span class="code">Size</span> is an arbitrary integer. <span class="code">Family</span> is a typeface of type <span class="code">times</span>, <span class="code">courier</span>, <span class="code">helvetica</span>, <span class="code">symbol</span>, <span class="code">new_century_schoolbook</span>, or <span class="code">screen</span> (which is a suitable screen font).</dd> <dt><strong><strong>Int.</strong></strong></dt> <dd>Any integer number, for example 42.</dd> <dt><strong><strong>Label.</strong></strong></dt> <dd>A label can either be a plain text label <span class="code">{text, String}</span>, or an image <span class="code">{image, FileName}</span> where <span class="code">FileName</span> should point out a bitmap.</dd> <dt><strong><strong>String.</strong></strong></dt> <dd>An Erlang list of ASCII bytes. For example, <span class="code">"Hi there"=[72,105,32,116,104,101,114,101]</span> </dd> <dt><strong><strong>Term.</strong></strong></dt> <dd>Any Erlang term.</dd> </dl> <p>In cases where the type is self-explanatory, the name of the parameter is used. For example, <span class="code">{move, {Dx,Dy}}</span>.</p> </div> <div class="footer"> <hr> <p>Copyright © 1997-2010 Ericsson AB. All Rights Reserved.</p> </div> </div> </div></body> </html>