1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
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>
|
