guiserver.lsp

> # guiserver.lsp

> Module index

> ## Module: guiserver.lsp

> Functions for programming GUIs and 2D graphics.

> Version: 1.40 use text-field as a password field with additional parameter
> Version: 1.41 bug fixes for gs:listen and gs:check-event
> Version: 1.42 new table UI
> Author: LM, August 2008, 2009, 2010
> This module has been tested on MacOS X 10.5 (Leopard) and Windows XP, both with the Standard SUN Java RE v.1.5 (runtime environment) which came pre-installed on those platforms. On Linux the installation of the original Sun Java Runtime Environment is required the preinstalled GNU Java is not compatible. After installation a soft-link has to be made from the original java executable to `/usr/bin/java`.
> On Win32 the MIDI sound features require a soundbank file to be installed. See the description for `gs:play-note` for details.

> ## What is newLISP-GS

> `guiserver.lsp` is a module for interfacing to `guiserver.jar` a Java server application for generating GUIs (graphical user interfaces) and 2D graphics for newLISP applications. The `guiserver.lsp`, module implements a newLISP API much smaller and more abstract than the APIs of the Java Swing libraries which it interfaces with. Because of this, GUI applications can be built much faster than when using the original Java APIs.

> ## Usage

> At the beginning of the program file, include a `load` statement for the module:

>      (load "/usr/share/newlisp/guiserver.lsp")

> or on MS Windows:

>      (load "c:/Program Files/newlisp/guiserver.lsp")

> `guiserver.lsp` expects the server `guiserver.jar` to be in the directoey specified in the environment variable NEWLISPDIR. When newLISP starts up and this variable is not set yet, it sets it to a default value of `/usr/share/newlisp` on MacOS X and Unix OSs, and to `C:\Program Files\newlisp` or whatever it finds in the `PROGRAMFILES` environment variable on Win32 systems and adding `/newlisp` to it. This can be overwritten by specifying system wide setting for the environment variable `NEWLISPDIR`, which normally is set to `%PROGRAMFILES%/newlisp` on Win32. When using the Win32 binary installer `NEWLISPDIR` is written to the registry automatically and gets into effect after rebooting.

> ## Architecture of a newLISP GUI application

> A GUI application in newLISP is composed of four parts:

> > initialization - this means starting the newLISP-GS `guiserver.jar` and initializing communications with it. Only one function call is required to do this.
> > building widgets - in this step windows, buttons, text fields etc., and all visual aspects of the GUI are described. newLISP newLISP-GS offers a wide range of different control widgets.
> > defining event actions - in this step all the functions are defined to react to events coming from the GUI as a consequence of button pushes, keystrokes, mouse-movements etc.. These event actions send many commands back to the GUI to change information for the user, popup dialogs etc..
> > listening for events - the newLISP program sits in a loop waiting for events and dispatching them to the defined event actions. Only one function call is required for this step.

> ## Example

> The following example application shows all the essential elements of a newLISP GUI application:
> example:

> >      #!/usr/bin/newlisp
> >      ; button-demo.lsp - demonstrate the button control

> >      ; initialization
> >      (load (append (env "NEWLISPDIR") "/guiserver.lsp"))

> >      (gs:init)

