diff options
Diffstat (limited to 'lib/gs/doc/src/gs_chapter3.xml')
| -rw-r--r-- | lib/gs/doc/src/gs_chapter3.xml | 177 |
1 files changed, 0 insertions, 177 deletions
diff --git a/lib/gs/doc/src/gs_chapter3.xml b/lib/gs/doc/src/gs_chapter3.xml deleted file mode 100644 index f21e75d970..0000000000 --- a/lib/gs/doc/src/gs_chapter3.xml +++ /dev/null @@ -1,177 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>2000</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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> - |