20002013
Ericsson AB. All Rights Reserved.
The contents of this file are subject to the Erlang Public License,
Version 1.1, (the "License"); you may not use this file except in
compliance with the License. You should have received a copy of the
Erlang Public License along with this software. If not, it can be
retrieved online at http://www.erlang.org/.
Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
the License for the specific language governing rights and limitations
under the License.
Options
gs_chapter3.xml
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 . The following example shows one way to create a red button with the text "Press Me" on it:
The evaluation order of options is not defined. This implies that the grouping of options shown in the following example is not recommended:
After the operation, the rectangle can be at position or . The following example produces a deterministic behaviour:
The value of each option can be read individually with the function as shown in the following example:
The next example shows how to read the text and the width options from a button:
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 or the back-end provides the default value. For example, the option can be used as follows:
Most options are read/write key-value tuples such as and , 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
causes the button to flash.
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 . |
Read-Only Options
is an example.
Data Types
As previously stated, each object is described in terms of its options. This section defines the data types for options.
Anchor|Align.
- An Erlang atom such as .
Bool.
- or
Color.
- , or a the predefined name ,, , , , , or . For example is black and is white.
Cursor.
- A mouse cursor, or any of the following: , , , , , , , or . has a special meaning, namely that this object will have the same cursor as its .
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: or , where is , , or a combination of those in a list. is an arbitrary integer. is a typeface of type , , , , , or (which is a suitable screen font).
Int.
- Any integer number, for example 42.
Label.
- A label can either be a plain text label , or an image where should point out a bitmap.
String.
- An Erlang list of ASCII bytes. For example,
Term.
- Any Erlang term.
In cases where the type is self-explanatory, the name of the parameter is used. For example, .