<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2000</year><year>2009</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      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.
    
    </legalnotice>

    <title>Options</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
    <file>gs_chapter3.xml</file>
  </header>

  <section>
    <title>The Option Concept</title>
    <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 <c><![CDATA[gs:config/2]]></c>. The following example shows one way to create a red button with the text "Press Me" on it:</p>
    <code type="none"><![CDATA[
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}]),
    ]]></code>
    <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>
    <code type="none"><![CDATA[
Rect = gs:create(rectangle,Can, [{coords,[{10,10},{20,20}]},
                                 {move,{5,5}}]),
    ]]></code>
    <p>After the operation, the rectangle can be at position <c><![CDATA[[{10,10},{20,20}]]]></c> or <c><![CDATA[[{15,15},{25,25}]]]></c>. The following example produces a deterministic behaviour:</p>
    <code type="none"><![CDATA[
Rect = gs:create(rectangle,Can,[{coords,[{10,10},{20,20}]},
gs:config(Rect,[{move,{5,5}}]),
    ]]></code>
    <p>The value of each option can be read individually with the <c><![CDATA[read/2]]></c> function as shown in the following example:</p>
    <code type="none"><![CDATA[
Value = gs:read(ObjectId,Option)
    ]]></code>
    <p>The next example shows how to read the text and the width options from a button:</p>
    <code type="none"><![CDATA[
Text = gs:read(Butt, text),
Width = gs:read(Butt, width),
    ]]></code>
  </section>

  <section>
    <title>The Option Tables</title>
    <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>
      <row>
        <cell align="left" valign="middle"><em>{Option,Value}</em></cell>
        <cell align="left" valign="middle"><em>Default</em></cell>
        <cell align="left" valign="middle"><em>Description</em></cell>
      </row>
      <row>
        <cell align="left" valign="middle">{fg, Color}</cell>
        <cell align="left" valign="middle">&lt;unspec&gt;</cell>
        <cell align="left" valign="middle">Foreground color of the object</cell>
      </row>
      <row>
        <cell align="left" valign="middle">{map, Bool}</cell>
        <cell align="left" valign="middle">false</cell>
        <cell align="left" valign="middle">Visibility on the screen</cell>
      </row>
      <row>
        <cell align="left" valign="middle">...</cell>
        <cell align="left" valign="middle">...</cell>
        <cell align="left" valign="middle">...</cell>
      </row>
      <tcaption>Options</tcaption>
    </table>
    <p>The &lt;unspec&gt; default value means that either <c><![CDATA[gs]]></c> or the back-end provides the default value.  For example, the <c><![CDATA[fg]]></c> option can be used as follows:</p>
    <code type="none"><![CDATA[
Rect = gs:create(rectangle, Window, [{fg, red}]),
Color = gs:read(Rect, fg),
    ]]></code>
  </section>

  <section>
    <title>Config-Only Options</title>
    <p>Most options are read/write key-value tuples such as <c><![CDATA[{select,true|false}]]></c> and <c><![CDATA[{map,true|false]]></c>, 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>
      <row>
        <cell align="left" valign="middle"><em>Config-Only</em></cell>
        <cell align="left" valign="middle"><em>Description</em></cell>
      </row>
      <row>
        <cell align="left" valign="middle">flash</cell>
        <cell align="left" valign="middle">Causes the object to flash for 2 seconds.</cell>
      </row>
      <row>
        <cell align="left" valign="middle">raise</cell>
        <cell align="left" valign="middle">Raises the object on top of other overlapping objects.</cell>
      </row>
      <row>
        <cell align="left" valign="middle">{move, {Dx, Dy}}</cell>
        <cell align="left" valign="middle">Moves the object relative to its current position.</cell>
      </row>
      <tcaption>Config-Only Options</tcaption>
    </table>
    <p><c><![CDATA[gs:config(Button,[flash]),]]></c> causes the button to flash.</p>
  </section>

  <section>
    <title>Read-Only Options</title>
    <p>The opposite of config-only options are read-only options. The following table exemplifies some read-only options:</p>
    <table>
      <row>
        <cell align="left" valign="middle"><em>Read-Only</em></cell>
        <cell align="left" valign="middle"><em>Return</em></cell>
        <cell align="left" valign="middle"><em>Description</em></cell>
      </row>
      <row>
        <cell align="left" valign="middle">size</cell>
        <cell align="left" valign="middle">Int</cell>
        <cell align="left" valign="middle">The number of items (entries).</cell>
      </row>
      <row>
        <cell align="left" valign="middle">{get, Index}</cell>
        <cell align="left" valign="middle">String</cell>
        <cell align="left" valign="middle">The entry at index <c><![CDATA[Index]]></c>.</cell>
      </row>
      <tcaption>Read-Only Options</tcaption>
    </table>
    <p><c><![CDATA[EntryString = gs:read(Listbox,{get, Index}),]]></c> is an example.</p>
  </section>

  <section>
    <title>Data Types</title>
    <p>As previously stated, each object is described in terms of its options. This section defines the data types for options.</p>
    <taglist>
      <tag><em>Anchor|Align.</em></tag>
      <item><c><![CDATA[n|w|s|e|nw|se|ne|sw|center]]></c></item>
      <tag><em>Atom.</em></tag>
      <item>An Erlang atom such as <c><![CDATA[myWay]]></c>.</item>
      <tag><em>Bool.</em></tag>
      <item><c><![CDATA[true]]></c> or <c><![CDATA[false]]></c></item>
      <tag><em>Color.</em></tag>
      <item><c><![CDATA[{R,G,B}]]></c>, or a the predefined name <c><![CDATA[red]]></c>,<c><![CDATA[green]]></c>, <c><![CDATA[blue]]></c>, <c><![CDATA[white]]></c>, <c><![CDATA[black]]></c>, <c><![CDATA[grey]]></c>, or <c><![CDATA[yellow]]></c>. For example <c><![CDATA[{0,0,0}]]></c> is black and <c><![CDATA[{255,255,255}]]></c> is white.</item>
      <tag><em>Cursor.</em></tag>
      <item>A mouse cursor, or any of the following: <c><![CDATA[arrow]]></c>, <c><![CDATA[busy]]></c>, <c><![CDATA[cross]]></c>, <c><![CDATA[hand]]></c>, <c><![CDATA[help]]></c>, <c><![CDATA[resize]]></c>, <c><![CDATA[text]]></c>, or <c><![CDATA[parent]]></c>. <c><![CDATA[parent]]></c> has a special meaning, namely that this object will have the same cursor as its <c><![CDATA[parent]]></c>.</item>
      <tag><em>FileName.</em></tag>
      <item><c><![CDATA[FileName]]></c> 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.</item>
      <tag><em>Float.</em></tag>
      <item>Any float, for example 3.1415.</item>
      <tag><em>Font.</em></tag>
      <item>A Font is represented as a two or three tuple:<c><![CDATA[{Family,Size}]]></c> or <c><![CDATA[{Family,Style,Size}]]></c>, where <c><![CDATA[Style]]></c> is <c><![CDATA[bold]]></c>, <c><![CDATA[italic]]></c>, or a combination of those in a list. <c><![CDATA[Size]]></c> is an arbitrary integer. <c><![CDATA[Family]]></c> is a typeface of type <c><![CDATA[times]]></c>, <c><![CDATA[courier]]></c>, <c><![CDATA[helvetica]]></c>, <c><![CDATA[symbol]]></c>, <c><![CDATA[new_century_schoolbook]]></c>, or <c><![CDATA[screen]]></c> (which is a suitable screen font).</item>
      <tag><em>Int.</em></tag>
      <item>Any integer number, for example 42.</item>
      <tag><em>Label.</em></tag>
      <item>A label can either be a plain text label <c><![CDATA[{text, String}]]></c>, or an image <c><![CDATA[{image, FileName}]]></c> where <c><![CDATA[FileName]]></c> should point out a bitmap.</item>
      <tag><em>String.</em></tag>
      <item>An Erlang list of ASCII bytes. For example, 
      <c><![CDATA["Hi there"=[72,105,32,116,104,101,114,101]]]></c></item>
      <tag><em>Term.</em></tag>
      <item>Any Erlang term.</item>
    </taglist>
    <p>In cases where the type is self-explanatory, the name of the parameter is used. For example, <c><![CDATA[{move, {Dx,Dy}}]]></c>.</p>
  </section>
</chapter>

