This section describes the built-in objects of the graphics interface. The following objects exist:

Some objects can act as container objects. The following table describes these relationships:

Most objects have a common subset of options and will be referred to as generic options. They apply to most objects.

The following options apply to objects which can have a frame as parent. Coordinates are relative to the parent.

The following table lists generic Read-Only options:

The basic object is the window object. It is the most common container object. All graphical applications use at least one (top-level) window.

The following tables show all window specific options:

The following example shows how to create a window and configure it to enable various events.

Buttons are the simplest and the most commonly used objects. You press them and get a click event. The following tables show the options for all button types.

Buttons and check buttons are simple to understand, radio buttons are more difficult. Each radio button has a group and a value option. The group option is used to group together two or more radio buttons. Normally, each radio button within a group has a unique value which means that only one radio button can be selected at a time. If two (or more) radio buttons share the same value and one of them is selected, then both will be selected and all others are de-selected. The following short example shows how to program radio button logic in a situation where two of them share the same value.

The example shown creates three radio buttons which are members of the same group. The default behavior is that all radio buttons created by the same process are members of the same group. Normally, only one in a group may be selected at the same time, but since we defined the value-option to have the same value for and , they will both be selected/de-selected simultaneously. The normal radio button group behavior is that all radio buttons within the same group have unique default values.

A label is a simple text field which is used to display text to the user. It is possible to have several lines of text by inserting newline '\ ' characters between each line. The label object does not automatically adjust its size so that text will fit inside. This has to be done manually, or the text may be clipped at the edges.

The frame object acts as a container for other objects. Its main use is to logically and visually group objects together. Grouped objects can then be moved, displayed, or hidden in one single operation.

It is possible to have frame objects within frame objects so that large hierarchical structures of objects can be created.

Entrys are used to prompt the user for text input.

A common usage of the entry object is to listen for the 'Return' key event and then read the text field. The following example shows a simple dialog which prompts the user for a name and returns the tuple when a name is entered, or if the cancel button is pressed.

The program draws the dialog and waits for the user to either press the return key or click one of the buttons. It then reads the text option of the entry and returns the string to the client process.

A listbox is a list of labels with optional scroll bars attached. The user selects one or more predefined alternative entries. You can add and remove entries in the listbox. The first element in a listbox has index 0.

is true if object is selected, false if de-selected.

Note that and are two discrete events: if you have subscribed to both, you will receive both a event and a event when double-clicking on one item (since two rapid clickings are regarded as both a and a ). The subscription of events does result in the events being unsubscribed!

The following example shows a simple application which prompts the user for a text item. The user has the following options:

The canvas object is a simple drawing area. The user can draw graphical objects and move them around the drawing area. The canvas also has optional scroll bars which can be used to scroll the drawing area. The graphical objects that can be created on a canvas object are:

These objects must have a canvas object as a parent, but they are otherwise similar to all other basic objects. The following tables show the options which apply to canvas objects.

Canvas objects have the same types of events as other objects. The following Config-Only options also apply to canvas objects:

The following sections describe the graphical objects which can be drawn on a canvas object.

The canvas arc object is defined within a rectangle and is drawn from a start angle to the extent angle. Origo is in the center of the rectangle.

Canvas Arc Object {Option,Value} Default Description {bw, Int} 1 Defines the width. {coords, [{X1,Y1},{X2,Y2}]}   Defines a rectangle to draw the arc within. {extent, Degrees}     {fg, Color}     {fill, Color|none} none Defines fill color of arc object. {start, Degrees}     {style, arc}   No line segments. {style, chord}   A single line segment connects the two end points of the perimeter section. {style, pieslice} This Style Two lines are drawn between the center of the oval and each end of the perimeter section. Canvas Arc Options

The canvas image object displays images and moves them around in a simple way. The currently supported image formats are bitmap and gif.

Canvas Image Object {Option,Value} Default Description {anchor, Anchor} nw Anchor reference specified by {X,Y} . {bg, Color} <unspec> Background color. Pixel value 0. {bitmap, FileName} <unspec> A bitmap file which contains a bmp bitmap. {coords, [{X,Y}]} <unspec> Position on the canvas. {fg, Color} <unspec> Foreground color. Pixel value 1. {load_gif, FileName} <unspec> Loads a gif image. Canvas Image Object Options

Line Object Drawn on a Canvas {Option,Value} Default Description {arrow, both | none | first | last} none Draws arrows at the end points of the line. {coords, [{X1,Y1},{X2,Y2}, ... {Xn,Yn}]} <unspec> A list of coordinates. The line will be drawn between all pairs in the list. {fg, Color} <unspec> The color of the line. {smooth, Bool} false Smoothing with Bezier splines. {splinesteps, Int} <unspec>   {width, Int} 1 The width of the line. Canvas Line Object Options

Oval Object Drawn on a Canvas {Option,Value} Default Description {bw, Int} 1 Width. {coords, [{X1,Y1},{X2,Y2}]} <unspec> Bounding rectangle which defines shape of object. {fg, Color}     {fill, Color|none} none Object fill color. Canvas Oval Object Options

Canvas Polygon Object {Option,Value} Default Description {bw, Int} 1 Width. {coords, [{X1,Y1},{X2,Y2} | {Xn,Yn}]} <unspec> Defines all points in the polygon. There may be any number of points in the polygon. {fg, Color} black The color of the polygon outline. {fill, Color|none} none   {smooth, Bool} false Smoothing with Bezier splines. {splinesteps, Int} <unspec>   Canvas Polygon Object Options

Rectangle Object Created on a Canvas {Option,Value} Default Description {bw, Int} 1 The width of the border line. {coords, [{X1,Y1},{X2,Y2}]} <unspec> Defines rectangle coordinates. {fg, Color} <unspec> The color of the border line. {fill, Color|none} none Fill color of rectangle. Canvas Rectangle Object Options

Canvas Text Object {Option,Value} Default Description {anchor, Anchor} nw Anchor reference specified by {X,Y}. {coords, [{X, Y}]} <unspec> Position in the canvas. {fg, Color} <unspec> Text color (background color is the canvas color). {justify, left | center | right} <unspec> Tex justification. Only valid with several lines of text. {text, String} <unspec> The text string to display. {width, Int}   The width in pixels. The text will be wrapped into several lines to fit inside the width. Canvas Text Object Options

Menus consist of four object types:

Simple Menu

The following example shows a short demo of the menus:

The grid object is similar to the listbox object. The main difference is that the grid is a multi-column object which is used to display tables. If needed, the grid can send click events when a user presses the mouse button in a table cell. Although the grid has a behavior which is similar to the listbox, the programming is somewhat different. The data in a table cell is represented as a pure object and can be treated as such. This object is called a grid line. It is located at a row in the parent grid. If a grid line is clicked, it sends an event to its owner.

Simple Grid

The following simple example shows how to use the grid.

The editor object is a simple text editor.

Simple Editor

A scale object is used to select a value within a specified range.

The following example prompts a user to specify an RGB-value for the background color of a window.