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, thefg
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
orfalse
- Color.
{R,G,B}
, or a the predefined namered
,green
,blue
,white
,black
,grey
, oryellow
. 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
, orparent
.parent
has a special meaning, namely that this object will have the same cursor as itsparent
.- 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}
, whereStyle
isbold
,italic
, or a combination of those in a list.Size
is an arbitrary integer.Family
is a typeface of typetimes
,courier
,helvetica
,symbol
,new_century_schoolbook
, orscreen
(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}
whereFileName
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}}
.