<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
<year>2000</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
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.
</legalnotice>
<title>Built-In Objects</title>
<prepared></prepared>
<docno></docno>
<date></date>
<rev></rev>
<file>gs_chapter8.xml</file>
</header>
<section>
<title>Overview</title>
<p>This section describes the built-in objects of the graphics interface. The following objects exist:</p>
<taglist>
<tag><em>Window</em></tag>
<item>An ordinary window.</item>
<tag><em>Button</em></tag>
<item>A simple press button.</item>
<tag><em>Checkbutton</em></tag>
<item>A button with a check-mark indicator.</item>
<tag><em>Radiobutton</em></tag>
<item>A button with an indicator that has an only-one-selected-at-a-time property.</item>
<tag><em>Label</em></tag>
<item>Shows a text or bitmap.</item>
<tag><em>Frame</em></tag>
<item>A plain container object. It is used for logical and visual grouping of objects.</item>
<tag><em>Entry</em></tag>
<item>A one-line object for entering text.</item>
<tag><em>Listbox</em></tag>
<item>A list of text strings.</item>
<tag><em>Canvas</em></tag>
<item>A drawing area which contains light-weight objects such as rectangle, line, etc.</item>
<tag><em>Menu</em></tag>
<item>A collection of objects for constructing pull-down and pop-up menus.</item>
<tag><em>Grid</em></tag>
<item>An object for showing tables. A kind of multi-column listbox.</item>
<tag><em>Editor</em></tag>
<item>A multi-line text editor.</item>
<tag><em>Scale</em></tag>
<item>To select a value within a range.</item>
</taglist>
<p>Some objects can act as container objects. The following table describes these relationships:</p>
<table>
<row>
<cell align="left" valign="middle"><em>Objects</em></cell>
<cell align="left" valign="middle"><em>Valid Parents</em></cell>
</row>
<row>
<cell align="left" valign="middle">window</cell>
<cell align="left" valign="middle">window, gs</cell>
</row>
<row>
<cell align="left" valign="middle">buttons, canvas, editor, entry, frame, grid, label, listbox, menubar, scale</cell>
<cell align="left" valign="middle">frame, window</cell>
</row>
<row>
<cell align="left" valign="middle">arc, image, line, oval, polygon, rectangle, text</cell>
<cell align="left" valign="middle">canvas</cell>
</row>
<row>
<cell align="left" valign="middle">menubutton</cell>
<cell align="left" valign="middle">menubar, window, frame</cell>
</row>
<row>
<cell align="left" valign="middle">gridline</cell>
<cell align="left" valign="middle">grid</cell>
</row>
<row>
<cell align="left" valign="middle">menuitem</cell>
<cell align="left" valign="middle">menu</cell>
</row>
<row>
<cell align="left" valign="middle">menu</cell>
<cell align="left" valign="middle">menubutton, menuitem (with {itemtype, cascade}), window, frame (the last two are for pop-up menus)</cell>
</row>
<tcaption>Relations Between Objects and Container Objects</tcaption>
</table>
</section>
<section>
<title>Generic Options</title>
<p>Most objects have a common subset of options and will be referred to as generic options. They apply to most objects.</p>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">beep</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">A beep will sound. Applies to all objects.</cell>
</row>
<row>
<cell align="left" valign="middle">{bg, Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Background color. Applies to objects which have a background color.</cell>
</row>
<row>
<cell align="left" valign="middle">{data, Term}</cell>
<cell align="left" valign="middle">[]</cell>
<cell align="left" valign="middle">Always delivered with the event in the data field. Applies to all objects.</cell>
</row>
<row>
<cell align="left" valign="middle">{default,Objecttype,{Key,Value}}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Applies to all container objects. Specifies the default value for an option for children of type Objecttype.</cell>
</row>
<row>
<cell align="left" valign="middle">{enable, Bool}</cell>
<cell align="left" valign="middle">true</cell>
<cell align="left" valign="middle">Objects can be enabled or disabled. A disabled object cannot be clicked on, and text cannot be entered. Applies to buttons, menuitem, entry, editor, scale.</cell>
</row>
<row>
<cell align="left" valign="middle">{font, Font}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Applies to all text related objects and the grid.</cell>
</row>
<row>
<cell align="left" valign="middle">{fg, Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Foreground color. Applies to objects which have a foreground color.</cell>
</row>
<row>
<cell align="left" valign="middle">flush</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Ensures that front-end and back-end are synchronized. Applies to all objects.</cell>
</row>
<row>
<cell align="left" valign="middle">{setfocus, Bool}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Set or remove keyboard focus to this object. Applies to objects which can receive keyboard events.</cell>
</row>
<tcaption>Generic Options</tcaption>
</table>
<p>The following options apply to objects which can have a <em>frame</em> as parent. Coordinates are relative to the parent.</p>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{cursor, Cursor}</cell>
<cell align="left" valign="middle">parent</cell>
<cell align="left" valign="middle">The appearance of the mouse cursor.</cell>
</row>
<row>
<cell align="left" valign="middle">{height, Int}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The height in pixels.</cell>
</row>
<row>
<cell align="left" valign="middle">{pack_x, Column|{StartColumn,EndColumn}}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Packing position. See The Packer section.</cell>
</row>
<row>
<cell align="left" valign="middle">{pack_y, row|{Startrow,Endrow}}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Packing position. See The Packer section.</cell>
</row>
<row>
<cell align="left" valign="middle">{pack_xy, {Column,row}}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Packing position. See The Packer section.</cell>
</row>
<row>
<cell align="left" valign="middle">{width, Int}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The width in pixels.</cell>
</row>
<row>
<cell align="left" valign="middle">{x, Int}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The x coordinate within the parent objects frame in pixels. 0 is to the left.</cell>
</row>
<row>
<cell align="left" valign="middle">{y, Int}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The y coordinate in pixels. 0 is at the top.</cell>
</row>
<tcaption>Generic Options (Frame as Parent)</tcaption>
</table>
<table>
<row>
<cell align="left" valign="middle"><em>Config-Only</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">lower</cell>
<cell align="left" valign="middle">Lowers this object to the bottom in the visual hierarchy.</cell>
</row>
<row>
<cell align="left" valign="middle">raise</cell>
<cell align="left" valign="middle">Lowers this object in the visual hierarchy.</cell>
</row>
<tcaption>Generic Config-Only Options</tcaption>
</table>
<p>The following table lists generic Read-Only options:</p>
<table>
<row>
<cell align="left" valign="middle"><em>Read-Only</em></cell>
<cell align="left" valign="middle"><em>Return</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">children</cell>
<cell align="left" valign="middle">[ObjectId1, ..., ObjectIdN]</cell>
<cell align="left" valign="middle">All children</cell>
</row>
<row>
<cell align="left" valign="middle">{choose_font,Font}</cell>
<cell align="left" valign="middle">Font</cell>
<cell align="left" valign="middle">Return the font that is actually used if a particular font is given.</cell>
</row>
<row>
<cell align="left" valign="middle">id</cell>
<cell align="left" valign="middle">ObjectId</cell>
<cell align="left" valign="middle">Return the object id for this object. Useful if the object is a named object.</cell>
</row>
<row>
<cell align="left" valign="middle">{font_wh,{Font,Text}}</cell>
<cell align="left" valign="middle">{Width,Height}</cell>
<cell align="left" valign="middle">Return the size of a text in a specified font. It returns the size of the font that is actually chosen by the back-end.</cell>
</row>
<row>
<cell align="left" valign="middle">type</cell>
<cell align="left" valign="middle">Atom</cell>
<cell align="left" valign="middle">The type of this object.</cell>
</row>
<row>
<cell align="left" valign="middle">parent</cell>
<cell align="left" valign="middle">ObjectId</cell>
<cell align="left" valign="middle">The parent of this object.</cell>
</row>
<tcaption>Generic Read-Only Options</tcaption>
</table>
<section>
<title>Generic Event Options</title>
<p>The table below lists all generic event options:
</p>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
</row>
<row>
<cell align="left" valign="middle">{buttonpress, Bool}</cell>
<cell align="left" valign="middle">false</cell>
</row>
<row>
<cell align="left" valign="middle">{buttonrelease, Bool}</cell>
<cell align="left" valign="middle">false</cell>
</row>
<row>
<cell align="left" valign="middle">{enter, Bool}</cell>
<cell align="left" valign="middle">false</cell>
</row>
<row>
<cell align="left" valign="middle">{leave, Bool}</cell>
<cell align="left" valign="middle">false</cell>
</row>
<row>
<cell align="left" valign="middle">{keypress, Bool}</cell>
<cell align="left" valign="middle">false</cell>
</row>
<row>
<cell align="left" valign="middle">{motion, Bool}</cell>
<cell align="left" valign="middle">false</cell>
</row>
<tcaption>Generic Event Options</tcaption>
</table>
</section>
</section>
<section>
<title>Window</title>
<p>The basic object is the window object. It is the most common container object. All graphical applications use at least one (top-level) window.</p>
<marker id="gs_fig8"></marker>
<image file="images/window.gif">
<icaption>Empty Window titled "A Window".</icaption>
</image>
<p>The following tables show all window specific options:</p>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{bg, Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">{R,G,B} or a color name</cell>
</row>
<row>
<cell align="left" valign="middle">{configure,Bool}</cell>
<cell align="left" valign="middle">false</cell>
<cell align="left" valign="middle">Will generate a <c><![CDATA[configure]]></c>event when the window has been resized or moved. The <c><![CDATA[Args]]></c>field contains [Width,Height,X,Y|_]</cell>
</row>
<row>
<cell align="left" valign="middle">{destroy,Bool}</cell>
<cell align="left" valign="middle">true</cell>
<cell align="left" valign="middle">Will generate a <c><![CDATA[destroy]]></c>event when the window is destroyed from the window manager. All GS applications should handle this event.</cell>
</row>
<row>
<cell align="left" valign="middle">{iconname, String}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle"> </cell>
</row>
<row>
<cell align="left" valign="middle">{iconify, Bool}</cell>
<cell align="left" valign="middle">false</cell>
<cell align="left" valign="middle"> </cell>
</row>
<row>
<cell align="left" valign="middle">{map, Bool}</cell>
<cell align="left" valign="middle">false</cell>
<cell align="left" valign="middle">Make it visible on the screen</cell>
</row>
<row>
<cell align="left" valign="middle">{title, String}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The title of the window. The default is the internal widget name which is platform specific.</cell>
</row>
<tcaption>Window Options</tcaption>
</table>
<table>
<row>
<cell align="left" valign="middle"><em>Config-Only</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">raise</cell>
<cell align="left" valign="middle">Raise window on top of all other windows.</cell>
</row>
<row>
<cell align="left" valign="middle">lower</cell>
<cell align="left" valign="middle">Lower window to background.</cell>
</row>
<tcaption>Window Config-Only Options</tcaption>
</table>
<p>The following example shows how to create a window and configure it to enable various events.</p>
<codeinclude file="examples/ex7.erl" tag="" type="erl"></codeinclude>
</section>
<section>
<title>Button</title>
<marker id="gs_fig9"></marker>
<image file="images/buttons.gif">
<icaption>Radio Buttons, Check Buttons, and Ordinary Button</icaption>
</image>
<p>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.</p>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{align, Align}</cell>
<cell align="left" valign="middle">center</cell>
<cell align="left" valign="middle">Text alignment within the frame.</cell>
</row>
<row>
<cell align="left" valign="middle">{justify, left | center | right}</cell>
<cell align="left" valign="middle">center</cell>
<cell align="left" valign="middle">Justification is only valid when there are several lines of text.</cell>
</row>
<row>
<cell align="left" valign="middle">{label, Label}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Text or image to show.</cell>
</row>
<row>
<cell align="left" valign="middle">{select, Bool}</cell>
<cell align="left" valign="middle">false</cell>
<cell align="left" valign="middle">Check buttons and radio buttons. true means that the button is selected.</cell>
</row>
<row>
<cell align="left" valign="middle">{underline, Int}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Underline character N to indicate a keyboard accelerator.</cell>
</row>
<row>
<cell align="left" valign="middle">{group, Atom}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Radio button: only one per group is selected at one time. Check button: All in the same group are selected automatically.</cell>
</row>
<row>
<cell align="left" valign="middle">{value, Atom}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Radio buttons only. Groups radio buttons together within a group.</cell>
</row>
<tcaption>Options for all Button Types</tcaption>
</table>
<table>
<row>
<cell align="left" valign="middle"><em>Config-Only</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">flash</cell>
<cell align="left" valign="middle">Flash button</cell>
</row>
<row>
<cell align="left" valign="middle">invoke</cell>
<cell align="left" valign="middle">Explicit button press.</cell>
</row>
<row>
<cell align="left" valign="middle">toggle</cell>
<cell align="left" valign="middle">Check buttons only. Toggles select value.</cell>
</row>
<tcaption>Config-Only Options for all Button types</tcaption>
</table>
<table>
<row>
<cell align="left" valign="middle"><em>Buttontype</em></cell>
<cell align="left" valign="middle"><em>Event</em></cell>
</row>
<row>
<cell align="left" valign="middle">normal</cell>
<cell align="left" valign="middle">{gs, itemId, click, Data, [Text| _]}</cell>
</row>
<row>
<cell align="left" valign="middle">check</cell>
<cell align="left" valign="middle">{gs, itemId, click, Data, [Text, Group, Bool | _]}</cell>
</row>
<row>
<cell align="left" valign="middle">radio</cell>
<cell align="left" valign="middle">{gs, itemId, click, Data, [Text, Group, Value | _]}</cell>
</row>
<tcaption>>Events for all Button types</tcaption>
</table>
<p>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.</p>
<codeinclude file="examples/ex8.erl" tag="" type="erl"></codeinclude>
<marker id="gs_fig10"></marker>
<image file="images/ex8.gif">
<icaption>Radio Button Group with Last Button Selected</icaption>
</image>
<p>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 <c><![CDATA[rb1]]></c> and <c><![CDATA[rb2]]></c>, 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.</p>
</section>
<section>
<title>Label</title>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{align,Align}</cell>
<cell align="left" valign="middle">center</cell>
<cell align="left" valign="middle">How the text is aligned within the frame.</cell>
</row>
<row>
<cell align="left" valign="middle">{justify,left|right|center}</cell>
<cell align="left" valign="middle">left</cell>
<cell align="left" valign="middle">How to justify several lines of text.</cell>
</row>
<row>
<cell align="left" valign="middle">{label,Label}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Text or image to show.</cell>
</row>
<row>
<cell align="left" valign="middle">{underline,Int}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Underline character N to indicate a keyboard accelerator.</cell>
</row>
<tcaption>Label Options</tcaption>
</table>
<p>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.</p>
</section>
<section>
<title>Frame</title>
<p>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.</p>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{bw,Int}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Border width</cell>
</row>
<row>
<cell align="left" valign="middle">{packer_x,PackList}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Makes the frame pack its children. See the packer section.</cell>
</row>
<row>
<cell align="left" valign="middle">{packer_y,PackList}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Makes the frame pack its children. See the packer section.</cell>
</row>
<tcaption>Frame Options</tcaption>
</table>
<p>It is possible to have frame objects within frame objects so that large hierarchical structures of objects can be created.</p>
</section>
<section>
<title>Entry</title>
<marker id="gs_fig11"></marker>
<image file="images/ex9.gif">
<icaption>Label and Entry Objects for User Input</icaption>
</image>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{justify, left|right|center}</cell>
<cell align="left" valign="middle">left</cell>
<cell align="left" valign="middle">Text justification in entry field.</cell>
</row>
<row>
<cell align="left" valign="middle">{text, String}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Use this option to initially set some text, and to read the text.</cell>
</row>
<tcaption>Entry Options</tcaption>
</table>
<p>Entrys are used to prompt the user for text input.</p>
<table>
<row>
<cell align="left" valign="middle"><em>Config-Only</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{delete, {From, To}}</cell>
<cell align="left" valign="middle">Deletes the characters within index {From,To}.</cell>
</row>
<row>
<cell align="left" valign="middle">{delete, last}</cell>
<cell align="left" valign="middle">Deletes the last character.</cell>
</row>
<row>
<cell align="left" valign="middle">{delete, Index}</cell>
<cell align="left" valign="middle">Deletes the character at position Index.</cell>
</row>
<row>
<cell align="left" valign="middle">{insert, {Index, String}}</cell>
<cell align="left" valign="middle">Inserts text at the specific character position. Index starts from 0.</cell>
</row>
<row>
<cell align="left" valign="middle">{select, {From, To}}</cell>
<cell align="left" valign="middle">Selects a range.</cell>
</row>
<row>
<cell align="left" valign="middle">{select, clear}</cell>
<cell align="left" valign="middle">De-selects selected text.</cell>
</row>
<tcaption>Entry Config-Only Options</tcaption>
</table>
<p>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 <c><![CDATA[{name,Name}]]></c> when a name is entered, or <c><![CDATA[cancel]]></c> if the cancel button is pressed.</p>
<codeinclude file="examples/ex9.erl" tag="" type="erl"></codeinclude>
<p>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.</p>
</section>
<section>
<title>Listbox</title>
<p>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.</p>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{hscroll, Bool | top | bottom}</cell>
<cell align="left" valign="middle">true</cell>
<cell align="left" valign="middle">Horizontal scroll bar.</cell>
</row>
<row>
<cell align="left" valign="middle">{items, [String, String ... String]}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">All items (entries) in the listbox.</cell>
</row>
<row>
<cell align="left" valign="middle">{scrollbg, Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Foreground color of scroll bar.</cell>
</row>
<row>
<cell align="left" valign="middle">{scrollfg, Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Background color of scroll bar.</cell>
</row>
<row>
<cell align="left" valign="middle">{selectmode, single | multiple}</cell>
<cell align="left" valign="middle">single</cell>
<cell align="left" valign="middle">Controls if it is possible to have several items selected at the same time.</cell>
</row>
<row>
<cell align="left" valign="middle">{vscroll, Bool | left | right}</cell>
<cell align="left" valign="middle">true</cell>
<cell align="left" valign="middle">Vertical scroll bar.</cell>
</row>
<tcaption>Listbox Options</tcaption>
</table>
<table>
<row>
<cell align="left" valign="middle"><em>Config-Only</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{add, {Index, String}}</cell>
<cell align="left" valign="middle">Add an item at specified index.</cell>
</row>
<row>
<cell align="left" valign="middle">{add, String}</cell>
<cell align="left" valign="middle">Add an item last.</cell>
</row>
<row>
<cell align="left" valign="middle">{change, {Index,String}}</cell>
<cell align="left" valign="middle">Change one item.</cell>
</row>
<row>
<cell align="left" valign="middle">clear</cell>
<cell align="left" valign="middle">Delete all items.</cell>
</row>
<row>
<cell align="left" valign="middle">{del, Index | {From, To}}</cell>
<cell align="left" valign="middle">Delete an item at specified index, or all from index From to index To.</cell>
</row>
<row>
<cell align="left" valign="middle">{see, Index}</cell>
<cell align="left" valign="middle">Make the item at specified index visible.</cell>
</row>
<row>
<cell align="left" valign="middle">{selection, Index | {From,To}| clear}</cell>
<cell align="left" valign="middle">Select an item (highlight it). Clear erases the selection.</cell>
</row>
<tcaption>Listbox Cinfig-only Options</tcaption>
</table>
<table>
<row>
<cell align="left" valign="middle"><em>Read-Only</em></cell>
<cell align="left" valign="middle"><em>Return</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">selection</cell>
<cell align="left" valign="middle">ListOfStrings</cell>
<cell align="left" valign="middle">Returns current selection. All selected item indices will be returned in a list.</cell>
</row>
<row>
<cell align="left" valign="middle">size</cell>
<cell align="left" valign="middle">Int</cell>
<cell align="left" valign="middle">The number of items (entries) in the listbox.</cell>
</row>
<row>
<cell align="left" valign="middle">{get, Index}</cell>
<cell align="left" valign="middle">String</cell>
<cell align="left" valign="middle">Returns item at specified index.</cell>
</row>
<tcaption>Listbox Read-Only Options</tcaption>
</table>
<table>
<row>
<cell align="left" valign="middle"><em>Event</em></cell>
</row>
<row>
<cell align="left" valign="middle">{gs, ListBox, click, Data, [Index, Text,Bool | _]}</cell>
</row>
<row>
<cell align="left" valign="middle">{gs, ListBox, doubleclick, Data, [Index, Text,Bool | _]}</cell>
</row>
<tcaption>Listbox Events</tcaption>
</table>
<p><c><![CDATA[Bool]]></c> is true if object is selected, false if de-selected.</p>
<p>Note that <c><![CDATA[click]]></c> and <c><![CDATA[doubleclick]]></c> are two discrete events: if you have subscribed to both, you will receive both a <c><![CDATA[click]]></c> event and a <c><![CDATA[doubleclick]]></c> event when double-clicking on one item (since two rapid clickings are regarded as both a <c><![CDATA[click]]></c> and a <c><![CDATA[doubleclick]]></c>). The subscription of <c><![CDATA[doubleclick]]></c> events does <c><![CDATA[not]]></c> result in the <c><![CDATA[click]]></c> events being unsubscribed!</p>
<p>The following example shows a simple application which prompts the user for a text item. The user has the following options:</p>
<list type="bulleted">
<item>browse the items and then double-click the required item</item>
<item>type the name into the entry field and then press the Return key</item>
<item>select the required item and then click the OK button.</item>
</list>
<marker id="gs_fig12"></marker>
<image file="images/ex1.gif">
<icaption>
Simple Browser Dialog</icaption>
</image>
<codeinclude file="examples/ex10.erl" tag="" type="erl"></codeinclude>
</section>
<section>
<title>Canvas</title>
<p>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:</p>
<list type="bulleted">
<item>arc</item>
<item>image</item>
<item>line</item>
<item>oval</item>
<item>polygon</item>
<item>rectangle</item>
<item>text.</item>
</list>
<p>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.</p>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{bg, Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Color of the drawing area.</cell>
</row>
<row>
<cell align="left" valign="middle">{hscroll, Bool | top | bottom}</cell>
<cell align="left" valign="middle">false</cell>
<cell align="left" valign="middle">Horizontal scroll bar.</cell>
</row>
<row>
<cell align="left" valign="middle">{scrollbg, Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Foreground color of scroll bar.</cell>
</row>
<row>
<cell align="left" valign="middle">{scrollfg, Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Background color of scroll bar.</cell>
</row>
<row>
<cell align="left" valign="middle">{scrollregion, {X1,Y1,X2,Y2}}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The size of the drawing area to be scrolled. </cell>
</row>
<row>
<cell align="left" valign="middle">{vscroll, Bool | left | right}</cell>
<cell align="left" valign="middle">false</cell>
<cell align="left" valign="middle">Vertical scroll bar.</cell>
</row>
<tcaption>Canvas Options</tcaption>
</table>
<table>
<row>
<cell align="left" valign="middle"><em>Read-Only</em></cell>
<cell align="left" valign="middle"><em>Return</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{hit, {X,Y}}</cell>
<cell align="left" valign="middle">list of ObjectId</cell>
<cell align="left" valign="middle">Returns the canvas objects at X,Y.</cell>
</row>
<row>
<cell align="left" valign="middle">{hit, [{X1,Y1},{X2,Y2}]}</cell>
<cell align="left" valign="middle">list of ObjectId</cell>
<cell align="left" valign="middle">Returns the canvas objects which are hit by the rectangle.</cell>
</row>
<tcaption>Canvas Read-Only Options</tcaption>
</table>
<p>Canvas objects have the same types of events as other objects. The following Config-Only options also apply to canvas objects:</p>
<table>
<row>
<cell align="left" valign="middle"><em>Config-Only</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">lower</cell>
<cell align="left" valign="middle">Lowers the object.</cell>
</row>
<row>
<cell align="left" valign="middle">{move, {Dx, Dy}}</cell>
<cell align="left" valign="middle">Moves object relative to its current position.</cell>
</row>
<row>
<cell align="left" valign="middle">raise</cell>
<cell align="left" valign="middle">Raises the object above all other objects.</cell>
</row>
<tcaption>Canvas Config-Only Options</tcaption>
</table>
<p>The following sections describe the graphical objects which can be drawn on a canvas object.</p>
<section>
<title>The Canvas Arc Object</title>
<p>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.</p>
<marker id="gs_fig13"></marker>
<image file="images/arc.gif">
<icaption>Canvas Arc Object</icaption>
</image>
<code type="none"><![CDATA[
gs:create(arc,Canvas,[{coords,[{10,10},{80,80}]},{fill,yellow}]).
]]></code>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{bw, Int}</cell>
<cell align="left" valign="middle">1</cell>
<cell align="left" valign="middle">Defines the width.</cell>
</row>
<row>
<cell align="left" valign="middle">{coords, [{X1,Y1},{X2,Y2}]}</cell>
<cell align="left" valign="middle"> </cell>
<cell align="left" valign="middle">Defines a rectangle to draw the arc within.</cell>
</row>
<row>
<cell align="left" valign="middle">{extent, Degrees}</cell>
<cell align="left" valign="middle"> </cell>
<cell align="left" valign="middle"> </cell>
</row>
<row>
<cell align="left" valign="middle">{fg, Color}</cell>
<cell align="left" valign="middle"> </cell>
<cell align="left" valign="middle"> </cell>
</row>
<row>
<cell align="left" valign="middle">{fill, Color|none}</cell>
<cell align="left" valign="middle">none</cell>
<cell align="left" valign="middle">Defines fill color of arc object.</cell>
</row>
<row>
<cell align="left" valign="middle">{start, Degrees}</cell>
<cell align="left" valign="middle"> </cell>
<cell align="left" valign="middle"> </cell>
</row>
<row>
<cell align="left" valign="middle">{style, arc}</cell>
<cell align="left" valign="middle"> </cell>
<cell align="left" valign="middle">No line segments.</cell>
</row>
<row>
<cell align="left" valign="middle">{style, chord}</cell>
<cell align="left" valign="middle"> </cell>
<cell align="left" valign="middle">A single line segment connects the two end points of the perimeter section.</cell>
</row>
<row>
<cell align="left" valign="middle">{style, pieslice}</cell>
<cell align="left" valign="middle">This Style</cell>
<cell align="left" valign="middle">Two lines are drawn between the center of the oval and each end of the perimeter section.</cell>
</row>
<tcaption>Canvas Arc Options</tcaption>
</table>
</section>
<section>
<title>The Canvas Image Object</title>
<p>The canvas image object displays images and moves them around in a simple way. The currently supported image formats are bitmap and gif.</p>
<marker id="gs_fig14"></marker>
<image file="images/image.gif">
<icaption>Canvas Image Object</icaption>
</image>
<code type="none"><![CDATA[
gs:create(image,Canvas,[{load_gif,"brick.gif"}]).
]]></code>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{anchor, Anchor}</cell>
<cell align="left" valign="middle">nw</cell>
<cell align="left" valign="middle">Anchor reference specified by {X,Y} .</cell>
</row>
<row>
<cell align="left" valign="middle">{bg, Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Background color. Pixel value 0.</cell>
</row>
<row>
<cell align="left" valign="middle">{bitmap, FileName}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">A bitmap file which contains a bmp bitmap.</cell>
</row>
<row>
<cell align="left" valign="middle">{coords, [{X,Y}]}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Position on the canvas.</cell>
</row>
<row>
<cell align="left" valign="middle">{fg, Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Foreground color. Pixel value 1.</cell>
</row>
<row>
<cell align="left" valign="middle">{load_gif, FileName}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Loads a gif image.</cell>
</row>
<tcaption>Canvas Image Object Options</tcaption>
</table>
</section>
<section>
<title>The Canvas Line Object</title>
<marker id="gs_fig15"></marker>
<image file="images/line.gif">
<icaption>Line Object Drawn on a Canvas</icaption>
</image>
<code type="none"><![CDATA[
gs:create(line,Canvas,
[{coords,[{25,25},{50,50},{50,40},{85,75}]},
{arrow,last},{width,2}]).
]]></code>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{arrow, both | none | first | last}</cell>
<cell align="left" valign="middle">none</cell>
<cell align="left" valign="middle">Draws arrows at the end points of the line.</cell>
</row>
<row>
<cell align="left" valign="middle">{coords, [{X1,Y1},{X2,Y2}, ... {Xn,Yn}]}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">A list of coordinates. The line will be drawn between all pairs in the list.</cell>
</row>
<row>
<cell align="left" valign="middle">{fg, Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The color of the line.</cell>
</row>
<row>
<cell align="left" valign="middle">{smooth, Bool}</cell>
<cell align="left" valign="middle">false</cell>
<cell align="left" valign="middle">Smoothing with Bezier splines.</cell>
</row>
<row>
<cell align="left" valign="middle">{splinesteps, Int}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle"> </cell>
</row>
<row>
<cell align="left" valign="middle">{width, Int}</cell>
<cell align="left" valign="middle">1</cell>
<cell align="left" valign="middle">The width of the line.</cell>
</row>
<tcaption>Canvas Line Object Options</tcaption>
</table>
</section>
<section>
<title>The Canvas Oval Object</title>
<marker id="gs_fig16"></marker>
<image file="images/oval.gif">
<icaption>Oval Object Drawn on a Canvas</icaption>
</image>
<code type="none"><![CDATA[
gs:create(oval,Canvas,
[{coords,[{25,25},{125,75}]},{fill,red},{bw,2}]).
]]></code>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{bw, Int}</cell>
<cell align="left" valign="middle">1</cell>
<cell align="left" valign="middle">Width.</cell>
</row>
<row>
<cell align="left" valign="middle">{coords, [{X1,Y1},{X2,Y2}]}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Bounding rectangle which defines shape of object.</cell>
</row>
<row>
<cell align="left" valign="middle">{fg, Color}</cell>
<cell align="left" valign="middle"> </cell>
<cell align="left" valign="middle"> </cell>
</row>
<row>
<cell align="left" valign="middle">{fill, Color|none}</cell>
<cell align="left" valign="middle">none</cell>
<cell align="left" valign="middle">Object fill color.</cell>
</row>
<tcaption>Canvas Oval Object Options</tcaption>
</table>
</section>
<section>
<title>The Canvas Polygon Object</title>
<marker id="gs_fig17"></marker>
<image file="images/polygon.gif">
<icaption>Canvas Polygon Object</icaption>
</image>
<code type="none"><![CDATA[
gs:create(polygon,Canvas,
[{coords,[{10,10},{50,50},{75,30}]}]).
]]></code>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{bw, Int}</cell>
<cell align="left" valign="middle">1</cell>
<cell align="left" valign="middle">Width.</cell>
</row>
<row>
<cell align="left" valign="middle">{coords, [{X1,Y1},{X2,Y2} | {Xn,Yn}]}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Defines all points in the polygon. There may be any number of points in the polygon.</cell>
</row>
<row>
<cell align="left" valign="middle">{fg, Color}</cell>
<cell align="left" valign="middle">black</cell>
<cell align="left" valign="middle">The color of the polygon outline. </cell>
</row>
<row>
<cell align="left" valign="middle">{fill, Color|none}</cell>
<cell align="left" valign="middle">none</cell>
<cell align="left" valign="middle"> </cell>
</row>
<row>
<cell align="left" valign="middle">{smooth, Bool}</cell>
<cell align="left" valign="middle">false</cell>
<cell align="left" valign="middle">Smoothing with Bezier splines.</cell>
</row>
<row>
<cell align="left" valign="middle">{splinesteps, Int}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle"> </cell>
</row>
<tcaption>Canvas Polygon Object Options</tcaption>
</table>
</section>
<section>
<title>The Canvas Rectangle Object</title>
<marker id="gs_fig18"></marker>
<image file="images/rectangle.gif">
<icaption>Rectangle Object Created on a Canvas</icaption>
</image>
<code type="none"><![CDATA[
gs:create(rectangle,Canvas,
[{coords,[{30,30},{70,70}]},{fill,cyan},{bw,2}]).
]]></code>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{bw, Int}</cell>
<cell align="left" valign="middle">1</cell>
<cell align="left" valign="middle">The width of the border line.</cell>
</row>
<row>
<cell align="left" valign="middle">{coords, [{X1,Y1},{X2,Y2}]}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Defines rectangle coordinates.</cell>
</row>
<row>
<cell align="left" valign="middle">{fg, Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The color of the border line.</cell>
</row>
<row>
<cell align="left" valign="middle">{fill, Color|none}</cell>
<cell align="left" valign="middle">none</cell>
<cell align="left" valign="middle">Fill color of rectangle.</cell>
</row>
<tcaption>Canvas Rectangle Object Options</tcaption>
</table>
</section>
<section>
<title>The Canvas Text Object</title>
<marker id="gs_fig19"></marker>
<image file="images/text.gif">
<icaption>Canvas Text Object</icaption>
</image>
<code type="none"><![CDATA[
gs:create(text,C,[{coords,[{50,50}]},
{font,{times,18}},
{fg,red},
{text,"Hello World!"}]).
]]></code>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{anchor, Anchor}</cell>
<cell align="left" valign="middle">nw</cell>
<cell align="left" valign="middle">Anchor reference specified by {X,Y}.</cell>
</row>
<row>
<cell align="left" valign="middle">{coords, [{X, Y}]}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Position in the canvas.</cell>
</row>
<row>
<cell align="left" valign="middle">{fg, Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Text color (background color is the canvas color).</cell>
</row>
<row>
<cell align="left" valign="middle">{justify, left | center | right}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Tex justification. Only valid with several lines of text.</cell>
</row>
<row>
<cell align="left" valign="middle">{text, String}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The text string to display.</cell>
</row>
<row>
<cell align="left" valign="middle">{width, Int}</cell>
<cell align="left" valign="middle"> </cell>
<cell align="left" valign="middle">The width in pixels. The text will be wrapped into several lines to fit inside the width.</cell>
</row>
<tcaption>Canvas Text Object Options</tcaption>
</table>
</section>
</section>
<section>
<title>Menu</title>
<p>Menus consist of four object types:</p>
<list type="bulleted">
<item>the menu bar</item>
<item>the menu button</item>
<item>the menu</item>
<item>the menu item.</item>
</list>
<section>
<title>Menu Bar</title>
<p>The menu bar is a simple object. It is placed at the top of the window and contains menu items. {x,y} or width cannot be controlled since, by definition, the menu bar is placed at the top of the window.</p>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle"><only generic options></cell>
<cell align="left" valign="middle"> </cell>
<cell align="left" valign="middle"> </cell>
</row>
<tcaption>Menu Bar Options</tcaption>
</table>
</section>
<section>
<title>Menu Button</title>
<p>The menu button displays a menu when pressed. The width of the menu button is automatically determined by the size of the text.</p>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{align, Align}</cell>
<cell align="left" valign="middle">center</cell>
<cell align="left" valign="middle">Text alignment within the frame.</cell>
</row>
<row>
<cell align="left" valign="middle">{justify, left | center | right}</cell>
<cell align="left" valign="middle">center</cell>
<cell align="left" valign="middle">Justification is only valid when there are several lines of text.</cell>
</row>
<row>
<cell align="left" valign="middle">{label,{text,Text}}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle"> </cell>
</row>
<row>
<cell align="left" valign="middle">{side, left | right}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Placement on the menu bar. The menu button created first will have the left/right position.</cell>
</row>
<row>
<cell align="left" valign="middle">{underline, Int}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Underline character N to indicate an keyboard accelerator.</cell>
</row>
<tcaption>Menu Button Options</tcaption>
</table>
</section>
<section>
<title>Menu</title>
<p>The menu contains menu items, which are displayed vertically. Its width is automatically determined by the width of the menu items it contains.</p>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{selectcolor, Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The indicator color of radio buttons and check buttons.</cell>
</row>
<tcaption>Menu Options</tcaption>
</table>
<table>
<row>
<cell align="left" valign="middle"><em>Config-Only</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{post_at,{X,Y}}</cell>
<cell align="left" valign="middle">Displays the menu as a pop-up menu at {X,Y} (coordinate system of the parent).</cell>
</row>
<tcaption>Menu Config-Only Options</tcaption>
</table>
</section>
<section>
<title>Menu Item</title>
<p>The menu item is an object of its own. It can send events when the user selects it.</p>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{group, Atom}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">For {type, radio|check}.</cell>
</row>
<row>
<cell align="left" valign="middle">{itemtype, type}</cell>
<cell align="left" valign="middle">normal</cell>
<cell align="left" valign="middle">The type of this item. Cannot be reconfigured.</cell>
</row>
<row>
<cell align="left" valign="middle">{label, {text,Text}}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The text of the item.</cell>
</row>
<row>
<cell align="left" valign="middle">{underline, Int}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Underline character N to indicate an keyboard accelerator.</cell>
</row>
<row>
<cell align="left" valign="middle">{value, Atom}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle"> </cell>
</row>
<tcaption>Menu Item Options</tcaption>
</table>
<p><c><![CDATA[type: normal | separator | check | radio | cascade]]></c></p>
<table>
<row>
<cell align="left" valign="middle"><em>itemtype</em></cell>
<cell align="left" valign="middle"><em>Event</em></cell>
</row>
<row>
<cell align="left" valign="middle">normal</cell>
<cell align="left" valign="middle">{gs, itemId, click, Data, [Text, Index | _]}</cell>
</row>
<row>
<cell align="left" valign="middle">check</cell>
<cell align="left" valign="middle">{gs, itemId, click, Data, [Text, Index, Group, Bool| _]}</cell>
</row>
<row>
<cell align="left" valign="middle">radio</cell>
<cell align="left" valign="middle">{gs, itemId, click, Data, [Text, Index, Group, Value| _]}</cell>
</row>
<tcaption>Menu Item Events</tcaption>
</table>
<table>
<row>
<cell align="left" valign="middle"><em>Read-Only</em></cell>
<cell align="left" valign="middle"><em>Return</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">index</cell>
<cell align="left" valign="middle">Int</cell>
<cell align="left" valign="middle">Index in the menu. Starts counting from 0.</cell>
</row>
<tcaption>Menu Item Read-Only Options</tcaption>
</table>
</section>
<section>
<title>Menu Demo</title>
<marker id="gs_fig20"></marker>
<image file="images/ex13.gif">
<icaption>Simple Menu</icaption>
</image>
<p>The following example shows a short demo of the <c><![CDATA[gs]]></c> menus:</p>
<codeinclude file="examples/ex13.erl" tag="" type="erl"></codeinclude>
</section>
</section>
<section>
<title>Grid</title>
<p>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 <c><![CDATA[gs]]></c> 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.</p>
<section>
<title>Grid Line</title>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{{bg, Column},Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The background color of a cell.</cell>
</row>
<row>
<cell align="left" valign="middle">{bg, {Column,Color}}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Equivalent to {{bg, Column},Color}.</cell>
</row>
<row>
<cell align="left" valign="middle">{bg, Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The background color of all cells.</cell>
</row>
<row>
<cell align="left" valign="middle">{click, Bool}</cell>
<cell align="left" valign="middle">true</cell>
<cell align="left" valign="middle">Turns click events on/off.</cell>
</row>
<row>
<cell align="left" valign="middle">{doubleclick, Bool}</cell>
<cell align="left" valign="middle">false</cell>
<cell align="left" valign="middle">Turns double-click events on/off.</cell>
</row>
<row>
<cell align="left" valign="middle">{{fg, Column},Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The foreground color of a cell.</cell>
</row>
<row>
<cell align="left" valign="middle">{fg, {Column,Color}}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Equivalent to {{fg, Column},Color}</cell>
</row>
<row>
<cell align="left" valign="middle">{fg,Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The foreground color of all cells.</cell>
</row>
<row>
<cell align="left" valign="middle">{text, {Column,Text}}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The text in the cell.</cell>
</row>
<row>
<cell align="left" valign="middle">{{text, Column},Text}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Equivalent to {text,{Column,Text}}.</cell>
</row>
<row>
<cell align="left" valign="middle">{text,Text}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The text for all cells.</cell>
</row>
<row>
<cell align="left" valign="middle">{row, {row}}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The grid row. Must not be occupied by another grid line.</cell>
</row>
<tcaption>Grid Line Options</tcaption>
</table>
<table>
<row>
<cell align="left" valign="middle"><em>Event</em></cell>
</row>
<row>
<cell align="left" valign="middle">{gs, GridLineId, click, Data, [Col, row, Text | _]}</cell>
</row>
<row>
<cell align="left" valign="middle">{gs, GridLineId, doubleclick, Data, [Col, row, Text | _]}</cell>
</row>
<tcaption>Gride Line Events</tcaption>
</table>
</section>
<section>
<title>Grid</title>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{font,Font}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">A "global" grid font.</cell>
</row>
<row>
<cell align="left" valign="middle">{hscroll, Bool|top|bottom}</cell>
<cell align="left" valign="middle">true</cell>
<cell align="left" valign="middle">Horizontal scroll bar.</cell>
</row>
<row>
<cell align="left" valign="middle">{vscoll, Bool|left|right}</cell>
<cell align="left" valign="middle">true</cell>
<cell align="left" valign="middle">Vertical scroll bar.</cell>
</row>
<row>
<cell align="left" valign="middle">{rows, {Minrow,Maxrow}}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The rows which are currently displayed.</cell>
</row>
<row>
<cell align="left" valign="middle">{columnwidths, [WidthCol1,WidthCol2, ..., WidthColN}}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Defines the number of columns and their widths in coordinates. The size of the columns can be reconfigured, but not the number of columns.</cell>
</row>
<row>
<cell align="left" valign="middle">{fg, Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The color of the grid pattern and the text.</cell>
</row>
<row>
<cell align="left" valign="middle">{bg, Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The background color.</cell>
</row>
<tcaption>Grid Options</tcaption>
</table>
<table>
<row>
<cell align="left" valign="middle"><em>Read-Only</em></cell>
<cell align="left" valign="middle"><em>Return</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{obj_at_row, row}</cell>
<cell align="left" valign="middle">Object |undefined</cell>
<cell align="left" valign="middle">The grid line at row.</cell>
</row>
<tcaption>Grid Read-Only Options</tcaption>
</table>
<p>The rows and columns start counting at 1.</p>
</section>
<section>
<title>Grid Demo</title>
<marker id="gs_fig21"></marker>
<image file="images/ex12.gif">
<icaption>Simple Grid</icaption>
</image>
<p>The following simple example shows how to use the grid.</p>
<codeinclude file="examples/ex12.erl" tag="" type="erl"></codeinclude>
</section>
</section>
<section>
<title>Editor</title>
<p>The editor object is a simple text editor.</p>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{hscroll, Bool | top | bottom}</cell>
<cell align="left" valign="middle">false</cell>
<cell align="left" valign="middle">Horizontal scroll bar.</cell>
</row>
<row>
<cell align="left" valign="middle">{insertpos,{row,Col}}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The position of the cursor.</cell>
</row>
<row>
<cell align="left" valign="middle">{insertpos,'end'}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The position of the cursor.</cell>
</row>
<row>
<cell align="left" valign="middle">{justify, left| right| center}</cell>
<cell align="left" valign="middle">left</cell>
<cell align="left" valign="middle">Text justification.</cell>
</row>
<row>
<cell align="left" valign="middle">{scrollbg, Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Background color of scroll bar.</cell>
</row>
<row>
<cell align="left" valign="middle">{scrollfg, Color}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">Foreground color of scroll bar.</cell>
</row>
<row>
<cell align="left" valign="middle">{selection, {FromIndex,ToIndex}}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The text range that is currently selected.</cell>
</row>
<row>
<cell align="left" valign="middle">{vscroll, Bool | left | right}</cell>
<cell align="left" valign="middle">false</cell>
<cell align="left" valign="middle">Vertical scroll bar.</cell>
</row>
<row>
<cell align="left" valign="middle">{vscrollpos, row}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The top most visible row in the editor.</cell>
</row>
<row>
<cell align="left" valign="middle">{wrap, none|char | word}</cell>
<cell align="left" valign="middle">none</cell>
<cell align="left" valign="middle">How to wrap text when the line is full.</cell>
</row>
<tcaption>Editor Options</tcaption>
</table>
<table>
<row>
<cell align="left" valign="middle"><em>Config-Only</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">clear</cell>
<cell align="left" valign="middle">Clears the editor.</cell>
</row>
<row>
<cell align="left" valign="middle">{del, {FromIndex, ToIndex}}}</cell>
<cell align="left" valign="middle">Deletes text.</cell>
</row>
<row>
<cell align="left" valign="middle">{fg, {{FromIndex,ToIndex},Color}}</cell>
<cell align="left" valign="middle">Sets the foreground color of a range of text.</cell>
</row>
<row>
<cell align="left" valign="middle">{load, FileName}</cell>
<cell align="left" valign="middle">Read FileName into the editor.</cell>
</row>
<row>
<cell align="left" valign="middle">{insert, {Index, Text}}</cell>
<cell align="left" valign="middle">Inserts new text.</cell>
</row>
<row>
<cell align="left" valign="middle">{overwrite, {Index, Text}}</cell>
<cell align="left" valign="middle">Writes new text at index.</cell>
</row>
<row>
<cell align="left" valign="middle">{save, FileName}</cell>
<cell align="left" valign="middle">Writes editor contents to file.</cell>
</row>
<tcaption>Editor Config-Only Options</tcaption>
</table>
<table>
<row>
<cell align="left" valign="middle"><em>Read-Only</em></cell>
<cell align="left" valign="middle"><em>Return</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">char_height</cell>
<cell align="left" valign="middle">Int</cell>
<cell align="left" valign="middle">The height of the editor window measured in characters.</cell>
</row>
<row>
<cell align="left" valign="middle">char_width</cell>
<cell align="left" valign="middle">Int</cell>
<cell align="left" valign="middle">The width of the editor window measured in characters.</cell>
</row>
<row>
<cell align="left" valign="middle">{fg,Index}</cell>
<cell align="left" valign="middle">Int</cell>
<cell align="left" valign="middle">The foreground color of the text at Index.</cell>
</row>
<row>
<cell align="left" valign="middle">{get,{FromIndex, ToIndex}}</cell>
<cell align="left" valign="middle">Text</cell>
<cell align="left" valign="middle">The text between the indices.</cell>
</row>
<row>
<cell align="left" valign="middle">size</cell>
<cell align="left" valign="middle">Int</cell>
<cell align="left" valign="middle">The number of rows in the editor.</cell>
</row>
<tcaption>Editor Read-Only Options</tcaption>
</table>
<code type="none"><![CDATA[
Index: 'end'|insert|{row,Col}|{row,lineend}
]]></code>
<section>
<title>Editor Demo</title>
<marker id="gs_fig22"></marker>
<image file="images/ex14.gif">
<icaption>Simple Editor</icaption>
</image>
<codeinclude file="examples/ex14.erl" tag="" type="erl"></codeinclude>
</section>
</section>
<section>
<title>Scale</title>
<p>A scale object is used to select a value within a specified range.</p>
<table>
<row>
<cell align="left" valign="middle"><em>{Option,Value}</em></cell>
<cell align="left" valign="middle"><em>Default</em></cell>
<cell align="left" valign="middle"><em>Description</em></cell>
</row>
<row>
<cell align="left" valign="middle">{orient, vertical | horizontal}</cell>
<cell align="left" valign="middle">horizontal</cell>
<cell align="left" valign="middle">The orientation of the scale.</cell>
</row>
<row>
<cell align="left" valign="middle">{pos, Int}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The current value of the scale objects within the range.</cell>
</row>
<row>
<cell align="left" valign="middle">{range, {Min, Max}}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">The value range.</cell>
</row>
<row>
<cell align="left" valign="middle">{showvalue, Bool}</cell>
<cell align="left" valign="middle">true</cell>
<cell align="left" valign="middle">Turns showing of scale value on/off.</cell>
</row>
<row>
<cell align="left" valign="middle">{text, String}</cell>
<cell align="left" valign="middle"><unspec></cell>
<cell align="left" valign="middle">If specified, a label will be attached to the scale.</cell>
</row>
<tcaption>Scale Object Options</tcaption>
</table>
<table>
<row>
<cell align="left" valign="middle"><em>Event</em></cell>
</row>
<row>
<cell align="left" valign="middle">{gs, Scale, click, Data, [Value | _]}</cell>
</row>
<tcaption>Scale Object Options</tcaption>
</table>
<p>The following example prompts a user to specify an RGB-value for the background color of a window.</p>
<marker id="gs_fig23"></marker>
<image file="images/ex11.gif">
<icaption>Scale Objects for Selecting RGB Values for a Window</icaption>
</image>
<codeinclude file="examples/ex11.erl" tag="" type="erl"></codeinclude>
</section>
</chapter>
