Erlang -- Options

User's Guide
Reference Manual
Release Notes
PDF
Top

Graphics System (GS)
User's Guide
Version 1.5.15.1

Expand All
Contract All

Chapters

- GS - The Graphics System
  - Top of chapter
  - Introduction
  - Basic Architecture of GS
- Interface Functions
  - Top of chapter
  - Overview
  - A First Example
  - Creating Objects
  - Ownership
  - Naming Objects
- Options
  - Top of chapter
  - The Option Concept
  - The Option Tables
  - Config-Only Options
  - Read-Only Options
  - Data Types
- Events
  - Top of chapter
  - Event Messages
  - Generic Events
  - Object Specific Events
  - Matching Events Against Object Identifiers
  - Matching Events Against Object Names
  - Matching Events Against the Data Field
  - Experimenting with Events
- Fonts
  - Top of chapter
  - The Font Model
- Default Values
  - Top of chapter
  - The Default Value Model
- The Packer
  - Top of chapter
  - The Packer
- Built-In Objects
  - Top of chapter
  - Overview
  - Generic Options
  - Window
  - Button
  - Label
  - Frame
  - Entry
  - Listbox
  - Canvas
  - Menu
  - Grid
  - Editor
  - Scale

# 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
... | ... | ...

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.

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}}.