> ## 3 Options

> ### 3.1 The Option Concept

> 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 `gs:config/2`. The following example shows one way to create a red button with the text "Press Me" on it:

>     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}]),

> The evaluation order of options is not defined. This implies that the grouping of options shown in the following example is not recommended:

>     Rect = gs:create(rectangle,Can, [{coords,[{10,10},{20,20}]},
>                                      {move,{5,5}}]),

> After the operation, the rectangle can be at position `[{10,10},{20,20}]` or `[{15,15},{25,25}]`. The following example produces a deterministic behaviour:

>     Rect = gs:create(rectangle,Can,[{coords,[{10,10},{20,20}]},
>     gs:config(Rect,[{move,{5,5}}]),

> The value of each option can be read individually with the `read/2` function as shown in the following example:

>     Value = gs:read(ObjectId,Option)

> The next example shows how to read the text and the width options from a button:

>     Text = gs:read(Butt, text),
>     Width = gs:read(Butt, width),

> ### 3.2 The Option Tables

> Each object is described in terms of its options. The options are listed in a table as is shown in the following example:

> {Option,Value} | Default | Description
> {fg, Color} | <unspec> | Foreground color of the object
> {map, Bool} | false | Visibility on the screen
> ... | ... | ...
> Options

> The <unspec> default value means that either `gs` or the back-end provides the default value. For example, the `fg` option can be used as follows:

>     Rect = gs:create(rectangle, Window, [{fg, red}]),
>     Color = gs:read(Rect, fg),

> ### 3.3 Config-Only Options

> Most options are read/write key-value tuples such as `{select,true|false}` and `{map,true|false`, 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:

> Config-Only | Description
> flash | Causes the object to flash for 2 seconds.
> raise | Raises the object on top of other overlapping objects.
> {move, {Dx, Dy}} | Moves the object relative to its current position.
> Config-Only Options

> `gs:config(Button,[flash]),` causes the button to flash.

> ### 3.4 Read-Only Options

> The opposite of config-only options are read-only options. The following table exemplifies some read-only options:

> Read-Only | Return | Description
> size | Int | The number of items (entries).
> {get, Index} | String | The entry at index `Index`.
> Read-Only Options

> `EntryString = gs:read(Listbox,{get, Index}),` is an example.

> ### 3.5 Data Types

> As previously stated, each object is described in terms of its options. This section defines the data types for options.

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

> In cases where the type is self-explanatory, the name of the parameter is used. For example, `{move, {Dx,Dy}}`.

Copyright © 1991-2003 Ericsson Utvecklings AB