> >      ; describe the GUI
> >      (gs:frame 'ButtonDemo 100 100 400 300 "Button demo")
> >      (gs:set-resizable 'ButtonDemo nil)
> >      (gs:panel 'ColorPanel 360 200)
> >      (gs:set-color 'ColorPanel (random) (random) (random))
> >      (gs:button 'aButton 'abutton-action "color")
> >      (gs:set-flow-layout 'ButtonDemo "center" 2 15)
> >      (gs:add-to 'ButtonDemo 'ColorPanel 'aButton)
> >      (gs:set-visible 'ButtonDemo true)

> >      ; define actions
> >      (define (abutton-action id)
> >          (gs:set-color 'ColorPanel (random) (random) (random)))

> >      ; listen for incoming action requests and dispatch
> >      (gs:listen)

> >      ; eof

> ## Application start

>          ./button-demo       ; on MacOS X and Unix
>          newlisp button-demo ; on Win32

> By default guiserver.jar uses the ports 47011 and 47012, but this setting can be overwritten either by supplying a port number parameter to the `gs:init` function or by overwriting the port number from the command-line. newLISP-GS will then use the port number supplied and the number following it:

>          ./button-demo 10001       ; on MacOS X and Unix
>          newlisp button-demo 10001 ; on Win32

> newLISP-GS `guiserver.jar` will now use the ports `10001` and `10002`. Ports under `1024` should not be used, as many of them are already in use by other OS services and need administrator privileges to use them.
> A second method to start a newLISP-GS application starts the `guiserver.jar` first, which then starts the newLISP application:

>          Java -jar /usr/share/newlisp/guiserver.jar 47011 /usr/home/aUser/MyApplication.lsp

> A different port number can be used. Port numbers below 1024 need administrator permissions. Optionally a splash screen can be specified as the last parameter:

>          Java -jar /usr/share/newlisp/guiserver.jar 47011 /home/apps/myapp.lsp /local/newLISP128.png

> The example specifies an image inside `guiserver.jar`. Any other image path on the local file system can be used.
> On Win32 similar methods can be used replacing the appropriate file paths, but on Win32 Java jar files can also be treated as executables and executed directly without calling Java explicitly. By default `guiserver.jar` and `guiserver.lsp` are installed in `c:\Program Files\newlisp\` or any other directory configured on a Win32 platform using the `PROGRAMFILES` environment variable:

>         "c:\Program Files\newlisp\guiserver.jar" 47011 c:\myprogs\MyApplication.lsp

> Quotes are necessary when spaces are present in the argument string. The example assumes that `newlisp.exe` is in the path for executables, and it also assumes that the Windows registry has an association of the `.jar` file extension with the `javaw.exe` executable. This association is normally present when a java run-time environment (JRE) is installed in Windows. If this association is not registered, the following method can be used:

>         javaw -jar "c:\Program Files\newlisp\guiserver.jar" 47011 c:\myprogs\MyApplication.lsp

> The quotes are necessary for path-names containing spaces.

> ## Debugging

> Tracing commands to newLISP-GS
> For debugging purpose put the following directive at the beginning of your application or at the place from where to start tracing.

>              (gs:set-trace true)

> Then start the application from a terminal or command shell window. Now newLISP-GS will output startup, version and connection messages and a trace for each `gs:xxs` directive as it is received by the newLISP-GS dispatcher:

> >      newLISP-GS v.0.94
> >      listening on 47011
> >      accepted from 0.0.0.0
> >      connecting to 0.0.0.0 47012
> >      retrying to connect
> >      connected
> >      -> frame MAIN:ButtonDemo 100 100 400 300 QnV0dG9uIGRlbW8= nil
> >      -> set-resizable MAIN:ButtonDemo nil
> >      -> panel MAIN:ColorPanel 360 200
> >      -> set-color MAIN:ColorPanel 0 1 0 0.2
> >      -> button MAIN:aButton MAIN:abutton-action Y29sb3I=
> >      -> set-flow-layout MAIN:ButtonDemo center 2 15
> >      -> add-to MAIN:ButtonDemo MAIN:ColorPanel MAIN:aButton
> >      -> set-visible MAIN:ButtonDemo true
> >      -> set-color MAIN:ColorPanel 0.8401877172 0.3943829268 0.7830992238
> >      server shut down

> Text strings for button names, icon paths and other texts are encode in Base64 strings as the first trace line for MAIN:ButtonDemo shows. To switch off tracing mode use:

>             (gs:set-trace nil)

> Even if trace mode is switched off, wrong or missing parameters are still messaged by newLISP-GS in a small message box. After such an error the application and guiserver will exit. Unknown commands will be ignored. Functions which are not applicable to certain widgets will also pop up an error message box. In certain situations a function will have no effect, e.g. `gs:set-size` or `gs:set-color` sometimes do not have an effect, depending on how a widget is configured or depending on the layout which hosts the widget. Sometimes the platform look-and-feel overwrites colors.

> ## Event handlers

> For most widgets, event handlers must be defined. Sometimes an event handler is not required. In this case specify `'gs:no-action` as the event handler symbol. When developing programs it is useful to watch the event handler first before coding for it. This can be done easily by printing out event parameters:

> >      (gs:button 'aButton 'abutton-handler "press")
> >      (define (abutton-handler id)
> >          (println id))

> Sometimes the same event handler function is attached to several widgets' keyboard or mouse events. Some of these events receive a greater number of parameters. There are two easy ways to discover the nature of an event:

> >      (define (the-handler)
> >          (doargs (p)
> >              (println "->" p)))

> The other method looks at the source of the event as it was transmitted by the newLISP-GS. This is useful to recognize the data types used in the event:

> >      (define (the-handler)
> >          (println gs:event))

> All text from text fields are received as base64-encoded strings. E.g. the text: `"Hello World"` would be received as: `"SGVsbG8gV29ybGQ="`:

> >      (gs:text-field 'TextField 'textfield-handler)

> >      (define (textfield-handler id text)
> >          (printnl id ": " (base64-dec text)))

> When the text "Hello World" is entered in the text field, the following output would be generated:

> >      TextField: "Hello World"

> In case the ESC key is pressed in the text field, the event handler would report `nil` for the text field. A handler should therefore always check text for string contents before trying to apply the `base64-dec` function on it.

> ## Coding considerations

> mapping or applying `gs:xxx` functions
> Like any newLISP functions, `gs:xxx` functions can be mapped or applied to lists of parameters using the newLISP `map` and `apply` functions. When doing this, make sure to map or apply the quoted `'gs:xxx symbol`, so the `gs:xx` functions get executed under the `gs` context, prefixing symbols in parameter lists correctly with the context prefix of their origin.

>         (map 'gs:panel '(first second third fourth)) ; note quoted gs: function

> ## Some shortcuts when writing `gs:xxx` functions

> Due to the nature of transfer between newLISP and the guiserver as text, the following convenient shortcuts can be taken when writing functions:

> > - Symbol ids of components can be expressed as strings.
> > - Number values can be expressed as strings.
> > - Numbers can be expressed as floats or integers.
> > - String constants for type and orientation constants can be given as symbols.

> Here are some examples:

>          (gs:panel 'ColorPanel 360 200)
>          ; is the same as
>          (gs:panel "ColorPanel" 360 200)
>          ; is the same as
>          (gs:panel "ColorPanel" "360" "200")
>          ; is the same as
>          (gs:panel "ColorPanel" 360.0 "200.00")

>          (gs:set-flow-layout 'ButtonDemo "center" 2 15)
>          ; is the same as
>          (gs:set-flow-layout 'ButtonDemo 'center 2 15)

> Although the first form is preferred for clarity and readability, in some cases coding may be more efficient using the other forms.
> Except for the symbols used for action handlers, all symbols are used only by their face (term) value. This means that reserved symbols of the newLISP programming language can be used freely in symbol ids for all components, e.g:

>          (gs:label 'term "Input here") ; term is a reserved name since v10.2.0

> The usage of the reserved symbol `term` will not pose a problem.

> ## Return values

> newLISP-GS is an event driven asynchronous system. Most functions return right away the number of characters sent out to the server. In general, return values of `gs:xxx` functions do not have any specific meaning and can be discarded. Only the functions `gs:get-bounds`, `gs:get-fonts`, `gs:get-font-metrics`, `gs:get-instruments` `gs:get-screen`, `gs:get-text` and `gs:get-version` return meaningful values or lists of values, which are stored in similar named variables: `gs:bounds`, `gs:fonts`, `gs:font-metrics`, `gs:instruments`, `gs:screen`, `gs:text` and `gs:version`. These functions will not return right away but block until the return valuse is sent back from newLISP-GS.
> The function `gs:get-text` can work both ways: event driven or with a return value depending on the call pattern used.

> ## Function overview

> - Initialization and application setup

>           (gs:init [server-port])

>   The initialization function starts `guiserver.jar` which will listen to the server-port and initiate another connection on `server-port + 1` back to newLISP. If a server-port is not supplied `guiserver` will assume `47011` and `47012`.
>   As the last statement in the application put:

>           (gs:listen)

>   This function listens on `47012` (by default) for event messages from newLISP-GS and dispatches them to the user-defined action handlers. To avoid newLISP shutting down when the guiserver shuts down, use:

>           (gs:listen true)

> Sometimes it is necessary to run other tasks while listening for events. In this case use `gs:check-event`, which will wait for certain amount of microseconds for an event to be executed. After the wait-time, it returns. The function is typically used in a loop:

>         (while (gs:check-event 10000) ; check for 10 milli seconds
>     			(do-myprocess))
>         (exit)

> The loop will exit when `gs:check-event` returns `nil` on communications errors, e.g. when the window's close button was clicked.
> - Containers
>   A container can contain any other container or control widget. Except for the `menu-bar` and the `split-pane`, containers can have a special layout-manager set with one of the three layout-manager function commands. By default containers have a flow layout. By nesting different containers and using different layout-manager settings, complex layouts can be configured. The function/command `add-to` is used to add components to containers.

>           (gs:dialog sym-id sym-parent-frame str-message int-width int-height [boolean-visible [boolean-modal]])
>           (gs:frame sym-id int-x int-y int-width int-height [str-title boolean-visible])
>           (gs:menu-bar sym-frame [sym-menu-1 ...])
>           (gs:panel sym-id [int-width int-height])
>           (gs:scroll-pane sym-id sym-widget [int-width int-height])
>           (gs:split-pane sym-id str-orientation [float-weight [float-location [int-divider-size>]]])
>           (gs:tabbed-pane sym-id sym-action str-orientation [sym-widget sym-tab-title ...])
>           (gs:tool-bar sym-frame [bool-floatable int-hgap int-vgap])
>           (gs:canvas sym-id)
>           (gs:window sym-id int-x int-y int-width int-height)

> - Labels
>   Labels can have text or an image or both. A normal text `label` can have an icon added to it and a `image-label` can have text added to it. Labels don't initiate actions and can be placed in any container like all button-type widgets - buttons, checkboxes and menu items. A basic set of icon images is built into `guiserver.jar`, but user-supplied images and icons in `.jpg`, `.png` and `.gif` formats can be used.

>           (gs:label sym-id str-text [str-align [int-width int-height]])
>           (gs:image-label sym-id str-icon-path [str-align])

> - Control widgets
>   Except for the passive progress bar, all control widgets fire action requests to the newLISP program. These requests must be served to avoid error messages but can be defined as empty functions, if an action is not required:

>           ; empty action definition
>           (define (my-button-action) )

>           ; action handler printing the name of the button pressed
>           (define (my-button-action id) (println id " has been pressed"))

>   All action events calls carry information about the widget, that initiated that the event, and event parameters like keystrokes, slider positions etc..

>           (gs:button sym-id sym-action [str-text [int-width int-height]])
>           (gs:check-box sym-id sym-action [str-text [bool-selected]])
>           (gs:combo-box sym-id sym-action [str-item-1 ...])
>           (gs:combo-box sym-id sym-action [list-str-items])
>           (gs:image-button sym-id sym-action str-icon-path [str-down-icon-path [int-width int-height]])
>           (gs:list-box sym-id sym-action [str-item-1 ...])
>           (gs:list-box sym-id sym-action [list-str-items])
>           (gs:menu sym-id str-text)
>           (gs:menu-popup sym-id str-text)
>           (gs:menu-item sym-id sym-action str-text)
>           (gs:menu-item-check sym-id sym-action str-text [bool-selected])
>           (gs:progress-bar sym-id int-min in-max int-initial-value)
>           (gs:radio-button sym-id sym-action [str-text [bool-selected]])
>           (gs:slider sym-id sym-action str-orientation int-min int-max int-initial-value)
>           (gs:text-area sym-id sym-action [int-width int-height])
>           (gs:text-field sym-id sym-action int-columns[str-echo-char])
>           (gs:text-pane sym-id sym-action str-style [int-width int-height])
>           (gs:toggle-button sym-id sym-action [str-text bool-selected])

>   For all button widgets, and the check box and menu-item widgets, icons can be set using the `gs:set-icon` and `gs:set-pressed-icon` functions.
> - Placing components in containers
>   For the flow and grid layouts the components are added in the sequence they are listed. The grid-layout fills the grid row by row starting with the left most column.

>           (gs:add-to sym-container sym-component [
>        For the border layout an orientation parameter is specified as either "north",
>        "west", "center", "east" or "south".

>           (gs:add-to sym-container [sym-component str-orientation ...])

> - Summary of commands
>   Most of the commands set special attributes of containers or control widgets. Not all functions can be applied to all containers and control widgets. A wrong application will either pop up an error message box or do nothing.
>   Some functions will work on certain widgets only in certain situations. For example `set-size` will work not on components in a grid layout but on components in a flow layout. Some widgets have a preset background color which cannot be changed or is overwritten by the current `gs:look-and-feel` settings.

>           (gs:add-list-item sym-list-combo str-text [str-text ...])
>           (gs:add-separator sym-menu-tool-bar)
>           (gs:add-to sym-container sym-component [sym-container sym-component str-orientation [sym-component str-orientation ...])
>           (gs:append-text sym-id str-text)
>           (gs:check-event int-microseconds)
>           (gs:clear-list sym-id)
>           (gs:clear-text sym-id)
>           (gs:copy-text sym-id)
>           (gs:cut-text sym-id)
>           (gs:destroy-shell sym-text-area)
>           (gs:disable sym-id-1 [sym-id-2 ...])
>           (gs:dispose sym-id)
>           (gs:dispose-splash)
>           (gs:enable sym-id-1 [sym-id-2 ...])
>           (gs:eval-shell sym-text-area str-commmand)
>           (gs:find-text sym-id str-text sym-action [str-direction]])
>           (gs:frame-closed sym-id sym-action)
>           (gs:get-fonts)
>           (gs:get-bounds sym-id)
>           (gs:get-font-metrics sym-id str-text)
>           (gs:get-screen)
>           (gs:get-selected-text sym-id sym-action)
>           (gs:get-text sym-id [sym-action])
>           (gs:get-text-position sym-id)
>           (gs:get-version);
>           (gs:goto-text sym-id sym-row sym-column)
>           (gs:insert-list-item sym-list-combo str-text int-index [str-text int-index])
>           (gs:insert-tab sym-tabbed-pane sym-component [str-text [int-index [str-icon-path]])
>           (gs:insert-text sym-id str-text int-pos)
>           (gs:layout sym-container)
>           (gs:load-text sym-id str-path)
>           (gs:no-action)
>           (gs:paste-text sym-id [str-text])
>           (gs:redo-text sym-id)
>           (gs:remove-from sym-container sym-component [sym-component ...])
>           (gs:remove-list-item sym-list-combo int-index [int-index ...])
>           (gs:remove-tab sym-tabbed-pane int-index)
>           (gs:request-focus sym-id)
>           (gs:run-shell sym-text-area str-commmand)
>           (gs:select-list-item sym-id str-item [boolean-flag])
>           (gs:select-text sym-id int-from [int-to])
>           (gs:set-accelerator sym-menu-item str-keystroke)
>           (gs:set-background sym-id float-red float-green float-blue [float-alpha])
>           (gs:set-background sym-id list-rgb [float-alpha])
>           (gs:set-bevel-border sym-panel str-type)
>           (gs:set-border-layout sym-container  [int-hgap int-vgap])
>           (gs:set-caret sym-id int-offset)
>           (gs:set-caret-color sym-id list-rgb)
>           (gs:set-caret-color sym-id float-red float-green float-blue)
>           (gs:set-color sym-id float-red float-green float-blue [float-alpha])
>           (gs:set-color sym-id list-rgb [float-alpha])
>           (gs:set-cursor sym-id str-shape)
>           (gs:set-echo-char sym-id str-echo-char)
>           (gs:set-editable sym-id boolean-flag)
>           (gs:set-flow-layout sym-container [str-alignment [int-hgap int-vgap]])
>           (gs:set-font sym-id str-family int-size str-type)
>           (gs:set-foreground sym-id float-red float-green float-blue [float-alpha])
>           (gs:set-foreground sym-id list-rgb [float-alpha])
>           (gs:set-grid-layout sym-container int-columns int-rows [int-hgap int-vgap])
>           (gs:set-icon sym-id str-icon-path [int-index])
>           (gs:set-look-and-feel str-look)
>           (gs:set-resizable sym-frame boolean-flag)
>           (gs:set-pressed-icon sym-id str-icon-path)
>           (gs:set-selected sym-id boolean-flag)
>           (gs:set-size sym-id int-width int-height)
>           (gs:set-selection-color sym-id float-red float-green float-blue [float-alpha])
>           (gs:set-syntax sym-id str-type)
>           (gs:set-syntax-colors list-rgb-comments list-rgb-keywords list-rgb-string list-rgb-number list-rgb-quoted list-rgb-prantheses)
>           (gs:set-tab-size sym-id int-size)
>           (gs:set-text sym-id str-text [int-index])
>           (gs:set-titled-border sym-component str-title)
>           (gs:set-tool-tip sym-id str-text)
>           (gs:set-trace boolean-flag)
>           (gs:set-utf8 boolean-flag)
>           (gs:set-value sym-id int-value)
>           (gs:set-visible sym-id boolean-visible)
>           (gs:undo-text sym-id)
>           (gs:undo-enable sym-id boolean-enabled)

> - The Table UI
>   Since version 1.42 Guiserver has a table widget and supporting functions.

>           (gs:table sym-id sym-action [str-column-header-name ...])
>           (gs:table-add-column sym-id str-column-header-name ...)
>           (gs:table-add-row sym-id [str-columns ... ])
>           (gs:table-get sym-id)
>           (gs:table-get-cell sym-id int-row int-column)
>           (gs:table-get-size sym-id)
>           (gs:table-set-cell sym-id int-row int-column str-value)
>           (gs:table-set-column sym-id int-column-number int-width [str-justification])
>           (gs:table-set-row-number sym-id bool-row-number)

> - Special dialogs
>   These are standard dialogs for opening and saving files and for choosing colors. Each dialog when closed fires an event for which a handler function must be defined by the newLISP program.

>           (gs:color-dialog sym-parent-frame sym-action str-title float-red float-green float-blue)
>           (gs:message-dialog sym-parent-frame str-title str-message [str-type [str-icon-path]])
>           (gs:confirm-dialog sym-parent-frame sym-action str-title str-message [str-type])
>           (gs:open-file-dialog sym-parent-frame sym-action [str-directory [str-mask str-description]])
>           (gs:save-file-dialog sym-parent-frame sym-action [str-directory [str-initial-file [str-mask str-description]]])

> - 2D Graphics functions
>   Every call to a `gs:draw-xxx` or `gs:fill-xxx` function will create a new graphics object, which will persist until destroyed by a call to `gs:delete-tag`. Graphics objects are animated using the tag operations `gs:move-tag`, `gs:rotate-tag`, `gs:scale-tag` and `gs:shear-tag` or using `gs:hide-tag` and `gs:show-tag`.
>   Any `gs:draw-xxx` or `gs:fill-xxx` will create graphics objects but not force a screen update. The canvas is automatically redrawn when made visible for the first time using `gs:set-visible` or after a call to `gs:update`. Redrawing is also forced when resizing the window which hosts the canvas or any action covering and uncovering the canvas.
>   After all tag operations redrawing is initiated by default, but it can be forced off by specifying `nil` as the last parameter in a `gs:xxx-tag` command. Suppressing immediate redraw is useful to avoid flicker when a batch of tag operations is performed.
>   Every graphics object (line, shape, text, or image) carries a group tag. Objects are deleted using `gs:delete-tag` and will disappear immediately from the canvas. Using `gs:move-tag` lines, shapes, text and images can be moved to a different position.

>           (gs:color-tag sym-tag list-rgb [boolean-repaint])
>           (gs:delete-tag sym-tag[boolean-repaint])
>           (gs:draw-arc sym-tag int-x int-y int-width int-height int-start int-angle [list-rgb])
>           (gs:draw-circle sym-tag int-x int-y int-radius [list-rgb])
>           (gs:draw-ellipse sym-tag int-x int-y int-radius-x int-radius-y [list-rgb])
>           (gs:draw-image sym-tag str-path int-x int-y [int-width int-height])
>           (gs:draw-line sym-tag int-x1 int-y1 int-x2 int-y2 [list-rgb])
>           (gs:draw-path sym-tag list-points [list-rgb])
>           (gs:draw-polygon sym-tag list-points [list-rgb])
>           (gs:draw-rect sym-tag int-x int-y int-width int-height [list-rgb])
>           (gs:draw-round-rect sym-tag int-x int-y int-width int-height int-arc-width int-arc-height [list-rgb])
>           (gs:draw-text sym-tag str-text int-x int-y [list-rgb [float-angle]])
>           (gs:export str-path-file [int-width int-height])
>           (gs:fill-arc sym-tag int-x int-y int-width int-height int-start int-angle [list-rgb])
>           (gs:fill-circle sym-tag int-x int-y int-radius [list-rgb])
>           (gs:fill-ellipse sym-tag int-x int-y int-radius-x int-radius-y [list-rgb])
>           (gs:fill-polygon sym-tag list-points [list-rgb])
>           (gs:fill-rect sym-tag int-x int-y int-width int-height [list-rgb])
>           (gs:fill-round-rect sym-tag int-x int-y int-width int-height int-arc-width int-arc-height [list-rgb])
>           (gs:hide-tag sym-tag  [boolean-repaint])
>           (gs:move-tag sym-tag int-dx int-dy [boolean-repaint])
>           (gs:reorder-tags list-tags)
>           (gs:rotate-tag sym-tag float theta int-x int-y [boolean-repaint])
>           (gs:save-text sym-id str-path)
>           (gs:scale-tag sym-tag float-x float-y [boolean-repaint])
>           (gs:shear-tag sym-tag float-x float-y [boolean-repaint])
>           (gs:show-popup sym-tag sym-host int-x int-y)
>           (gs:show-tag sym-tag [boolean-repaint])
>           (gs:set-canvas sym-tag)
>           (gs:set-paint list-rgb)
>           (gs:set-rotation float-angle)
>           (gs:set-scale int-x int-y)
>           (gs:set-stroke float-width [str-cap [str-join [float-miterlimit]]])
>           (gs:set-translation int-x int-y)
>           (gs:set-anti-aliasing boolean-flag)
>           (gs:translate-tag sym-tag int-x int-y [boolean-repaint])
>           (gs:update)

> - Events
>   Additionally to the event actions registered when creating a widget, the canvas, windows and dialogs can fire events as a result of key or mouse actions or when the position or size of a windows or dialog has changed.

>           (gs:key-event sym-id sym-action)
>           (gs:mouse-clicked sym-canvas sym-action [boolean-tags])
>           (gs:mouse-dragged sym-canvas sym-action)
>           (gs:mouse-event sym-id sym-action)
>           (gs:mouse-moved sym-canvas sym-action [boolean-tags])
>           (gs:mouse-pressed sym-canvas sym-action [boolean-tags])
>           (gs:mouse-released sym-canvas sym-action [boolean-tags])
>           (gs:mouse-wheel sym-canvas sym-action)
>           (gs:window-closed sym-id sym-action)
>           (gs:window-moved sym-id sym-action)
>           (gs:window-resized sym-id sym-action)

> - Built-in icons and images
>   The `guiserver.jar` file has the following icons and images built in. Each of them is prefixed with the path `/local/`. For example `/local/newLISP128.png` addresses the newLISP logo of size 128x128. To address images outside of `guiserver.jar`, use a normal file path suitable to your platform. On Win32 use forward slashes instead of backslashes.

>        Image path
>        ----------
>        clear-down32.png
>        clear32.png
>        copy-down32.png
>        copy32.png
>        cut-down32.png
>        cut32.png
>        dotgray16.png
>        dotgray32.png
>        dotgreen16.png
>        dotgreen32.png
>        dotred16.png
>        dotred32.png
>        dotyellow16.png
>        dotyellow32.png
>        edit-down32.png
>        edit32.png
>        folder-closed-down32.png
>        folder-closed32.png
>        folder-opened-down32.png
>        folder-opened32.png
>        font-book-down32.png
>        font-book32.png
>        green10.png
>        info-down32.png
>        info32.png
>        new-down32.png
>        new32.png
>        newLISP-down32.png
>        newLISP128.png
>        newLISP16.png
>        newLISP20.png
>        newLISP32.png
>        newLISP64.png
>        newLISPsplashWin.png
>        paste-down32.png
>        paste32.png
>        pressedbutton32.png
>        red10.png
>        restart-down32.png
>        restart32.png
>        run-down32.png
>        run32.png
>        save-down32.png
>        save32.png
>        search-down32.png
>        search32.png
>        stop-down32.png
>        stop32.png

> - Predefined colors
>   The following colors are predefined:

>        Name          rgb components
>        ----          --------------
>        gs:black      (0.0 0.0 0.0)
>        gs:blue       (0.0 0.0 1.0)
>        gs:cyan       (0.0 1.0 1.0)
>        gs:darkGray   (0.2509804 0.2509804 0.2509804)
>        gs:gray       (0.5019608 0.5019608 0.5019608)
>        gs:green      (0.0 1.0 0.0)
>        gs:lightGray  (0.7529412 0.7529412 0.7529412)
>        gs:magenta    (1.0 0.0 1.0)
>        gs:orange     (1.0 0.78431374 0.0)
>        gs:pink       (1.0 0.6862745 0.6862745)
>        gs:red        (1.0 0.0 0.0)
>        gs:white      (1.0 1.0 1.0)
>        gs:yellow     (1.0 1.0 0.0)

>   Colors in newLISP-GS can be specified as three (four with alpha component) single numbers or as a list of the three RGB values followed by the alpha channel number.

>        (gs:set-background 'aPanel gs:magenta
>        (gs:set-background 'aPanel 1.0 0 1
>        (gs:set-background 'aPanel '(1 0 1)

>   All of the above statements will produce the same background color on the `aPanel`.
> - Sound and MIDI API
>   The newLISP-GS sound API uses the default saundbank and sound hardware installed on the platform newLISP-GS is running on. On Mac OS X nothing additional needs to be installed. On Win32 and some Unix platforms a soundbank file needs to be installed. Soundbanks for the Java JRE can be obtained at: http://java.sun.com/products/java-media/sound/soundbanks.html The demo files shipped with the newLISP-GS installation use the midsize soundbank. Other soundbanks may require different naming of instruments in the `gs:midi-patch` statement.
>   The sound API is capable of playing of mutliple tracks at the same time depending on the sound hardware installed on a specific platform. Mac OS X platforms and most Win32 platforms should be capable of playing 16 instruments (channels) at the the same time 32 on parallel sounding tracks. newLISP GS supports 128 instruments of the default soundbank installed.
>   On Mac OS X and Win32 channel 9 is a special channel sounding a different rythm instrument for all 128 different keys/notes.
>   Basic capabilities of the sound API are shown in the demo files `midi-demo.lsp` and `midi2-demo.lsp` in the `/usr/share/newlisp/guiserver/` or `c:\Program files\newlisp\guiserver\` directory.

>           (gs:add-track int channellist-notes)
>           (gs:channel-bend int-channel bend)
>           (gs:get-instruments)
>           (gs:instruments)
>           (gs:midi-bpm int-bpm [int-resolution])
>           (gs:midi-close)
>           (gs:midi-init [str-file-path])
>           (gs:midi-patch int-instrument [int-channel])
>           (gs:mute-track int-track bool-on-off)
>           (gs:play-note int-key [int-duration [int-velocity [int-channel [int-bend]]]])
>           (gs:play-sequence [int-start-tick [int-loop-count [int-start-loop [int-end-loop]]]])
>           (gs:save-sequence str-file-path)
>           (gs:stop-sequence)
>           (gs:play-sound str-file-path)

> §

> ### gs:add-list-item

> syntax: (gs:add-list-item sym-list-combo str-text [str-text ...])
> parameter: sym-list-combo - The name of the combo box or list box to which text entries are added.
> parameter: str-text - The text of the entry to be added.
> Items are added in the same sequence as they appear in the `gs:add-list-item` command and added to the end of the existing list of items.
> §

> ### gs:add-separator

> syntax: (gs:add-separator sym-menu-tool-bar)
> parameter: sym-menu-tool-bar - The name of the tool bar or menu bar to which a spacer entry is added.
> Depending on the OS platform the separator may not be visible and only occupy space before the next component added to the tool or menu bar.
> §

> ### gs:add-track

> syntax: (gs:add-track int-channel list-of-notes)
> parameter: int-channel - The channel belonging to this track.
> parameter: list-of-notes - A list of notes. Each note is a list of key duration velocity and bend.
> In case of `gs:add-track` the duration of a note is given in ticks. 16 ticks are in a quarter note or beat.
> A note is a list of 4 elements: `(int-key int-duration int-velocity [int-bend])`. key duration, velocity and bend can be given as variables, which will be evaluated by `gs:add-track`. The int-bend parameter is optional and assumed as `0` if not present. See the command `gs:play-note` for more information on the note bend parameter. The following code is a complete example:
> example:

> >      (load (append (env "NEWLISPDIR") "/guiserver.lsp"))
> >      (gs:init)
> >      (gs:midi-init)

> >      (map set '(C C# D D# E F F# G G# A A# B c c# d e f f# g g# a a# b) (sequence 60 82))
> >      (set 'pp 30 'p 40 'm 64 'f 127) ; set velocity/volume

> >      (gs:midi-patch "Piano" 0)
> >      (gs:midi-patch "Pizzicato Strings" 1)
> >      (gs:midi-patch "Woodblock" 2)

> >      (gs:add-track 0 '( (C 12 m) (C# 4 m) (D 16 m) (c 16 f) (D 16 m)) )
> >      (gs:add-track 1 (dup '(d 4 pp) 16))
> >      (gs:add-track 2 '( (c 4 p) (c 12 p) (c 4 p) (c 12 p) (c 4 p) (c 12 p)  (c 4 p) (c 12 p)) )

> >      (gs:play-sequence)

> >      (sleep 5000)
> >      (gs:midi-close)
> >      (exit)

> The second example shows the usage of pitch-bend in notes:
> example:

> >      (load (append (env "NEWLISPDIR") "/guiserver.lsp"))
> >      (gs:init)
> >      (gs:midi-init)

> >      (gs:midi-patch "Piano" 0)
> >      (gs:midi-patch "Gunshot" 1)
> >      (gs:midi-patch "Telephone" 2)

> >      (for (n -8192 8191 128) (push (list 64 1 95 n) track0 -1))
> >      (for (n 64 96 2) (push (list n 8 76) track1 -1))

> >      (gs:add-track 0 track0)
> >      (gs:add-track 1 track1)
> >      (gs:add-track 2 '((44 128 127)))

> >      (gs:play-sequence)
> >      ;(gs:save-sequence "extremeAlarm.mid")

> >      (sleep 8000)
> >      (gs:midi-close)
> >      (exit)

> §

> ### gs:add-to

> syntax: (gs:add-to sym-container sym-component [sym-componentl ...])
> parameter: sym-container - The name of the container to which components are added.
> parameter: sym-component - One or more symbols of the components to add.
> syntax: (gs:add-to sym-container sym-component str-orientation [sym-component str-orientation ...])
> parameter: sym-container - The name of the container to which components are added.
> parameter: sym-component - The name of a component to add.
> parameter: str-orientation - The orientation of a component to add in border layout, `"north"`, `"west"`, `"center"`, `"east"` or `"south"`.
> §

> ### gs:append-text

> syntax: (gs:append-text sym-id str-text)
> parameter: sym-id - The name of the text field or text area to which text is appended.
> parameter: str-text - The text to be appended.
> §

> ### gs:button

> syntax: (gs:button sym-id sym-action [str-text [int-width int-height]])
> parameter: sym-id - The name of the button.
> parameter: sym-action - The name of the event handler.
> parameter: str-text - An optional text for the button.
> parameter: int-width - The optional width of the button.
> parameter: int-height - The optional height of the button.
> §

> ### gs:canvas

> syntax: (gs:canvas sym-id)
> parameter: sym-id - The name of the canvas.
> A canvas is a panel for drawing and receiving mouse input events. For most applications a background color should be specified for the canvas using `gs:set-background` or `gs:set-color` which call the same function internally. The background forces the canvas to be cleared before redrawing components which have been moved, rotated, scaled or deleted. In applications where this is not desired but a background color is still required, the background color can be specified for the container hosting the canvas. The canvas background will then appear in the color of the container, but erasing the canvas before repainting is not enforced.
> A canvas can also be used to host widgets like buttons etc.. In this case the canvas is treated like a `gs:panel`, with a flow layout by default. Similar to a panel created with `gs:panel` other layouts can be set.
> When widgets are present on a canvas they appear to be floating over the drawing. See the file `textrot-demo.lsp` for an example.
> §

> ### gs:channel-bend

> syntax: (gs:channel-bend int-channel bend)
> parameter: int-channel - The channel where the pitch bend is set.
> parameter: int-bend - The channel bend between `0` and `16383`.
> Numbers upwards of `8192` bend the tone upwards, numbers smaller than `8192` bend the tone downwards. To switch off channel bend set the number to the middle posiotion of `8192`. `gs:channel-bend` can be used to bring a channel in tune with an external sound source.
> §

> ### gs:check-box

> syntax: (gs:check-box sym-id sym-action [str-text [bool-selected]])
> parameter: sym-id - The name of the check box.
> parameter: sym-action - The name of the event handler.
> parameter: str-text - The text of the check box.
> parameter: bool-selected - An optional flag indicating the selection state `true` or `nil` (default).
> §

> ### gs:check-event

> syntax: (gs:check-event int-microseconds)
> parameter: int-microseconds - Wait for an event a maximum of int-microseconds and execute it.
> The function `gs:check-event` is used as an alternative to `gs:listen` when the application is performing some activity while waiting for user input from the GUI. Typically `gs:check-event` is used in a loop, which performs some other task and at the same time checks for events from the GUI part of the application. Like `gs:listen` the function will force an exit of the application when communication between the newLISP-GS and the newLISP application process fails.
> example:

> >      (while (gs:check-event 10000) ; check for 10 milliseconds
> >          (do-myprocess)
> >      )

> §

> ### gs:clear-list

> syntax: (gs:clear-list sym-id)
> parameter: sum-id - The name of the list component in which to clear all entries.
> §

> ### gs:clear-text

> syntax: (gs:clear-text sym-id)
> parameter: sum-id - The name of the component in which to clear the text.
> §

> ### gs:copy-text

> syntax: (gs:copy-text sym-id)
> parameter: sum-id - The name of the text component from which to copy the selection to the clipboard.
> §

> ### gs:cut-text

> syntax: (gs:cut-text sym-id)
> parameter: sym-id-text - The name of the text component from which to cut selected text and place it on the clipboard..
> §

> ### gs:color-dialog

> syntax: (gs:color-dialog sym-parent-frame sym-action str-title float-red float-green float-blue)
> parameter: sym-parent-frame - The name symbol of the parent frame.
> parameter: sym-action - The symbol of the handler to call when leaving the dialog
> parameter: str-title - The title of the color dialog.
> parameter: float-red - The initial red color component.
> parameter: float-green - The initial green color component.
> parameter: float-blue - The initial blue color component.
> §

> ### gs:color-tag

> syntax: (gs:color-tag sym-tag list-color [boolean-update])
> parameter: sym-tag - The name tag of the shape(s) to set a new color.
> parameter: list-color - The new color as a list of 3 numbers for the rgb components.
> parameter: boolean-repaint - An optional flag to indicate if repainting is required (default is `true`).
> §

> ### gs:combo-box

> syntax: (gs:combo-box sym-id sym-action [str-item-1 ...])
> parameter: sym-id - The name of the combo box.
> parameter: sym-action - The name of the event handler.
> parameter: str-item - Zero, one or more text entries in the combo box.
> syntax: (gs:combo-box sym-id sym-action [list-str-items])
> parameter: sym-id - The name of the combo box.
> parameter: sym-action - The name of the event handler.
> parameter: list-str-items - Zero, one or more text entries in a list.
> §

> ### gs:confirm-dialog

> syntax: (gs:confirm-dialog sym-parent-frame sym-action str-title str-message [str-type])
> parameter: sym-parent-frame - The symbol name of the parent frame.
> parameter: sym-action - The action to perform when the diaog is closed.
> parameter: str-title - The title of the message box.
> parameter: str-message - The message in the message box.
> parameter: str-type - The type of the message box.
> The type of the message box can be one of: `"yes-no"`, `"yes-no-cancel"` On return of the message box sym-action carries one of the responses `0` for the yes-, `1` for the no- or `2` for the cancel-button.
> §

> ### gs:delete-tag

> syntax: (gs:delete-tag sym-tag [boolean-repaint])
> parameter: sym-tag - The tag group to be deleted.
> parameter: boolean-repaint - An optional flag to indicate if repainting is required (default is `true`).
> Deletes all 2D objects (lines, shapes, text, images) tagged with sym-tag.
> Each time a `gs:draw-xxx` or `gs:fill-xxx` function is called a graphical object is created. The tag used during creation is a way to address one or more of these objects. See the file `mouse-demo.lsp` for an example.
> §

> ### gs:destroy-shell

> syntax: (gs:destroy-shell sym-text-area)
> parameter: sym-text-area - The name of the text component for which the shell process is destroyed.
> §

> ### gs:dialog

> syntax: (gs:dialog sym-id sym-parent str-title int-width int-height [boolean-visible [boolean-modal]])
> parameter: sym-id - The name of the dialog
> parameter: sym-parent - The name of the parent frame.
> parameter: str-title - The title string of the dialog frame.
> parameter: int-width - The width of the dialog frame.
> parameter: int-height - The height of the dialog frame.
> parameter: boolean-visible - The optional flag with a value of `true` or `nil` for visibility of the dialog.
> parameter: boolean-modal - The optional flag with a value of `true` or `nil` for modality of the dialog.
> Initially the dialog should not be visible until all widgets are added to it. When no flags for visibility and modality are specified, `nil` is assumed. A modal dialog will prevent input in the parent window. Components can be added to a dialog using `gs:add-to`. Use the `gs:set-border-layout`, `ga:set-flow-layout` or `gs:set-grid-layout` to set a specific layout.
> §

> ### gs:disable

> syntax: (gs:disable sym-id-1 [sym-id-2 ...])
> parameter: sym-id - The name of the component to disable.
> Disabled components are grayed and do not accept input.
> §

> ### gs:dispose

> syntax: (gs:dispose sym-id)
> parameter: sym-id - The name of the component to dispose of.
> §

> ### gs:dispose-splash

> syntax: (gs:dispose-splash)
> A splash screen can be specified when starting the newLISP-GS process before newLISP. The function `gs:dispose-splash` is used to turn off the splash image after the newLISP GUI application has started.
> example:

> >      java -jar /usr/share/newlisp/guiserver.jar 4711 program.lsp /local/newLISP128.png
> >      ; or on Win32
> >      java -jar "c:\Program Files\newlisp\guiserver.jar" 4711 "newlisp program.lsp" /local/newLISPsplashWin.png

> The example starts newLISP-GS with an application `program.lsp` and a splash screen showing the built-in newLISP logos and using port 4711. Instead, the full pathname of a different image file can be specified. Inside `program.lsp` the function `gs:dispose-splash` or a mouse click on the image will turn off the splash screen. For `program.lsp` the full pathname may be necessary. On Win32 quotes are necessary to bracket arguments to `guiserver.jar` which contain spaces.
> §

> ### gs:draw-arc

> syntax: (gs:draw-arc sym-tag int-x int-y int-width int-height int-start int-angle [list-rgb])
> parameter: sym-tag - The tag group of the arc.
> parameter: int-x - The X position of the arc.
> parameter: int-y - The Y position of the arc.
> parameter: int-width - The width of the arc.
> parameter: int-height - The height of the arc.
> parameter: int-start-angle - The start angle of the arc in 0 to 360 degrees.
> parameter: int-arc-angle - The opening angle of the arc in 0 to 360 degrees.
> parameter: list-rgb - The outline color as a list of 3 numbers for the rgb components
> The resulting arc begins at int-start-angle and extends for int-arc-angle degrees, using the current color. Angles are interpreted such that 0 degrees is at the 3 o'clock position. A positive value indicates a counter-clockwise rotation while a negative value indicates a clockwise rotation.
> The center of the arc is the center of the rectangle whose origin is (x, y) and whose size is specified by the width and height arguments.
> The resulting arc covers an area int-width pixels wide by int-height pixels tall.
> §

> ### gs:draw-circle

> syntax: (gs:draw-circle sym-tag int-x int-y int-radius [list-rgb])
> parameter: sym-tag - The tag group of the circle.
> parameter: int-x - The X position of the circle center.
> parameter: int-y - The Y position of the circle center.
> parameter: int-radius - The radius of the circle.
> parameter: list-rgb - The outline color as a list of 3 numbers for the rgb components
> Creates the outline of a circle. The color numbers must be entered in list form. If no list-rgb is used the current paint specified with `gs:set-paint` is used.
> §

> ### gs:draw-ellipse

> syntax: (gs:draw-ellipse sym-tag int-x int-y int-radius-x int-radius-y [list-rgb])
> parameter: sym-tag - The tag group of the ellipse.
> parameter: int-x - The X position of the ellipse center.
> parameter: int-y - The Y position of the ellipse center.
> parameter: int-radius-x - The radius of the ellipse.
> parameter: int-radius-y - The radius of the ellipse.
> parameter: list-rgb - The outline color as a list of 3 numbers for the rgb components
> Creates the outline of an ellipse. The color numbers must be enterd in list form. If no list-rgb is used the current paint specified with `gs:set-paint` is used.
> §

> ### gs:draw-image

> syntax: (gs:draw-image sym-tag str-path int-x int-y [int-width int-height])
> parameter: sym-tag - The tag group of the image.
> parameter: int-x - The X position of the image top left corner.
> parameter: int-y - The Y position of the image top left corner.
> parameter: int-width - The optional width in which to draw the image.
> parameter: int-height - The optional height in which to draw the image.
> When int-width and int-height parameters are specified and they are not equal to the original size of the image (measured in pixels) the image will be displayed in either compressed or zoomed form.
> §

> ### gs:draw-line

> syntax: (gs:draw-line sym-tag int-x1 int-y1 int-x2 int-y2 [list-rgb])
> parameter: sym-tag - The tage of the line.
> parameter: int-x1 - The X position of the first point.
> parameter: int-y1 - The Y position of the first point.
> parameter: int-x2 - The X position of the second point.
> parameter: int-y2 - The Y position of the second point.
> Draws a line. The color numbers must be entered in list form. If no list-rgb is used the current paint specified with `gs:set-paint` is used.
> §

> ### gs:draw-path

> syntax: (gs:draw-path sym-tag list-points [list-rgb])
> parameter: sym-tag - The tage group of the path.
> parameter: list-points - The list of x and y coordinates of the points.
> Draws a path with the points found in list-points.
> example:

> >      (gs:draw-path 'P '(1 0 2 2 3 0))

> The example will draw an upwards-pointing triangle without base at the points `1,0`, `2,2` and `3,0`
> §

> ### gs:draw-polygon

> syntax: (gs:draw-polygon sym-tag list-points [list-rgb])
> parameter: sym-tag - The tag group of the polygon.
> parameter: list-points - The list of x and y coordinates of the points.
> Draws a polygon with the points found in list-points.
> example:

> >      (gs:draw-polygon 'P '(1 0 2 2 3 0))

> The example will draw an upwards-pointing triangle with the points `1,0`, `2,2` and `3,0`.
> §

> ### gs:draw-rect

> syntax: (gs:draw-rect sym-tag int-x int-y int-width int-height [list-rgb])
> parameter: sym-tag - The tag group of the rectangle.
> parameter: int-x - The X position of the top left corner.
> parameter: int-y - The Y position of the top left corner.
> parameter: int-width - The width of the rectangle.
> parameter: int-height - The height of the rectangle..
> parameter: list-rgb - The outline color as a list of 3 numbers for the rgb components
> Creates the outline of a rectangle. The color numbers must be entered in list form. If no list-rgb is used the current paint specified with `gs:set-paint` is used.
> §

> ### gs:draw-round-rect

> syntax: (gs:draw-round-rect sym-tag int-x int-y int-width int-height int-arc-width int-arc-height [list-rgb])
> parameter: sym-tag - The tag group of the round rectangle.
> parameter: int-x - The X position of the top left corner.
> parameter: int-y - The Y position of the top left corner.
> parameter: int-width - The width of the rectangle.
> parameter: int-height - The height of the rectangle..
> parameter: int-arc-width - The width of the corner rectangle.
> parameter: int-arc-height - The height of the corner rectangle..
> parameter: list-rgb - The outline color as a list of 3 numbers for the rgb components
> Draws a rectangle shape with round corners. The rounding is defined by the rectangle enclosing the rounding arc.
> §

> ### gs:draw-text

> syntax: (gs:draw-text sym-tag str-text int-x int-y [list-rgb [float-angle])
> parameter: sym-tag - The tag group of the text.
> parameter: str-text - The text to be drawn.
> parameter: int-x - The X position of the text.
> parameter: int-y - The Y position of the text.
> parameter: list-rgb - The optonal color for the text.
> parameter: float-angle - The optional angle for text in degrees
> If no list-rgb is used, the current paint specified with `gs:set-paint` is used. The optional angle is `0` by default for horizontal text. A value of `90` will rotate the text around the `x`, `y` position downwards clockwise.
> §

> ### gs:enable

> syntax: (gs:enable sym-id-1 [sym-id-2 ...])
> parameter: sym-id - The name of a component to enable.
> Components are enabled by default.
> §

> ### gs:eval-shell

> syntax: (gs:eval-shell sym-id-text-area str-command)
> parameter: sym-id-text-area - The name of the text area in which to evaluate text.
> parameter: str-command - The text to evaluate in the shell.
> §

> ### gs:export

> syntax: (gs:export str-path-file [int-width int-height])
> parameter: str-path-file - The path and file name of the image file to write to.
> parameter: int-width - The optional width of the image in pixels.
> parameter: int-height - The optional height of the image in pixels.
> If no width and height are specified, the current size of the canvas is assumed.
> example:

> >      (gs:export "/usr/home/pictures/mypic.png")

> This will generate a `.png` file exactly as the image seen on the screen. The color format is RGBA with 8 bit per color and an alpha channel. When no background color is defined for the canvas, the background will be transparent.
> When specifying width and height, a smaller or bigger portion of the canvas than seen on the screen is printed to the image.
> §

> ### gs:fill-arc

> syntax: (gs:fill-arc sym-tag int-x int-y int-width int-height int-start int-angle [list-rgb])
> parameter: sym-tag - The tag group of the arc.
> parameter: int-x - The X position of the arc.
> parameter: int-y - The Y position of the arc.
> parameter: int-width - The width of the arc.
> parameter: int-height - The height of the arc.
> parameter: int-start-angle - The start angle of the arc in 0 to 360 degrees.
> parameter: int-arc-angle - The opening angle of the arc in 0 to 360 degrees.
> parameter: list-rgb - The outline color as a list of 3 numbers for the rgb components.
> The resulting arc begins at int-start-angle and extends for int-arc-angle degrees, using the current color. Angles are interpreted such that 0 degrees is at the 3 o'clock position. A positive value indicates a counter-clockwise rotation while a negative value indicates a clockwise rotation.
> The center of the arc is the center of the rectangle whose origin is (x, y) and whose size is specified by the width and height arguments.
> The resulting arc covers an area int-width pixels wide by int-height pixels tall.
> §

> ### gs:fill-circle

> syntax: (gs:fill-circle sym-tag int-x int-y int-radius [list-rgb])
> parameter: sym-tag - The tag group of the circle.
> parameter: int-x - The X position of the circle center.
> parameter: int-y - The Y position of the circle center.
> parameter: int-radius - The radius of the circle.
> parameter: list-rgb - The outline color as a list of 3 numbers for the rgb components.
> Creates a filled circle. The color numbers must be entered in list form. If no list-rgb is used, the current paint specified with `gs:set-paint` is used.
> §

> ### gs:fill-ellipse

> syntax: (gs:fill-ellipse sym-tag int-x int-y int-radius-x int-radius-y [list-rgb])
> parameter: sym-tag - The tag group of the ellipse.
> parameter: int-x - The X position of the ellipse center.
> parameter: int-y - The Y position of the ellipse center.
> parameter: int-radius-x - The radius of the ellipse.
> parameter: int-radius-y - The radius of the ellipse.
> parameter: list-rgb - The fill color as a list of 3 numbers for the rgb components.
> Creates a filled ellipse. The color numbers must be entered in list form. If no list-rgb is used, the current paint specified with `gs:set-paint` is used.
> §

> ### gs:fill-polygon

> syntax: (gs:fill-polygon sym-tag list-points [list-color])
> parameter: sym-tag - The tag group of the polygon.
> parameter: list-points - The list of x and y coordinates of the points.
> Draws a polygon with the points found in list-points and fills it with the current color set with `gs:set-paint` or the optional color given in list-color.
> example:

> >      (gs:fill-polygon 'P '(1 0 2 2 3 0))

> >      (gs:fill-polygon 'P '(1 0 2 2 3 0) gs:gray)

> The example will fill an upwards pointing triangle with the points `1,0`, `2,2` and `3,0` and fill it with the current color set with `gs:set-paint`. The second example paints a gray triangle regardless of the current color set with `gs:set-paint`.
> §

> ### gs:fill-rect

> syntax: (gs:fill-rect sym-tag int-x int-y int-width int-height [list-rgb])
> parameter: sym-tag - The tag group of the rectangle.
> parameter: int-x - The X position of the top left corner.
> parameter: int-y - The Y position of the top left corner.
> parameter: int-width - The width of the rectangle.
> parameter: int-height - The height of the rectangle.
> parameter: list-rgb - The fill color as a list of 3 numbers for the rgb components.
> Creates a filled rectangle. The color numbers must be entered in list form. If no list-rgb is used, the current paint specified with `gs:set-paint` is used.
> §

> ### gs:fill-round-rect

> syntax: (gs:fill-round-rect sym-tag int-x int-y int-width int-height int-arc-width int-arc-height [list-rgb])
> parameter: sym-tag - The tag group of the round rectangle.
> parameter: int-x - The X position of the top left corner.
> parameter: int-y - The Y position of the top left corner.
> parameter: int-width - The width of the rectangle.
> parameter: int-height - The height of the rectangle..
> parameter: int-arc-width - The width of the corner rectangle.
> parameter: int-arc-height - The height of the corner rectangle.
> parameter: list-rgb - The outline color as a list of 3 numbers for the rgb components.
> Paints a rectangle shape with round corners. The rounding is defined by the rectangle enclosing the rounding arc.
> §

> ### gs:find-text

> syntax: (gs:find-text sym-id str-text sym-action [str-direction])
> parameter: sym-id - The name of the text area or text pane.
> parameter: str-text - The searching text.
> parameter: sym-action - A optional action to peform after find-text.
> parameter: str-direction - The optional direction string `"next"` (default) or `"previous"`.
> The text area or text pane will be searched starting at the current caret position forward or backwards depending on the optional direction field. After the search the found text is highlighted. If the optional sym-action is specified an event containing the id of the text area or pane and found position or `-1` will be fired.
> §

> ### gs:frame

> syntax: (gs:frame sym-id int-x int-y int-width int-height [str-title boolean-visible])
> parameter: sym-id - The name of the frame window.
> parameter: int-x - The X position of the top left window corner.
> parameter: int-y - The Y position of the top left windows corner.
> parameter: int-width - The width of the window frame.
> parameter: int-height - The height of the windows frame.
> parameter: str-title - The optional title of the window.
> parameter: boolean-visible - The optional flag with a value of `true` or `nil` for the visibility of the window.
> Initially the frame should not be visible until all widgets are added to it. When no flag for visibility is specified `nil` is assumed. The default layout of a frame behaves like a grid layout with one cell. Use the `set-flow-layout`, `set-border-layout` and `set-grid-layout` to change the layout.
> §

> ### gs:get-bounds

> syntax: (gs:get-bounds sym-id)
> parameter: sym-id - The id of the component for which to get the list of bounding values.

> return: The bounding list `(x y width height)`

> §

> ### gs:get-fonts

> syntax: (gs:get-fonts)

> return: A list of family names for fonts on the current system.

> The function should be called only once because it may take considerable time in a system loaded with many fonts. The variable `gs:fonts` contains the same list of fonts originally returned by a call to `gs:get-fonts`.
> §

> ### gs:get-font-metrics

> syntax: (gs:get-font-metrics sym-id str-text)

> return: A list of the two values for width and height in pixels.

> The font metrics for the currently set font in sym-id are returned as a list of width and height in pixels when displaying the string in str-text. After the function call the variable `gs:font-metrics` contains the same list of values as originally returned by the call to `gs:get-font-metrics`.
> §

> ### gs:get-instruments

> syntax: (gs:get-instruments)

> return: A list of instrument names in the default MIDI soundbank.

> The function should be called only once because it may take considerable time in a system loaded with a big soundbank. The variable `gs:instruments` contains the same list of instruments originally returned by a call to `gs:get-instruments`.
> §

> ### gs:get-screen

> syntax: (gs:get-screen)

> return: A list of screen width, height and resolution of the main computer screen.

> After calling the `gs:get-screen` once the screen parameters are also available in the variable `gs:screen`.
> §

> ### gs:get-selected-text

> syntax: (gs:get-selected-text sym-id sym-action)
> parameter: sym-id - The name of the component from which to get the selected text.
> parameter: sym-action - The symbol of the event handler which will receive the selected text.
> §

> ### gs:get-text

> syntax: (gs:get-text sym-id [sym-action])
> parameter: sym-id - The name of the component from which to get the text.
> parameter: sym-action - The optional symbol of the event handler which will receive the text.
> If no sym-action is specified the function will block until the text is returned. After return the text is also available in the variable `gs:text`. If sym-action is specified the function will return immediately and a sym-action event is fired containing the text.
> §

> ### gs:get-text-position

> syntax: (gs:get-text-position sym-id)
> parameter: sym-id - The name of the text component for which the line and column position is returned.

> return: A list of line and column position of the text caret.

> §

> ### gs:get-version

> syntax: (gs:get-version)

> return: The version of newLISP-GS running.

> After calling the `gs:get-version` once the version number is also available in `gs:version`.
> §

> ### gs:goto-text

> syntax: (gs:goto-text sym-id int-row int-column)
> parameter: sym-id - The name of the text widget.
> parameter: int-row - The row number where to place the cursor.
> parameter: int-column - The column number where to place the cursor.
> §

> ### gs:hide-tag

> syntax: (gs:hide-tag sym-tag [boolean-repaint])
> parameter: sym-tag - The tag of the group to hide.
> parameter: boolean-repaint - An optional flag to indicate if repainting is required (default is `true`).
> §

> ### gs:image-button

> syntax: (gs:image-button sym-id sym-action str-icon-path [str-down-icon-path [int-width int-height]])
> parameter: sym-id - The name of the image button.
> parameter: sym-action - The name of the event handler.
> parameter: str-icon-path - The path for an image icon.
> parameter: str-down-con-path - The path for a pressed down image icon.
> parameter: int-width - The optional width of the image button.
> parameter: int-height - The optional height of the image button.
> §

> ### gs:image-label

> syntax: (gs:image-label sym-id str-icon-path [str-align])
> parameter: sym-id - The name of the label.
> parameter: str-ucon-path - A string with the icon file path.
> parameter: str-align - An optional alignment `"left"`, `"center"` or `"right"`, `"leading"`, `"trailing"`, `"bottom"` or `"top"`.
> §

> ### gs:init

> syntax: (gs:init [int-port str-host [bool-manual]])
> parameter: int-port - The optional guiserver server port.
> parameter: str-host - The optional remote host of the guiserver.
> §

> ### gs:insert-list-item

> syntax: (gs:insert-list-item sym-list-combo str-text int-index [str-text int-index])
> parameter: sym-list-combo - The name of the combo box or list box from which entries are removed.
> parameter: str-text - The text of the list or combo box item to insert.
> parameter: int-index - The index of an entry to add to the list or combo box.
> When specifying an index of `0` the first item gets inserted at the beginning. When specifying an index equal or greater to the number of items in the list, the item is added at the end.
> §

> ### gs:insert-tab

> syntax: (gs:insert-tab sym-tabbed-pane sym-component [str-text [int-index [str-icon-path]]])
> parameter: sym-tabbed-pane - The name of the tabbed pane.
> parameter: sym-component - The name of the component to insert as a tab.
> parameter: str-text - The optional text on the tab.
> parameter: int-index - The optional index where to insert the new tab.
> parameter: str-icon-path - The file path to an optional icon.
> §

> ### gs:insert-text

> syntax: (gs:insert-text sym-id str-text int-position)
> parameter: sym-id - The name of the text component.
> parameter: str-text - The text to insert.
> parameter: int-position - The offset position where to insert the text.
> §

> ### gs:key-event

> syntax: (gs:key-event sym-id sym-action)
> parameter: sym-id - The id of the component to register the action handler.
> parameter: sym-action - The symbol of the action handler.
> `gs:key-event` can be used to register a general unspecific key event handler for any component in the system. Since version 1.05 of newLISP-GS this also includes text widgets, which already handle key events using their normal event handler function. With `gs:key-event` a second handler function can be registered for text widgets. Both functions will fire on their respective events.
> Components respond to the following key event types: `"pressed"`, `"released"`, `"typed"`.
> example:

> >      (define (key-action id type code modifiers)
> >          (println "id:" id " type:" type " key code:" code " modifiers:" modifiers)
> >      )

> The example shows a handler which prints all key event parameters to the terminal/shell window where the applicaton was started.
> In order for key events to work, the component for which a key action handler is registered must have the input focus. Use `"gs:request-focus"` to set the input focus for the component.
> §

> ### gs:label

> syntax: (gs:label sym-id str-text [str-align [int-width int-height]])
> parameter: sym-id - The name of the label.
> parameter: str-text - The text to appear on the label.
> parameter: str-align - The optional alignment of the text.
> parameter: int-width - The optional width of the label.
> parameter: int-height - The optional height of the label.
> The following alignment constants can be supplied: `"left"`, `"center"`, '"right"", `"leading"`, `"trailing"`, `"bottom"` and "`top`". By default each label text is `"center"` aligned.
> §

> ### gs:layout

> syntax: (gs:layout sym-container)
> parameter: sym-container - The id of the container to lay out.
> Forces the container to lay out its components again, e.g. after a `gs:add-to` or `gs:remove-from` when the container was already visible.
> §

> ### gs:load-text

> syntax: (gs:load-text sym-id str-path)
> parameter: sym-id - The id of the `gs:text-pane`.
> parameter: str-path - The full path name of the file to load.
> `gs:load-text` will load text into a `gs:text-pane` directly by specifying the path name. During loading, CR-LF line terminators are automatically translated to LF-only line terminators by stripping all CRs from the file. All internal operations of guiserver on text assume LF as a line terminator.
> §

> ### gs:listen

> syntax: (gs:listen [boolean-flag])
> parameter: boolean-flag - Prevent exit on loss of communication.

> return: Never returns. Exits the application when the guiserver exits, except when boolean-flag is `true`.

> §

> ### gs:list-box

> syntax: (gs:list-box sym-id sym-action [str-item-1 ...])
> parameter: sym-id - The name of the list box.
> parameter: sym-action - The name of the event handler.
> parameter: str-item - Zero, one or more text entries in the list box.
> syntax: (gs:list-box sym-id sym-action [list-str-items])
> parameter: sym-id - The name of the list box.
> parameter: sym-action - The name of the event handler.
> parameter: list-str-items - Zero, one or more text entries in a list.
> The listbox when clicked with the mouse, or when the [enter] key is presses, will pass the following parameters to the event handler:
> id - the id string of the list box
> index - the zero offset index of the highlighted listbox entry
> item - the string of the highlighted listbox entry
> click-count - the number of times the mouse has been clicked
> §

> ### gs:message-dialog

> syntax: (gs:message-dialog sym-parent-frame str-title str-message [str-type [str-icon-path]])
> parameter: sym-parent-frame - The symbol name of the parent frame.
> parameter: str-title - The title of the message box.
> parameter: str-message - The message in the message box.
> parameter: str-type - The type of the message box.
> parameter: str-icon-path - The optional path for an icon.
> The type of the message box can be one of: `"error"`, `"information"`, `"warning"`, `"question"`, `"plain"`. The function initiating the message-dialog will return when the dialog is closed.
> §

> ### gs:menu

> syntax: (gs:menu sym-id str-text)
> parameter: sym-id - The name of the menu.
> parameter: str-text - The title string of the menu.
> §

> ### gs:menu-popup

> syntax: (gs:menu-popup sym-id str-text)
> parameter: sym-id - The name of the menu.
> parameter: str-text - The title string of the menu.
> §

> ### gs:menu-bar

> syntax: (gs:menu-bar sym-frame [sym-menu-1 ...])
> parameter: sym-frame - The name of the frame hosting the menu bar.
> parameter: sym-menu - Zero or more symbol names of menus to be positioned on the menu bar.
> §

> ### gs:menu-item

> syntax: (gs:menu-item sym-id sym-action str-text)
> parameter: sym-id - The name of the menu item.
> parameter: sym-action - The name of the event handler.
> parameter: str-text - The text to appear for the menu item.
> §

> ### gs:menu-item-check

> syntax: (gs:menu-item-check sym-id sym-action str-text [bool-selected])
> parameter: sym-id - The name of the menu item.
> parameter: sym-action - The name of the event handler.
> parameter: str-text - The text to appear for the menu item.
> parameter: bool-selected - An optional flag indicating the selection state `true` or `nil` (default).
> §

> ### gs:midi-bpm

> syntax: (gs:midi-bpm [int-bpm [int-resolution]]])
> parameter: int-bpm - Beats per minute pay speed. Default is 120 BPM.
> parameter: int-resolution - Ticks per beat. Deafult is 16 ticks per beat;
> Sets the speed of playing a notes with with either `gs:play-note` or playing a sequence with `gs:play-sequence` in beats per minute (BPM).
> Before using `gs:midi-bpm` the default speed is set to 120 BPM, which corresponds to two beats per second, where each beat corresponds to a quarter note of 16 ticks default resolution.
> While the BPM parameter controls the play-back speed of the sequencer, the resolution is a parameter of the sequence creation itself and must be set before the first `gs:add-track` call.
> The preset resolution of 16 ticks per quarter note is the highest which can be set and should be sufficient for all applications.
> §

> ### gs:midi-close

> syntax: (gs:midi-close)
> Shut down the MIDI subsystem.
> §

> ### gs:midi-init

> syntax: (gs:midi-init [str-file-path])
> parameter: str-file-path - The optional file path for a soundbank file.
> Initialize the MIDI subsystem. If a soundbank file is specified load it, else load the built-in synthesizer's default soundbank.
> When not using the default soundbank, the function `gs:get-instruments` should be used first to find out the correct naming of instruments for the `gs:midi-patch` statements. The soundbank used for testing the demo files `midi-demo.lsp` and `midi2-demo.lsp` on Win32 is the midsize soundbank available here: http://java.sun.com/products/java-media/sound/soundbanks.html This soundbank has equivalent named instruments to those used in the Mac OS X default JRE installation. Currently only the first 128 instruments in a soundbank are accessed by newLISP-GS.
> §

> ### gs:midi-patch

> syntax: (gs:midi-patch str-instrument [int-channel])
> parameter: str-instrument - The name of the instrument to attach to a channel.
> parameter: int-channel - The channel for the instrument, default is `0`.
> An instrument from the current soundbank is attached to a specific channel or to channel `0` if no channel is specified.
> example:

> >      (gs:midi-patch (find "Electric Grand" gs:instruments) 0)

> In order for the `gs:instruments` variable to contain a list of instruments, `gs:get-instruments` must have been called earlier, i.e. after `gs:midi-init`.
> §

> ### gs:mouse-clicked

> syntax: (gs:mouse-clicked sym-canvas sym-action [boolean-tags])
> parameter: sym-canvas - The id of the canvas to register the action handler.
> parameter: sym-action - The symbol of the action handler.
> parameter: boolean-tags - A `true` to indicate checking for tags.
> If boolean-tags is `true`, the action event will carry a list of all tags which contained the X,Y coordinates of the mouse.
> §

> ### gs:mouse-dragged

> syntax: (gs:mouse-dragged sym-canvas sym-action)
> parameter: sym-canvas - The id of the canvas to register the action handler.
> parameter: sym-action - The symbol of the action handler.
> §

> ### gs:mouse-event

> syntax: (gs:mouse-event sym-id sym-action)
> parameter: sym-id - The id of the component to register the action handler.
> parameter: sym-action - The symbol of the action handler.
> `gs:mouse-event` can be used to register a general unspecific mouse event handler for any component in the system. Components respond to the following types: `"pressed"`, `"released"`, `"clicked"`,
> example:

> >      (define (mouse-action id type x y button cnt mods)
> >          (println "id:" id " type:" type " x:" x " y:" y " button:" button " count:" cnt " mods:" mods)
> >      )

> The example shows a handler which prints all mouse event parameters to the terminal/shell window where the applicaton was started.
> §

> ### gs:mouse-moved

> syntax: (gs:mouse-moved sym-canvas sym-action)
> parameter: sym-canvas - The id of the canvas to register the action handler.
> parameter: sym-action - The symbol of the action handler.
> parameter: boolean-tags - A `true` to indicate checking for tags.
> If boolean-tags is `true`, the action event will carry a list of all tags which contained the X,Y coordinates of the mouse.
> §

> ### gs:mouse-pressed

> syntax: (gs:mouse-pressed sym-canvas sym-action [boolean-tags])
> parameter: sym-canvas - The id of the canvas to register the action handler.
> parameter: sym-action - The symbol of the action handler.
> parameter: boolean-tags - A `true` to indicate checking for tags.
> If boolean-tags is `true`, the action event will carry a list of all tags which contained the X,Y coordinates of the mouse.
> §

> ### gs:mouse-released

> syntax: (gs:mouse-released sym-canvas sym-action [boolean-tags])
> parameter: sym-canvas - The id of the canvas to register the action handler.
> parameter: sym-action - The symbol of the action handler.
> parameter: boolean-tags - A `true` to indicate checking for tags.
> If boolean-tags is `true`, the the action event will carry a list of all tags which contained the X,Y coordinates of the mouse.
> §

> ### gs:mouse-wheel

> syntax: (gs:mouse-wheel sym-canvas sym-action)
> parameter: sym-canvas - The id of the canvas to register the action handler.
> parameter: sym-action - The symbol of the action handler.
> §

> ### gs:move-tag

> syntax: (gs:move-tag sym-tag int-dx int-dy [boolean-repaint])
> parameter: sym-tag - The tag of the group of objects to move.
> parameter: int-dx - The distance to move on the X-axis.
> parameter: int-dy - The distance to move on the Y-axis.
> parameter: boolean-repaint - An optional flag to indicate if repainting is required (default is `true`).
> `gs:move-tag` is the only tag operation which actually changes the internal data of a drawn object. All other tag operations like `gs:translate-tag`, `gs:scale-tag`, `gs:rotate-tag` and `gs:shear-tag` will transform object coordinates only for drawing.
> §

> ### gs:mute-track

> syntax: (gs:mute-track int-number [boolean-on-off])
> parameter: int-number - The number of the track starting with `0` for the first. Default is `true`.
> parameter: boolean-on-off - The track will be muted with a value of `true`
> Any other value than `true` will unmute the track again. Muting tracks is practical during music development. The track can only be muted when th sequence has benn started using `gs:play-sequence`. To completely mute a track the `gs:mute-track` statement should come right after the `gs:play-sequece` statement.
> §

> ### gs:no-action

> syntax: (gs:no-action)
> Specify as sym-action for widgets where no action handler is defined.
> §

> ### gs:open-file-dialog

> syntax: (gs:open-file-dialog sym-parent-frame sym-action [str-directory [str-mask str-description]])
> parameter: sym-parent-frame - The parent frame of the file dialog.
> parameter: sym-action - The handler function symbol.
> parameter: str-directory - The initial directory to show.
> parameter: str-mask - An optonal string mask.
> parameter: str-description - An optional mask description.
> §

> ### gs:panel

> syntax: (gs:panel sym-id [int-width int-height])
> parameter: sym-id - The name of the panel.
> parameter: int-width - The optional width of the panel.
> parameter: int-height - The optional height of the panel.
> Panels have a flow layout by default. In a flow layout an unsized button will assume the natural size necessary to display the text on it. To change the layout use the `set-flow-layout` or `set-grid-layout` functions.
> §

> ### gs:paste-text

> syntax: (gs:paste-text sym-id [str-text])
> parameter: sym-id - The name of the text component in which to paste text.
> parameter: str-text - An optional text string to paste instead of the clipboard contents.
> If the sym-id contains selected text, this text gets replaced, otherwise the text is inserted at the current caret position. If no text is given in str-text, the text is taken from the clipboard.
> §

> ### gs:play-note

> syntax: (gs:play-note int-key [int-duration [int-velocity [int-channel [int-bend]]]])
> parameter: int-key - The note or midi key `0` to `127`.
> parameter: int-duration - The duration of the note in ticks, default is `16` for one beat or quarter note.
> parameter: int-velocity - The velocity/volume of the note between `0` and `127`, default is `64`.
> parameter: int-channel - The channel through which to play the note from `0` to `15`, default is `0`.
> parameter: int-bend - The optional note bend to tune the note lower or higher from `-8192` to `8191`.
> Before using `gs:play-note`, `gs:midi-init` should be used to initialize the MIDI system. The key of the note increases in half-tone steps. The key 60 corresponds to a Middle-C. The velocity of the note is usually it's volume and/or brightness, i.e. the speed with which a key was pressed on an instrument. The channel is `0` by default and assigned to a Piano instrument unless the function `gs:midi-patch` has been used to change assignment to a different instrument.
> On Win32 and some Linux or other UNIX no MIDI soundbank files are installed by default. Goto http://java.sun.com/products/java-media/sound/soundbanks.html for instructions how to download and install a soundbank. For the demo files `mide-demo.lsp` and `midi2-demo` the midsize quality soundbank was used. On Mac OS X a soundbank is installed by default. The default for the bend parameer is `0` for no bend. Negative values down to `-8192` tune the note lower. Positive values up to `8191` tune the note higher. The following code is a complete example:
> example:

> >      ; load Guiserver
> >      (load (append (env "NEWLISPDIR") "/guiserver.lsp"))
> >      (gs:init)

> >      ; play a chromatic scale on the default instrument (piano)
> >      ; each note a 16th note of 4 ticks and a moderate volume

> >      (gs:midi-init)
> >      (gs:midi-patch "Piano" 0)
> >      (for (key 24 95) (gs:play-note key 4 95 0))
> >      (sleep 2000) ; wait until playing has finished
> >      (gs:midi-close)

> The second example demonstrated usage of the int-bend parameter:
> example:

> >      ; play the same note but with different bends below and above the note
> >      (gs:midi-patch "Violin" 0)
> >      (for (bend -2024 2024 128)
> >          (gs:play-note 80 1 95 0 bend))

> To play polyphone music of multiple parallel tracks see the function `gs:add-track` for a complete code example.
> §

> ### gs:play-sequence

> syntax: (gs:play-sequence [int-start [int-loop-count [int-start-loop [int-end-loop]]])
> parameter: int-start - The starting point in the sequence in ticks. Default is `0` for the beginning.
> parameter: int-loop-count - The number of repetitions for looping. Default is `0` for no looping.
> parameter: int-start-loop - The start of the loop to play in ticks. Default is `0`.
> parameter: int-end-loop - The end of the loop in ticks. Default is `-1` for the end.
> All parameters are optional. When no parameters are given all tracks in the sequence are sequenced from start to end with no repetiton (loop count of 0). Note that the start-loop and end-loop positions refer only to loop played after playing the full track. After the sequence started playing `gs:stop-sequence` can be used to stop it at any time. The midi system should not be close using `gs:midi-close` before playing has finished or playing will be cut off.
> See the function `gs:add-track` for complete code example.
> §

> ### gs:play-sound

> syntax: (gs:play-sound str-file-path)
> parameter: str-file-path - The path and file name of the sound file.
> On most OS platforms `.au` and `.wav` sound file formats are supported.
> §

> ### gs:progress-bar

> syntax: (gs:progress-bar sym-id int-min in-max int-initial-value)
> parameter: sym-id - The symbols of the progress bar.
> parameter: int-min - The minimum value of the slider.
> parameter: int-max - The maximum value of the slider.
> parameter: int-initial-value - The initial value of the slider.
> §

> ### gs:radio-button

> syntax: (gs:radio-button sym-id sym-action [str-text [bool-selected]])
> parameter: sym-id - The name of the radio button.
> parameter: sym-action - The name of the event handler.
> parameter: str-text - The optional text of the radio button.
> parameter: bool-seected - An optional flag `true` or `nil` (default) indicating the initial state of the radio button.
> §

> ### gs:redo-text

> syntax: (gs:redo-text sym-id)
> parameter: sym-id - The id of the `gs:text-pane` where to perform a redo operation.
> §

> ### gs:remove-from

> syntax: (gs:remove-from sym-container sym-component [sym-component ...])
> parameter: sym-container - The container from which to remove a component.
> parameter: sym-component - One or more optional components to remove.
> §

> ### gs:remove-list-item

> syntax: (gs:remove-list-item sym-list-combo int-index [int-index ...])
> parameter: sym-list-combo - The name of the combo box or list box from which entries are removed.
> parameter: int-index - The index of an entry to remove from the list or combo box.
> When specifying an index of `0`, the first item gets removed. When specifying an index equal or greater to the number of items in the list, the item is removed at the end.
> §

> ### gs:remove-tab

> syntax: (gs:remove-tab sym-tabbed-pane [int-index])
> parameter: sym-tabbed-pane - The name of the tabbed pane.
> parameter: int-index - The optional index of the tab to remove. The default is `0` for the first tab.
> §

> ### gs:request-focus

> syntax: (gs:request-focus sym-id [int-tab-index])
> parameter: sym-id - The name of the component for which to request focus.
> parameter: int-tab-index - The index of a tab for which focus is requested.
> §

> ### gs:reorder-tags

> syntax: (gs:reorder-tags list-tags)
> parameter: list-tags - The list of tag symbols or tag string names in the new order of display.
> The re-ordering itself will not repaint the canvas use `gs:update` to repaint the current canvas after using `gs:reorder-tags`. The list of tags can be given as either a list of tags symbols or name strings. Tags not appearing in list-tags will be deleted.
> §

> ### gs:rotate-tag

> syntax: (gs:rotate-tag sym-tag float theta int-x int-y [boolean-repaint])
> parameter: sym-tag - The tag group to rotate.
> parameter: float-theta - The rotation angle in degrees (0 - 360).
> parameter: int-x - The X-coordinate of the rotation center.
> parameter: int-y - The Y-coordinate of the rotation center.
> parameter: boolean-repaint - An optional flag to indicate if repainting is required (default is `true`).
> Like all tag operations, multiple `gs:rotate-tag` operations are cumulative.
> §

> ### gs:run-shell

> syntax: (gs:run-shell id-text-area str-command)
> parameter: idx-text-area - The id of the text area to wich a shell process will be attached.
> parameter: str-command - The command string to start the shell process.
> §

> ### gs:save-file-dialog

> syntax: (gs:save-file-dialog sym-parent-frame sym-action [str-directory [str-initial-file [str-mask str-description]]])
> parameter: sym-parent-frame - The parent frame of the file dialog.
> parameter: sym-action - The handler function symbol.
> parameter: str-directory - The initial directory to show.
> parameter: str-file - The initial file name.
> parameter: str-mask - An optional string mask.
> parameter: str-description - An optional mask description.
> §

> ### gs:save-sequence

> syntax: (gs:save-sequence str-file-path)
> parameter: str-file-name - The name of the MIDI file to save to.
> Save the contents of a sequence created with `gs:add-track` to a MIDI file. The file always should have the extension `.mid`.
> Note that all MIDI files created with `gs:save-sequence` will play back at a fixed speed of 120 BPM. Therefore, when creating sequences for recording using `gs:add-track`, they should be timed for a play-back speed of 120 BPM.
> To change the speed for replay from a saved MIDI file the resolution parameter can be chaged from it's default of 16 tick per beat using the second optional parameter of `gs:midi-bpm`. In this case the resolution parameter should be adjusted before calling `gs:add-track` the first time.
> §

> ### gs:save-text

> syntax: (gs:save-text sym-id str-path)
> parameter: sym-id - The id of the `gs:text-pane`.
> parameter: str-path - The full path name of the file to save.
> This function will write text back from a `gs:text-pane` directly by specifying a path name only. Line feed characters (ASCII 10) are used as line terminators. If this behavior is not desired, as is the case with Windows text files, then `gs:get-text` should be used instead. A program can then add CR characters using a newLISP `replace`, i.e. `(replace "\n" text "\r\n")` before saving the text to a file.
> §

> ### gs:scale-tag

> syntax: (gs:scale-tag sym-tag float-x float-y [boolean-repaint])
> parameter: sym-tag - The tag group to scale.
> parameter: float-x - The X scaling factor.
> parameter: float-y - The Y scaling factor.
> parameter: boolean-repaint - An optional flag to indicate if repainting is required (default is `true`).
> `gs:scale` scales the object to draw relative to the `0,0` point of the coordinate system. This means if a object is not at the center it will not only change in size when scaled but also change the distance to the center point of the coordinate system, moving away when scaling up with scale factor bigger `1.0` and moving closer to the center when scaling down using factors smaller than `1.0`.
> This means that objects which will be scaled should be defined in coordinates relative to their center point. Then a `gs:translate-tag` command should be used to place the object to correct place:
> example:

> >      (gs:circle 'C 0 0 50)
> >      (gs:gs:translate-tag 'C 200 100)
> >      ...
> >      (gs:scale-tag 'C 1.1 1.1)

> In the example the circle, although defined for `0,0`, will be displayed at the `200,200` position because of the `gs:translate-tag` statement. When later scaling the circle will get bigger but stay in place. Like all tag operations, multiple `gs:scale-tag` operations are cumulative.
> §

> ### gs:select-list-item

> syntax: (gs:select-list-item sym-id str-item [boolean-flag])
> parameter: sym-id - The name of the list or combo box.
> parameter: str-item - The item to select.
> parameter: boolean-flag - An optional flag only for list boxes to force scrolling to the selected entry.
> On combo boxes the optional boolean-flag has no effect. The selected entry will always appear as the visible text of the combo box. The flag has either the value `true` or `nil`.
> §

> ### gs:select-text

> syntax: (gs:select-text sym-id int-from [int-to])
> parameter: sym-id - The ame of the text component.
> parameter: int-from - Start offset of selection.
> parameter: int-to - Optional end offset of selection.
> If no int-to end offset is given, `gs:select-text` will select to the end of the text.
> §

> ### gs:scroll-pane

> syntax: (gs:scroll-pane sym-id sym-widget [int-width int-height])
> parameter: sym-id - The name of the scroll pane.
> parameter: sym-widget - The component in the scroll pane to be scrolled.
> parameter: int-width - The optional width of the scroll pane.
> parameter: int-height - The optional height of the scroll pane.
> §

> ### gs:set-accelerator

> syntax: (gs:set-accelerator sym-menu-item str-keystroke)
> parameter: sym-menu-item - The name of the menu item for which an accelerator key is set.
> parameter: str-keystroke - A text string identifying the keystroke.
> The following rules are used to create keystroke strings:
> Syntax:

> >      modifiers* (typedID | pressedReleasedID)
> >      modifiers := shift | control | ctrl | meta | alt | button1 | button2 | button3
> >      typedID := typed typedKey
> >      typedKey := string of length 1 giving Unicode character.
> >      pressedReleasedID := (pressed | released) key
> >      key := KeyEvent key code name, i.e. the name following "VK_".

> Examples:

> >      "INSERT"
> >      "control DELETE"
> >      "alt shift X"
> >      "alt shift released X"
> >      "typed a"

> Note that the apple key on MacOS X is the `meta` key. The `alt` on MacOS X is the option key. For letters use uppercase. Keys are added to the menu item display automatically on all platforms.
> §

> ### gs:set-anti-aliasing

> syntax: (gs:set-anti-aliasing boolean-flag)
> parameter: boolean-flag - The anti aliasing setting for the current canvas `true` or `nil`.
> The default setting is `true`.
> §

> ### gs:set-background

> syntax: (gs:set-background sym-id float-red float-green float-blue [float-alpha])
> parameter: sym-id - The name of the component for which to set the color.
> parameter: float-red - The red color component expressed as a number between 0.0 and 1.0.
> parameter: float-green - The green color component expressed as a number between 0.0 and 1.0.
> parameter: float-blue - The blue color component expressed as a number between 0.0 and 1.0.
> parameter: float-alpha - The transparency of the color expressed as a number between 0.0 (fully transparent)and 1.0 (completely opaque).
> syntax: (gs:set-background sym-id list-rgb [float-alpha])
> parameter: sym-id - The name of the component for which to set the color.
> parameter: list-rgb - The rgb color can be given as a list of three numbers.
> parameter: float-alpha - The transparency of the color expressed as a number between 0.0 (fully transparent)and 1.0 (completely opaque).
> Note `set-background` is the same as `set-color`.
> §

> ### gs:set-bevel-border

> syntax: (gs:set-bevel-border sym-id str-type)
> parameter: sym-id - The name of the component.
> parameter: str-type - The type of the bevel `"raised"` or `"lowered"`.
> §

> ### gs:set-border-layout

> syntax: (gs:set-border-layout sym-container [int-hgap int-vgap])
> parameter: sym-container - The name of the container for which border layout is set.
> parameter: int-hgap - The horizontal gap between components in the border layout.
> parameter: int-vgap - The vertical gap between components in the border layout.
> Border layout divides the layout into 5 zones labeled `"north"`, `"west"`, `"center"`, `"east"` and `"south"`. These string constants are used in the `gs:add-to` command when adding components to a border layout.
> In a border layout each component will take the maximum size if components are not sized. If components are sized only some dimensions will be honored. The `"north"` and `"south"` components will stretch to maximum width and assume the height given in a size parameter of the component. The `"east"` and `"west"` components will stretch to the maximum height available assuming their width specified earlier. The `"center"` component will take the left over maximum space.
> §

> ### gs:set-canvas

> syntax: (gs:set-canvas sym-id)
> parameter: sym-id - The id of the canvas to switch to.
> The canvas in sym-id must have been created earlier with a `gs:canvas` statement. All graphics operations which do not take a canvas as argument will automatically refer to this current canvas. If no `gs:set-canvas` is used, the current canvas is assumed to be the last one created.
> §

> ### gs:set-caret

> syntax: (gs:set-caret sym-id int-offset)
> parameter: sym-id - The name of the component for which to set the cursor caret.
> The functions has the same effect as calling `gs:select-text` with the same offset for the dot and mark position.
> §

> ### gs:set-caret-color

> syntax: (gs:set-caret-color sym-id float-red float-green float-blue)
> parameter: sym-id - The name of the component for which to set the color.
> parameter: float-red - The red color component expressed as a number between 0.0 and 1.0.
> parameter: float-green - The green color component expressed as a number between 0.0 and 1.0.
> parameter: float-blue - The blue color component expressed as a number between 0.0 and 1.0.
> syntax: (gs:set-caret-color sym-id list-rgb [float-alpha])
> parameter: sym-id - The name of the component for which to set the color.
> parameter: list-rgb - The rgb color can be given as a list of three numbers.
> §

> ### gs:set-color

> syntax: (gs:set-color sym-id float-red float-green float-blue [float-alpha])
> parameter: sym-id - The name of the component for which to set the color.
> parameter: float-red - The red color component expressed as a number between 0.0 and 1.0.
> parameter: float-green - The green color component expressed as a number between 0.0 and 1.0.
> parameter: float-blue - The blue color component expressed as a number between 0.0 and 1.0.
> parameter: float-alpha - The transparency of the color expressed as a number between 0.0 (fully transparent)and 1.0 (completely opaque).
> syntax: (gs:set-color sym-id list-rgb [float-alpha])
> parameter: sym-id - The name of the component for which to set the color.
> parameter: list-rgb - The rgb color can be given as a list of three numbers.
> parameter: float-alpha - The transparency of the color expressed as a number between 0.0 (fully transparent)and 1.0 (completely opaque).
> Note that `set-color` is the same as `set-background`.
> §

> ### gs:set-cursor

> syntax: (gs:set-cursor sym-id str-shape)
> parameter: sym-id - The name of the frame, dialog or window.
> parameter: str-shape - The string describing the cursor shape.
> The cursor shape can be one of the following:

>       "default"
>       "crosshair"
>       "text"
>       "wait"
>       "sw-resize"
>       "se-resize"
>       "nw-resize"
>       "ne-resize"
>       "n-resize"
>       "s-resize"
>       "w-resize"
>       "e-resize"
>       "hand"
>       "move"

> §

> ### gs:set-echo-char

> syntax: (gs:set-echo-char sym-id [str-covered-text])
> parameter: sym-id - The name of the component for which text is set.
> parameter: str-covered-text - Obscured by the first letter for Password Input field.
> example:

> >      (gs:set-echo-char 'TheTextField "*")
> >      (gs:set-echo-char 'TheTextField)   ; no echo, behave as normal text field

> If no str-covered-text is specyfied or the string in str-covered-text is of 0 length, then the text field behaves as a normal text field.
> §

> ### gs:set-editable

> syntax: (gs:set-editable sym-id boolean-editable)
> parameter: sym-id - The name of the text widget.
> parameter: boolean-editable - The flag `true` or `nil` to indicate if this text widget can be edited.
> §

> ### gs:set-flow-layout

> syntax: (gs:set-flow-layout sym-container [str-alignment [int-hgap int-vgap]])
> parameter: sym-container - The name of the container for which flow layout is set.
> parameter: sym-alignment - The alignment of the flow layout `"left"`, `"center"` or `"right"`.
> parameter: int-hgap - The horizontal gap between components in the flow layout.
> parameter: int-vgap - The vertical gap between components in the flow layout.
> The flow layout lets components appear in their natural or preferred size. The preferred size of a component is set using the function `gs:set-size`. Button-type widgets and combo boxes will take as much space as necessary to show the included text.
> §

> ### gs:set-font

> syntax: (gs:set-font sym-id str-family int-size str-type)
> parameter: sym-id - The name of the component for which to set the text font.
> parameter: str-familiy - The family of the font, e.g.: `"Monospaced"`, `"Serif"`, `"Sans Serif"`.
> parameter: int-size - The font size in points.
> parameter: str-type - The type of the font, one or more of `"plain"`, `"bold"`, `"italic"`.
> More than the above noted families are available depending on the platform.
> §

> ### gs:set-foreground

> syntax: (gs:set-foreground sym-id float-red float-green float-blue [float-alpha])
> parameter: sym-id - The name of the component for which to set the color.
> parameter: float-red - The red color component expressed as a number between 0.0 and 1.0.
> parameter: float-green - The green color component expressed as a number between 0.0 and 1.0.
> parameter: float-blue - The blue color component expressed as a number between 0.0 and 1.0.
> parameter: float-alpha - The transparency of the color expressed as a number between 0.0 (fully transparent)and 1.0 (completely opaque).
> syntax: (gs:set-foreground sym-id list-rgb [float-alpha])
> parameter: sym-id - The name of the component for which to set the color.
> parameter: list-rgb - The rgb color can be given as a list of three numbers.
> parameter: float-alpha - The transparency of the color expressed as a number between 0.0 (fully transparent)and 1.0 (completely opaque).
> The foreground color is the color of the text in a component.
> §

> ### gs:set-grid-layout

> syntax: (gs:set-grid-layout sym-container int-rows int-columns [int-hgap int-vgap])
> parameter: sym-container - The name of the container for which grid layout is set.
> parameter: int-rows - The number of rows in the layout grid.
> parameter: int-columns - The number of columns in the layout grid.
> parameter: int-hgap - The horizontal gap between components in the grid layout.
> parameter: int-vgap - The vertical gap between components in the grid layout.
> In a grid layout each component will assume the maximum size the grid cell allows regardless of sizes preset using `gs:set-size` Because of this grid layout cells are frequently filled with panels using `gs:panel` which have flow layout by default and allow deliberate sizing of components using `gs:set-size`.
> §

> ### gs:set-icon

> syntax: (gs:set-icon sym-id str-icon-path [int-index])
> parameter: sym-id - The name of a button or label or menu-item for which to set an icon.
> parameter: str-icon-path - The file path of the icon to be set.
> parameter: int-index - If sym-id is a tabbed pane int-index is the index of the tab.
> §

> ### gs:set-look-and-feel

> syntax: (gs:set-look-and-feel str-look)
> parameter: str-look - The class description string for the look and feel of the application.
> The following strings can be tried in str-look, but not all will work on a specific platform. On the Mac the default look-and-feel is built-in to the JVM as the default style. The `"MacLookAndFeel"` is not available as an explicit flavor here, but may be on other platforms.

>         "com.sun.java.swing.plaf.motif.MotifLookAndFeel"

>         "javax.swing.plaf.metal.MetalLookAndFeel"

>         "com.sun.java.swing.plaf.windows.WindowsLookAndFeel"

>         "javax.swing.plaf.mac.MacLookAndFeel"

>         "com.sun.java.swing.plaf.gtk.GTKLookAndFeel"

> §

> ### gs:set-paint

> syntax: (gs:set-paint list-rgb)
> parameter: list-rgb - The current paint used for outlines, text and fill color.
> §

> ### gs:set-pressed-icon

> syntax: (gs:set-pressed-icon sym-id str-icon-path)
> parameter: sym-id - The name of the button, image button or toggle button.
> parameter: str-icon-path - The file path of the icon or image to be set to the button in pressed state.
> By default a small grey dot is shown on image buttons when in a pressed state.
> §

> ### gs:set-resizable

> syntax: (gs:set-resizable sym-frame boolean-resizable)
> parameter: sym-frame - The name of the frame window.
> parameter: bbolean-resizable - The flag `true` or `nil` to indicate if a frame can be resized by the user.
> §

> ### gs:set-rotation

> syntax: (gs:set-rotation float-angle)
> parameter: float-angle - The angle in degrees (0 - 360) of the canvas rotation.
> Unlike the `gs:rotate-tag` operation which is cumulative, `gs:set-rotation` will set an absolute rotation value each time it is called.
> §

> ### gs:set-scale

> syntax: (gs:set-scale float-x float-y)
> parameter: float-x - The X-scale value of the current canvas.
> parameter: float-y - The Y-scale value of the current canvas.
> Unlike the `gs:scale-tag` operation which is cumulative, `gs:set-scale` will set an absolute scale value each time it is called.
> §

> ### gs:set-selected

> syntax: (gs:set-selected sym-id boolean-selected [sym-id boolean-selected])
> parameter: sym-id - The name of the toggle or radio button or check box or menu item.
> parameter: boolean-selected - A flag of `true` or `nil` to indicated the selection state.
> More then one toggle control may be set selected or unselected.
> §

> ### gs:set-selection-color

> syntax: (gs:set-selection-color sym-id float-red float-green float-blue [float-alpha])
> parameter: sym-id - The name of the component for which to set the text selection color.
> parameter: float-red - The red color component expressed as a number between 0.0 and 1.0.
> parameter: float-green - The green color component expressed as a number between 0.0 and 1.0.
> parameter: float-blue - The blue color component expressed as a number between 0.0 and 1.0.
> parameter: float-alpha - The transparency of the color expressed as a number between 0.0 (fully transparent)and 1.0 (completely opaque).
> syntax: (gs:set-selection-color sym-id list-rgb [float-alpha])
> parameter: sym-id - The name of the component for which to set the text selection color.
> parameter: list-rgb - The rgb color can be given as a list of three numbers.
> parameter: float-alpha - The transparency of the color expressed as a number between 0.0 (fully transparent)and 1.0 (completely opaque).
> Note `set-background` is the same as `set-color`.
> §

> ### gs:set-size

> syntax: (gs:set-size sym-id int-width int-height)
> parameter: sym-id - The name of the component of which a preferred size is set.
> parameter: int-width - The preferred width of the component.
> parameter: int-height - The preferred height of the component.
> Note that not all layouts allow setting the size of a component. The grid and border layouts will size the component to its maximum possible in the layout.
> §

> ### gs:set-stroke

> syntax: (gs:set-stroke float-width [str-cap [str-join [float-miterlimit]]])
> parameter: float-width - The width for drawing lines and outlines in shapes.
> parameter: str-cap - One of optional `"butt"` (default), `"round"` or `"sqare"`.
> parameter: str-join - One of optional `"miter"` (default), `"bevel"` or `"round"`
> For a float-width 0f 0.0 the thinnest possible line width be chosen. Join is the decoration applied at the intersection of two path segments and at the intersection of the endpoints. Cap is the decoration applied to the ends of unclosed subpaths and dash segments. The float-miterlimit should be greater or equal 1.0.
> §

> ### gs:set-syntax

> syntax: (gs:set-syntax sym-id str-type)
> parameter: sym-id - The name of the text pane for syntax coloring is enabled or disabled.
> parameter: str-type - A string `"lsp"`, `"c"`, `"cpp"`, `"java"` or `"php"` to indicate the
> syntax desired, or `nil` to switch off syntax highlighting.
> Colors for syntax highlighting are preselected for a white background, but can be changed using the following functions: `gs:set-background`, `gs:set-foreground`, `gs:set-caret`, `gs:set-selection-color` and `gs:set-syntax-colors`.
> §

> ### gs:set-syntax-colors

> syntax: (gs:set-syntax-colors list-rgb-comment list-rgb-keyword list-rgb-string list-rgb-number list-rgb-quoted list-rgb-parentheses)
> parameter: list-rgb-comment - The color for comments.
> parameter: list-rgb-keyword - The color for reserved keywords.
> parameter: list-rgb-string - The color for strings.
> parameter: list-rgb-number - The color for numbers.
> parameter: list-rgb-quoted - The color for the quote and quoted symbols.
> parameter: list-rgb-parentheses - The color for parenthesis.
> Syntax highlighting colors are given as lists of red, green and blue values between 0.0 and 1.0. Depending on the syntax colors and the foreground and background colors set for the text pane, the caret color and color for selected text should also be changed. Only text widgets created using `gs:text-pane` feature syntax highlighting.
> §

> ### gs:set-tab-size

> syntax: (gs:set-tab-size sym-id int-size)
> parameter: sym-id - The name of the text area component.
> parameter: int-size - The tabulator size.
> Note that `gs:set-tab-size` will only work with fixed spaced fonts.
> §

> ### gs:set-text

> syntax: (gs:set-text sym-id str-text [int-index])
> parameter: sym-id - The name of the component for which text is set.
> parameter: str-text - The text to be set in the component.
> parameter: int-index - The index for a tab if the sym-id is a tabbed pane.
> §

> ### gs:set-titled-border

> syntax: (gs:set-titled-border sym-component str-title)
> parameter: sym-component - The name of the component.
> parameter: str-title - The text in the titled border around the component.
> The component is usually a `panel`.
> §

> ### gs:set-tool-tip

> syntax: (gs:set-tool-tip sym-id str-text)
> parameter: sym-id - The name of the widget for which to supply a tool tip.
> parameter: str-text - The text of the tool tip.
> The tool tip text is shown when leaving the mouse over the widget for certain amount of time.
> §

> ### gs:set-trace

> syntax: (gs:set-trace boolean-flag)
> parameter: boolean-flag - The flag `true` or `nil`.
> §

> ### gs:set-translation

> syntax: (gs:set-translation int-x int-y)
> parameter: int-x - The X-translation value of the current canvas.
> parameter: int-y - The Y-translation value of the current canvas.
> Translates the current origin of the current canvas to the point in int-x int-y. Unlike the `gs:translate-tag` operation which is cumulative, `gs:set-translation` will set an absolute translation value each time it is called.
> §

> ### gs:set-utf8

> syntax: (gs:set-utf8 boolean-flag)
> parameter: boolean - The flag `true` or `nil` to indicate if in UTF-8 mode.
> When set in UTF-8 mode, guiserver will convert files to UTF-8 encoding when loading and saving files. On Mac OS X UTF-8 mode is by default enabled. On startup guiserver.lsp will detect if newLISP is UTF-8 enabled and switch the mode in Guiserver accordingly using `gs:set-utf8`.
> §

> ### gs:set-value

> syntax: (gs:set-value sym-id int-value)
> parameter: sym-id - The name of a slider or progress bar for which to set the value.
> parameter: int-value - The integer value of the name to be set.
> The value should not be bigger or smaller than the minimum or maximum values set when creating the slider or progress bar, otherwise the setting will default to either the minimum or maximum preset value.
> §

> ### gs:set-visible

> syntax: (gs:set-visible sym-id boolean-visible)
> parameter: sym-id - The component which is hidden or made visible.
> parameter: boolean-visible - A flag indicating if the component is visible `"true"`, `"nil"`.
> Except for frames and dialog windows, components are visible by default. Normally frames and dialogs are not set visible before all other components are placed inside.
> §

> ### gs:shear-tag

> syntax: (gs:shear-tag sym-tag int-x int-y [boolean-repaint])
> parameter: sym-tag - The tag group to shear.
> parameter: float-x - The X shearing factor.
> parameter: float-y - The Y shearing factor.
> parameter: boolean-repaint - An optional flag to indicate if repainting is required (default is `true`).
> §

> ### gs:show-popup

> syntax: (gs:show-popup sym-tag sym-host int-x int-y)
> parameter: sym-tag - The id of the popup menu.
> parameter: sym-host - The host container where to pop up the menu.
> parameter: int-x - The X coordinate of the menu popup position.
> parameter: int-y - The Y coordinate of the menu popup position.
> §

> ### gs:show-tag

> syntax: (gs:show-tag sym-tag [boolean-repaint])
> parameter: sym-tag - The tag of the group to show.
> parameter: boolean-repaint - An optional flag to indicate if repainting is required (default is `true`).
> §

> ### gs:slider

> syntax: (gs:slider sym-id sym-action str-orientation int-min int-max int-initial-value)
> parameter: sym-id - The name of the slider.
> parameter: sym-action - The name of the event handler.
> parameter: str-orientation - The orientation of the slider `"horizontal"` or `"vertical"`
> parameter: int-min - The minimum value of the slider.
> parameter: int-max - The maximum value of the slider.
> parameter: int-initial-value - The initial value of the slider.
> §

> ### gs:split-pane

> syntax: (gs:split-pane sym-id str-orientation [float-weight [float-location [int-divider-size]]])
> parameter: sym-id - The name of the split-pane.
> parameter: str-orientation - The orientation `"horizontal"` or `"vertical"`.
> parameter: float-weight - The optional weight distribution between `0.0` and `1.0` when re-sizing the window. The default is `0.0`.
> parameter: float-location - The optional initial divider location between `0.0` and `1.0`.
> parameter: int-divider-size - The optional size of the draggable divider in pixels.
> §

> ### gs:stop-sequence

> syntax: (gs:stop-sequence)
> Stops playing tracks, as started with `gs:play-sequence`.
> §

> ### gs:tabbed-pane

> syntax: (gs:tabbed-pane sym-id sym-action str-orientation [sym-tab sym-tab-title ...])
> parameter: sym-id - The name of the tabbed pane.
> parameter: str-orientation - The position of the tabs; either `"top"` (default), `"bottom"`,`"left"` or `"right"`.
> parameter: sym-tab - The id symbol name of a tab
> parameter: str-title - The title of the tab.
> §

> ### gs:table

> syntax: (gs:table sym-id sym-action [str-column-header-name ...])
> parameter: sym-id - The name of the table.
> parameter: sym-action - The handler function symbol when cell selected.
> parameter: str-column-header-name - the optional column header name.
> Creates a table with str-column-header-name specified column and empty row. For empty strings specified as column headers, the column number will be used. If there are no columns, an empty table (0 x 0) is created.
> §

> ### gs:table-add-column

> syntax: (gs:table-add-column sym-id str-column-header-name ...)
> parameter: sym-id - The name of the table.
> parameter: str-column-header-name - Add column header name(s).
> When a column header name is empty, the name is set to the column number. The table size grows.
> §

> ### gs:table-add-row

> syntax: (gs:table-add-row sym-id [str-columns ... ])
> syntax: (gs:table-add-row sym-id ([str-columns ...))
> parameter: sym-id - The name of the table.
> parameter: str-columns - Add a row with contents in str-columns
> Add row with each column value. If necessary a scrollbar will appear. If no contents is defined in str-columns, or if contents for less columns is defined than available, column contents is left empty. Mutliple multiple column content can be specified as either a list of strings or addtional parameters of `gs:table-add-row`.
> §

> ### gs:table-get

> syntax: (gs:table-get sym-id)

> return: table cells. stored in `gs:table-full`.

> Get full table as a list of row lists.

>      ( ("column0" "column1" ... ) ; 1'st row
>        ("column0" "column1" ... ) ; 2'nd row
>        ...
>        ... )

> The entire table contents is stored as a list of row lists in the return value of `gs:table-get`, and is also stored in the variable `gs:table-full`.
> §

> ### gs:table-get-cell

> syntax: (gs:table-get-cell sym-id int-row int-column)
> parameter: sym-id - The name of the table.
> parameter: int-row - The row of the cell.
> parameter: int-column - The column of the cell.

> return: cell value. stored in gs:table-cell.

> Get the cell contents as a string at sepcifed int-row and int-column.
> §

> ### gs:table-get-size

> syntax: (gs:table-get-size sym-id)
> parameter: sym-id - The name of the table.

> return: table size list (row-size, column-size)

> Get table size, stored in `gs:table-size`. Note, that adding columns or row will not automatically update the `gs:table-size` variable. Use `gs:table-get-size` to update this variable.
> §

> ### gs:table-set-cell

> syntax: (gs:table-set-cell sym-id int-row int-column str-value)
> parameter: sym-id - The name of the table.
> parameter: int-row - The row of the cell set.
> parameter: int-column - The column of the cell set.
> parameter: str-value - The cell value.

> return: The previous contents of the cell; also stored in `gs:table-cell`.

> Sets a new table cell contents and returns the old cell contents. Row and column numbering starts with '0' (zero). The cell contents is passed as a string.
> §

> ### gs:table-set-column

> syntax: (gs:table-set-column sym-id int-column-number int-width [str-justification])
> parameter: sym-id - The name of the table.
> parameter: int-column-number - The column number of align.
> parameter: int-width - The column width.
> parameter: str-justification - The column align property, "left", "center", "right".
> A table column property is changed, adjusting the column width and alignment of cell contents. The str-justification parameter is optional and alignment is "left" by default.
> §

> ### gs:table-set-row-number

> syntax: (gs:table-set-row-number sym-id bool-row-number)
> parameter: sym-id - The name of the table.
> parameter: bool-row-number - `true` if rowns should carry a row number; default `nil`.
> Show or hide the row number headers. The default is hiding row numbers.
> §

> ### gs:text-area

> syntax: (gs:text-area sym-id sym-action int-width int-height)
> parameter: symid - The name of the text area.
> parameter: sym-action - The name of the event handler.
> parameter: int-width - The optional width of the text area..
> parameter: int-height - The optional height of the text area.
> example:

> >      (gs:text-area 'TheText 'textarea-event 10 8)

> >      (define (textarea-event id code dot mark) ...)

> `gs:text-area` transmits the following parameters in its event:

>      id   - name of the widget
>      code - key code equals ASCII code. Only for text keys
>      dot  - position of text caret in the text
>      mark - extended (selection) position of caret

> §

> ### gs:text-field

> syntax: (gs:text-field sym-id sym-action int-columns [str-covered-text])
> parameter: sym-id - The name of the text field.
> parameter: sym-action - The name of the event handler.
> parameter: int-columns - The number of columns in the text field.
> parameter: str-covered-text - Obscured by the first letter for Password Input field.
> example:

> >      (gs:text-field 'TheTextField 'textfield-event)
> >      (gs:text-field 'PasswordTextField 'textfield-event "*")

> The `textfield-event` is fired when the enter key is pressed in the text field. As an alternative the cover character for passwords can be set with `gs:set-echo-char`.
> §

> ### gs:text-pane

> syntax: (gs:text-pane sym-id sym-action str-style [int-width int-height])
> parameter: sym-id - The name of the text pane.
> parameter: sym-action - The key action handler for the html pane.
> parameter: sym-style - The content type of the text pane.
> parameter: int-width - The optional width of the pane.
> parameter: int-height - The optional height of the pane.
> The `gs:text-pane` is used similar to 'gs:text-area. The following styles are supported in sym-style:

>         "text/plain"
>         "text/html"

> The `gs:text-pane` widget will automatically display scroll bars when text does not fit in the visible space of the pane. When entering parentheses they are automatically matched with their opening or closing counterparts, if they exist. If this is undesired behavior, the simpler `gs:text-area` control should be used instead.
> On each change of the caret or selection in the text pane an event is fired containing several parameters about the caret and selection positions, the last character typed, and the modifier keys used. See the the file `newlisp-edit.lsp` for a complex application using all features available in this widget.
> To make hyperlinks in `HTML` formatted text clickable, editing must be disabled using the `gs:set-editable` function. The functions `gs:set-font` and `gs:append-text` will work only on the `text/plain` content style.
> example:

> >      (gs:text-pane 'TheTextPane 'textpane-event "text/plain")

> >      (define (textpane-event id code mods dot mark len undo redo) ...)

> `gs:text-pane` transmits the following parameters in its event:

>      id   - name of the widget
>      code - key code equals ASCII code. Only for text keys
>      mods - keys pressed together with the previous, like shift, ctrl etc.
>      dot  - position of the text caret in the text
>      mark - extended (selection) position of the caret
>      len  - length of the text in the textarea
>      undo - undo enabled/disabled
>      redo - redo enabled/disabled

> §

> ### gs:toggle-button

> syntax: (gs:toggle-button sym-id sym-action str-text [bool-selected])
> parameter: sym-id - The name of the toggle button.
> parameter: sym-action - The name of the event handler.
> parameter: str-text - The optional text of the toggle button.
> parameter: bool-selected - An optional flag `true` or `nil` (default) indicating the initial state of the toggle button.
> §

> ### gs:tool-bar

> syntax: (gs:tool-bar sym-frame [bool-floatable int-hgap int-vgap])
> parameter: sym-frame - The name of the frame hosting the toolbar.
> parameter: bool-floatable - The optional flag `true` or `nil` to indicate if the toolbar can be detached.
> parameter: int-hgap - The horizontal gap between components on the toolbar.
> parameter: int-vgap - The vertical gap between the components on the toolbar.
> §

> ### gs:translate-tag

> syntax: (gs:translate-tag sym-tag int-x int-y [boolean-repaint])
> parameter: sym-tag - The name tag of the group to translate.
> parameter: int-x - The X-coordinate translation value.
> parameter: int-y - The Y-coordinate translation value.
> parameter: boolean-repaint - An optional flag to indicate if repainting is required (default is `true`).
> Moves the origin of the coordinate system of all objects tagged with sym-tag. Like all tag operations multiple `gs:translate-tag` operations are cumulative.
> §

> ### gs:undo-text

> syntax: (gs:undo-text sym-id)
> parameter: sym-id - The id of the `gs:text-pane` where to perform an undo operation.
> §

> ### gs:undo-enable

> syntax: (gs:undo-enable sym-id boolean-enabled)
> parameter: sym-id - The id of the `gs:text-pane` for which to enabe/disable undo.
> parameter: boolean-enabled - `true` or `nil` to enable or disable undo.
> §

> ### gs:update

> syntax: (gs:update)
> Forces a repaint of the current canvas, e.g. after changing the scale or translation of a visible canvas. This function is rarely used, as most screen updates are performed automatically. All tag operations can carry an additional parameter to force update after they have been draw.
> §

> ### gs:window

> syntax: (gs:window sym-id int-x int-y int-width int-height)
> parameter: sym-id - The name of the invisible window.
> parameter: int-x - The x-coordinate of the screen position.
> parameter: int-y - The y-coordinate of the screen position.
> parameter: int-width - The width of the window.
> parameter: int-height - The height of the window.
> Creates a borderless window. Note that a borderless window may treat some hosted components differently from normal frames and dialogs.
> §

> ### gs:window-closed

> syntax: (gs:window-closed sym-id sym-action)
> parameter: sym-id - The name of the frame or dialog.
> parameter: sym-action - The action to perform when the frame or dialog closes.
> A window or dialog window can be closed using the system close button in one of the corners of the window. In this case it is useful to specify a handler function which is called upon closing.
> §

> ### gs:window-moved

> syntax: (gs:window-moved sym-id sym-action)
> parameter: sym-id - The name of the frame or dialog.
> parameter: sym-action - The action to perform when the frame or dialog moves.
> The event will carry the sym-id of the window or dialog and current `X` and `Y` coordinates on the screen.
> §

> ### gs:window-resized

> syntax: (gs:window-resized sym-id sym-action)
> parameter: sym-id - The name of the frame or dialog.
> parameter: sym-action - The action to perform when the frame or dialog is resized.
> The event will carry the sym-id of the window or dialog and current width and height.
> - ∂ -
> generated with newLISP and newLISPdoc