The R13B03 release.OTP_R13B03

1 files changed, 176 insertions, 0 deletions

diff --git a/lib/gs/doc/src/gs_chapter3.xml b/lib/gs/doc/src/gs_chapter3.xml
new file mode 100644
index 0000000000..66b1b975a8
--- /dev/null
+++ b/lib/gs/doc/src/gs_chapter3.xml
@@ -0,0 +1,176 @@
+<?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>
+