diff options
Diffstat (limited to 'lib/gs/doc/src/gs_chapter3.xml')
| -rw-r--r-- | lib/gs/doc/src/gs_chapter3.xml | 176 |
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"><unspec></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 <unspec> 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> + |