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

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

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
... ... ...
Table 3.1:   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.
Table 3.2:   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.
Table 3.3:   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.

An Erlang atom such as myWay.
true or false
{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.
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 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.
Any float, for example 3.1415.
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).
Any integer number, for example 42.
A label can either be a plain text label {text, String}, or an image {image, FileName} where FileName should point out a bitmap.
An Erlang list of ASCII bytes. For example, "Hi there"=[72,105,32,116,104,101,114,101]
Any Erlang term.

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