guiserver/guiserver.lsp.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <META http-equiv="Content-Type" content="text/html; charset=utf-8">
   5 <title>guiserver.lsp</title>
   6
   7 <style type="text/css" media="screen">
   8 <!--
   9 span.arw {
  10         color:#666666;
  11         font-size: 100%;
  12         }
  13
  14 body, p {
  15         font-family: Georgia, Times New Roman, Times, serif;
  16         line-height: 115%;
  17         }
  18
  19 h1, h2, h3, h4 {
  20         font-family: Georgia, Times New Roman, Times, serif;
  21         font-size: 110%;
  22         }
  23
  24 pre {
  25         font-family: Andale Mono, "Bitstream Vera Sans Mono", Monaco, "Courier New";
  26         font-size: 100%;
  27         }
  28
  29 tt {
  30         font-family: Andale Mono, "Bitstream Vera Sans Mono", Monaco, "Courier New";
  31         font-size: 100%;
  32         }
  33 -->
  34 </style>
  35 </head>
  36
  37 <body style="margin: 20px;" text="#333333" bgcolor="#FFFFFF"
  38                         link="#376590" vlink="#551A8B" alink="#ffAA28">
  39 <blockquote>
  40 <center><h1>guiserver.lsp</h1></center>
  41 <p><a href="index.html">Module index</a></p><br/><br/><br/><h2>Module:&nbsp;guiserver.lsp</h2><p>Functions for programming GUIs and 2D graphics.</p>
  42 <b>Version: </b>1.14<br/>
  43 <b>Author: </b>Lutz Mueller, December 2007<br/>
  44 <p></p>
  45  This module has been tested on MacOS X 10.8 and Windows XP, both with the
  46  Standard SUN Java RE v.1.5 (runtime environment) which came pre-installed on
  47  those platforms.
  48  <br><br>
  49  <h2>What is newLISP-GS</h2>
  50  <tt>guiserver.lsp</tt> is a module for interfacing to <tt>guiserver.jar</tt>
  51  a Java server application for generating GUIs (graphical user interfaces)
  52  and 2D graphics for newLISP applications. The <tt>guiserver.lsp</tt> module
  53  implements a newLISP API much smaller and more abstract than the APIs of the
  54  Java Swing libraries which it interfaces with. Because of this, GUI applications
  55  can be built much faster than when using the original Java APIs.
  56  <br><br>
  57  <h2>Requirements</h2>
  58  At the beginning of the program file, include a <tt>load</tt> statement for the module:
  59  <pre>
  60  (load "/usr/share/newlisp/guiserver.lsp")
  61  </pre>
  62  or on MS Windows:
  63  <pre>
  64  (load "c:/Program Files/newlisp/guiserver.lsp")
  65  </pre>
  66 <p></p>
  67  <tt>guiserver.lsp</tt> expects the server <tt>guiserver.jar</tt> to be
  68  installed in <tt>/usr/share/newlisp</tt> on MacOS X and Unix OSs, and
  69  in <tt>C:\Program Files\newlisp</tt> on MS Windows systems. On Win32 the
  70  standard environment variable <tt>PROGRAMFILES</tt> is used to find the exact location
  71  of non-English installations of Windows.. Both, the <tt>guiserver.lsp</tt> and
  72  <tt>guiserver.jar</tt> are installed by default when installing newLISP with one of
  73  the binary installers available.
  74  <br><br>
  75  <h3>Architecture of a newLISP GUI application</h3>
  76  A GUI application in newLISP is composed of four parts:
  77 <p></p>
  78  <blockquote>
  79  <em>initialization</em> - this means starting the newLISP-GS <tt>guiserver.jar</tt> and initializing
  80  communications with it. Only one function call is required to do this.
  81 <p></p>
  82  <em>building widgets</em> - in this step windows, buttons, text fields etc., and
  83  all visual aspects of the GUI are described. newLISP newLISP-GS offers a wide range
  84  of different control widgets.
  85 <p></p>
  86  <em>defining event actions</em> - in this step all the functions are defined to
  87  react to events coming from the GUI as a consequence of button pushes, keystrokes,
  88  mouse-movements etc.. These event actions send many commands back to the GUI
  89  to change information for the user, popup dialogs etc..
  90 <p></p>
  91  <em>listening for events</em> - the newLISP program sits in a loop waiting for
  92  events and dispatching them to the defined event actions. Only one function call
  93  is required for this step.
  94  </blockquote>
  95  <br><br>
  96  <h2>Example</h2>
  97  The following example application shows all the essential elements of a newLISP GUI
  98  application:
  99  <blockquote><pre>
 100  #!/usr/bin/newlisp
 101  ; button-demo.lsp - demonstrate the button control
 102 <p></p>
 103  ;;;; initialization
 104  (load (append (env "NEWLISPDIR") "/guiserver.lsp"))
 105 <p></p>
 106  (gs:init)
 107 <p></p>
 108  ;;;; describe the GUI
 109  (gs:frame 'ButtonDemo 100 100 400 300 "Button demo")
 110  (gs:set-resizable 'ButtonDemo nil)
 111  (gs:panel 'ColorPanel 360 200)
 112  (gs:set-color 'ColorPanel (random) (random) (random))
 113  (gs:button 'aButton 'abutton-action "color")
 114  (gs:set-flow-layout 'ButtonDemo "center" 2 15)
 115  (gs:add-to 'ButtonDemo 'ColorPanel 'aButton)
 116  (gs:set-visible 'ButtonDemo true)
 117 <p></p>
 118  ;;;; define actions
 119  (define (abutton-action id)
 120      (gs:set-color 'ColorPanel (random) (random) (random)))
 121 <p></p>
 122  ;;;; listen for incoming action requests and dispatch
 123  (gs:listen)
 124 <p></p>
 125  ;; eof
 126  </pre></blockquote>
 127  <br>
 128  <h3>Application start</h3>
 129  <pre>
 130      ./button-demo       ; on MacOS X and Unix
 131 <p></p>
 132      newlisp button-demo ; on Win32
 133  </pre>
 134  By default guiserver.jar uses the ports 47011 and 47012, but this setting can be overwritten
 135  either by supplying a port number parameter to the <tt>gs:init</tt> function or by overwriting the
 136  port number from the command-line. newLISP-GS will then use the port number supplied and the number
 137  following it:
 138  <pre>
 139      ./button-demo 10001       ; on MacOS X and Unix
 140 <p></p>
 141      newlisp button-demo 10001 ; on Win32
 142  </pre>
 143  newLISP-GS <tt>guiserver.jsr</tt> will now use the ports <tt>10001</tt> and <tt>10002</tt>.
 144  Ports under <tt>1024</tt> should not be used, as many of them are already in use by other
 145  OS services and need administrator privileges to use them.
 146 <p></p>
 147  A second method to start a newLISP-GS application starts the <tt>guiserver.jar</tt> first, which then
 148  starts the newLISP application:
 149  <pre>
 150      Java -jar /usr/share/newlisp/guiserver.jar 47011 /usr/home/aUser/MyApplication.lsp
 151  </pre>
 152  A different port number can be used. Port numbers below 1024 need administrator
 153  permissions. Optionally a splash screen can be specified as the last parameter:
 154  <pre>
 155      Java -jar /usr/share/newlisp/guiserver.jar 47011 /home/apps/myapp.lsp /local/newLISP128.png
 156  </pre>
 157  The example specifies an image inside <tt>guiserver.jar</tt>. Any other image path on the local file system
 158  can be used.
 159 <p></p>
 160  On Win32 similar methods can be used replacing the appropriate file paths, but on Win32 Java jar files
 161  can also be treated as executables and executed directly without calling Java explicitly. By default
 162  <tt>guiserver.jar</tt> and <tt>guiserver.lsp</tt> are  installed in <tt>c:\Program Files\newlisp\</tt> or any other
 163  directory configured on a Win32 platform using the <tt>PROGRAMFILES</tt> environment variable:
 164  <pre>
 165     "c:\Program Files\newlisp\guiserver.jar" 47011 c:\myprogs\MyApplication.lsp
 166  </pre>
 167  Quotes are necessary when spaces are present in the argument string. The example also assumes that
 168  <tt>newlisp.exe</tt> is in the path for executables.
 169 <p></p>
 170  <br><br>
 171  <h2>Debugging</h2>
 172  <b>Tracing commands to newLISP-GS</b><br><br>
 173  For debugging purpose put the following directive at the beginning of your application
 174  or at the place from where to start tracing.
 175  <pre>
 176          (gs:set-trace true)
 177  </pre>
 178  Then start the application from a terminal or command shell window. Now newLISP-GS
 179  will output startup, version and connection messages and a trace for each <tt>gs:xxs</tt> directive
 180  as it is received by the newLISP-GS dispatcher:
 181 <p></p>
 182  <blockquote><pre>
 183  newLISP-GS v.0.94
 184  listening on 47011
 185  accepted from 0.0.0.0
 186  connecting to 0.0.0.0 47012
 187  retrying to connect
 188  connected
 189  -> frame MAIN:ButtonDemo 100 100 400 300 QnV0dG9uIGRlbW8= nil
 190  -> set-resizable MAIN:ButtonDemo nil
 191  -> panel MAIN:ColorPanel 360 200
 192  -> set-color MAIN:ColorPanel 0 1 0 0.2
 193  -> button MAIN:aButton MAIN:abutton-action Y29sb3I=
 194  -> set-flow-layout MAIN:ButtonDemo center 2 15
 195  -> add-to MAIN:ButtonDemo MAIN:ColorPanel MAIN:aButton
 196  -> set-visible MAIN:ButtonDemo true
 197  -> set-color MAIN:ColorPanel 0.8401877172 0.3943829268 0.7830992238
 198  server shut down
 199  </blockquote></pre>
 200 <p></p>
 201  Text strings for button names, icon paths and other texts are encode in
 202  Base64 strings as the first trace line for MAIN:ButtonDemo shows. To switch
 203  off tracing mode use:
 204  <pre>
 205         (gs:set-trace nil)
 206  </pre>
 207  Even if trace mode is switched off, wrong or missing parameters are still messaged
 208  by newLISP-GS in a small message box. After such an error the application and guiserver
 209  will exit. Unknown commands will be ignored. Functions which are not applicable to
 210  certain widgets will also pop up an error message box. In certain situations a
 211  function will have no effect, e.g. <tt>gs:set-size</tt> or <tt>gs:set-color</tt> sometimes do not
 212  have an effect, depending on how a widget is configured or depending on the layout
 213  which hosts the widget. Sometimes the platform look-and-feel overwrites colors.
 214  <br><br>
 215 <p></p>
 216  <b>Event handlers</b><br><br>
 217  For most widgets, event handlers must be defined. Sometimes an event handler is
 218  not required. In this case specify <tt>'gs:no-action</tt> as the event handler
 219  symbol. When developing programs it is useful to watch the event handler first
 220  before coding for it. This can be done easily by printing out event parameters:
 221 <p></p>
 222  <blockquote><pre>
 223  (gs:button 'aButton 'abutton-handler "press")
 224 <p></p>
 225  (define (abutton-handler id)
 226      (println id))
 227  </pre></blockquote>
 228 <p></p>
 229  Sometimes the same event handler function is attached to several widgets' keyboard
 230  or mouse events. Some of these events receive a greater number of parameters. There
 231  are two easy ways to discover the nature of an event:
 232 <p></p>
 233  <blockquote><pre>
 234  (define (the-handler)
 235      (doargs (p)
 236          (println "->" p)))
 237  </pre></blockquote>
 238 <p></p>
 239  The other method looks at the source of the event as it was transmitted by the newLISP-GS.
 240  This is useful to recognize the data types used in the event:
 241 <p></p>
 242  <blockquote><pre>
 243  (define (the-handler)
 244      (println gs:event))
 245  </pre></blockquote>
 246 <p></p>
 247  All text from text fields are received as base64-encoded strings. E.g. the text:
 248  <tt>"Hello World"</tt> would be received as: <tt>"SGVsbG8gV29ybGQ="</tt>:
 249 <p></p>
 250  <blockquote><pre>
 251  (gs:text-field 'TextField 'textfield-handler)
 252 <p></p>
 253  (define (textfield-handler id text)
 254      (printnl id ": " (base64-dec text)))
 255  </pre></blockquote>
 256 <p></p>
 257  When the text "Hello World" is entered in the text field, the following output
 258  would be generated:
 259 <p></p>
 260  <blockquote><pre>
 261  TextField: "Hello World"
 262  </pre></blockquote>
 263 <p></p>
 264  In case the ESC key is pressed in the text field, the event handler would
 265  report <tt>nil</tt> for the text field. A handler should therefore always check text
 266  for string contents before trying to apply the <tt>base64-dec</tt> function on it.
 267  <br><br>
 268 <p></p>
 269  <h3>Coding considerations</h3>
 270  <b>mapping or applying <tt>gs:xxx</tt> functions</b><br><br>
 271  Like any newLISP functions, <tt>gs:xxx</tt> functions can be mapped or applied to lists of
 272  parameters using the newLISP <tt>map</tt> and <tt>apply</tt> functions. When doing this, make sure to
 273  map or apply the quoted <tt>'gs:xxx symbol</tt>, so the <tt>gs:xx</tt> functions
 274  get executed under the <tt>gs</tt> context, prefixing symbols in parameter lists
 275  correctly with the context prefix of their origin.
 276 <p></p>
 277  <blockquote><pre>
 278     (map 'gs:panel '(first second third fourth)) ; note quoted gs: function
 279  </blockquote></pre>
 280 <p></p>
 281  <br>
 282  <h2>Some shortcuts when writing <tt>gs:xxx</tt> functions</h2>
 283  Due to the nature of transfer between newLISP and the guiserver as text, the following
 284  convenient shortcuts can be taken when writing functions:
 285 <p></p>
 286  <blockquote>
 287  <ul>
 288  <li>Symbol ids of components can be expressed as strings.</li>
 289  <li>Number values can be expressed as strings.</li>
 290  <li>Numbers can be expressed as floats or integers.</li>
 291  <li>String constants for type and orientation constants can be given as symbols.</li>
 292  </ul>
 293  </blockquote>
 294 <p></p>
 295  Here are some examples:
 296  <pre>
 297      (gs:panel 'ColorPanel 360 200)
 298      ; is the same as
 299      (gs:panel "ColorPanel" 360 200)
 300      ; is the same as
 301      (gs:panel "ColorPanel" "360" "200")
 302      ; is the same as
 303      (gs:panel "ColorPanel" 360.0 "200.00")
 304 <p></p>
 305      (gs:set-flow-layout 'ButtonDemo "center" 2 15)
 306      ; is the same as
 307      (gs:set-flow-layout 'ButtonDemo 'center 2 15)
 308  </pre>
 309  Although the first form is preferred for clarity and readability, in some cases coding
 310  may be more efficient using the other forms.
 311 <p></p>
 312  Except for the symbols used for action handlers, all symbols are used only by their
 313  face (name) value. This means that reserved symbols of the newLISP programming
 314  language can be used freely in symbol ids for all components, e.g:
 315  <pre>
 316      (gs:label 'name "Input here")
 317  </pre>
 318  The usage of the reserved symbol <tt>name</tt> will not pose a problem.
 319  <br><br>
 320  <h2>Return values</h2>
 321  The return value of all functions is usually the number of characters
 322  sent to newLISP-GS. In general, return values of <tt>gs:xxx</tt> functions do not have
 323  any specific meaning and can be discarded. Only the functions <tt>gs:get-version</tt>,
 324  <tt>gs:get-screen</tt> and <tt>gs:get-fonts</tt> return their respective data and copy them
 325  also to the variables <tt>gs:version</tt>, <tt>gs:screen</tt> and <tt>gs:fonts</tt> for later access.
 326 <p></p>
 327  <br><br>
 328  <h2>Function overview</h2>
 329  <ul>
 330  <li><b>Initialization and application setup</b><br>
 331  <pre>
 332     (gs:init [<em>server-port</em>])
 333  </pre>
 334  The initialization function starts <tt>guiserver.jar</tt> which will listen to the <i>server-port</i>
 335  and initiate another connection on <tt>server-port + 1</tt> back to newLISP. If a <em>server-port</em>
 336  is not supplied <tt>guiserver</tt> will assume <tt>47011</tt> and <tt>47012</tt>.
 337 <p></p>
 338  As the last statement in the application put:
 339  <pre>
 340     (gs:listen)
 341  </pre>
 342  This function listens on <tt>47012</tt> (by default) for event messages from newLISP-GS
 343  and dispatches them to the user-defined action handlers. To avoid newLISP shutting down
 344  when the guiserver shuts down, use:
 345  <pre>
 346     (gs:listen true)
 347  </pre>
 348  </li>
 349 <p></p>
 350  Sometimes it is necessary to run other tasks while listening for events. In this case use
 351  <tt>gs:check-event</tt>, which will wait for certain amount of microseconds for an event
 352  to be executed. After the wait-time, it returns. The function is typically used in a loop:
 353 <p></p>
 354  <pre>
 355     (while (gs:check-event 10000) ; check for 10 milli seconds
 356                         (do-myprocess)
 357           )
 358 <p></p>
 359     (exit)
 360  </pre>
 361 <p></p>
 362  The loop will exit when <tt>gs:check-event</tt> returns <tt>nil</tt> on communications errors, e.g.
 363  when the window's close button was clicked.
 364 <p></p>
 365  <li><b>Containers</b><br>
 366  A <em>container</em> can contain any other container or control widget. Except for the
 367  <tt>menu-bar</tt> and the <tt>split-pane</tt>, containers can have a special layout-manager set
 368  with one of the three layout-manager function commands. By default containers have a flow layout. By
 369  nesting different containers and using different layout-manager settings, complex layouts
 370  can be configured. The function/command <tt>add-to</tt> is used to add components to containers.
 371 <p></p>
 372  <pre>
 373     (gs:dialog <em>sym-id</em> <em>sym-parent-frame</em> <em>str-message</em> <em>int-width</em> <em>int-height</em> [<em>boolean-visible</em> [<em>boolean-modal</em>]])
 374     (gs:frame <em>sym-id</em> <em>int-x</em> <em>int-y</em> <em>int-width</em> <em>int-height</em> [<em>str-title</em> <em>boolean-visible</em>])
 375     (gs:menu-bar <em>sym-frame</em> [<em>sym-menu-1</em> ...])
 376     (gs:panel <em>sym-id</em> [<em>int-width</em> <em>int-height</em>])
 377     (gs:scroll-pane <em>sym-id</em> <em>sym-widget</em> [<em>int-width</em> <em>int-height</em>])
 378     (gs:split-pane <em>sym-id</em> <em>str-orientation</em> [<em>float-weight</em> [<em>float-location</em> [int-divider-size>]]])
 379     (gs:tabbed-pane <em>sym-id</em> <em>sym-action</em> <em>str-orientation</em> [<em>sym-widget</em> <em>sym-tab-title</em> ...])
 380     (gs:tool-bar <em>sym-frame</em> [<em>bool-floatable</em> <em>int-hgap</em> <em>int-vgap</em>])
 381     (gs:canvas <em>sym-id</em>)
 382     (gs:window <em>sym-id</em> <em>int-x</em> <em>int-y</em> <em>int-width</em> <em>int-height</em>)
 383  </pre>
 384  </li>
 385  <li><b>Labels</b><br>
 386  Labels can have text or an image or both. A normal text <tt>label</tt> can have an icon
 387  added to it and a <tt>image-label</tt> can have text added to it. Labels don't initiate
 388  actions and can be placed in any container like all button-type widgets - buttons, checkboxes
 389  and menu items. A basic set of icon images is built into <tt>guiserver.jar</tt>,
 390  but user-supplied images and icons in <tt>.jpg</tt>, <tt>.png</tt> and <tt>.gif</tt> formats
 391  can be used.
 392  <pre>
 393     (gs:label <em>sym-id</em> <em>str-text</em> [<em>str-align</em> [<em>int-width</em> <em>int-height</em>]])
 394     (gs:image-label <em>sym-id</em> <em>str-icon-path</em> [<em>str-align</em>])
 395  </pre>
 396  </li>
 397  <li><b>Control widgets</b><br>
 398  Except for the passive progress bar, all control widgets fire action requests to
 399  the newLISP program. These requests must be served to avoid error messages but can
 400  be defined as empty functions, if an action is not required:
 401  <pre>
 402     ; empty action definition
 403     (define (my-button-action) )
 404 <p></p>
 405     ; action handler printing the name of the button pressed
 406     (define (my-button-action id) (println id " has been pressed"))
 407  </pre>
 408  All action events calls carry information about the widget, that initiated that the event,
 409  and event parameters like keystrokes, slider positions etc..
 410  <pre>
 411     (gs:button <em>sym-id</em> <em>sym-action</em> [<em>str-text</em> [<em>int-width</em> <em>int-height</em>]])
 412     (gs:check-box <em>sym-id</em> <em>sym-action</em> [<em>str-text</em> [<em>bool-selected</em>]])
 413     (gs:combo-box <em>sym-id</em> <em>sym-action</em> [<em>str-item-1</em> ...])
 414     (gs:combo-box <em>sym-id</em> <em>sym-action</em> [<em>list-str-items</em>])
 415     (gs:image-button <em>sym-id</em> <em>sym-action</em> <em>str-icon-path</em> [<em>str-down-icon-path</em> [<em>int-width</em> <em>int-height</em>]])
 416     (gs:list-box <em>sym-id</em> <em>sym-action</em> [<em>str-item-1</em> ...])
 417     (gs:list-box <em>sym-id</em> <em>sym-action</em> [<em>list-str-items</em>])
 418     (gs:menu <em>sym-id</em> <em>str-text</em>)
 419     (gs:menu-popup <em>sym-id</em> <em>str-text</em>)
 420     (gs:menu-item <em>sym-id</em> <em>sym-action</em> <em>str-text</em>)
 421     (gs:menu-item-check <em>sym-id</em> <em>sym-action</em> <em>str-text</em> [<em>bool-selected</em>])
 422     (gs:progress-bar <em>sym-id</em> <em>int-min</em> <em>in-max</em> <em>int-initial-value</em>)
 423     (gs:radio-button <em>sym-id</em> <em>sym-action</em> [<em>str-text</em> [<em>bool-selected</em>]])
 424     (gs:slider <em>sym-id</em> <em>sym-action</em> <em>str-orientation</em> <em>int-min</em> <em>int-max</em> <em>int-initial-value</em>)
 425     (gs:text-area <em>sym-id</em> <em>sym-action</em> [<em>int-width</em> <em>int-height</em>])
 426     (gs:text-field <em>sym-id</em> <em>sym-action</em> <em>int-columns</em>)
 427     (gs:text-pane <em>sym-id</em> <em>sym-action</em> <em>str-style</em> [<em>int-width</em> <em>int-height</em>])
 428     (gs:toggle-button <em>sym-id</em> <em>sym-action</em> [<em>str-text</em> <em>bool-selected</em>])
 429  </pre>
 430  For all button widgets, and the check box and menu-item widgets, icons can be set using
 431  the <tt>gs:set-icon</tt> and <tt>gs:set-pressed-icon</tt> functions.
 432 <p></p>
 433  </li>
 434  <li><b>Placing components in containers</b><br>
 435  For the flow and grid layouts the components are added in the sequence they are listed.
 436  The grid-layout fills the grid row by row starting with the left most column.
 437  <pre>
 438     (gs:add-to <em>sym-container</em> <em>sym-component</em> [<sym-component ...])
 439  </pre>
 440  For the border layout an orientation parameter is specified as either <tt>"north"</tt>,
 441  <tt>"west"</tt>, <tt>"center"</tt>, <tt>"east"</tt> or <tt>"south"</tt>.
 442  <pre>
 443     (gs:add-to <em>sym-container</em> [<em>sym-component</em> <em>str-orientation</em> ...])
 444  </pre>
 445
 446  </li>
 447  <li><b>Summary of commands</b><br>
 448  Most of the commands set special attributes of containers or control widgets.
 449  Not all functions can be applied to all containers and control widgets. A wrong
 450  application will either pop up an error message box or do nothing.
 451 <p></p>
 452  Some functions will work on certain widgets only in certain situations. For example
 453  <tt>set-size</tt> will work not on components in a grid layout but on components
 454  in a flow layout. Some widgets have a preset background color which cannot be changed
 455  or is overwritten by the current <tt>gs:look-and-feel</tt> settings.
 456 <p></p>
 457         <pre>
 458     (gs:add-list-item <em>sym-list-combo</em> <em>str-text</em> [<em>str-text</em> ...])
 459     (gs:add-separator <em>sym-menu-tool-bar</em>)
 460     (gs:add-to <em>sym-container</em> <em>sym-component</em> [<sym-component ...])
 461     (gs:add-to <em>sym-container</em> <em>sym-component</em> <em>str-orientation</em> [<em>sym-component</em> <em>str-orientation</em> ...])
 462     (gs:append-text <em>sym-id</em> <em>str-text</em>)
 463     (gs:check-event <em>int-microseconds</em>)
 464     (gs:clear-list <em>sym-id</em>)
 465     (gs:clear-text <em>sym-id</em>)
 466     (gs:copy-text <em>sym-id</em>)
 467     (gs:cut-text <em>sym-id</em>)
 468     (gs:destroy-shell <em>sym-text-area</em>)
 469     (gs:disable <em>sym-id-1</em> [<em>sym-id-2</em> ...])
 470     (gs:dispose <em>sym-id</em>)
 471     (gs:dispose-splash)
 472     (gs:enable <em>sym-id-1</em> [<em>sym-id-2</em> ...])
 473     (gs:eval-shell <em>sym-text-area</em> <em>str-commmand</em>)
 474     (gs:find-text <em>sym-id</em> <em>str-text</em> <em>sym-action</em> [<em>str-direction</em>]])
 475     (gs:frame-closed <em>sym-id</em> <em>sym-action</em>)
 476     (gs:get-fonts)
 477     (gs:get-bounds <em>sym-id</em>)
 478     (gs:get-font-metrics <em>sym-id</em> <em>str-text</em>)
 479     (gs:get-screen)
 480     (gs:get-selected-text <em>sym-id</em> <em>sym-action</em>)
 481     (gs:get-text <em>sym-id</em> [<em>sym-action</em>])
 482     (gs:get-text-position <em>sym-id</em>)
 483     (gs:get-version);
 484     (gs:goto-text <em>sym-id</em> <em>sym-row</em> <em>sym-column</em>)
 485     (gs:insert-list-item <em>sym-list-combo</em> <em>str-text</em> <em>int-index</em> [<em>str-text</em> <em>int-index</em>])
 486     (gs:insert-tab <em>sym-tabbed-pane</em> <em>sym-component</em> [<em>str-text</em> [<em>int-index</em> [<em>str-icon-path</em>]])
 487     (gs:insert-text <em>sym-id</em> <em>str-text</em> <em>int-pos</em>)
 488     (gs:layout <em>sym-container</em>)
 489     (gs:load-text <em>sym-id</em> <em>str-path</em>)
 490     (gs:no-action)
 491     (gs:paste-text <em>sym-id</em> [<em>str-text</em>])
 492     (gs:redo-text <em>sym-id</em>)
 493     (gs:remove-from <em>sym-container</em> <em>sym-component</em> [<em>sym-component</em> ...])
 494     (gs:remove-list-item <em>sym-list-combo</em> <em>int-index</em> [<em>int-index</em> ...])
 495     (gs:remove-tab <em>sym-tabbed-pane</em> <em>int-index</em>)
 496     (gs:request-focus <em>sym-id</em>)
 497     (gs:run-shell <em>sym-text-area</em> <em>str-commmand</em>)
 498     (gs:select-list-item <em>sym-id</em> <em>str-item</em> [<em>boolean-flag</em>])
 499     (gs:select-text <em>sym-id</em> <em>int-from</em> [<em>int-to</em>])
 500     (gs:set-accelerator <em>sym-menu-item</em> <em>str-keystroke</em>)
 501     (gs:set-background <em>sym-id</em> <em>float-red</em> <em>float-green</em> <em>float-blue</em> [<em>float-alpha</em>])
 502     (gs:set-background <em>sym-id</em> <em>list-rgb</em> [<em>float-alpha</em>])
 503     (gs:set-bevel-border <em>sym-panel</em> <em>str-type</em>)
 504     (gs:set-border-layout <em>sym-container</em>  [<em>int-hgap</em> <em>int-vgap</em>])
 505     (gs:set-caret <em>sym-id</em> <em>int-offset</em>)
 506     (gs:set-caret-color <em>sym-id</em> <em>list-rgb</em>)
 507     (gs:set-caret-color <em>sym-id</em> <em>float-red</em> <em>float-green</em> <em>float-blue</em>)
 508     (gs:set-color <em>sym-id</em> <em>float-red</em> <em>float-green</em> <em>float-blue</em> [<em>float-alpha</em>])
 509     (gs:set-color <em>sym-id</em> <em>list-rgb</em> [<em>float-alpha</em>])
 510     (gs:set-cursor <em>sym-id</em> <em>str-shape</em>)
 511     (gs:set-editable <em>sym-id</em> <em>boolean-flag</em>)
 512     (gs:set-flow-layout <em>sym-container</em> [<em>str-alignment</em> [<em>int-hgap</em> <em>int-vgap</em>]])
 513     (gs:set-font <em>sym-id</em> <em>str-family</em> <em>int-size</em> <em>str-type</em>)
 514     (gs:set-foreground <em>sym-id</em> <em>float-red</em> <em>float-green</em> <em>float-blue</em> [<em>float-alpha</em>])
 515     (gs:set-foreground <em>sym-id</em> <em>list-rgb</em> [<em>float-alpha</em>])
 516     (gs:set-grid-layout <em>sym-container</em> <em>int-columns</em> <em>int-rows</em> [<em>int-hgap</em> <em>int-vgap</em>])
 517     (gs:set-icon <em>sym-id</em> <em>str-icon-path</em> [<em>int-index</em>])
 518     (gs:set-look-and-feel <em>str-look</em>)
 519     (gs:set-resizable <em>sym-frame</em> <em>boolean-flag</em>)
 520     (gs:set-pressed-icon <em>sym-id</em> <em>str-icon-path</em>)
 521     (gs:set-selected <em>sym-id</em> <em>boolean-flag</em>)
 522     (gs:set-size <em>sym-id</em> <em>int-width</em> <em>int-height</em>)
 523     (gs:set-selection-color <em>sym-id</em> <em>float-red</em> <em>float-green</em> <em>float-blue</em> [<em>float-alpha</em>])
 524     (gs:set-syntax <em>sym-id</em> <em>str-type</em>)
 525     (gs:set-syntax-colors <em>list-rgb-comments</em> <em>list-rgb-keywords</em> <em>list-rgb-string</em> <em>list-rgb-number</em> <em>list-rgb-quoted</em> <em>list-rgb-prantheses</em>)
 526     (gs:set-tab-size <em>sym-id</em> <em>int-size</em>)
 527     (gs:set-text <em>sym-id</em> <em>str-text</em> [<em>int-index</em>])
 528     (gs:set-titled-border <em>sym-component</em> <em>str-title</em>)
 529     (gs:set-tool-tip <em>sym-id</em> <em>str-text</em>)
 530     (gs:set-trace <em>boolean-flag</em>)
 531     (gs:set-utf8 <em>boolean-flag</em>)
 532     (gs:set-value <em>sym-id</em> <em>int-value</em>)
 533     (gs:set-visible <em>sym-id</em> <em>boolean-visible</em>)
 534     (gs:undo-text <em>sym-id</em>)
 535     (gs:undo-enable <em>sym-id</em> <em>boolean-enabled</em>)
 536  </pre>
 537  </li>
 538  <li><b>Special dialogs</b><br>
 539   These are standard dialogs for opening and saving files and for choosing colors.
 540   Each dialog when closed fires an event for which a handler function must be
 541   defined by the newLISP program.
 542         <pre>
 543     (gs:color-dialog <em>sym-parent-frame</em> <em>sym-action</em> <em>str-title</em> <em>float-red</em> <em>float-green</em> <em>float-blue</em>)
 544     (gs:message-dialog <em>sym-parent-frame</em> <em>str-title</em> <em>str-message</em> [<em>str-type</em> [<em>str-icon-path</em>]])
 545     (gs:confirm-dialog <em>sym-parent-frame</em> <em>sym-action</em> <em>str-title</em> <em>str-message</em> [<em>str-type</em>])
 546     (gs:open-file-dialog <em>sym-parent-frame</em> <em>sym-action</em> [<em>str-directory</em> [<em>str-mask</em> <em>str-description</em>]])
 547     (gs:save-file-dialog <em>sym-parent-frame</em> <em>sym-action</em> [<em>str-directory</em> [<em>str-initial-file</em> [<em>str-mask</em> <em>str-description</em>]]])
 548  </pre>
 549  </li>
 550  <li><b>2D Graphics functions</b><br>
 551  Every call to a <tt>gs:draw-xxx</tt> or <tt>gs:fill-xxx</tt> function will create a new graphics object, which
 552  will persist until destroyed by a call to <tt>gs:delete-tag</tt>. Graphics objects are animated
 553  using the tag operations <tt>gs:move-tag</tt>, <tt>gs:rotate-tag</tt>, <tt>gs:scale-tag</tt> and
 554  <tt>gs:shear-tag</tt> or using <tt>gs:hide-tag</tt> and <tt>gs:show-tag</tt>.
 555 <p></p>
 556  Any <tt>gs:draw-xxx</tt> or <tt>gs:fill-xxx</tt> will create graphics objects but not force a screen update.
 557  The canvas is automatically redrawn when made visible for the first time using <tt>gs:set-visible</tt> or
 558  after a call to <tt>gs:update</tt>. Redrawing is also forced when resizing the window which hosts the canvas
 559  or any action covering and uncovering the canvas.
 560 <p></p>
 561  After all tag operations redrawing is initiated by default, but it can be forced off by spcifying
 562  <tt>nil</tt> as the last parameter in a <tt>gs:xxx-tag</tt> command. Suppressing immediate redraw is useful to avoid
 563  flicker when a batch of tag operations is performed.
 564 <p></p>
 565  Every graphics object (line, shape, text, or image) carries a group tag. Objects are deleted
 566  using <tt>gs:delete-tag</tt> and will disappear immediately from the canvas. Using <tt>gs:move-tag</tt>
 567  lines, shapes, text and images can be moved to a different position.
 568 <p></p>
 569  <pre>
 570     (gs:color-tag <em>sym-tag</em> <em>list-rgb</em> [<em>boolean-repaint</em>])
 571     (gs:delete-tag <em>sym-tag</em>[<em>boolean-repaint</em>])
 572     (gs:draw-arc <em>sym-tag</em> <em>int-x</em> <em>int-y</em> <em>int-width</em> <em>int-height</em> <em>int-start</em> <em>int-angle</em> [<em>list-rgb</em>])
 573     (gs:draw-circle <em>sym-tag</em> <em>int-x</em> <em>int-y</em> <em>int-radius</em> [<em>list-rgb</em>])
 574     (gs:draw-ellipse <em>sym-tag</em> <em>int-x</em> <em>int-y</em> <em>int-radius-x</em> <em>int-radius-y</em> [<em>list-rgb</em>])
 575     (gs:draw-image <em>sym-tag</em> <em>str-path</em> <em>int-x</em> <em>int-y</em> [<em>int-width</em> <em>int-height</em>])
 576     (gs:draw-line <em>sym-tag</em> <em>int-x1</em> <em>int-y1</em> <em>int-x2</em> <em>int-y2</em> [<em>list-rgb</em>])
 577     (gs:draw-path <em>sym-tag</em> <em>list-points</em> [<em>list-rgb</em>])
 578     (gs:draw-polygon <em>sym-tag</em> <em>list-points</em> [<em>list-rgb</em>])
 579     (gs:draw-rect <em>sym-tag</em> <em>int-x</em> <em>int-y</em> <em>int-width</em> <em>int-height</em> [<em>list-rgb</em>])
 580     (gs:draw-round-rect <em>sym-tag</em> <em>int-x</em> <em>int-y</em> <em>int-width</em> <em>int-height</em> <em>int-arc-width</em> <em>int-arc-height</em> [<em>list-rgb</em>])
 581     (gs:g <em>sym-tag</em> <em>str-text</em> <em>int-x</em> <em>int-y</em> [<em>list-rgb</em> [<em>float-angle</em>]])
 582     (gs:export <em>str-path-file</em> [<em>int-width</em> <em>int-height</em>])
 583     (gs:fill-arc <em>sym-tag</em> <em>int-x</em> <em>int-y</em> <em>int-width</em> <em>int-height</em> <em>int-start</em> <em>int-angle</em> [<em>list-rgb</em>])
 584     (gs:fill-circle <em>sym-tag</em> <em>int-x</em> <em>int-y</em> <em>int-radius</em> [<em>list-rgb</em>])
 585     (gs:fill-ellipse <em>sym-tag</em> <em>int-x</em> <em>int-y</em> <em>int-radius-x</em> <em>int-radius-y</em> [<em>list-rgb</em>])
 586     (gs:fill-polygon <em>sym-tag</em> <em>list-points</em> [<em>list-rgb</em>])
 587     (gs:fill-rect <em>sym-tag</em> <em>int-x</em> <em>int-y</em> <em>int-width</em> <em>int-height</em> [<em>list-rgb</em>])
 588     (gs:fill-round-rect <em>sym-tag</em> <em>int-x</em> <em>int-y</em> <em>int-width</em> <em>int-height</em> <em>int-arc-width</em> <em>int-arc-height</em> [<em>list-rgb</em>])
 589     (gs:hide-tag <em>sym-tag</em>  [<em>boolean-repaint</em>])
 590     (gs:move-tag <em>sym-tag</em> <em>int-dx</em> <em>int-dy</em> [<em>boolean-repaint</em>])
 591     (gs:reorder-tags <em>list-tags</em>)
 592     (gs:rotate-tag <em>sym-tag</em> <em>float theta</em> <em>int-x</em> <em>int-y</em> [<em>boolean-repaint</em>])
 593     (gs:save-text <em>sym-id</em> <em>str-path</em>)
 594     (gs:scale-tag <em>sym-tag</em> <em>float-x</em> <em>float-y</em> [<em>boolean-repaint</em>])
 595     (gs:shear-tag <em>sym-tag</em> <em>float-x</em> <em>float-y</em> [<em>boolean-repaint</em>])
 596     (gs:show-popup <em>sym-tag</em> <em>sym-host</em> <em>int-x</em> <em>int-y</em>)
 597     (gs:show-tag <em>sym-tag</em> [<em>boolean-repaint</em>])
 598     (gs:set-canvas <em>sym-tag</em>)
 599     (gs:set-paint <em>list-rgb</em>)
 600     (gs:set-rotation <em>float-angle</em>)
 601     (gs:set-scale <em>int-x</em> <em>int-y</em>)
 602     (gs:set-stroke <em>float-width</em> [<em>str-cap</em> [<em>str-join</em> [<em>float-miterlimit</em>]]])
 603     (gs:set-translation <em>int-x</em> <em>int-y</em>)
 604     (gs:set-anti-aliasing <em>boolean-flag</em>)
 605     (gs:translate-tag <em>sym-tag</em> <em>int-x</em> <em>int-y</em> [<em>boolean-repaint</em>])
 606     (gs:update)
 607  </pre>
 608  </li>
 609 <p></p>
 610  <li><b>Events</b><br>
 611  Additionally to the event actions registered when creating a widget,
 612  the canvas, windows and dialogs can fire events as a result of key or mouse
 613  actions or when the position or size of a windows or dialog has changed.
 614 <p></p>
 615  <pre>
 616     (gs:key-event <em>sym-id</em> <em>sym-action</em>)
 617     (gs:mouse-clicked <em>sym-canvas</em> <em>sym-action</em> [<em>boolean-tags</em>])
 618     (gs:mouse-dragged <em>sym-canvas</em> <em>sym-action</em>)
 619     (gs:mouse-event <em>sym-id</em> <em>sym-action</em>)
 620     (gs:mouse-moved <em>sym-canvas</em> <em>sym-action</em> [<em>boolean-tags</em>])
 621     (gs:mouse-pressed <em>sym-canvas</em> <em>sym-action</em> [<em>boolean-tags</em>])
 622     (gs:mouse-released <em>sym-canvas</em> <em>sym-action</em> [<em>boolean-tags</em>])
 623     (gs:mouse-wheel <em>sym-canvas</em> <em>sym-action</em>)
 624     (gs:window-closed <em>sym-id</em> <em>sym-action</em>)
 625     (gs:window-moved <em>sym-id</em> <em>sym-action</em>)
 626     (gs:window-resized <em>sym-id</em> <em>sym-action</em>)
 627  </pre>
 628  </li>
 629 <p></p>
 630  <li><b>Built-in icons and images</b><br>
 631  The <tt>guiserver.jar</tt> file has the following icons and images built in. Each of
 632  them is prefixed with the path <tt>/local/</tt>. For example <tt>/local/newLISP128.png</tt>
 633  addresses the newLISP logo of size 128x128. To address images outside of
 634  <tt>guiserver.jar</tt>, use a normal file path suitable to your platform. On Win32
 635  use forward slashes instead of backslashes.
 636 <p></p>
 637  <pre>
 638  Image path
 639  ----------
 640  clear-down32.png
 641  clear32.png
 642  copy-down32.png
 643  copy32.png
 644  cut-down32.png
 645  cut32.png
 646  dotgray16.png
 647  dotgray32.png
 648  dotgreen16.png
 649  dotgreen32.png
 650  dotred16.png
 651  dotred32.png
 652  dotyellow16.png
 653  dotyellow32.png
 654  edit-down32.png
 655  edit32.png
 656  folder-closed-down32.png
 657  folder-closed32.png
 658  folder-opened-down32.png
 659  folder-opened32.png
 660  font-book-down32.png
 661  font-book32.png
 662  green10.png
 663  info-down32.png
 664  info32.png
 665  new-down32.png
 666  new32.png
 667  newLISP-down32.png
 668  newLISP128.png
 669  newLISP16.png
 670  newLISP20.png
 671  newLISP32.png
 672  newLISP64.png
 673  newLISPsplashWin.png
 674  paste-down32.png
 675  paste32.png
 676  pressedbutton32.png
 677  red10.png
 678  restart-down32.png
 679  restart32.png
 680  run-down32.png
 681  run32.png
 682  save-down32.png
 683  save32.png
 684  search-down32.png
 685  search32.png
 686  stop-down32.png
 687  stop32.png
 688  </pre>
 689  <li><b>Predefined colors</b><br>
 690  The following colors are predefined:
 691  <pre>
 692  Name          rgb components
 693  ----          --------------
 694  gs:black      (0.0 0.0 0.0)
 695  gs:blue       (0.0 0.0 1.0)
 696  gs:cyan       (0.0 1.0 1.0)
 697  gs:darkGray   (0.2509804 0.2509804 0.2509804)
 698  gs:gray       (0.5019608 0.5019608 0.5019608)
 699  gs:green      (0.0 1.0 0.0)
 700  gs:lightGray  (0.7529412 0.7529412 0.7529412)
 701  gs:magenta    (1.0 0.0 1.0)
 702  gs:orange     (1.0 0.78431374 0.0)
 703  gs:pink       (1.0 0.6862745 0.6862745)
 704  gs:red        (1.0 0.0 0.0)
 705  gs:white      (1.0 1.0 1.0)
 706  gs:yellow     (1.0 1.0 0.0)
 707  </pre>
 708 <p></p>
 709  Colors in newLISP-GS can be specified as three (four with alpha component) single
 710  numbers or as a list of the three RGB values followed by the alpha channel number.
 711  <pre>
 712  (gs:set-background 'aPanel gs:magenta
 713  (gs:set-background 'aPanel 1.0 0 1
 714  (gs:set-background 'aPanel '(1 0 1)
 715  </pre>
 716  All of the above statements will produce the same background color on the <tt>aPanel</tt>.
 717  <li><b>Sound API</b><br>
 718  <pre>
 719     (gs:play-sound <em>str-file-path</em>)
 720  </ul>
 721
 722
 723
 724
 725  <br><br><br>
 726
 727 <p></p><center>- &sect; -</center><p></p>
 728 <a name="gs_add-list-item"></a><h3><font color=#CC0000>gs:add-list-item</font></h3>
 729 <b>syntax: (<font color=#CC0000>gs:add-list-item</font> <em>sym-list-combo</em> <em>str-text</em> [<em>str-text</em> ...])</b><br/>
 730 <b>parameter: </b><em>sym-list-combo</em> - The name of the combo box or list box to which text entries are added.<br/>
 731 <b>parameter: </b><em>str-text</em> - The text of the entry to be added.<br/>
 732 <p></p>
 733  Items are added in the same sequence as they appear in the <tt>gs:add-list</tt> command and added to the
 734  end of the existing list of items.
 735
 736
 737 <p></p><center>- &sect; -</center><p></p>
 738 <a name="gs_add-separator"></a><h3><font color=#CC0000>gs:add-separator</font></h3>
 739 <b>syntax: (<font color=#CC0000>gs:add-separator</font> <em>sym-menu-tool-bar</em>)</b><br/>
 740 <b>parameter: </b><em>sym-menu-tool-bar</em> - The name of the tool bar or menu bar to which a spacer entry is added.<br/>
 741 <p></p>
 742  Depending on the OS platform the separator may not be visible and only occupy space before the next
 743  component added to the tool or menu bar.
 744
 745
 746 <p></p><center>- &sect; -</center><p></p>
 747 <a name="gs_add-to"></a><h3><font color=#CC0000>gs:add-to</font></h3>
 748 <b>syntax: (<font color=#CC0000>gs:add-to</font> <em>sym-container</em> <em>sym-component</em> [<em>sym-componentl</em> ...])</b><br/>
 749 <b>parameter: </b><em>sym-container</em> - The name of the container to which components are added.<br/>
 750 <b>parameter: </b><em>sym-component</em> - One or more symbols of the components to add.<br/>
 751
 752
 753 <b>syntax: (<font color=#CC0000>gs:add-to</font> <em>sym-container</em> <em>sym-component</em> <em>str-orientation</em> [<em>sym-component</em> <em>str-orientation</em> ...])</b><br/>
 754 <b>parameter: </b><em>sym-container</em> - The name of the container to which components are added.<br/>
 755 <b>parameter: </b><em>sym-component</em> - The name of a component to add.<br/>
 756 <b>parameter: </b><em>str-orientation</em> - The orientation of a component to add in border layout, <tt>"north"</tt>, <tt>"west"</tt>, <tt>"center"</tt>, <tt>"east"</tt> or <tt>"south"</tt>.<br/>
 757
 758
 759 <p></p><center>- &sect; -</center><p></p>
 760 <a name="gs_append-text"></a><h3><font color=#CC0000>gs:append-text</font></h3>
 761 <b>syntax: (<font color=#CC0000>gs:append-text</font> <em>sym-id</em> <em>str-text</em>)</b><br/>
 762 <b>parameter: </b><em>sym-id</em> - The name of the text field or text area to which text is appended.<br/>
 763 <b>parameter: </b><em>str-text</em> - The text to be appended.<br/>
 764
 765
 766 <p></p><center>- &sect; -</center><p></p>
 767 <a name="gs_button"></a><h3><font color=#CC0000>gs:button</font></h3>
 768 <b>syntax: (<font color=#CC0000>gs:button</font> <em>sym-id</em> <em>sym-action</em> [<em>str-text</em> [<em>int-width</em> <em>int-height</em>]])</b><br/>
 769 <b>parameter: </b><em>sym-id</em> - The name of the button.<br/>
 770 <b>parameter: </b><em>sym-action</em> - The name of the event handler.<br/>
 771 <b>parameter: </b><em>str-icon-path</em> - An optional text for the button.<br/>
 772 <b>parameter: </b><em>int-width</em> - The optional width of the button.<br/>
 773 <b>parameter: </b><em>int-height</em> - The optional height of the button.<br/>
 774
 775
 776 <p></p><center>- &sect; -</center><p></p>
 777 <a name="gs_canvas"></a><h3><font color=#CC0000>gs:canvas</font></h3>
 778 <b>syntax: (<font color=#CC0000>gs:canvas</font> <em>sym-id</em>)</b><br/>
 779 <b>parameter: </b><em>sym-id</em> - The name of the canvas.<br/>
 780 <p></p>
 781  A canvas is a pane for drawing and receiving mouse input events. For most
 782  applications a background color should be specified for the canvas using
 783  <tt>gs:set-background</tt> or <tt>gs:set-color</tt> which call the same function internally. The
 784  background forces the canvas to be cleared before redrawing components
 785  which have been moved, rotated, scaled or deleted. In applications where
 786  this is not desired but a background color is still required, the background
 787  color can be specified for the container hosting the canvas. The canvas
 788  background will then appear in the color of the container, but erasing
 789  the canvas before repainting is not enforced.
 790 <p></p>
 791  A canvas can also be used to host widgets like buttons etc.. In this case
 792  the canvas is treated like a <tt>gs:pane</tt>, with a flow layout by default.
 793  Similar to a panel created with <tt>gs:pane</tt> other layouts can be set.
 794 <p></p>
 795  When widgets are present on a canvas they appear to be floating over
 796  the drawing. See the file <tt>textrot-demo.lsp</tt> for an example.
 797
 798
 799 <p></p><center>- &sect; -</center><p></p>
 800 <a name="gs_check-box"></a><h3><font color=#CC0000>gs:check-box</font></h3>
 801 <b>syntax: (<font color=#CC0000>gs:check-box</font> <em>sym-id</em> <em>sym-action</em> [<em>str-text</em> [<em>bool-selected</em>]])</b><br/>
 802 <b>parameter: </b><em>sym-id</em> - The name of the check box.<br/>
 803 <b>parameter: </b><em>sym-action</em> - The name of the event handler.<br/>
 804 <b>parameter: </b><em>str-text</em> - The text of the check box.<br/>
 805 <b>parameter: </b><em>bool-selected</em> - An optional flag indicating the selection state <tt>true</tt> or <tt>nil</tt> (default).<br/>
 806 <p></p>
 807 <p></p><center>- &sect; -</center><p></p>
 808 <a name="gs_check-event"></a><h3><font color=#CC0000>gs:check-event</font></h3>
 809 <b>syntax: (<font color=#CC0000>gs:check-event</font> <em>int-microseconds</em>)</b><br/>
 810 <b>parameter: </b><em>int-microseconds</em> - Wait for for an event a maximum of <em>int-microseconds</em> and execute it.<br/>
 811 <p></p>
 812  The function <tt>gs:check-event</tt> is used as an alternative to <tt>gs:listen</tt> when the application
 813  is performing some activity while waiting for user input from the GUI. Typically
 814  <tt>gs:check-event</tt> is used in a loop, which performs some other task and at the same time
 815  checks for events from the GUI part of the application. Like <tt>gs:listen</tt> the function will
 816  force an exit of the application when communication between the newLISP-GS and the newLISP
 817  application process fails.
 818 <p></p>
 819 <p></p><b>example:</b><blockquote><pre> (while (gs:check-event 10000) ; check for 10 milliseconds
 820      (do-myprocess)
 821  )</pre></blockquote>
 822 <p></p><center>- &sect; -</center><p></p>
 823 <a name="gs_clear-list"></a><h3><font color=#CC0000>gs:clear-list</font></h3>
 824 <b>syntax: (<font color=#CC0000>gs:clear-list</font> <em>sym-id</em>)</b><br/>
 825 <b>parameter: </b><em>sum-id</em> - The name of the list component in which to clear all entries.<br/>
 826
 827
 828 <p></p><center>- &sect; -</center><p></p>
 829 <a name="gs_clear-text"></a><h3><font color=#CC0000>gs:clear-text</font></h3>
 830 <b>syntax: (<font color=#CC0000>gs:clear-text</font> <em>sym-id</em>)</b><br/>
 831 <b>parameter: </b><em>sum-id</em> - The name of the component in which to clear the text.<br/>
 832
 833
 834 <p></p><center>- &sect; -</center><p></p>
 835 <a name="gs_copy-text"></a><h3><font color=#CC0000>gs:copy-text</font></h3>
 836 <b>syntax: (<font color=#CC0000>gs:copy-text</font> <em>sym-id</em>)</b><br/>
 837 <b>parameter: </b><em>sum-id</em> - The name of the text component from which to copy the selection to the clipboard.<br/>
 838
 839
 840 <p></p><center>- &sect; -</center><p></p>
 841 <a name="gs_cut-text"></a><h3><font color=#CC0000>gs:cut-text</font></h3>
 842 <b>syntax: (<font color=#CC0000>gs:cut-text</font> <em>sym-id</em>)</b><br/>
 843 <b>parameter: </b><em>sym-id-text</em> - The name of the text component from which to cut selected text and place it on the clipboard..<br/>
 844
 845
 846
 847 <p></p><center>- &sect; -</center><p></p>
 848 <a name="gs_color-dialog"></a><h3><font color=#CC0000>gs:color-dialog</font></h3>
 849 <b>syntax: (<font color=#CC0000>gs:color-dialog</font> <em>sym-parent-frame</em> <em>sym-action</em> <em>str-title</em> <em>float-red</em> <em>float-green</em> <em>float-blue</em>)</b><br/>
 850 <b>parameter: </b><em>sym-parent-frame</em> - The name symbol of the parent frame.<br/>
 851 <b>parameter: </b><em>sym-action</em> - The symbol of the handler to call when leaving the dialog<br/>
 852 <b>parameter: </b><em>str-title</em> - The title of the color dialog.<br/>
 853 <b>parameter: </b><em>float-red</em> - The initial red color component.<br/>
 854 <b>parameter: </b><em>float-green</em> - The initial green color component.<br/>
 855 <b>parameter: </b><float-blue - The initial blue color component.<br/>
 856
 857
 858
 859 <p></p><center>- &sect; -</center><p></p>
 860 <a name="gs_color-tag"></a><h3><font color=#CC0000>gs:color-tag</font></h3>
 861 <b>syntax: (<font color=#CC0000>gs:color-tag</font> <em>sym-tag</em> <em>list-color</em> [<em>boolean-update</em>])</b><br/>
 862 <b>parameter: </b><em>sym-tag</em> - The name tage of the shape(s) to set a new color.<br/>
 863 <b>parameter: </b><em>list-color</em> - The new color as a list of 3 numbers for the rgb components.<br/>
 864 <b>parameter: </b><em>boolean-repaint</em> - An optional flag to indicate if repainting is required (default is <tt>true</tt>).<br/>
 865
 866
 867 <p></p><center>- &sect; -</center><p></p>
 868 <a name="gs_combo-box"></a><h3><font color=#CC0000>gs:combo-box</font></h3>
 869 <b>syntax: (<font color=#CC0000>gs:combo-box</font> <em>sym-id</em> <em>sym-action</em> [<em>str-item-1</em> ...])</b><br/>
 870 <b>parameter: </b><em>sym-id</em> - The name of the combo box.<br/>
 871 <b>parameter: </b><em>sym-action</em> - The name of the event handler.<br/>
 872 <b>parameter: </b><em>str-item</em> - Zero, one or more text entries in the combo box.<br/>
 873 <b>syntax: (<font color=#CC0000>gs:combo-box</font> <em>sym-id</em> <em>sym-action</em> [<em>list-str-items</em>])</b><br/>
 874 <b>parameter: </b><em>sym-id</em> - The name of the combo box.<br/>
 875 <b>parameter: </b><em>sym-action</em> - The name of the event handler.<br/>
 876 <b>parameter: </b><em>list-str-items</em> - Zero, one or more text entries in a list.<br/>
 877
 878
 879 <p></p><center>- &sect; -</center><p></p>
 880 <a name="gs_confirm-dialog"></a><h3><font color=#CC0000>gs:confirm-dialog</font></h3>
 881 <b>syntax: (<font color=#CC0000>gs:confirm-dialog</font> <em>sym-parent-frame</em> <em>sym-action</em> <em>str-title</em> <em>str-message</em> [<em>str-type</em>])</b><br/>
 882 <b>parameter: </b><em>sym-parent-frame</em> - The symbol name of the parent frame.<br/>
 883 <b>parameter: </b><em>sym-action</em> - The action to perform when the diaog is closed.<br/>
 884 <b>parameter: </b><em>str-title</em> - The title of the message box.<br/>
 885 <b>parameter: </b><em>str-message</em> - The message in the message box.<br/>
 886 <b>parameter: </b><em>str-type</em> - The type of the message box.<br/>
 887 <p></p>
 888  The type of the message box can be one of: <tt>"yes-no"</tt>, <tt>"yes-no-cancel"</tt>
 889  On return of the message box <em>sym-action</em> carries one of the responses <tt>0</tt> for the yes-,
 890  <tt>1</tt> for the no- or <tt>3</tt> for the cancel-button.
 891
 892
 893 <p></p><center>- &sect; -</center><p></p>
 894 <a name="gs_delete-tag"></a><h3><font color=#CC0000>gs:delete-tag</font></h3>
 895 <b>syntax: (<font color=#CC0000>gs:delete-tag</font> <em>sym-tag</em> [<em>boolean-repaint</em>])</b><br/>
 896 <b>parameter: </b><em>sym-tag</em> - The tag group to be deleted.<br/>
 897 <b>parameter: </b><em>boolean-repaint</em> - An optional flag to indicate if repainting is required (default is <tt>true</tt>).<br/>
 898 <p></p>
 899  Deletes all 2D objects (lines, shapes, text, images) tagged with <em>sym-tag</em>.
 900 <p></p>
 901  Each time a <tt>gs:draw-xxx</tt> or <tt>gs:fill-xxx</tt> function is called a graphical
 902  object is created. The tag used during creation is a way to address one
 903  or more of these objects. See the file <tt>mouse-demo.lsp</tt> for an example.
 904
 905
 906 <p></p><center>- &sect; -</center><p></p>
 907 <a name="gs_destroy-shell"></a><h3><font color=#CC0000>gs:destroy-shell</font></h3>
 908 <b>syntax: (<font color=#CC0000>gs:destroy-shell</font> <em>sym-text-area</em>)</b><br/>
 909 <b>parameter: </b><em>sym-text-area</em> - The name of the text component for which the shell process is destroyed.<br/>
 910
 911
 912 <p></p><center>- &sect; -</center><p></p>
 913 <a name="gs_dialog"></a><h3><font color=#CC0000>gs:dialog</font></h3>
 914 <b>syntax: (<font color=#CC0000>gs:dialog</font> <em>sym-id</em> <em>sym-parent</em> <em>str-title</em> <em>int-width</em> <em>int-height</em> [<em>boolean-visible</em> [<em>boolean-modal</em>]])</b><br/>
 915 <b>parameter: </b><em>sym-id</em> - The name of the dialog<br/>
 916 <b>parameter: </b><em>sym-parent</em> - The name of the parent frame.<br/>
 917 <b>parameter: </b><em>str-title</em> - The title string of the dialog frame.<br/>
 918 <b>parameter: </b><em>int-width</em> - The width of the dialog frame.<br/>
 919 <b>parameter: </b><em>int-height</em> - The height of the dialog frame.<br/>
 920 <b>parameter: </b><em>boolean-visible</em> - The optional flag with a value of <tt>true</tt> or <tt>nil</tt> for visibility of the dialog.<br/>
 921 <b>parameter: </b><em>boolean-modal</em> - The optional flag with a value of <tt>true</tt> or <tt>nil</tt> for modality of the dialog.<br/>
 922 <p></p>
 923  Initially the dialog should not be visible until all widgets are added to it.
 924  When no flags for visibility and modality are specified, <tt>nil</tt> is assumed. A modal dialog will
 925  prevent input in the parent window. Components can be added to a dialog using <tt>gs:add-to</tt>.
 926  Use the <tt>gs:set-border-layout</tt>, <tt>ga:set-flow-layout</tt> or <tt>gs:set-grid-layout</tt> to set a specific
 927  layout.
 928
 929
 930 <p></p><center>- &sect; -</center><p></p>
 931 <a name="gs_disable"></a><h3><font color=#CC0000>gs:disable</font></h3>
 932 <b>syntax: (<font color=#CC0000>gs:disable</font> <em>sym-id-1</em> [sym-id-2 ...])</b><br/>
 933 <b>parameter: </b><em>sym-id</em> - The name of the component to disable.<br/>
 934 <p></p>
 935  Disabled components are grayed and do not accept input.
 936
 937
 938 <p></p><center>- &sect; -</center><p></p>
 939 <a name="gs_dispose"></a><h3><font color=#CC0000>gs:dispose</font></h3>
 940 <b>syntax: (<font color=#CC0000>gs:dispose</font> <em>sym-id</em>)</b><br/>
 941 <b>parameter: </b><em>sym-id</em> - The name of the component to dispose of.<br/>
 942
 943
 944 <p></p><center>- &sect; -</center><p></p>
 945 <a name="gs_dispose-splash"></a><h3><font color=#CC0000>gs:dispose-splash</font></h3>
 946 <b>syntax: (<font color=#CC0000>gs:dispose-splash</font>)</b><br/>
 947 <p></p>
 948  A splash screen can be specified when starting the newLISP-GS process before newLISP.
 949  The function <tt>gs:dispose-splash</tt> is used to turn off the splash image after
 950  the newLISP GUI application has started.
 951 <p></p>
 952 <p></p><b>example:</b><blockquote><pre> java -jar /usr/share/newlisp/guiserver.jar 4711 program.lsp /local/newLISP128.png
 953  ; or on Win32
 954  java -jar "c:\Program Files\newlisp\guiserver.jar" 4711 "newlisp program.lsp" /local/newLISPsplashWin.png</pre></blockquote>
 955  The example starts newLISP-GS with an application <tt>program.lsp</tt> and a splash
 956  screen showing the built-in newLISP logos and using port 4711. Instead, the full pathname
 957  of a different image file can be specified. Inside <tt>program.lsp</tt> the function
 958  <tt>gs:dispose-splash</tt> or a mouse click on the image will turn off the splash screen.
 959  For <tt>program.lsp</tt> the full pathname may be necessary. On Win32 quotes are necessary to bracket
 960  arguments to <tt>guiserver.jar</tt> which contain spaces.
 961
 962
 963 <p></p><center>- &sect; -</center><p></p>
 964 <a name="gs_draw-arc"></a><h3><font color=#CC0000>gs:draw-arc</font></h3>
 965 <b>syntax: (<font color=#CC0000>gs:draw-arc</font> <em>sym-tag</em> <em>int-x</em> <em>int-y</em> <em>int-width</em> <em>int-height</em> <em>int-start</em> <em>int-angle</em> [<em>list-rgb</em>])</b><br/>
 966 <b>parameter: </b><em>sym-tag</em> - The tag group of the arc.<br/>
 967 <b>parameter: </b><em>int-x</em> - The X position of the arc.<br/>
 968 <b>parameter: </b><em>int-y</em> - The Y position of the arc.<br/>
 969 <b>parameter: </b><em>int-width</em> - The width of the arc.<br/>
 970 <b>parameter: </b><em>int-height</em> - The height of the arc.<br/>
 971 <b>parameter: </b><em>int-start-angle</em> - The start angle of the arc in 0 to 360 degrees.<br/>
 972 <b>parameter: </b><em>int-arc-angle</em> - The opening angle of the arc in 0 to 360 degrees.<br/>
 973 <b>parameter: </b><em>list-rgb</em> - The outline color as a list of 3 numbers for the rgb components<br/>
 974 <p></p>
 975  The resulting arc begins at <em>int-start-angle</em> and extends for <em>int-arc-angle degrees</em>,
 976  using the current color. Angles are interpreted such that 0 degrees is at the 3 o'clock
 977  position. A positive value indicates a counter-clockwise rotation while a negative value
 978  indicates a clockwise rotation.
 979 <p></p>
 980  The center of the arc is the center of the rectangle whose origin is (x, y) and whose size
 981  is specified by the width and height arguments.
 982 <p></p>
 983  The resulting arc covers an area <em>int-width</em> pixels wide by <em>int-height</em> pixels tall.
 984
 985
 986
 987 <p></p><center>- &sect; -</center><p></p>
 988 <a name="gs_draw-circle"></a><h3><font color=#CC0000>gs:draw-circle</font></h3>
 989 <b>syntax: (<font color=#CC0000>gs:draw-circle</font> <em>sym-tag</em> <em>int-x</em> <em>int-y</em> <em>int-radius</em> [<em>list-rgb</em>])</b><br/>
 990 <b>parameter: </b><em>sym-tag</em> - The tag group of the circle.<br/>
 991 <b>parameter: </b><em>int-x</em> - The X position of the circle center.<br/>
 992 <b>parameter: </b><em>int-y</em> - The Y position of the circle center.<br/>
 993 <b>parameter: </b><em>int-radius</em> - The radius of the circle.<br/>
 994 <b>parameter: </b><em>list-rgb</em> - The outline color as a list of 3 numbers for the rgb components<br/>
 995 <p></p>
 996  Creates the outline of a circle. The color numbers must be entered in list form.
 997  If no <em>list-rgb</em> is used the current paint specified with <tt>gs:set-paint</tt> is used.
 998
 999
1000 <p></p><center>- &sect; -</center><p></p>
1001 <a name="gs_draw-ellipse"></a><h3><font color=#CC0000>gs:draw-ellipse</font></h3>
1002 <b>syntax: (<font color=#CC0000>gs:draw-ellipse</font> <em>sym-tag</em> <em>int-x</em> <em>int-y</em> <em>int-radius-x</em> <em>int-radius-y</em> [<em>list-rgb</em>])</b><br/>
1003 <b>parameter: </b><em>sym-tag</em> - The tag group of the ellipse.<br/>
1004 <b>parameter: </b><em>int-x</em> - The X position of the ellipse center.<br/>
1005 <b>parameter: </b><em>int-y</em> - The Y position of the ellipse center.<br/>
1006 <b>parameter: </b><em>int-radius-x</em> - The radius of the ellipse.<br/>
1007 <b>parameter: </b><em>int-radius-y</em> - The radius of the ellipse.<br/>
1008 <b>parameter: </b><em>list-rgb</em> - The outline color as a list of 3 numbers for the rgb components<br/>
1009 <p></p>
1010  Creates the outline of an ellipse. The color numbers must be enterd in list form.
1011  If no <em>list-rgb</em> is used the current paint specified with <tt>gs:set-paint</tt> is used.
1012
1013
1014 <p></p><center>- &sect; -</center><p></p>
1015 <a name="gs_draw-image"></a><h3><font color=#CC0000>gs:draw-image</font></h3>
1016 <b>syntax: (<font color=#CC0000>gs:draw-image</font> <em>sym-tag</em> <em>str-path</em> <em>int-x</em> <em>int-y</em> [<em>int-width</em> <em>int-height</em>])</b><br/>
1017 <b>parameter: </b><em>sym-tag</em> - The tag group of the image.<br/>
1018 <b>parameter: </b><em>int-x</em> - The X position of the image top left corner.<br/>
1019 <b>parameter: </b><em>int-y</em> - The Y position of the image top left corner.<br/>
1020 <b>parameter: </b><em>int-width</em> - The optional width in which to draw the image.<br/>
1021 <b>parameter: </b><em>int-height</em> - The optional height in which to draw the image.<br/>
1022 <p></p>
1023  When <em>int-width</em> and <em>int-height</em> parameters are specified and they are not
1024  equal to the original size of the image (measured in pixels) the image will
1025  be displayed in either compressed or zoomed form.
1026
1027
1028 <p></p><center>- &sect; -</center><p></p>
1029 <a name="gs_draw-line"></a><h3><font color=#CC0000>gs:draw-line</font></h3>
1030 <b>syntax: (<font color=#CC0000>gs:draw-line</font> <em>sym-tag</em> <em>int-x1</em> <em>int-y1</em> <em>int-x2</em> <em>int-y2</em> [<em>list-rgb</em>])</b><br/>
1031 <b>parameter: </b><em>sym-tag</em> - The tage of the line.<br/>
1032 <b>parameter: </b><em>int-x1</em> - The X position of the first point.<br/>
1033 <b>parameter: </b><em>int-y1</em> - The Y position of the first point.<br/>
1034 <b>parameter: </b><em>int-x2</em> - The X position of the second point.<br/>
1035 <b>parameter: </b><em>int-y2</em> - The Y position of the second point.<br/>
1036 <p></p>
1037  Draws a line. The color numbers must be entered in list form.
1038  If no <em>list-rgb</em> is used the current paint specified with <tt>gs:set-paint</tt> is used.
1039
1040
1041 <p></p><center>- &sect; -</center><p></p>
1042 <a name="gs_draw-path"></a><h3><font color=#CC0000>gs:draw-path</font></h3>
1043 <b>syntax: (<font color=#CC0000>gs:draw-path</font> <em>sym-tag</em> <em>list-points</em> [<em>list-rgb</em>])</b><br/>
1044 <b>parameter: </b><em>sym-tag</em> - The tage group of the path.<br/>
1045 <b>parameter: </b><em>list-points</em> - The list of x and y coordinates of the points.<br/>
1046 <p></p>
1047  Draws a path with the points found in <em>list-points</em>.
1048 <p></p>
1049 <p></p><b>example:</b><blockquote><pre> (gs:draw-path 'P '(1 0 2 2 3 0))</pre></blockquote>
1050  The example will draw an upwards-pointing triangle without base at the
1051  points <tt>1,0</tt>, <tt>2,2</tt> and <tt>3,0</tt>
1052
1053
1054 <p></p><center>- &sect; -</center><p></p>
1055 <a name="gs_draw-polygon"></a><h3><font color=#CC0000>gs:draw-polygon</font></h3>
1056 <b>syntax: (<font color=#CC0000>gs:draw-polygon</font> <em>sym-tag</em> <em>list-points</em> [<em>list-rgb</em>])</b><br/>
1057 <b>parameter: </b><em>sym-tag</em> - The tag group of the polygon.<br/>
1058 <b>parameter: </b><em>list-points</em> - The list of x and y coordinates of the points.<br/>
1059 <p></p>
1060  Draws a polygon with the points found in <em>list-points</em>.
1061 <p></p>
1062 <p></p><b>example:</b><blockquote><pre> (gs:draw-polygon 'P '(1 0 2 2 3 0))</pre></blockquote>
1063  The example will draw an upwards-pointing triangle with the points <tt>1,0</tt>, <tt>2,2</tt>
1064  and <tt>3,0</tt>.
1065
1066
1067
1068 <p></p><center>- &sect; -</center><p></p>
1069 <a name="gs_draw-rect"></a><h3><font color=#CC0000>gs:draw-rect</font></h3>
1070 <b>syntax: (<font color=#CC0000>gs:draw-rect</font> <em>sym-tag</em> <em>int-x</em> <em>int-y</em> <em>int-width</em> <em>int-height</em> [<em>list-rgb</em>])</b><br/>
1071 <b>parameter: </b><em>sym-tag</em> - The tag group of the rectangle.<br/>
1072 <b>parameter: </b><em>int-x</em> - The X position of the top left corner.<br/>
1073 <b>parameter: </b><em>int-y</em> - The Y position of the top left corner.<br/>
1074 <b>parameter: </b><em>int-width</em> - The width of the rectangle.<br/>
1075 <b>parameter: </b><em>int-height</em> - The height of the rectangle..<br/>
1076 <b>parameter: </b><em>list-rgb</em> - The outline color as a list of 3 numbers for the rgb components<br/>
1077 <p></p>
1078  Creates the outline of a rectangle. The color numbers must be entered in list form.
1079  If no <em>list-rgb</em> is used the current paint specified with <tt>gs:set-paint</tt> is used.
1080
1081
1082
1083 <p></p><center>- &sect; -</center><p></p>
1084 <a name="gs_draw-round-rect"></a><h3><font color=#CC0000>gs:draw-round-rect</font></h3>
1085 <b>syntax: (<font color=#CC0000>gs:draw-round-rect</font> <em>sym-tag</em> <em>int-x</em> <em>int-y</em> <em>int-width</em> <em>int-height</em> <em>int-arc-width</em> <em>int-arc-height</em> [<em>list-rgb</em>])</b><br/>
1086 <b>parameter: </b><em>sym-tag</em> - The tag group of the round rectangle.<br/>
1087 <b>parameter: </b><em>int-x</em> - The X position of the top left corner.<br/>
1088 <b>parameter: </b><em>int-y</em> - The Y position of the top left corner.<br/>
1089 <b>parameter: </b><em>int-width</em> - The width of the rectangle.<br/>
1090 <b>parameter: </b><em>int-height</em> - The height of the rectangle..<br/>
1091 <b>parameter: </b><em>int-arc-width</em> - The width of the corner rectangle.<br/>
1092 <b>parameter: </b><em>int-arc-height</em> - The height of the corner rectangle..<br/>
1093 <b>parameter: </b><em>list-rgb</em> - The outline color as a list of 3 numbers for the rgb components<br/>
1094 <p></p>
1095  Draws a rectangle shape with round corners. The rounding is defined by the rectangle enclosing
1096  the rounding arc.
1097
1098
1099
1100 <p></p><center>- &sect; -</center><p></p>
1101 <a name="gs_draw-text"></a><h3><font color=#CC0000>gs:draw-text</font></h3>
1102 <b>syntax: (<font color=#CC0000>gs:draw-text</font> <em>sym-tag</em> <em>str-text</em> <em>int-x</em> <em>int-y</em> [<em>list-rgb</em> [<em>float-angle</em>])</b><br/>
1103 <b>parameter: </b><em>sym-tag</em> - The tag group of the text.<br/>
1104 <b>parameter: </b><em>str-text</em> - The text to be drawn.<br/>
1105 <b>parameter: </b><em>int-x</em> - The X position of the text.<br/>
1106 <b>parameter: </b><em>int-y</em> - The Y position of the text.<br/>
1107 <b>parameter: </b><em>list-rgb</em> - The optonal color for the text.<br/>
1108 <b>parameter: </b><em>float-angle</em> - The optional angle for text in degrees<br/>
1109 <p></p>
1110  If no <em>list-rgb</em> is used, the current paint specified with <tt>gs:set-paint</tt> is used.
1111  The optional angle is <tt>0</tt> by default for horizontal text. A value of <tt>90</tt>
1112  will rotate the text around the <tt>x</tt>, <tt>y</tt> position downwards clockwise.
1113
1114
1115
1116
1117
1118 <p></p><center>- &sect; -</center><p></p>
1119 <a name="gs_enable"></a><h3><font color=#CC0000>gs:enable</font></h3>
1120 <b>syntax: (<font color=#CC0000>gs:enable</font> <em>sym-id-1</em> [sym-id-2 ...])</b><br/>
1121 <b>parameter: </b><em>sym-id</em> - The name of a component to enable.<br/>
1122 <p></p>
1123  Components are enabled by default.
1124
1125
1126 <p></p><center>- &sect; -</center><p></p>
1127 <a name="gs_eva-shell"></a><h3><font color=#CC0000>gs:eva-shell</font></h3>
1128 <b>syntax: (<font color=#CC0000>gs:eva-shell</font> <em>sym-id-text-area</em> <em>str-command</em>)</b><br/>
1129 <b>parameter: </b><em>sym-id-text-area</em> - The name of the text are in which to evaluate text.<br/>
1130 <b>parameter: </b><em>str-command</em> - The text to evaluate in the shell.<br/>
1131
1132
1133 <p></p><center>- &sect; -</center><p></p>
1134 <a name="gs_export"></a><h3><font color=#CC0000>gs:export</font></h3>
1135 <b>syntax: (<font color=#CC0000>gs:export</font> <em>str-path-file</em> [<em>int-width</em> <em>int-height</em>])</b><br/>
1136 <b>parameter: </b><em>str-path-file</em> - The path and file name of the image file to write to.<br/>
1137 <b>parameter: </b><em>int-width</em> - The optional width of the image in pixels.<br/>
1138 <b>parameter: </b><em>int-height</em> - The optional height of the image in pixels.<br/>
1139 <p></p>
1140  If no width and height are specified, the current size of the canvas is assumed.
1141 <p></p>
1142 <p></p><b>example:</b><blockquote><pre>
1143  (gs:export "/usr/home/pictures/mypic.png")</pre></blockquote>
1144  This will generate a <tt>.png</tt> file exactly as the image seen on the screen.
1145  The color format is RGBA with 8 bit per color and an alpha channel. When
1146  no background color is defined for the canvas, the background will be
1147  transparent.
1148 <p></p>
1149  When specifying width and height, a smaller or bigger portion of the canvas
1150  than seen on the screen is printed to the image.
1151
1152
1153 <p></p><center>- &sect; -</center><p></p>
1154 <a name="gs_fill-arc"></a><h3><font color=#CC0000>gs:fill-arc</font></h3>
1155 <b>syntax: (<font color=#CC0000>gs:fill-arc</font> <em>sym-tag</em> <em>int-x</em> <em>int-y</em> <em>int-width</em> <em>int-height</em> <em>int-start</em> <em>int-angle</em> [<em>list-rgb</em>])</b><br/>
1156 <b>parameter: </b><em>sym-tag</em> - The tag group of the arc.<br/>
1157 <b>parameter: </b><em>int-x</em> - The X position of the arc.<br/>
1158 <b>parameter: </b><em>int-y</em> - The Y position of the arc.<br/>
1159 <b>parameter: </b><em>int-width</em> - The width of the arc.<br/>
1160 <b>parameter: </b><em>int-height</em> - The height of the arc.<br/>
1161 <b>parameter: </b><em>int-start-angle</em> - The start angle of the arc in 0 to 360 degrees.<br/>
1162 <b>parameter: </b><em>int-arc-angle</em> - The opening angle of the arc in 0 to 360 degrees.<br/>
1163 <b>parameter: </b><em>list-rgb</em> - The outline color as a list of 3 numbers for the rgb components.<br/>
1164 <p></p>
1165  The resulting arc begins at <em>int-start-angle</em> and extends for <em>int-arc-angle degrees</em>,
1166  using the current color. Angles are interpreted such that 0 degrees is at the 3 o'clock
1167  position. A positive value indicates a counter-clockwise rotation while a negative value
1168  indicates a clockwise rotation.
1169 <p></p>
1170  The center of the arc is the center of the rectangle whose origin is (x, y) and whose size
1171  is specified by the width and height arguments.
1172 <p></p>
1173  The resulting arc covers an area <em>int-width</em> pixels wide by <em>int-height</em> pixels tall.
1174
1175
1176 <p></p><center>- &sect; -</center><p></p>
1177 <a name="gs_fill-circle"></a><h3><font color=#CC0000>gs:fill-circle</font></h3>
1178 <b>syntax: (<font color=#CC0000>gs:fill-circle</font> <em>sym-tag</em> <em>int-x</em> <em>int-y</em> <em>int-radius</em> [<em>list-rgb</em>])</b><br/>
1179 <b>parameter: </b><em>sym-tag</em> - The tag group of the circle.<br/>
1180 <b>parameter: </b><em>int-x</em> - The X position of the circle center.<br/>
1181 <b>parameter: </b><em>int-y</em> - The Y position of the circle center.<br/>
1182 <b>parameter: </b><em>int-radius</em> - The radius of the circle.<br/>
1183 <b>parameter: </b><em>list-rgb</em> - The outline color as a list of 3 numbers for the rgb components.<br/>
1184 <p></p>
1185  Creates a filled  circle. The color numbers must be entered in list form.
1186  If no <em>list-rgb</em> is used, the current paint specified with <tt>gs:set-paint</tt> is used.
1187
1188
1189 <p></p><center>- &sect; -</center><p></p>
1190 <a name="gs_fill-ellipse"></a><h3><font color=#CC0000>gs:fill-ellipse</font></h3>
1191 <b>syntax: (<font color=#CC0000>gs:fill-ellipse</font> <em>sym-tag</em> <em>int-x</em> <em>int-y</em> <em>int-radius-x</em> <em>int-radius-y</em> [<em>list-rgb</em>])</b><br/>
1192 <b>parameter: </b><em>sym-tag</em> - The tag group of the ellipse.<br/>
1193 <b>parameter: </b><em>int-x</em> - The X position of the ellipse center.<br/>
1194 <b>parameter: </b><em>int-y</em> - The Y position of the ellipse center.<br/>
1195 <b>parameter: </b><em>int-radius-x</em> - The radius of the ellipse.<br/>
1196 <b>parameter: </b><em>int-radius-y</em> - The radius of the ellipse.<br/>
1197 <b>parameter: </b><em>list-rgb</em> - The fill color as a list of 3 numbers for the rgb components.<br/>
1198 <p></p>
1199  Creates a filled ellipse. The color numbers must be entered in list form.
1200  If no <em>list-rgb</em> is used, the current paint specified with <tt>gs:set-paint</tt> is used.
1201
1202
1203 <p></p><center>- &sect; -</center><p></p>
1204 <a name="gs_fill-polygon"></a><h3><font color=#CC0000>gs:fill-polygon</font></h3>
1205 <b>syntax: (<font color=#CC0000>gs:fill-polygon</font> <em>sym-tag</em> <em>list-points</em> [<em>list-color</em>])</b><br/>
1206 <b>parameter: </b><em>sym-tag</em> - The tag group of the polygon.<br/>
1207 <b>parameter: </b><em>list-points</em> - The list of x and y coordinates of the points.<br/>
1208 <p></p>
1209  Draws a polygon with the points found in <em>list-points</em> and fills it with
1210  the current color set with <tt>gs:set-paint</tt> or the optional color
1211  given in <em>list-color</em>.
1212 <p></p>
1213 <p></p><b>example:</b><blockquote><pre> (gs:fill-polygon 'P '(1 0 2 2 3 0))
1214
1215  (gs:fill-polygon 'P '(1 0 2 2 3 0) gs:gray)</pre></blockquote>
1216  The example will fill an upwards pointing triangle with the points <tt>1,0</tt>, <tt>2,2</tt>
1217  and <tt>3,0</tt> and fill it with the current color set with <tt>gs:set-paint</tt>. The second
1218  example paints a gray triangle regardless of the current color set with
1219  <tt>gs:set-paint</tt>.
1220
1221
1222 <p></p><center>- &sect; -</center><p></p>
1223 <a name="gs_fill-rect"></a><h3><font color=#CC0000>gs:fill-rect</font></h3>
1224 <b>syntax: (<font color=#CC0000>gs:fill-rect</font> <em>sym-tag</em> <em>int-x</em> <em>int-y</em> <em>int-width</em> <em>int-height</em> [<em>list-rgb</em>])</b><br/>
1225 <b>parameter: </b><em>sym-tag</em> - The tag group of the rectangle.<br/>
1226 <b>parameter: </b><em>int-x</em> - The X position of the top left corner.<br/>
1227 <b>parameter: </b><em>int-y</em> - The Y position of the top left corner.<br/>
1228 <b>parameter: </b><em>int-width</em> - The width of the rectangle.<br/>
1229 <b>parameter: </b><em>int-height</em> - The height of the rectangle.<br/>
1230 <b>parameter: </b><em>list-rgb</em> - The fill color as a list of 3 numbers for the rgb components.<br/>
1231 <p></p>
1232  Creates a filled rectangle. The color numbers must be entered in list form.
1233  If no <em>list-rgb</em> is used, the current paint specified with <tt>gs:set-paint</tt> is used.
1234
1235
1236 <p></p><center>- &sect; -</center><p></p>
1237 <a name="gs_fill-round-rect"></a><h3><font color=#CC0000>gs:fill-round-rect</font></h3>
1238 <b>syntax: (<font color=#CC0000>gs:fill-round-rect</font> <em>sym-tag</em> <em>int-x</em> <em>int-y</em> <em>int-width</em> <em>int-height</em> <em>int-arc-width</em> <em>int-arc-height</em> [<em>list-rgb</em>])</b><br/>
1239 <b>parameter: </b><em>sym-tag</em> - The tag group of the round rectangle.<br/>
1240 <b>parameter: </b><em>int-x</em> - The X position of the top left corner.<br/>
1241 <b>parameter: </b><em>int-y</em> - The Y position of the top left corner.<br/>
1242 <b>parameter: </b><em>int-width</em> - The width of the rectangle.<br/>
1243 <b>parameter: </b><em>int-height</em> - The height of the rectangle..<br/>
1244 <b>parameter: </b><em>int-arc-width</em> - The width of the corner rectangle.<br/>
1245 <b>parameter: </b><em>int-arc-height</em> - The height of the corner rectangle.<br/>
1246 <b>parameter: </b><em>list-rgb</em> - The outline color as a list of 3 numbers for the rgb components.<br/>
1247 <p></p>
1248  Paints a rectangle shape with round corners. The rounding is defined by the rectangle enclosing
1249  the rounding arc.
1250
1251
1252 <p></p><center>- &sect; -</center><p></p>
1253 <a name="gs_find-text"></a><h3><font color=#CC0000>gs:find-text</font></h3>
1254 <b>syntax: (<font color=#CC0000>gs:find-text</font> <em>sym-id</em> <em>str-text</em> <em>sym-action</em> [<em>str-direction</em>])</b><br/>
1255 <b>parameter: </b><em>sym-id</em> - The name of the textr area or text pane.<br/>
1256 <b>parameter: </b><em>boolean-next</em> - The optional direction string <tt>"next"</tt> (default) or <tt>"previous"</tt>.<br/>
1257 <b>parameter: </b><em>sym-action</em> - A optional action to peform after find-text.<br/>
1258 <p></p>
1259  The text area or text pane will be searched starting at the current caret position
1260  forward or backwards depending on the optional direction field. After the search
1261  the found text is highlighted. If the optional <em>sym-action</em> is specified an event
1262  containing the id of the text area or pane and found position or <tt>-1</tt> will be fired.
1263
1264
1265
1266
1267 <p></p><center>- &sect; -</center><p></p>
1268 <a name="gs_frame"></a><h3><font color=#CC0000>gs:frame</font></h3>
1269 <b>syntax: (<font color=#CC0000>gs:frame</font> <em>sym-id</em> <em>int-x</em> <em>int-y</em> <em>int-width</em> <em>int-height</em> [<em>str-title</em> <em>boolean-visible</em>])</b><br/>
1270 <b>parameter: </b><em>sym-id</em> - The name of the frame window.<br/>
1271 <b>parameter: </b><em>int-x</em> - The X position of the top left window corner.<br/>
1272 <b>parameter: </b><em>int-y</em> - The Y position of the top left windows corner.<br/>
1273 <b>parameter: </b><em>int-width</em> - The width of the window frame.<br/>
1274 <b>parameter: </b><em>int-height</em> - The height of the windows frame.<br/>
1275 <b>parameter: </b><em>str-title</em> - The optional title of the window.<br/>
1276 <b>parameter: </b><em>boolean-visible</em> - The optional flag with a value of <tt>true</tt> or <tt>nil</tt> for the visibility of the window.<br/>
1277 <p></p>
1278  Initially the frame should not be visible until all widgets are added to it.
1279  When no flag for visibility is specified <tt>nil</tt> is assumed. The default layout of a frame behaves
1280  like a grid layout with one cell. Use the <tt>set-flow-layout</tt>, <tt>set-border-layout</tt> and
1281  <tt>set-grid-layout</tt> to change the layout.
1282
1283
1284
1285 <p></p><center>- &sect; -</center><p></p>
1286 <a name="gs_get-bounds"></a><h3><font color=#CC0000>gs:get-bounds</font></h3>
1287 <b>syntax: (<font color=#CC0000>gs:get-bounds</font> <em>sym-id</em>)</b><br/>
1288 <b>parameter: </b><em>sym-id</em> - The id of the component for which to get the list of bounding values.<br/>
1289 <p><b>return: </b>The bounding list <tt>(<em>x</em> <em>y</em> <em>width</em> <em>height</em>)</tt></p>
1290
1291
1292 <p></p><center>- &sect; -</center><p></p>
1293 <a name="gs_get-fonts"></a><h3><font color=#CC0000>gs:get-fonts</font></h3>
1294 <b>syntax: (<font color=#CC0000>gs:get-fonts</font>)</b><br/>
1295 <p><b>return: </b>A list of family names for fonts on the current system.</p>
1296 <p></p>
1297  The function should be called only once because it may take considerable
1298  time in a system loaded with many fonts. The variable <tt>gs:fonts</tt> contains
1299  the same list of fonts originally returned by a call to <tt>gs:get-fonts</tt>.
1300
1301
1302 <p></p><center>- &sect; -</center><p></p>
1303 <a name="gs_get-font-metrics"></a><h3><font color=#CC0000>gs:get-font-metrics</font></h3>
1304 <b>syntax: (<font color=#CC0000>gs:get-font-metrics</font> <em>sym-id</em> <em>str-text</em>)</b><br/>
1305 <p><b>return: </b>A list of the two values for width and height in pixels.</p>
1306 <p></p>
1307  The font metrics for the currently set font in <em>sym-id</em> are returned as a list
1308  of width and height in pixels when displaying the string in <em>str-text</em>.
1309  After the function call the variable <tt>gs:font-metrics</tt> contains the same list
1310  of values as originally returned by the call to <tt>gs:get-font-metrics</tt>.
1311
1312
1313
1314 <p></p><center>- &sect; -</center><p></p>
1315 <a name="gs_get-screen"></a><h3><font color=#CC0000>gs:get-screen</font></h3>
1316 <b>syntax: (<font color=#CC0000>gs:get-screen</font>)</b><br/>
1317 <p><b>return: </b>A list of screen width, height and resolution of the main computer screen.</p>
1318 <p></p>
1319  After calling the <tt>gs:get-screen</tt> once the screen parameters are also available
1320  in the variable <tt>gs:screen</tt>.
1321
1322
1323
1324 <p></p><center>- &sect; -</center><p></p>
1325 <a name="gs_get-selected-text"></a><h3><font color=#CC0000>gs:get-selected-text</font></h3>
1326 <b>syntax: (<font color=#CC0000>gs:get-selected-text</font> <em>sym-id</em> <em>sym-action</em>)</b><br/>
1327 <b>parameter: </b><em>sym-id</em> - The name of the component from which to get the selected text.<br/>
1328 <b>parameter: </b><em>sym-action</em> - The symbol of the event handler which will receive the selected text.<br/>
1329
1330
1331
1332
1333 <p></p><center>- &sect; -</center><p></p>
1334 <a name="gs_get-text"></a><h3><font color=#CC0000>gs:get-text</font></h3>
1335 <b>syntax: (<font color=#CC0000>gs:get-text</font> <em>sym-id</em> [<em>sym-action</em>])</b><br/>
1336 <b>parameter: </b><em>sym-id</em> - The name of the component from which to get the text.<br/>
1337 <b>parameter: </b><em>sym-action</em> - The optional symbol of the event handler which will receive the text.<br/>
1338 <p></p>
1339  If no <em>sym-action</em> is specified the function will block until the text is returned.
1340  After return the text is also available in the variable <tt>gs:text</tt>.
1341  If <em>sym-action</em> is specified the function will return immediately and a <em>sym-action</em> event
1342  is fired containing the text.
1343
1344
1345
1346 <p></p><center>- &sect; -</center><p></p>
1347 <a name="gs_get-text-position"></a><h3><font color=#CC0000>gs:get-text-position</font></h3>
1348 <b>syntax: (<font color=#CC0000>gs:get-text-position</font> <em>sym-id</em>)</b><br/>
1349 <b>parameter: </b><em>sym-id</em> - The name of the text component for which the line and column position is returned.<br/>
1350 <p><b>return: </b>A list of line and column position of the text caret.</p>
1351 <p></p>
1352 <p></p><center>- &sect; -</center><p></p>
1353 <a name="gs_get-version"></a><h3><font color=#CC0000>gs:get-version</font></h3>
1354 <b>syntax: (<font color=#CC0000>gs:get-version</font>)</b><br/>
1355 <p><b>return: </b>The version string of newLISP-GS running.</p>
1356 <p></p>
1357  After calling the <tt>gs:get-version</tt> once the version number is also
1358  available in <tt>gs:version</tt>.
1359
1360
1361 <p></p><center>- &sect; -</center><p></p>
1362 <a name="gs_goto-text"></a><h3><font color=#CC0000>gs:goto-text</font></h3>
1363 <b>syntax: (<font color=#CC0000>gs:goto-text</font> <em>sym-id</em> <em>int-row</em> <em>int-column</em>)</b><br/>
1364 <b>parameter: </b><em>sym-id</em> - The name of the text widget.<br/>
1365 <b>parameter: </b><em>int-row</em> - The row number where to place the cursor.<br/>
1366 <b>parameter: </b><em>int-column</em> - The column number where to place the cursor.<br/>
1367
1368
1369
1370
1371 <p></p><center>- &sect; -</center><p></p>
1372 <a name="gs_hide-tag"></a><h3><font color=#CC0000>gs:hide-tag</font></h3>
1373 <b>syntax: (<font color=#CC0000>gs:hide-tag</font> <em>sym-tag</em> [<em>boolean-repaint</em>])</b><br/>
1374 <b>parameter: </b><em>sym-tag</em> - The tag of the group to hide.<br/>
1375 <b>parameter: </b><em>boolean-repaint</em> - An optional flag to indicate if repainting is required (default is <tt>true</tt>).<br/>
1376 <p></p>
1377 <p></p><center>- &sect; -</center><p></p>
1378 <a name="gs_image-button"></a><h3><font color=#CC0000>gs:image-button</font></h3>
1379 <b>syntax: (<font color=#CC0000>gs:image-button</font> <em>sym-id</em> <em>sym-action</em> <em>str-icon-path</em> [<em>str-down-icon-path</em> [<em>int-width</em> <em>int-height</em>]])</b><br/>
1380 <b>parameter: </b><em>sym-id</em> - The name of the image button.<br/>
1381 <b>parameter: </b><em>sym-action</em> - The name of the event handler.<br/>
1382 <b>parameter: </b><em>str-icon-path</em> - The path for an image icon.<br/>
1383 <b>parameter: </b><em>str-down-con-path</em> - The path for a pressed down image icon.<br/>
1384 <b>parameter: </b><em>int-width</em> - The optional width of the image button.<br/>
1385 <b>parameter: </b><em>int-height</em> - The optional height of the image button.<br/>
1386
1387
1388 <p></p><center>- &sect; -</center><p></p>
1389 <a name="gs_image-label"></a><h3><font color=#CC0000>gs:image-label</font></h3>
1390 <b>syntax: (<font color=#CC0000>gs:image-label</font> <em>sym-id</em> <em>str-icon-path</em> [<em>str-align</em>])</b><br/>
1391 <b>parameter: </b><em>sym-id</em> - The name of the label.<br/>
1392 <b>parameter: </b><em>str-ucon-path</em> - A string with the icon file path.<br/>
1393 <b>parameter: </b><em>str-align</em> - An optional alignment <tt>"left"</tt>, <tt>"center"</tt> or <tt>"right"</tt>, <tt>"leading"</tt>, <tt>"trailing"</tt>, <tt>"bottom"</tt> or <tt>"top"</tt>.<br/>
1394
1395
1396
1397 <p></p><center>- &sect; -</center><p></p>
1398 <a name="gs_init"></a><h3><font color=#CC0000>gs:init</font></h3>
1399 <b>syntax: (<font color=#CC0000>gs:init</font> [<em>int-port</em> <em>str-host</em>])</b><br/>
1400 <b>parameter: </b><em>int-port</em> - The optional guiserver server port.<br/>
1401 <b>parameter: </b><em>str-host</em> - The optional remote host of the guiserver.<br/>
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411 <p></p><center>- &sect; -</center><p></p>
1412 <a name="gs_insert-list-item"></a><h3><font color=#CC0000>gs:insert-list-item</font></h3>
1413 <b>syntax: (<font color=#CC0000>gs:insert-list-item</font> <em>sym-list-combo</em> <em>str-text</em> <em>int-index</em> [<em>str-text</em> <em>int-index</em>])</b><br/>
1414 <b>parameter: </b><em>sym-list-combo</em> - The name of the combo box or list box from which entries are removed.<br/>
1415 <b>parameter: </b><em>str-text</em> - The text of the list or combo box item to insert.<br/>
1416 <b>parameter: </b><em>int-index</em> - The index of an entry to add to the list or combo box.<br/>
1417 <p></p>
1418  When specifying an index of <tt>0</tt> the first item gets inserted at the beginning.
1419  When specifying an index equal or greater to the number of items in the list, the item
1420  is added at the end.
1421
1422
1423 <p></p><center>- &sect; -</center><p></p>
1424 <a name="gs_insert-tab"></a><h3><font color=#CC0000>gs:insert-tab</font></h3>
1425 <b>syntax: (<font color=#CC0000>gs:insert-tab</font> <em>sym-tabbed-pane</em> <em>sym-component</em> [<em>str-text</em> [<em>int-index</em> [<em>str-icon-path</em>]]])</b><br/>
1426 <b>parameter: </b><em>sym-tabbed-pane</em> - The name of the tabbed pane.<br/>
1427 <b>parameter: </b><em>sym-component</em> - The name of the component to insert as a tab.<br/>
1428 <b>parameter: </b><em>str-text</em> - The optional text on the tab.<br/>
1429 <b>parameter: </b><em>int-index</em> - The optional index where to insert the new tab.<br/>
1430 <b>parameter: </b><em>str-icon-path</em> - The file path to an optional icon.<br/>
1431
1432
1433 <p></p><center>- &sect; -</center><p></p>
1434 <a name="gs_insert-text"></a><h3><font color=#CC0000>gs:insert-text</font></h3>
1435 <b>syntax: (<font color=#CC0000>gs:insert-text</font> <em>sym-id</em> <em>str-text</em> <em>int-position</em>)</b><br/>
1436 <b>parameter: </b><em>sym-id</em> - The name of the text component.<br/>
1437 <b>parameter: </b><em>str-text</em> - The text to insert.<br/>
1438 <b>parameter: </b><em>int-position</em> - The offset position where to insert the text.<br/>
1439
1440
1441 <p></p><center>- &sect; -</center><p></p>
1442 <a name="gs_key-event"></a><h3><font color=#CC0000>gs:key-event</font></h3>
1443 <b>syntax: (<font color=#CC0000>gs:key-event</font> <em>sym-id</em> <em>sym-action</em>)</b><br/>
1444 <b>parameter: </b><em>sym-canvas</em> - The id of the component to register the action handler.<br/>
1445 <b>parameter: </b><em>sym-action</em> - The symbol of the action handler.<br/>
1446 <p></p>
1447  <tt>gs:key-event</tt> can be used to register a general unspecific key event handler
1448  for any component in the system. Since version 1.05 of newLISP-GS this also
1449  includes text widgets, which alrady handle key events using their normal event
1450  handler function. With <tt>gs:key-event</tt> a second handler function can be registered
1451  for text widgets. Both functions will fire on their respective events.
1452 <p></p>
1453  Components respond to the following key event types: <tt>"pressed"</tt>, <tt>"released"</tt>, <tt>"typed"</tt>.
1454 <p></p>
1455 <p></p><b>example:</b><blockquote><pre>
1456  (define (key-action id type code modifiers)
1457      (println "id:" id " type:" type " key code:" code " modifiers:" modifiers)
1458  )</pre></blockquote>
1459  The example shows a handler which prints all key event parameters to the terminal/shell
1460  window where the applicaton was started.
1461 <p></p>
1462  In order for key events to work, the component for which a key action handler
1463  is registered must have the input focus. Use <tt>"gs:request-focus"</tt> to set the
1464  input focus for the component.
1465
1466
1467
1468 <p></p><center>- &sect; -</center><p></p>
1469 <a name="gs_label"></a><h3><font color=#CC0000>gs:label</font></h3>
1470 <b>syntax: (<font color=#CC0000>gs:label</font> <em>sym-id</em> <em>str-text</em> [<em>str-align</em> [<em>int-width</em> <em>int-height</em>]])</b><br/>
1471 <b>parameter: </b><em>sym-id</em> - The name of the label.<br/>
1472 <b>parameter: </b><em>str-text</em> - The text to appear on the label.<br/>
1473 <b>parameter: </b><em>str-align</em> - The optional alignment of the text.<br/>
1474 <b>parameter: </b><em>int-width</em> - The optional width of the label.<br/>
1475 <b>parameter: </b><em>int-height</em> - The optional height of the label.<br/>
1476 <p></p>
1477  The following alignment constants can be supplied: <tt>"left"</tt>, <tt>"center"</tt>, '"right"",
1478  <tt>"leading"</tt>, <tt>"trailing"</tt>, <tt>"bottom"</tt> and "<tt>top</tt>". By default each label text is
1479  <tt>"center"</tt> aligned.
1480
1481
1482
1483 <p></p><center>- &sect; -</center><p></p>
1484 <a name="gs_layout"></a><h3><font color=#CC0000>gs:layout</font></h3>
1485 <b>syntax: (<font color=#CC0000>gs:layout</font> <em>sym-container</em>)</b><br/>
1486 <b>parameter: </b><em>sym-container</em> - The id of the container to lay out.<br/>
1487 <p></p>
1488  Forces the container to lay out its components again, e.g. after a <tt>gs:add-to</tt> or <tt>gs:remove-from</tt>
1489  when the container was already visible.
1490
1491
1492 <p></p><center>- &sect; -</center><p></p>
1493 <a name="gs_load-text"></a><h3><font color=#CC0000>gs:load-text</font></h3>
1494 <b>syntax: (<font color=#CC0000>gs:load-text</font> <em>sym-id</em> <em>str-path</em>)</b><br/>
1495 <b>parameter: </b><em>sym-id</em> - The id of the <tt>gs:text-pane</tt>.<br/>
1496 <b>parameter: </b><em>str-path</em> - The full path name of the file to load.<br/>
1497 <p></p>
1498  <tt>gs:load-text</tt> will load text into a <tt>gs:text-pane</tt> directly by specifying
1499  the path name. During loading, CR-LF line terminators are automatically
1500  translated to LF-only line terminators by stripping all CRs from the file. All internal
1501  operations of guiserver on text assume LF as a line terminator.
1502
1503
1504 <p></p><center>- &sect; -</center><p></p>
1505 <a name="gs_listen"></a><h3><font color=#CC0000>gs:listen</font></h3>
1506 <b>syntax: (<font color=#CC0000>gs:listen</font> [<em>boolean-flag</em>])</b><br/>
1507 <b>parameter: </b><em>boolean-flag</em> - Prevent exit on loss of communication.<br/>
1508 <p><b>return: </b>Never returns. Exits the application when the guiserver exits, except when <em>boolean-flag</em> is <tt>true</tt>.</p>
1509
1510
1511 <p></p><center>- &sect; -</center><p></p>
1512 <a name="gs_list-box"></a><h3><font color=#CC0000>gs:list-box</font></h3>
1513 <b>syntax: (<font color=#CC0000>gs:list-box</font> <em>sym-id</em> <em>sym-action</em> [<em>str-item-1</em> ...])</b><br/>
1514 <b>parameter: </b><em>sym-id</em> - The name of the list box.<br/>
1515 <b>parameter: </b><em>sym-action</em> - The name of the event handler.<br/>
1516 <b>parameter: </b><em>str-item</em> - Zero, one or more text entries in the list box.<br/>
1517 <b>syntax: (<font color=#CC0000>gs:list-box</font> <em>sym-id</em> <em>sym-action</em> [<em>list-str-items</em>])</b><br/>
1518 <b>parameter: </b><em>sym-id</em> - The name of the list box.<br/>
1519 <b>parameter: </b><em>sym-action</em> - The name of the event handler.<br/>
1520 <b>parameter: </b><em>str-item</em> - Zero, one or more text entries in the list box.<br/>
1521
1522  The listbox when clicked with the mouse, or when the [enter] key is
1523  presses, will pass the following parameters to the event handler:
1524  <br><br>
1525  <em>id</em> - the id string of the list box<br>
1526  <em>index</em> - the zero offset index of the highlighted listbox entry<br>
1527  <em>item</em> - the string of the highlighted listbox entry<br>
1528  <em>click-count</em> - the number of times the mouse has been clicked<br>
1529  </tt>
1530
1531
1532
1533 <p></p><center>- &sect; -</center><p></p>
1534 <a name="gs_message-dialog"></a><h3><font color=#CC0000>gs:message-dialog</font></h3>
1535 <b>syntax: (<font color=#CC0000>gs:message-dialog</font> <em>sym-parent-frame</em> <em>str-title</em> <em>str-message</em> [<em>str-type</em> [<em>str-icon-path</em>]])</b><br/>
1536 <b>parameter: </b><em>sym-parent-frame</em> - The symbol name of the parent frame.<br/>
1537 <b>parameter: </b><em>str-title</em> - The title of the message box.<br/>
1538 <b>parameter: </b><em>str-message</em> - The message in the message box.<br/>
1539 <b>parameter: </b><em>str-type</em> - The type of the message box.<br/>
1540 <b>parameter: </b><em>str-icon-path</em> - The optional path for an icon.<br/>
1541 <p></p>
1542  The type of the message box can be one of: <tt>"error"</tt>, <tt>"information"</tt>, <tt>"warning"</tt>, <tt>"question"</tt>, <tt>"plain"</tt>.
1543  The function initiating the message-dialog will return when the dialog is closed.
1544
1545
1546 <p></p><center>- &sect; -</center><p></p>
1547 <a name="gs_menu"></a><h3><font color=#CC0000>gs:menu</font></h3>
1548 <b>syntax: (<font color=#CC0000>gs:menu</font> <em>sym-id</em> <em>str-text</em>)</b><br/>
1549 <b>parameter: </b><em>sym-id</em> - The name of the menu.<br/>
1550 <b>parameter: </b><em>str-text</em> - The title string of the menu.<br/>
1551
1552
1553 <p></p><center>- &sect; -</center><p></p>
1554 <a name="gs_menu-popup"></a><h3><font color=#CC0000>gs:menu-popup</font></h3>
1555 <b>syntax: (<font color=#CC0000>gs:menu-popup</font> <em>sym-id</em> <em>str-text</em>)</b><br/>
1556 <b>parameter: </b><em>sym-id</em> - The name of the menu.<br/>
1557 <b>parameter: </b><em>str-text</em> - The title string of the menu.<br/>
1558
1559
1560 <p></p><center>- &sect; -</center><p></p>
1561 <a name="gs_menu-bar"></a><h3><font color=#CC0000>gs:menu-bar</font></h3>
1562 <b>syntax: (<font color=#CC0000>gs:menu-bar</font> <em>sym-frame</em> [<em>sym-menu-1</em> ...])</b><br/>
1563 <b>parameter: </b><em>sym-frame</em> - The name of the frame hosting the menu bar.<br/>
1564 <b>parameter: </b><em>sym-menu</em> - Zero or more symbol names of menus to be positioned on the menu bar.<br/>
1565
1566
1567 <p></p><center>- &sect; -</center><p></p>
1568 <a name="gs_menu-item"></a><h3><font color=#CC0000>gs:menu-item</font></h3>
1569 <b>syntax: (<font color=#CC0000>gs:menu-item</font> <em>sym-id</em> <em>sym-action</em> <em>str-text</em>)</b><br/>
1570 <b>parameter: </b><em>sym-id</em> - The name of the menu item.<br/>
1571 <b>parameter: </b><em>sym-action</em> - The name of the event handler.<br/>
1572 <b>parameter: </b><em>str-text</em> - The text to appear for the menu item.<br/>
1573
1574
1575 <p></p><center>- &sect; -</center><p></p>
1576 <a name="gs_menu-item-check"></a><h3><font color=#CC0000>gs:menu-item-check</font></h3>
1577 <b>syntax: (<font color=#CC0000>gs:menu-item-check</font> <em>sym-id</em> <em>sym-action</em> <em>str-text</em> [<em>bool-selected</em>])</b><br/>
1578 <b>parameter: </b><em>sym-id</em> - The name of the menu item.<br/>
1579 <b>parameter: </b><em>sym-action</em> - The name of the event handler.<br/>
1580 <b>parameter: </b><em>str-text</em> - The text to appear for the menu item.<br/>
1581 <b>parameter: </b><em>bool-selected</em> - An optional flag indicating the selection state <tt>true</tt> or <tt>nil</tt> (default).<br/>
1582
1583
1584 <p></p><center>- &sect; -</center><p></p>
1585 <a name="gs_mouse-clicked"></a><h3><font color=#CC0000>gs:mouse-clicked</font></h3>
1586 <b>syntax: (<font color=#CC0000>gs:mouse-clicked</font> <em>sym-canvas</em> <em>sym-action</em> [<em>boolean-tags</em>])</b><br/>
1587 <b>parameter: </b><em>sym-canvas</em> - The id of the canvas to register the action handler.<br/>
1588 <b>parameter: </b><em>sym-action</em> - The symbol of the action handler.<br/>
1589 <b>parameter: </b><em>boolean-tags</em> - A <tt>true</tt> to indicate checking for tags.<br/>
1590 <p></p>
1591  If <em>boolean-tags</em> is <tt>true</tt>, the action event will carry a list of
1592  all tags which contained the X,Y coordinates of the mouse.
1593
1594
1595 <p></p><center>- &sect; -</center><p></p>
1596 <a name="gs_mouse-dragged"></a><h3><font color=#CC0000>gs:mouse-dragged</font></h3>
1597 <b>syntax: (<font color=#CC0000>gs:mouse-dragged</font> <em>sym-canvas</em> <em>sym-action</em>)</b><br/>
1598 <b>parameter: </b><em>sym-canvas</em> - The id of the canvas to register the action handler.<br/>
1599 <b>parameter: </b><em>sym-action</em> - The symbol of the action handler.<br/>
1600
1601
1602 <p></p><center>- &sect; -</center><p></p>
1603 <a name="gs_mouse-event"></a><h3><font color=#CC0000>gs:mouse-event</font></h3>
1604 <b>syntax: (<font color=#CC0000>gs:mouse-event</font> <em>sym-id</em> <em>sym-action</em>)</b><br/>
1605 <b>parameter: </b><em>sym-canvas</em> - The id of the component to register the action handler.<br/>
1606 <b>parameter: </b><em>sym-action</em> - The symbol of the action handler.<br/>
1607 <p></p>
1608  <tt>gs:mouse-event</tt> can be used to register a general unspecific mouse event handler
1609  for any component in the system. Components respond to the following types:
1610  <tt>"pressed"</tt>, <tt>"released"</tt>, <tt>"clicked"</tt>,
1611 <p></p>
1612 <p></p><b>example:</b><blockquote><pre>
1613  (define (mouse-action id type x y button cnt mods)
1614      (println "id:" id " type:" type " x:" x " y:" y " button:" button " count:" cnt " mods:" mods)
1615  )</pre></blockquote>
1616  The example shows a handler which prints all mouse event parameters to the terminal/shell
1617  window where the applicaton was started.
1618
1619
1620
1621 <p></p><center>- &sect; -</center><p></p>
1622 <a name="gs_mouse-moved"></a><h3><font color=#CC0000>gs:mouse-moved</font></h3>
1623 <b>syntax: (<font color=#CC0000>gs:mouse-moved</font> <em>sym-canvas</em> <em>sym-action</em>)</b><br/>
1624 <b>parameter: </b><em>sym-canvas</em> - The id of the canvas to register the action handler.<br/>
1625 <b>parameter: </b><em>sym-action</em> - The symbol of the action handler.<br/>
1626 <b>parameter: </b><em>boolean-tags</em> - A <tt>true</tt> to indicate checking for tags.<br/>
1627 <p></p>
1628  If <em>boolean-tags</em> is <tt>true</tt>, the action event will carry a list of
1629  all tags which contained the X,Y coordinates of the mouse.
1630
1631
1632 <p></p><center>- &sect; -</center><p></p>
1633 <a name="gs_mouse-pressed"></a><h3><font color=#CC0000>gs:mouse-pressed</font></h3>
1634 <b>syntax: (<font color=#CC0000>gs:mouse-pressed</font> <em>sym-canvas</em> <em>sym-action</em> [<em>boolean-tags</em>])</b><br/>
1635 <b>parameter: </b><em>sym-canvas</em> - The id of the canvas to register the action handler.<br/>
1636 <b>parameter: </b><em>sym-action</em> - The symbol of the action handler.<br/>
1637 <b>parameter: </b><em>boolean-tags</em> - A <tt>true</tt> to indicate checking for tags.<br/>
1638 <p></p>
1639  If <em>boolean-tags</em> is <tt>true</tt>, the action event will carry a list of
1640  all tags which contained the X,Y coordinates of the mouse.
1641
1642
1643 <p></p><center>- &sect; -</center><p></p>
1644 <a name="gs_mouse-released"></a><h3><font color=#CC0000>gs:mouse-released</font></h3>
1645 <b>syntax: (<font color=#CC0000>gs:mouse-released</font> <em>sym-canvas</em> <em>sym-action</em> [<em>boolean-tags</em>])</b><br/>
1646 <b>parameter: </b><em>sym-canvas</em> - The id of the canvas to register the action handler.<br/>
1647 <b>parameter: </b><em>sym-action</em> - The symbol of the action handler.<br/>
1648 <b>parameter: </b><em>boolean-tags</em> - A <tt>true</tt> to indicate checking for tags.<br/>
1649 <p></p>
1650  If <em>boolean-tags</em> is <tt>true</tt>, the the action event will carry a list of
1651  all tags which contained the X,Y coordinates of the mouse.
1652
1653
1654 <p></p><center>- &sect; -</center><p></p>
1655 <a name="gs_mouse-wheel"></a><h3><font color=#CC0000>gs:mouse-wheel</font></h3>
1656 <b>syntax: (<font color=#CC0000>gs:mouse-wheel</font> <em>sym-canvas</em> <em>sym-action</em>)</b><br/>
1657 <b>parameter: </b><em>sym-canvas</em> - The id of the canvas to register the action handler.<br/>
1658 <b>parameter: </b><em>sym-action</em> - The symbol of the action handler.<br/>
1659
1660
1661 <p></p><center>- &sect; -</center><p></p>
1662 <a name="gs_move-tag"></a><h3><font color=#CC0000>gs:move-tag</font></h3>
1663 <b>syntax: (<font color=#CC0000>gs:move-tag</font> <em>sym-tag</em> <em>int-dx</em> <em>int-dy</em> [<em>boolean-repaint</em>])</b><br/>
1664 <b>parameter: </b><em>sym-tag</em> - The tag of the group of objects to move.<br/>
1665 <b>parameter: </b><em>int-dx</em> - The distance to move on the X-axis.<br/>
1666 <b>parameter: </b><em>int-dy</em> - The distance to move on the Y-axis.<br/>
1667 <b>parameter: </b><em>boolean-repaint</em> - An optional flag to indicate if repainting is required (default is <tt>true</tt>).<br/>
1668 <p></p>
1669  <tt>gs:move-tag</tt> is the only tag operation which actually changes the
1670  internal data of a drawn object. All other tag operations like
1671  <tt>gs:translate-tag</tt>, <tt>gs:scale-tag</tt>, <tt>gs:rotate-tag</tt> and <tt>gs:shear-tag</tt>
1672  will transform object coordinates only for drawing.
1673
1674
1675 <p></p><center>- &sect; -</center><p></p>
1676 <a name="gs_no-action"></a><h3><font color=#CC0000>gs:no-action</font></h3>
1677 <b>syntax: (<font color=#CC0000>gs:no-action</font>)</b><br/>
1678 <p></p>
1679  Specify as <em>sym-action</em> for widgets where no action handler is defined.
1680
1681
1682 <p></p><center>- &sect; -</center><p></p>
1683 <a name="gs_open-file-dialog"></a><h3><font color=#CC0000>gs:open-file-dialog</font></h3>
1684 <b>syntax: (<font color=#CC0000>gs:open-file-dialog</font> <em>sym-parent-frame</em> <em>sym-action</em> [<em>str-directory</em> [<em>str-mask</em> <em>str-description</em>]])</b><br/>
1685 <b>parameter: </b><em>sym-parent-frame</em> - The parent frame of the file dialog.<br/>
1686 <b>parameter: </b><em>sym-action</em> - The handler function symbol.<br/>
1687 <b>parameter: </b><em>str-directory</em> - The initial directory to show.<br/>
1688 <b>parameter: </b><em>str-mask</em> - An optonal string mask.<br/>
1689 <b>parameter: </b>Mstr-description> - An optional mask description.<br/>
1690
1691
1692 <p></p><center>- &sect; -</center><p></p>
1693 <a name="gs_panel"></a><h3><font color=#CC0000>gs:panel</font></h3>
1694 <b>syntax: (<font color=#CC0000>gs:panel</font> <em>sym-id</em> [<em>int-width</em> <em>int-height</em>])</b><br/>
1695 <b>parameter: </b><em>sym-id</em> - The name of the panel.<br/>
1696 <b>parameter: </b><em>int-width</em> - The optional width of the panel.<br/>
1697 <b>parameter: </b><em>int-height</em> - The optional height of the panel.<br/>
1698 <p></p>
1699  Panels have a flow layout by default. In a flow layout an unsized button will
1700  assume the natural size necessary to display the text on it.
1701  To change the layout use the <tt>set-flow-layout</tt> or <tt>set-grid-layout</tt> functions.
1702
1703
1704 <p></p><center>- &sect; -</center><p></p>
1705 <a name="gs_paste-text"></a><h3><font color=#CC0000>gs:paste-text</font></h3>
1706 <b>syntax: (<font color=#CC0000>gs:paste-text</font> <em>sym-id</em> [<em>str-text</em>])</b><br/>
1707 <b>parameter: </b><em>sym-id</em> - The name of the text component in which to paste text.<br/>
1708 <b>parameter: </b><em>str-text</em> - An optional text string to paste instead of the clipboard contents.<br/>
1709 <p></p>
1710  If the <em>sym-id</em> contains selected text, this text gets replaced,
1711  otherwise the text is inserted at the current caret position.
1712  If no text is given in <em>str-text</em>, the text is taken from the clipboard.
1713
1714
1715 <p></p><center>- &sect; -</center><p></p>
1716 <a name="gs_play-sound"></a><h3><font color=#CC0000>gs:play-sound</font></h3>
1717 <b>syntax: (<font color=#CC0000>gs:play-sound</font> <em>str-file-path</em>)</b><br/>
1718 <b>parameter: </b><em>str-file-path</em> - The path and file name of the sound file.<br/>
1719 <p></p>
1720  On most OS platforms <tt>.au</tt> and <tt>.wav</tt> sound file formats are supported.
1721
1722
1723 <p></p><center>- &sect; -</center><p></p>
1724 <a name="gs_progress-bar"></a><h3><font color=#CC0000>gs:progress-bar</font></h3>
1725 <b>syntax: (<font color=#CC0000>gs:progress-bar</font> <em>sym-id</em> <em>int-min</em> <em>in-max</em> <em>int-initial-value</em>)</b><br/>
1726 <b>parameter: </b><em>sym-id</em> - The symbols of the progress bar.<br/>
1727 <b>parameter: </b><em>int-min</em> - The minimum value of the slider.<br/>
1728 <b>parameter: </b><em>int-max</em> - The maximum value of the slider.<br/>
1729 <b>parameter: </b><em>int-initial-value</em> - The initial value of the slider.<br/>
1730
1731
1732 <p></p><center>- &sect; -</center><p></p>
1733 <a name="gs_radio-button"></a><h3><font color=#CC0000>gs:radio-button</font></h3>
1734 <b>syntax: (<font color=#CC0000>gs:radio-button</font> <em>sym-id</em> <em>sym-action</em> [<em>str-text</em> [<em>bool-selected</em>]])</b><br/>
1735 <b>parameter: </b><em>sym-id</em> - The name of the radio button.<br/>
1736 <b>parameter: </b><em>sym-action</em> - The name of the event handler.<br/>
1737 <b>parameter: </b><em>str-text</em> - The optional text of the radio button.<br/>
1738 <b>parameter: </b><em>bool-seected</em> - An optional flag <tt>true</tt> or <tt>nil</tt> (default) indicating the initial state of the radio button.<br/>
1739
1740
1741 <p></p><center>- &sect; -</center><p></p>
1742 <a name="gs_redo-text"></a><h3><font color=#CC0000>gs:redo-text</font></h3>
1743 <b>syntax: (<font color=#CC0000>gs:redo-text</font> <em>sym-id</em>)</b><br/>
1744 <b>parameter: </b><em>sym-id</em> - The id of the <tt>gs:text-pane</tt> where to perform a redo operation.<br/>
1745
1746
1747 <p></p><center>- &sect; -</center><p></p>
1748 <a name="gs_remove-from"></a><h3><font color=#CC0000>gs:remove-from</font></h3>
1749 <b>syntax: (<font color=#CC0000>gs:remove-from</font> <em>sym-container</em> <em>sym-component</em> [<em>sym-component</em> ...])</b><br/>
1750 <b>parameter: </b><em>sym-container</em> - The container from which to remove a component.<br/>
1751 <b>parameter: </b><em>sym-component</em> - One or more optional components to remove.<br/>
1752 <p></p>
1753 <p></p><center>- &sect; -</center><p></p>
1754 <a name="gs_remove-list-item"></a><h3><font color=#CC0000>gs:remove-list-item</font></h3>
1755 <b>syntax: (<font color=#CC0000>gs:remove-list-item</font> <em>sym-list-combo</em> <em>int-index</em> [<em>int-index</em> ...])</b><br/>
1756 <b>parameter: </b><em>sym-list-combo</em> - The name of the combo box or list box from which entries are removed.<br/>
1757 <b>parameter: </b><em>int-index</em> - The index of an entry to remove from the list or combo box.<br/>
1758 <p></p>
1759  When specifying an index of <tt>0</tt>, the first item gets removed. When specifying an
1760  index equal or greater to the number of items in the list, the item is added at the end.
1761
1762
1763 <p></p><center>- &sect; -</center><p></p>
1764 <a name="gs_remove-tab"></a><h3><font color=#CC0000>gs:remove-tab</font></h3>
1765 <b>syntax: (<font color=#CC0000>gs:remove-tab</font> <em>sym-tabbed-pane</em> [<em>int-index</em>])</b><br/>
1766 <b>parameter: </b><em>sym-tabbed-pane</em> - The name of the tabbed pane.<br/>
1767 <b>parameter: </b><em>int-index</em> - The optional index of the tab to remove. The default is <tt>0</tt> for the first tab.<br/>
1768
1769
1770 <p></p><center>- &sect; -</center><p></p>
1771 <a name="gs_request-focus"></a><h3><font color=#CC0000>gs:request-focus</font></h3>
1772 <b>syntax: (<font color=#CC0000>gs:request-focus</font> <em>sym-id</em> [<em>int-tab-index</em>])</b><br/>
1773 <b>parameter: </b><em>sym-id</em> - The name of the component for which to request focus.<br/>
1774 <b>parameter: </b><em>int-tab-index</em> - The index of a tab for which focus is requested.<br/>
1775
1776
1777 <p></p><center>- &sect; -</center><p></p>
1778 <a name="gs_reorder-tags"></a><h3><font color=#CC0000>gs:reorder-tags</font></h3>
1779 <b>syntax: (<font color=#CC0000>gs:reorder-tags</font> <em>list-tags</em>)</b><br/>
1780 <b>parameter: </b><em>list-tags</em> - The list of tag symbols or tag string names in the new order of display.<br/>
1781 <p></p>
1782  The re-ordering itself will not repaint the canvas use <tt>gs:update</tt> to repaint the current
1783  canvas after using <tt>gs:reorder-tags</tt>. The list of tags can be given as either a list of
1784  tags symbols or name strings. Tags not appearing in <em>list-tags</em> will be deleted.
1785
1786
1787 <p></p><center>- &sect; -</center><p></p>
1788 <a name="gs_rotate-tag"></a><h3><font color=#CC0000>gs:rotate-tag</font></h3>
1789 <b>syntax: (<font color=#CC0000>gs:rotate-tag</font> <em>sym-tag</em> <em>float theta</em> <em>int-x</em> <em>int-y</em> [<em>boolean-repaint</em>])</b><br/>
1790 <b>parameter: </b><em>sym-tag</em> - The tag group to rotate.<br/>
1791 <b>parameter: </b><em>float-theta</em> - The rotation angle in degrees (0 - 360).<br/>
1792 <b>parameter: </b><em>int-x</em> - The X-coordinate of the rotation center.<br/>
1793 <b>parameter: </b><em>int-y</em> - The Y-coordinate of the rotation center.<br/>
1794 <b>parameter: </b><em>boolean-repaint</em> - An optional flag to indicate if repainting is required (default is <tt>true</tt>).<br/>
1795 <p></p>
1796  Like all tag operations, multiple <tt>gs:rotate-tag</tt> operations are cumulative.
1797
1798
1799 <p></p><center>- &sect; -</center><p></p>
1800 <a name="gs_run-shell"></a><h3><font color=#CC0000>gs:run-shell</font></h3>
1801 <b>syntax: (<font color=#CC0000>gs:run-shell</font> <em>id-text-area</em> <em>str-command</em>)</b><br/>
1802 <b>parameter: </b><em>idx-text-area</em> - The id of the text area to wich a shell process will be attached.<br/>
1803 <b>parameter: </b><em>str-command</em> - The command string to start the shell process.<br/>
1804
1805
1806 <p></p><center>- &sect; -</center><p></p>
1807 <a name="gs_save-file-dialog"></a><h3><font color=#CC0000>gs:save-file-dialog</font></h3>
1808 <b>syntax: (<font color=#CC0000>gs:save-file-dialog</font> <em>sym-parent-frame</em> <em>sym-action</em> [<em>str-directory</em> [<em>str-initial-file</em> [<em>str-mask</em> <em>str-description</em>]]])</b><br/>
1809 <b>parameter: </b><em>sym-parent-frame</em> - The parent frame of the file dialog.<br/>
1810 <b>parameter: </b><em>sym-action</em> - The handler function symbol.<br/>
1811 <b>parameter: </b><em>str-directory</em> - The initial directory to show.<br/>
1812 <b>parameter: </b><em>str-file</em> - The initial file name.<br/>
1813 <b>parameter: </b><em>str-mask</em> - An optional string mask.<br/>
1814 <b>parameter: </b><em>str-description</em> - An optional mask description.<br/>
1815
1816
1817 <p></p><center>- &sect; -</center><p></p>
1818 <a name="gs_save-text"></a><h3><font color=#CC0000>gs:save-text</font></h3>
1819 <b>syntax: (<font color=#CC0000>gs:save-text</font> <em>sym-id</em> <em>str-path</em>)</b><br/>
1820 <b>parameter: </b><em>sym-id</em> - The id of the <tt>gs:text-pane</tt>.<br/>
1821 <b>parameter: </b><em>str-path</em> - The full path name of the file to save.<br/>
1822 <p></p>
1823  This function will write text back from a <tt>gs:text-pane</tt> directly
1824  by specifying a path name only. Line feed characters (ASCII 10)
1825  are used as line terminators. If this behavior is not desired,
1826  as is the case with Windows text files, then <tt>gs:get-text</tt> should
1827  be used instead. A program can then add CR characters using a
1828  newLISP <tt>replace</tt>, i.e. <tt>(replace "\n" text "\r\n")</tt> before
1829  saving the text to a file.
1830
1831
1832
1833 <p></p><center>- &sect; -</center><p></p>
1834 <a name="gs_scale-tag"></a><h3><font color=#CC0000>gs:scale-tag</font></h3>
1835 <b>syntax: (<font color=#CC0000>gs:scale-tag</font> <em>sym-tag</em> <em>float-x</em> <em>float-y</em> [<em>boolean-repaint</em>])</b><br/>
1836 <b>parameter: </b><em>sym-tag</em> - The tag group to scale.<br/>
1837 <b>parameter: </b><em>float-x</em> - The X scaling factor.<br/>
1838 <b>parameter: </b><em>float-y</em> - The Y scaling factor.<br/>
1839 <b>parameter: </b><em>boolean-repaint</em> - An optional flag to indicate if repainting is required (default is <tt>true</tt>).<br/>
1840 <p></p>
1841  <tt>gs:scale</tt> scales the object to draw relative to the <tt>0,0</tt> point of
1842  the coordinate system. This means if a object is not at the center it
1843  will not only change in size when scaled but also change the distance
1844  to the center point of the coordinate system, moving away when scaling
1845  up with scale factor bigger <tt>1.0</tt> and moving closer to the center
1846  when scaling down using factors smaller than <tt>1.0</tt>.
1847 <p></p>
1848  This means that objects which will be scaled should be defined in
1849  coordinates relative to their center point. Then a <tt>gs:translate-tag</tt>
1850  command should be used to place the object to correct place:
1851 <p></p>
1852 <p></p><b>example:</b><blockquote><pre> (gs:circle 'C 0 0 50)
1853  (gs:gs:translate-tag 'C 200 100)
1854  ...
1855  (gs:scale-tag 'C 1.1 1.1)</pre></blockquote>
1856  In the example the circle, although defined for <tt>0,0</tt>, will be displayed
1857  at the <tt>200,200</tt> position because of the <tt>gs:translate-tag</tt> statement. When
1858  later scaling the circle will get bigger but stay in place.
1859  Like all tag operations, multiple <tt>gs:scale-tag</tt> operations are cumulative.
1860
1861
1862 <p></p><center>- &sect; -</center><p></p>
1863 <a name="gs_select-list-item"></a><h3><font color=#CC0000>gs:select-list-item</font></h3>
1864 <b>syntax: (<font color=#CC0000>gs:select-list-item</font> <em>sym-id</em> <em>str-item</em> [<em>boolean-flag</em>])</b><br/>
1865 <b>parameter: </b><em>sym-id</em> - The name of the list or combo box.<br/>
1866 <b>parameter: </b><em>str-item</em> - The item to select.<br/>
1867 <b>parameter: </b><em>boolean-flag</em> - An optional flag only for list boxes to force scrolling to the selected entry.<br/>
1868 <p></p>
1869  On combo boxes the optional <em>boolean-flag</em> has no effect. The selected entry will always
1870  appear as the visible text of the combo box. The flag has either the value <tt>true</tt> or <tt>nil</tt>.
1871
1872
1873
1874 <p></p><center>- &sect; -</center><p></p>
1875 <a name="gs_select-text"></a><h3><font color=#CC0000>gs:select-text</font></h3>
1876 <b>syntax: (<font color=#CC0000>gs:select-text</font> <em>sym-id</em> <em>int-from</em> [<em>int-to</em>])</b><br/>
1877 <b>parameter: </b><em>sym-id</em> - The ame of the text component.<br/>
1878 <b>parameter: </b><em>int-from</em> - Start offset of selection.<br/>
1879 <b>parameter: </b><em>int-to</em> - Optional end offset of selection.<br/>
1880 <p></p>
1881  If no <em>int-to</em> end offset is given, <tt>gs:select-text</tt> will
1882  select to the end of the text.
1883
1884
1885 <p></p><center>- &sect; -</center><p></p>
1886 <a name="gs_scroll-pane"></a><h3><font color=#CC0000>gs:scroll-pane</font></h3>
1887 <b>syntax: (<font color=#CC0000>gs:scroll-pane</font> <em>sym-id</em> <em>sym-widget</em> [<em>int-width</em> <em>int-height</em>])</b><br/>
1888 <b>parameter: </b><em>sym-id</em> - The name of the scroll pane.<br/>
1889 <b>parameter: </b><em>sym-widget</em> - The component in the scroll pane to be scrolled.<br/>
1890 <b>parameter: </b><em>int-width</em> - The optional width of the scroll pane.<br/>
1891 <b>parameter: </b><em>int-height</em> - The optional height of the scroll pane.<br/>
1892
1893
1894 <p></p><center>- &sect; -</center><p></p>
1895 <a name="gs_set-accelerator"></a><h3><font color=#CC0000>gs:set-accelerator</font></h3>
1896 <b>syntax: (<font color=#CC0000>gs:set-accelerator</font> <em>sym-menu-item</em> <em>str-keystroke</em>)</b><br/>
1897 <b>parameter: </b><em>sym-menu-item</em> - The name of the menu item for which an accelerator key is set.<br/>
1898 <b>parameter: </b><em>str-keystroke</em> - A text string identifying the keystroke.<br/>
1899 <p></p>
1900  The following rules are used to create keystroke strings:
1901 <p></p>
1902  Syntax:
1903  <blockquote><pre>
1904  modifiers* (typedID | pressedReleasedID)
1905  modifiers := shift | control | ctrl | meta | alt | button1 | button2 | button3
1906  typedID := typed typedKey
1907  typedKey := string of length 1 giving Unicode character.
1908  pressedReleasedID := (pressed | released) key
1909  key := KeyEvent key code name, i.e. the name following "VK_".
1910  </pre></blockquote>
1911  Examples:
1912  <blockquote><pre>
1913  "INSERT"
1914  "control DELETE"
1915  "alt shift X"
1916  "alt shift released X"
1917  "typed a"
1918  </pre></blockquote>
1919  Note that the <i>apple</i> key on MacOS X is the <tt>meta</tt> key.
1920  The <tt>alt</tt> on MacOS X is the <i>option</i> key.
1921  For letters use uppercase.
1922  Keys are added to the menu item display automatically on all platforms.
1923
1924
1925 <p></p><center>- &sect; -</center><p></p>
1926 <a name="gs_set-anti-aliasing"></a><h3><font color=#CC0000>gs:set-anti-aliasing</font></h3>
1927 <b>syntax: (<font color=#CC0000>gs:set-anti-aliasing</font> <em>boolean-flag</em>)</b><br/>
1928 <b>parameter: </b><em>boolean-flag</em> - The anti aliasing setting for the current canvas <tt>true</tt> or <tt>nil</tt>.<br/>
1929 <p></p>
1930  The default setting is <tt>true</tt>.
1931
1932
1933 <p></p><center>- &sect; -</center><p></p>
1934 <a name="gs_set-background"></a><h3><font color=#CC0000>gs:set-background</font></h3>
1935 <b>syntax: (<font color=#CC0000>gs:set-background</font> <em>sym-id</em> <em>float-red</em> <em>float-green</em> <em>float-blue</em> [<em>float-alpha</em>])</b><br/>
1936 <b>parameter: </b><em>sym-id</em> - The name of the component for which to set the color.<br/>
1937 <b>parameter: </b><em>float-red</em> - The red color component expressed as a number between 0.0 and 1.0.<br/>
1938 <b>parameter: </b><em>float-green</em> - The green color component expressed as a number between 0.0 and 1.0.<br/>
1939 <b>parameter: </b><em>float-blue</em> - The blue color component expressed as a number between 0.0 and 1.0.<br/>
1940 <b>parameter: </b><em>float-alpha</em> - The transparency of the color expressed as a number between 0.0 (fully transparent)and 1.0 (completely opaque).<br/>
1941 <p></p>
1942 <b>syntax: (<font color=#CC0000>gs:set-background</font> <em>sym-id</em> <em>list-rgb</em> [<em>float-alpha</em>])</b><br/>
1943 <b>parameter: </b><em>sym-id</em> - The name of the component for which to set the color.<br/>
1944 <b>parameter: </b><em>list-rgb</em> - The rgb color can be given as a list of three numbers.<br/>
1945 <b>parameter: </b><em>float-alpha</em> - The transparency of the color expressed as a number between 0.0 (fully transparent)and 1.0 (completely opaque).<br/>
1946 <p></p>
1947  Note <tt>set-background</tt> is the same as <tt>set-color</tt>.
1948
1949
1950 <p></p><center>- &sect; -</center><p></p>
1951 <a name="gs_set-bevel-border"></a><h3><font color=#CC0000>gs:set-bevel-border</font></h3>
1952 <b>syntax: (<font color=#CC0000>gs:set-bevel-border</font> <em>sym-id</em> <em>str-type</em>)</b><br/>
1953 <b>parameter: </b><em>sym-id</em> - The name of the component.<br/>
1954 <b>parameter: </b><em>str-type</em> - The type of the bevel <tt>"raised"</tt> or <tt>"lowered"</tt>.<br/>
1955
1956
1957 <p></p><center>- &sect; -</center><p></p>
1958 <a name="gs_set-border-layout"></a><h3><font color=#CC0000>gs:set-border-layout</font></h3>
1959 <b>syntax: (<font color=#CC0000>gs:set-border-layout</font> <em>sym-container</em>  [<em>int-hgap</em> <em>int-vgap</em>])</b><br/>
1960 <b>parameter: </b><em>sym-container</em> - The name of the container for which border layout is set.<br/>
1961 <b>parameter: </b><em>int-hgap</em> - The horizontal gap between components in the border layout.<br/>
1962 <b>parameter: </b><em>int-vgap</em> - The vertical gap between components in the border layout.<br/>
1963 <p></p>
1964  Border layout divides the layout into 5 zones labeled <tt>"north"</tt>, <tt>"west"</tt>,
1965  <tt>"center"</tt>, <tt>"east"</tt> and <tt>"south"</tt>. These string constants are used in
1966  the <tt>gs:add-to</tt> command when adding components to a border layout.
1967 <p></p>
1968  In a border layout each component will take the maximum size if components
1969  are not sized. If components are sized only some dimensions will be honored.
1970  The <tt>"north"</tt> and <tt>"south"</tt> components will stretch to maximum width and
1971  assume the height given in a size parameter of the component. The <tt>"east"</tt>
1972  and <tt>"west"</tt> components will stretch to the maximum height available assuming
1973  their width specified earlier. The <tt>"center"</tt> component will take the left over
1974  maximum space.
1975
1976
1977 <p></p><center>- &sect; -</center><p></p>
1978 <a name="gs_set-canvas"></a><h3><font color=#CC0000>gs:set-canvas</font></h3>
1979 <b>syntax: (<font color=#CC0000>gs:set-canvas</font> <em>sym-id</em>)</b><br/>
1980 <b>parameter: </b><em>sym-id</em> - The id of the canvas to switch to.<br/>
1981 <p></p>
1982  The canvas in <em>sym-id</em> must have been created earlier with a <tt>gs:canvas</tt>
1983  statement. All graphics operations which do not take a canvas as argument
1984  will automatically refer to this current canvas. If no <tt>gs:set-canvas</tt> is
1985  used, the current canvas is assumed to be the last one created.
1986
1987
1988
1989 <p></p><center>- &sect; -</center><p></p>
1990 <a name="gs_set-caret"></a><h3><font color=#CC0000>gs:set-caret</font></h3>
1991 <b>syntax: (<font color=#CC0000>gs:set-caret</font> <em>sym-id</em> <em>int-offset</em>)</b><br/>
1992 <b>parameter: </b><em>sym-id</em> - The name of the component for which to set the cursor caret.<br/>
1993 <p></p>
1994  The functions has the same effect as calling <tt>gs:select-text</tt> with the same
1995  offset for the dot and mark position.
1996
1997
1998 <p></p><center>- &sect; -</center><p></p>
1999 <a name="gs_set-caret-color"></a><h3><font color=#CC0000>gs:set-caret-color</font></h3>
2000 <b>syntax: (<font color=#CC0000>gs:set-caret-color</font> <em>sym-id</em> <em>float-red</em> <em>float-green</em> <em>float-blue</em>)</b><br/>
2001 <b>parameter: </b><em>sym-id</em> - The name of the component for which to set the color.<br/>
2002 <b>parameter: </b><em>float-red</em> - The red color component expressed as a number between 0.0 and 1.0.<br/>
2003 <b>parameter: </b><em>float-green</em> - The green color component expressed as a  number between 0.0 and 1.0.<br/>
2004 <b>parameter: </b><em>float-blue</em> - The blue color component expressed as a  number between 0.0 and 1.0.<br/>
2005 <b>syntax: (<font color=#CC0000>gs:set-caret-color</font> <em>sym-id</em> <em>list-rgb</em> [<em>float-alpha</em>])</b><br/>
2006 <b>parameter: </b><em>sym-id</em> - The name of the component for which to set the color.<br/>
2007 <b>parameter: </b><em>list-rgb</em> - The rgb color can be given as a list of three numbers.<br/>
2008
2009
2010 <p></p><center>- &sect; -</center><p></p>
2011 <a name="gs_set-color"></a><h3><font color=#CC0000>gs:set-color</font></h3>
2012 <b>syntax: (<font color=#CC0000>gs:set-color</font> <em>sym-id</em> <em>float-red</em> <em>float-green</em> <em>float-blue</em> [<em>float-alpha</em>])</b><br/>
2013 <b>parameter: </b><em>sym-id</em> - The name of the component for which to set the color.<br/>
2014 <b>parameter: </b><em>float-red</em> - The red color component expressed as a number between 0.0 and 1.0.<br/>
2015 <b>parameter: </b><em>float-green</em> - The green color component expressed as a number between 0.0 and 1.0.<br/>
2016 <b>parameter: </b><em>float-blue</em> - The blue color component expressed as a number between 0.0 and 1.0.<br/>
2017 <b>parameter: </b><em>float-alpha</em> - The transparency of the color expressed as a number between 0.0 (fully transparent)and 1.0 (completely opaque).<br/>
2018 <p></p>
2019 <b>syntax: (<font color=#CC0000>gs:set-color</font> <em>sym-id</em> <em>list-rgb</em> [<em>float-alpha</em>])</b><br/>
2020 <b>parameter: </b><em>sym-id</em> - The name of the component for which to set the color.<br/>
2021 <b>parameter: </b><em>list-rgb</em> - The rgb color can be given as a list of three numbers.<br/>
2022 <b>parameter: </b><em>float-alpha</em> - The transparency of the color expressed as a number between 0.0 (fully transparent)and 1.0 (completely opaque).<br/>
2023 <p></p>
2024  Note that <tt>set-color</tt> is the same as <tt>set-background</tt>.
2025
2026
2027 <p></p><center>- &sect; -</center><p></p>
2028 <a name="gs_set-cursor"></a><h3><font color=#CC0000>gs:set-cursor</font></h3>
2029 <b>syntax: (<font color=#CC0000>gs:set-cursor</font> <em>sym-id</em> <em>str-shape</em>)</b><br/>
2030 <b>parameter: </b><em>sym-id</em> - The name of the frame, dialog or window.<br/>
2031 <b>parameter: </b><em>str-shape</em> - The string describing the cursor shape.<br/>
2032 <p></p>
2033  The cursor shape can be one of the following:
2034  <pre>
2035   "default"
2036   "crosshair"
2037   "text"
2038   "wait"
2039   "sw-resize"
2040   "se-resize"
2041   "nw-resize"
2042   "ne-resize"
2043   "n-resize"
2044   "s-resize"
2045   "w-resize"
2046   "e-resize"
2047   "hand"
2048   "move"
2049  </pre>
2050
2051
2052 <p></p><center>- &sect; -</center><p></p>
2053 <a name="gs_set-editable"></a><h3><font color=#CC0000>gs:set-editable</font></h3>
2054 <b>syntax: (<font color=#CC0000>gs:set-editable</font> <em>sym-id</em> <em>boolean-editable</em>)</b><br/>
2055 <b>parameter: </b><em>sym-id</em> - The name of the text widget.<br/>
2056 <b>parameter: </b><em>boolean-editable</em> - The flag <tt>true</tt> or <tt>nil</tt> to indicate if this text widget can be edited.<br/>
2057
2058
2059 <p></p><center>- &sect; -</center><p></p>
2060 <a name="gs_set-flow-layout"></a><h3><font color=#CC0000>gs:set-flow-layout</font></h3>
2061 <b>syntax: (<font color=#CC0000>gs:set-flow-layout</font> <em>sym-container</em> [<em>str-alignment</em> [<em>int-hgap</em> <em>int-vgap</em>]])</b><br/>
2062 <b>parameter: </b><em>sym-container</em> - The name of the container for which flow layout is set.<br/>
2063 <b>parameter: </b><em>sym-alignment</em> - The alignment of the flow layout <tt>"left"</tt>, <tt>"center"</tt> or <tt>"right"</tt>.<br/>
2064 <b>parameter: </b><em>int-hgap</em> - The horizontal gap between components in the flow layout.<br/>
2065 <b>parameter: </b><em>int-vgap</em> - The vertical gap between components in the flow layout.<br/>
2066 <p></p>
2067  The flow layout lets components appear in their natural or preferred size. The preferred
2068  size of a component is set using the function <tt>gs:set-size</tt>. Button-type widgets and
2069  combo boxes will take as much space as necessary to show the included text.
2070
2071
2072 <p></p><center>- &sect; -</center><p></p>
2073 <a name="gs_set-font"></a><h3><font color=#CC0000>gs:set-font</font></h3>
2074 <b>syntax: (<font color=#CC0000>gs:set-font</font> <em>sym-id</em> <em>str-family</em> <em>int-size</em> <em>str-type</em>)</b><br/>
2075 <b>parameter: </b><em>sym-id</em> - The name of the component for which to set the text font.<br/>
2076 <b>parameter: </b><em>str-familiy</em> - The family of the font, e.g.: <tt>"Monospaced"</tt>, <tt>"Serif"</tt>, <tt>"Sans Serif"</tt>.<br/>
2077 <b>parameter: </b><em>int-size</em> - The font size in points.<br/>
2078 <b>parameter: </b><em>str-type</em> - The type of the font, one or more of <tt>"plain"</tt>, <tt>"bold"</tt>, <tt>"italic"</tt>.<br/>
2079 <p></p>
2080  More than the above noted families are available depending on the platform.
2081
2082
2083 <p></p><center>- &sect; -</center><p></p>
2084 <a name="gs_set-foreground"></a><h3><font color=#CC0000>gs:set-foreground</font></h3>
2085 <b>syntax: (<font color=#CC0000>gs:set-foreground</font> <em>sym-id</em> <em>float-red</em> <em>float-green</em> <em>float-blue</em> [<em>float-alpha</em>])</b><br/>
2086 <b>parameter: </b><em>sym-id</em> - The name of the component for which to set the color.<br/>
2087 <b>parameter: </b><em>float-red</em> - The red color component expressed as a number between 0.0 and 1.0.<br/>
2088 <b>parameter: </b><em>float-green</em> - The green color component expressed as a  number between 0.0 and 1.0.<br/>
2089 <b>parameter: </b><em>float-blue</em> - The blue color component expressed as a  number between 0.0 and 1.0.<br/>
2090 <b>parameter: </b><em>float-alpha</em> - The transparency of the color expressed as a number between 0.0 (fully transparent)and 1.0 (completely opaque).<br/>
2091 <p></p>
2092 <b>syntax: (<font color=#CC0000>gs:set-foreground</font> <em>sym-id</em> <em>list-rgb</em> [<em>float-alpha</em>])</b><br/>
2093 <b>parameter: </b><em>sym-id</em> - The name of the component for which to set the color.<br/>
2094 <b>parameter: </b><em>list-rgb</em> - The rgb color can be given as a list of three numbers.<br/>
2095 <b>parameter: </b><em>float-alpha</em> - The transparency of the color expressed as a number between 0.0 (fully transparent)and 1.0 (completely opaque).<br/>
2096 <p></p>
2097  The foreground color is the color of the text in a component.
2098
2099
2100
2101 <p></p><center>- &sect; -</center><p></p>
2102 <a name="gs_set-grid-layout"></a><h3><font color=#CC0000>gs:set-grid-layout</font></h3>
2103 <b>syntax: (<font color=#CC0000>gs:set-grid-layout</font> <em>sym-container</em> <em>int-rows</em> <em>int-columns</em> [<em>int-hgap</em> <em>int-vgap</em>])</b><br/>
2104 <b>parameter: </b><em>sym-container</em> - The name of the container for which grid layout is set.<br/>
2105 <b>parameter: </b><em>int-rows</em> - The number of rows in the layout grid.<br/>
2106 <b>parameter: </b><em>int-columns</em> - The number of columns in the layout grid.<br/>
2107 <b>parameter: </b><em>int-hgap</em> - The horizontal gap between components in the grid layout.<br/>
2108 <b>parameter: </b><em>int-vgap</em> - The vertical gap between components in the grid layout.<br/>
2109 <p></p>
2110  In a grid layout each component will assume the maximum size the grid cell allows
2111  regardless of sizes preset using <tt>gs:set-size</tt> Because of this grid layout cells are
2112  frequently filled with panels using <tt>gs:panel</tt> which have flow layout by default
2113  and allow deliberate sizing of components using <tt>gs:set-size</tt>.
2114
2115
2116 <p></p><center>- &sect; -</center><p></p>
2117 <a name="gs_set-icon"></a><h3><font color=#CC0000>gs:set-icon</font></h3>
2118 <b>syntax: (<font color=#CC0000>gs:set-icon</font> <em>sym-id</em> <em>str-icon-path</em> [<em>int-index</em>])</b><br/>
2119 <b>parameter: </b><em>sym-id</em> - The name of a button or label or menu-item for which to set an icon.<br/>
2120 <b>parameter: </b><em>str-icon-path</em> - The file path of the icon to be set.<br/>
2121 <b>parameter: </b><em>int-index</em> - If <em>sym-id</em> is a tabbed pane <em>int-index</em> is the index of the tab.<br/>
2122
2123
2124 <p></p><center>- &sect; -</center><p></p>
2125 <a name="gs_set-look-and-feel"></a><h3><font color=#CC0000>gs:set-look-and-feel</font></h3>
2126 <b>syntax: (<font color=#CC0000>gs:set-look-and-feel</font> <em>str-look</em>)</b><br/>
2127 <b>parameter: </b><em>str-look</em> - The class description string for the look and feel of the application.<br/>
2128 <p></p>
2129  The following strings can be tried in <em>str-look</em>, but not all will work on a specific
2130  platform. On the Mac the default look-and-feel is built-in to the JVM as the default
2131  style. The <tt>"MacLookAndFeel"</tt> is not available as an explicit flavor here, but may be
2132  on other platforms.
2133  <pre>
2134     <tt>"com.sun.java.swing.plaf.motif.MotifLookAndFeel"</tt><br>
2135     <tt>"javax.swing.plaf.metal.MetalLookAndFeel"</tt><br>
2136     <tt>"com.sun.java.swing.plaf.windows.WindowsLookAndFeel"</tt><br>
2137     <tt>"javax.swing.plaf.mac.MacLookAndFeel"</tt><br>
2138     <tt>"com.sun.java.swing.plaf.gtk.GTKLookAndFeel"</tt>
2139  </pre>
2140
2141
2142 <p></p><center>- &sect; -</center><p></p>
2143 <a name="gs_set-paint"></a><h3><font color=#CC0000>gs:set-paint</font></h3>
2144 <b>syntax: (<font color=#CC0000>gs:set-paint</font> <em>list-rgb</em>)</b><br/>
2145 <b>parameter: </b><em>list-rgb</em> - The current paint used for outlines, text and fill color.<br/>
2146
2147
2148 <p></p><center>- &sect; -</center><p></p>
2149 <a name="gs_set-pressed-icon"></a><h3><font color=#CC0000>gs:set-pressed-icon</font></h3>
2150 <b>syntax: (<font color=#CC0000>gs:set-pressed-icon</font> <em>sym-id</em> <em>str-icon-path</em>)</b><br/>
2151 <b>parameter: </b><em>sym-id</em> - The name of the button, image button or toggle button.<br/>
2152 <b>parameter: </b><em>str-icon-path</em> - The file path of the icon or image to be set to the button in pressed state.<br/>
2153 <p></p>
2154  By default a small grey dot is shown on image buttons when in a pressed state.
2155
2156
2157 <p></p><center>- &sect; -</center><p></p>
2158 <a name="gs_set-resizable"></a><h3><font color=#CC0000>gs:set-resizable</font></h3>
2159 <b>syntax: (<font color=#CC0000>gs:set-resizable</font> <em>sym-frame</em> <em>boolean-resizable</em>)</b><br/>
2160 <b>parameter: </b><em>sym-frame</em> - The name of the frame window.<br/>
2161 <b>parameter: </b><em>bbolean-resizable</em> - The flag <tt>true</tt> or <tt>nil</tt> to indicate if a frame can be resized by the user.<br/>
2162
2163
2164 <p></p><center>- &sect; -</center><p></p>
2165 <a name="gs_set-rotation"></a><h3><font color=#CC0000>gs:set-rotation</font></h3>
2166 <b>syntax: (<font color=#CC0000>gs:set-rotation</font> <em>float-angle</em>)</b><br/>
2167 <b>parameter: </b><em>float-angle</em> - The angle in degrees (0 - 360) of the canvas rotation.<br/>
2168 <p></p>
2169  Unlike the <tt>gs:rotate-tag</tt> operation which is cumulative, <tt>gs:set-rotation</tt>
2170  will set an absolute rotation value each time it is called.
2171
2172
2173 <p></p><center>- &sect; -</center><p></p>
2174 <a name="gs_set-scale"></a><h3><font color=#CC0000>gs:set-scale</font></h3>
2175 <b>syntax: (<font color=#CC0000>gs:set-scale</font> <em>int-x</em> <em>int-y</em>)</b><br/>
2176 <b>parameter: </b><em>int-x</em> - The X-scale value of the current canvas.<br/>
2177 <b>parameter: </b><em>int-y</em> - The Y-scale value of the current canvas.<br/>
2178 <p></p>
2179  Unlike the <tt>gs:scale-tag</tt> operation which is cumulative, <tt>gs:set-scale</tt>
2180  will set an absolute scale value each time it is called.
2181
2182
2183 <p></p><center>- &sect; -</center><p></p>
2184 <a name="gs_set-selected"></a><h3><font color=#CC0000>gs:set-selected</font></h3>
2185 <b>syntax: (<font color=#CC0000>gs:set-selected</font> <em>sym-id</em> <em>boolean-selected</em> [<em>sym-id</em> <em>boolean-selected</em>])</b><br/>
2186 <b>parameter: </b><em>sym-id</em> - The name of the toggle or radio button or check box or menu item.<br/>
2187 <b>parameter: </b><em>boolean-selected</em> - A flag of <tt>true</tt> or <tt>nil</tt> to indicated the selection state.<br/>
2188 <p></p>
2189  More then one toggle control may be set selected or unselected.
2190
2191
2192 <p></p><center>- &sect; -</center><p></p>
2193 <a name="gs_set-selection-color"></a><h3><font color=#CC0000>gs:set-selection-color</font></h3>
2194 <b>syntax: (<font color=#CC0000>gs:set-selection-color</font> <em>sym-id</em> <em>float-red</em> <em>float-green</em> <em>float-blue</em> [<em>float-alpha</em>])</b><br/>
2195 <b>parameter: </b><em>sym-id</em> - The name of the component for which to set the text selection color.<br/>
2196 <b>parameter: </b><em>float-red</em> - The red color component expressed as a number between 0.0 and 1.0.<br/>
2197 <b>parameter: </b><em>float-green</em> - The green color component expressed as a number between 0.0 and 1.0.<br/>
2198 <b>parameter: </b><em>float-blue</em> - The blue color component expressed as a number between 0.0 and 1.0.<br/>
2199 <b>parameter: </b><em>float-alpha</em> - The transparency of the color expressed as a number between 0.0 (fully transparent)and 1.0 (completely opaque).<br/>
2200 <p></p>
2201 <b>syntax: (<font color=#CC0000>gs:set-selection-color</font> <em>sym-id</em> <em>list-rgb</em> [<em>float-alpha</em>])</b><br/>
2202 <b>parameter: </b><em>sym-id</em> - The name of the component for which to set the text selection color.<br/>
2203 <b>parameter: </b><em>list-rgb</em> - The rgb color can be given as a list of three numbers.<br/>
2204 <b>parameter: </b><em>float-alpha</em> - The transparency of the color expressed as a number between 0.0 (fully transparent)and 1.0 (completely opaque).<br/>
2205 <p></p>
2206  Note <tt>set-background</tt> is the same as <tt>set-color</tt>.
2207
2208
2209
2210 <p></p><center>- &sect; -</center><p></p>
2211 <a name="gs_set-size"></a><h3><font color=#CC0000>gs:set-size</font></h3>
2212 <b>syntax: (<font color=#CC0000>gs:set-size</font> <em>sym-id</em> <em>int-width</em> <em>int-height</em>)</b><br/>
2213 <b>parameter: </b><em>sym-id</em> - The name of the component of which a preferred size is set.<br/>
2214 <b>parameter: </b><em>int-width</em> - The preferred width of the component.<br/>
2215 <b>parameter: </b><em>int-height</em> - The preferred height of the component.<br/>
2216 <p></p>
2217  Note that not all layouts allow setting the size of a component. The grid and
2218  border layouts will size the component to its maximum possible in the layout.
2219
2220
2221 <p></p><center>- &sect; -</center><p></p>
2222 <a name="gs_set-stroke"></a><h3><font color=#CC0000>gs:set-stroke</font></h3>
2223 <b>syntax: (<font color=#CC0000>gs:set-stroke</font> <em>float-width</em> [<em>str-cap</em> [<em>str-join</em> [<em>float-miterlimit</em>]]])</b><br/>
2224 <b>parameter: </b><em>float-width</em> - The width for drawing lines and outlines in shapes.<br/>
2225 <b>parameter: </b><em>str-cap</em> - One of optional <tt>"butt"</tt> (default), <tt>"round"</tt> or <tt>"sqare"</tt>.<br/>
2226 <b>parameter: </b><em>str-join</em> - One of optional <tt>"miter"</tt> (default), <tt>"bevel"</tt> or <tt>"round"</tt><br/>
2227 <p></p>
2228  For a <em>float-width</em> 0f 0.0 the thinnest possible line width be be chosen.
2229  Join is the decoration applied at the intersection of two path segments and at the
2230  intersection of the endpoints.
2231  Cap is the decoration applied to the ends of unclosed subpaths and dash segments.
2232  The <em>float-miterlimit</em> should be greater or equal 1.0.
2233
2234
2235 <p></p><center>- &sect; -</center><p></p>
2236 <a name="gs_set-syntax"></a><h3><font color=#CC0000>gs:set-syntax</font></h3>
2237 <b>syntax: (<font color=#CC0000>gs:set-syntax</font> <em>sym-id</em> <em>str-type</em>)</b><br/>
2238 <b>parameter: </b><em>sym-id</em> - The name of the text pane for syntax coloring is enabled or disabled.<br/>
2239 <b>parameter: </b><em>str-type</em> - A string <tt>"lsp"</tt>, <tt>"c"</tt>, <tt>"cpp"</tt>, <tt>"java"</tt> or <tt>"php"</tt> to indicate the <br/>
2240  syntax desired, or <tt>nil</tt> to switch off syntax highlighting.
2241 <p></p>
2242  Colors for syntax highlighting are preselected for a white background, but can be changed using
2243  the following functions: <tt>gs:set-background</tt>, <tt>gs:set-foreground</tt>, <tt>gs:set-caret</tt>, <tt>gs:set-selection-color</tt>
2244  and <tt>gs:set-syntax-colors</tt>.
2245
2246
2247 <p></p><center>- &sect; -</center><p></p>
2248 <a name="gs_set-syntax-colors"></a><h3><font color=#CC0000>gs:set-syntax-colors</font></h3>
2249 <b>syntax: (<font color=#CC0000>gs:set-syntax-colors</font> <em>list-rgb-comment</em> <em>list-rgb-keyword</em> <em>list-rgb-string</em> <em>list-rgb-number</em> <em>list-rgb-quoted</em> <em>list-rgb-parentheses</em>)</b><br/>
2250 <b>parameter: </b><em>list-rgb-comment</em> - The color for comments.<br/>
2251 <b>parameter: </b><em>list-rgb-keyword</em> - The color for reserved keywords.<br/>
2252 <b>parameter: </b><em>list-rgb-string</em> - The color for strings.<br/>
2253 <b>parameter: </b><em>list-rgb-number</em> - The color for numbers.<br/>
2254 <b>parameter: </b><em>list-rgb-quoted</em> - The color for the quote and quoted symbols.<br/>
2255 <b>parameter: </b><em>list-rgb-parentheses</em> - The color for parenthesis.<br/>
2256 <p></p>
2257  Syntax highlighting colors are given as lists of red, green and blue values between 0.0 and 1.0.
2258  Depending on the syntax colors and the foreground and background colors set for the text pane,
2259  the caret color and color for selected text should also be changed. Only text widgets created
2260  using <tt>gs:text-pane</tt> feature syntax highlighting.
2261
2262
2263 <p></p><center>- &sect; -</center><p></p>
2264 <a name="gs_set-tab-size"></a><h3><font color=#CC0000>gs:set-tab-size</font></h3>
2265 <b>syntax: (<font color=#CC0000>gs:set-tab-size</font> <em>sym-id</em> <em>int-size</em>)</b><br/>
2266 <b>parameter: </b><em>sym-id</em> - The name of the text area component.<br/>
2267 <b>parameter: </b><em>int-size</em> - The tabulator size.<br/>
2268 <p></p>
2269  Note that <tt>gs:set-tab-size</tt> will only work with fixed spaced fonts.
2270
2271
2272 <p></p><center>- &sect; -</center><p></p>
2273 <a name="gs_set-text"></a><h3><font color=#CC0000>gs:set-text</font></h3>
2274 <b>syntax: (<font color=#CC0000>gs:set-text</font> <em>sym-id</em> <em>str-text</em> [<em>int-index</em>])</b><br/>
2275 <b>parameter: </b><em>sym-id</em> - The name of the component for which text is set.<br/>
2276 <b>parameter: </b><em>str-text</em> - The text to be set in the component.<br/>
2277 <b>parameter: </b><em>int-index</em> - The index for a tab if the <em>sym-id</em> is a tabbed pane.<br/>
2278
2279
2280 <p></p><center>- &sect; -</center><p></p>
2281 <a name="gs_set-titled-border"></a><h3><font color=#CC0000>gs:set-titled-border</font></h3>
2282 <b>syntax: (<font color=#CC0000>gs:set-titled-border</font> <em>sym-component</em> <em>str-title</em>)</b><br/>
2283 <b>parameter: </b><em>sym-component</em> - The name of the component.<br/>
2284 <b>parameter: </b><em>str-title</em> - The text in the titled border around the component.<br/>
2285 <p></p>
2286  The component is usually a <tt>panel</tt>.
2287
2288
2289 <p></p><center>- &sect; -</center><p></p>
2290 <a name="gs_set-tool-tip"></a><h3><font color=#CC0000>gs:set-tool-tip</font></h3>
2291 <b>syntax: (<font color=#CC0000>gs:set-tool-tip</font> <em>sym-id</em> <em>str-text</em>)</b><br/>
2292 <b>parameter: </b><em>sym-id</em> - The name of the widget for which to supply a tool tip.<br/>
2293 <b>parameter: </b><em>str-text</em> - The text of the tool tip.<br/>
2294 <p></p>
2295  The tool tip text is shown when leaving the mouse over the widget for certain
2296  amount of time.
2297
2298
2299 <p></p><center>- &sect; -</center><p></p>
2300 <a name="gs_set-trace"></a><h3><font color=#CC0000>gs:set-trace</font></h3>
2301 <b>syntax: (<font color=#CC0000>gs:set-trace</font> <em>boolean-flag</em>)</b><br/>
2302 <b>parameter: </b><em>boolean-flag</em> - The flag <tt>true</tt> or <tt>nil</tt>.<br/>
2303
2304
2305 <p></p><center>- &sect; -</center><p></p>
2306 <a name="gs_set-translation"></a><h3><font color=#CC0000>gs:set-translation</font></h3>
2307 <b>syntax: (<font color=#CC0000>gs:set-translation</font> <em>int-x</em> <em>int-y</em>)</b><br/>
2308 <b>parameter: </b><em>int-x</em> - The X-translation value of the current canvas.<br/>
2309 <b>parameter: </b><em>int-y</em> - The Y-translation value of the current canvas.<br/>
2310 <p></p>
2311  Translates the current origin of the current canvas to the point in <em>int-x</em> <em>int-y</em>.
2312  Unlike the <tt>gs:translate-tag</tt> operation which is cumulative, <tt>gs:set-translation</tt>
2313  will set an absolute translation value each time it is called.
2314
2315
2316 <p></p><center>- &sect; -</center><p></p>
2317 <a name="gs_set-utf8"></a><h3><font color=#CC0000>gs:set-utf8</font></h3>
2318 <b>syntax: (<font color=#CC0000>gs:set-utf8</font> <em>boolean-flag</em>)</b><br/>
2319 <b>parameter: </b><em>boolean</em> - The flag <tt>true</tt> or <tt>nil</tt> to indicate if in UTF-8 mode.<br/>
2320 <p></p>
2321  When set in UTF-8 mode, guiserver will convert files to UTF-8 encoding
2322  when loading and saving files. On Mac OX X UTF-8 mode is by default enabled.
2323  On startup guiserver.lsp will detect if newLISP is UTF-8 enabled and
2324  switch the mode in Guiserver accordingly using <tt>gs:set-utf8</tt>.
2325
2326
2327 <p></p><center>- &sect; -</center><p></p>
2328 <a name="gs_set-value"></a><h3><font color=#CC0000>gs:set-value</font></h3>
2329 <b>syntax: (<font color=#CC0000>gs:set-value</font> <em>sym-id</em> <em>int-value</em>)</b><br/>
2330 <b>parameter: </b><em>sym-id</em> - The name of a slider or progress bar for which to set the value.<br/>
2331 <b>parameter: </b><em>int-value</em> - The integer value of the name to be set.<br/>
2332 <p></p>
2333  The value should not be bigger or smaller than the minimum or maximum values set
2334  when creating the slider or progress bar, otherwise the setting will default to either
2335  the minimum or maximum preset value.
2336
2337
2338 <p></p><center>- &sect; -</center><p></p>
2339 <a name="gs_set-visible"></a><h3><font color=#CC0000>gs:set-visible</font></h3>
2340 <b>syntax: (<font color=#CC0000>gs:set-visible</font> <em>sym-id</em> <em>boolean-visible</em>)</b><br/>
2341 <b>parameter: </b><em>sym-id</em> - The component which is hidden or made visible.<br/>
2342 <b>parameter: </b><em>boolean-visible</em> - A flag indicating if the component is visible <tt>"true"</tt>, <tt>"nil"</tt>.<br/>
2343 <p></p>
2344  Except for frames and dialog windows, components are visible by default. Normally
2345  frames and dialogs are not set visible before all other components are placed inside.
2346
2347
2348 <p></p><center>- &sect; -</center><p></p>
2349 <a name="gs_shear-tag"></a><h3><font color=#CC0000>gs:shear-tag</font></h3>
2350 <b>syntax: (<font color=#CC0000>gs:shear-tag</font> <em>sym-tag</em> <em>int-x</em> <em>int-y</em> [<em>boolean-repaint</em>])</b><br/>
2351 <b>parameter: </b><em>sym-tag</em> - The tag group to shear.<br/>
2352 <b>parameter: </b><em>float-x</em> - The X shearing factor.<br/>
2353 <b>parameter: </b><em>float-y</em> - The Y shearing factor.<br/>
2354 <b>parameter: </b><em>boolean-repaint</em> - An optional flag to indicate if repainting is required (default is <tt>true</tt>).<br/>
2355
2356
2357 <p></p><center>- &sect; -</center><p></p>
2358 <a name="gs_show-popup"></a><h3><font color=#CC0000>gs:show-popup</font></h3>
2359 <b>syntax: (<font color=#CC0000>gs:show-popup</font> <em>sym-tag</em> <em>sym-host</em> <em>int-x</em> <em>int-y</em>)</b><br/>
2360 <b>parameter: </b><em>sym-tag</em> - The id of the popup menu.<br/>
2361 <b>parameter: </b><em>sym-host</em> - The host container where to pop up the menu.<br/>
2362 <b>parameter: </b><em>int-x</em> - The X coordinate of the menu popup position.<br/>
2363 <b>parameter: </b><em>int-y</em> - The Y coordinate of the menu popup position.<br/>
2364
2365
2366 <p></p><center>- &sect; -</center><p></p>
2367 <a name="gs_show-tag"></a><h3><font color=#CC0000>gs:show-tag</font></h3>
2368 <b>syntax: (<font color=#CC0000>gs:show-tag</font> <em>sym-tag</em> [<em>boolean-repaint</em>])</b><br/>
2369 <b>parameter: </b><em>sym-tag</em> - The tag of the group to show.<br/>
2370 <b>parameter: </b><em>boolean-repaint</em> - An optional flag to indicate if repainting is required (default is <tt>true</tt>).<br/>
2371 <p></p>
2372 <p></p><center>- &sect; -</center><p></p>
2373 <a name="gs_slider"></a><h3><font color=#CC0000>gs:slider</font></h3>
2374 <b>syntax: (<font color=#CC0000>gs:slider</font> <em>sym-id</em> <em>sym-action</em> <em>str-orientation</em> <em>int-min</em> <em>int-max</em> <em>int-initial-value</em>)</b><br/>
2375 <b>parameter: </b><em>sym-id</em> - The name of the slider.<br/>
2376 <b>parameter: </b><em>sym-action</em> - The name of the event handler.<br/>
2377 <b>parameter: </b><em>str-orientation</em> - The orientation of the slider <tt>"horizontal"</tt> or <tt>"vertical"</tt><br/>
2378 <b>parameter: </b><em>int-min</em> - The minimum value of the slider.<br/>
2379 <b>parameter: </b><em>int-max</em> - The maximum value of the slider.<br/>
2380 <b>parameter: </b><em>int-initial-value</em> - The initial value of the slider.<br/>
2381
2382
2383 <p></p><center>- &sect; -</center><p></p>
2384 <a name="gs_split-pane"></a><h3><font color=#CC0000>gs:split-pane</font></h3>
2385 <b>syntax: (<font color=#CC0000>gs:split-pane</font> <em>sym-id</em> <em>str-orientation</em> [<em>float-weight</em> [<em>float-location</em> [<em>int-divider-size</em>]]])</b><br/>
2386 <b>parameter: </b><em>sym-id</em> - The name of the split-pane.<br/>
2387 <b>parameter: </b><em>str-orientation</em> - The orientation <tt>"horizontal"</tt> or <tt>"vertical"</tt>.<br/>
2388 <b>parameter: </b><em>float-weight</em> - The optional weight distribution between <tt>0.0</tt> and <tt>1.0</tt> when re-sizing the window. The default is <tt>0.0</tt>.<br/>
2389 <b>parameter: </b><em>float-location</em> - The optional initial divider location between <tt>0.0</tt> and <tt>1.0</tt>.<br/>
2390 <b>parameter: </b><int-divider-size) - The optional size of the draggable divider in pixels.<br/>
2391
2392
2393 <p></p><center>- &sect; -</center><p></p>
2394 <a name="gs_tabbed-pane"></a><h3><font color=#CC0000>gs:tabbed-pane</font></h3>
2395 <b>syntax: (<font color=#CC0000>gs:tabbed-pane</font> <em>sym-id</em> <em>sym-action</em> <em>str-orientation</em> [<em>sym-tab</em> <em>sym-tab-title</em> ...])</b><br/>
2396 <b>parameter: </b><em>sym-id</em> - The name of the tabbed pane.<br/>
2397 <b>parameter: </b><em>str-orientation</em> - The position of the tabs; either <tt>"top"</tt> (default), <tt>"bottom"</tt>,<tt>"left"</tt> or <tt>"right"</tt>.<br/>
2398 <b>parameter: </b><em>sym-tab</em> - The id symbol name of a tab<br/>
2399 <b>parameter: </b><em>str-title</em> - The title of the tab.<br/>
2400
2401
2402 <p></p><center>- &sect; -</center><p></p>
2403 <a name="gs_text-area"></a><h3><font color=#CC0000>gs:text-area</font></h3>
2404 <b>syntax: (<font color=#CC0000>gs:text-area</font> <em>sym-id</em> <em>sym-action</em> <em>int-width</em> <em>int-height</em>)</b><br/>
2405 <b>parameter: </b><em>symid</em> - The name of the text area.<br/>
2406 <b>parameter: </b><em>sym-action</em> - The name of the event handler.<br/>
2407 <b>parameter: </b><em>int-width</em> - The optional width of the text area..<br/>
2408 <b>parameter: </b><em>int-height</em> - The optional height of the text area.<br/>
2409 <p></p><b>example:</b><blockquote><pre> (gs:text-area 'TheText 'textarea-event 10 8)
2410
2411  (define (textarea-event id code dot mark) ...)</pre></blockquote>
2412  <tt>gs:text-area</tt> transmits the following parameters in its event:
2413  <pre>
2414  id   - name of the widget
2415  code - key code equals ASCII code. Only for text keys
2416  dot  - position of text caret in the text
2417  mark - extended (selection) position of caret
2418  </pre>
2419
2420
2421
2422 <p></p><center>- &sect; -</center><p></p>
2423 <a name="gs_text-field"></a><h3><font color=#CC0000>gs:text-field</font></h3>
2424 <b>syntax: (<font color=#CC0000>gs:text-field</font> <em>sym-id</em> <em>sym-action</em> <em>int-columns</em>)</b><br/>
2425 <b>parameter: </b><em>sym-id</em> - The name of the text field.<br/>
2426 <b>parameter: </b><em>sym-action</em> - The name of the event handler.<br/>
2427 <b>parameter: </b><em>int-columns</em> - The number of columns in the text field.<br/>
2428 <p></p><b>example:</b><blockquote><pre> (gs:text-field 'TheText 'textfield-event)</pre></blockquote>
2429  The <tt>textfield-event</tt> is fired when the enter key is pressed in the
2430  text field.
2431
2432
2433 <p></p><center>- &sect; -</center><p></p>
2434 <a name="gs_text-pane"></a><h3><font color=#CC0000>gs:text-pane</font></h3>
2435 <b>syntax: (<font color=#CC0000>gs:text-pane</font> <em>sym-id</em> <em>sym-action</em> <em>str-style</em> [<em>int-width</em> <em>int-height</em>])</b><br/>
2436 <b>parameter: </b><em>sym-id</em> - The name of the text pane.<br/>
2437 <b>parameter: </b><em>sym-action</em> - The key action handler for the html pane.<br/>
2438 <b>parameter: </b><em>sym-style</em> - The content type of the text pane.<br/>
2439 <b>parameter: </b><em>int-width</em> - The optional width of the pane.<br/>
2440 <b>parameter: </b><em>int-height</em> - The optional height of the pane.<br/>
2441 <p></p>
2442  The <tt>gs:text-pane</tt> is used similar to 'gs:text-area. The following styles
2443  are supported in <em>sym-style</em>:
2444  <pre>
2445     "text/plain"
2446     "text/html"
2447  </pre>
2448 <p></p>
2449  The <tt>gs:text-pane</tt> widget will automatically display scroll bars when
2450  text does not fit in the visible space of the pane. When entering parentheses
2451  they are automatically matched with their opening or closing counterparts, if they exist.
2452  If this is undesired behavior, the simpler <tt>gs:text-area</tt> control should
2453  be used instead.
2454 <p></p>
2455  On each change of the caret or selection in the text pane
2456  an event is fired containing several parameters about the caret and selection
2457  positions, the last character typed, and the modifier keys used. See the
2458  the file <tt>newlisp-edit.lsp</tt> for a complex application using all features
2459  available in this widget.
2460 <p></p>
2461  To make hyperlinks in <tt>HTML</tt> formatted text clickable, editing must
2462  be disabled using the <tt>gs:set-editable</tt> function. The functions <tt>gs:set-font</tt>
2463  and <tt>gs:append-text</tt> will work only on the <tt>text/plain</tt> content style.
2464 <p></p><b>example:</b><blockquote><pre> (gs:text-pane 'TheTextPane 'textpane-event "text/plain")
2465
2466  (define (textpane-event id code mods dot mark len undo redo) ...)</pre></blockquote>
2467  <tt>gs:text-pane</tt> transmits the following parameters in its event:
2468  <pre>
2469  id   - name of the widget
2470  code - key code equals ASCII code. Only for text keys
2471  mods - keys pressed together with the previous, like shift, ctrl etc.
2472  dot  - position of the text caret in the text
2473  mark - extended (selection) position of the caret
2474  len  - length of the text in the textarea
2475  undo - undo enabled/disabled
2476  redo - redo enabled/disabled
2477  </pre>
2478
2479
2480 <p></p><center>- &sect; -</center><p></p>
2481 <a name="gs_toggle-button"></a><h3><font color=#CC0000>gs:toggle-button</font></h3>
2482 <b>syntax: (<font color=#CC0000>gs:toggle-button</font> <em>sym-id</em> <em>sym-action</em> <em>str-text</em> [<em>bool-selected</em>])</b><br/>
2483 <b>parameter: </b><em>sym-id</em> - The name of the toggle button.<br/>
2484 <b>parameter: </b><em>sym-action</em> - The name of the event handler.<br/>
2485 <b>parameter: </b><em>str-text</em> - The optional text of the toggle button.<br/>
2486 <b>parameter: </b><em>bool-selected</em> - An optional flag <tt>true</tt> or <tt>nil</tt> (default) indicating the initial state of the toggle button.<br/>
2487
2488
2489 <p></p><center>- &sect; -</center><p></p>
2490 <a name="gs_tool-bar"></a><h3><font color=#CC0000>gs:tool-bar</font></h3>
2491 <b>syntax: (<font color=#CC0000>gs:tool-bar</font> <em>sym-frame</em> [<em>bool-floatable</em> <em>int-hgap</em> <em>int-vgap</em>])</b><br/>
2492 <b>parameter: </b><em>sym-frame</em> - The name of the frame hosting the toolbar.<br/>
2493 <b>parameter: </b><em>bool-floatable</em> - The optional flag <tt>true</tt> or <tt>nil</tt> to indicate if the toolbar can be detached.<br/>
2494 <b>parameter: </b><em>int-hgap</em> - The horizontal gap between components on the toolbar.<br/>
2495 <b>parameter: </b><em>int-vgap</em> - The vertical gap between the components on the toolbar.<br/>
2496
2497
2498 <p></p><center>- &sect; -</center><p></p>
2499 <a name="gs_translate-tag"></a><h3><font color=#CC0000>gs:translate-tag</font></h3>
2500 <b>syntax: (<font color=#CC0000>gs:translate-tag</font> <em>sym-tag</em> <em>int-x</em> <em>int-y</em> [<em>boolean-repaint</em>])</b><br/>
2501 <b>parameter: </b><em>sym-tag</em> - The name tag of the group to translate.<br/>
2502 <b>parameter: </b><em>int-x</em> - The X-coordinate translation value.<br/>
2503 <b>parameter: </b><em>int-y</em> - The Y-coordinate translation value.<br/>
2504 <b>parameter: </b><em>boolean-repaint</em> - An optional flag to indicate if repainting is required (default is <tt>true</tt>).<br/>
2505 <p></p>
2506  Moves the origin of the coordinate system of all objects tagged with <em>sym-tag</em>.
2507  Like all tag operations multiple <tt>gs:translate-tag</tt> operations are cumulative.
2508
2509
2510 <p></p><center>- &sect; -</center><p></p>
2511 <a name="gs_undo-text"></a><h3><font color=#CC0000>gs:undo-text</font></h3>
2512 <b>syntax: (<font color=#CC0000>gs:undo-text</font> <em>sym-id</em>)</b><br/>
2513 <b>parameter: </b><em>sym-id</em> - The id of the <tt>gs:text-pane</tt> where to perform an undo operation.<br/>
2514
2515
2516 <p></p><center>- &sect; -</center><p></p>
2517 <a name="gs_undo-enable"></a><h3><font color=#CC0000>gs:undo-enable</font></h3>
2518 <b>syntax: (<font color=#CC0000>gs:undo-enable</font> <em>sym-id</em> <boolean-enabled)</b><br/>
2519 <b>parameter: </b><em>sym-id</em> - The id of the <tt>gs:text-pane</tt> for which to enabe/disable undo.<br/>
2520
2521
2522
2523 <p></p><center>- &sect; -</center><p></p>
2524 <a name="gs_update"></a><h3><font color=#CC0000>gs:update</font></h3>
2525 <b>syntax: (<font color=#CC0000>gs:update</font>)</b><br/>
2526 <p></p>
2527  Forces a repaint of the current canvas, e.g. after changing the scale or translation of a visible
2528  canvas. This function is rarely used, as most screen updates are performed automatically.
2529  All tag operations can carry an additional parameter to force update after they have been
2530  draw.
2531
2532
2533 <p></p><center>- &sect; -</center><p></p>
2534 <a name="gs_window"></a><h3><font color=#CC0000>gs:window</font></h3>
2535 <b>syntax: (<font color=#CC0000>gs:window</font> <em>sym-id</em> <em>int-x</em> <em>int-y</em> <em>int-width</em> <em>int-height</em>)</b><br/>
2536 <b>parameter: </b><em>sym-id</em> - The name of the invisible window.<br/>
2537 <b>parameter: </b><em>int-x</em> - The x-coordinate of the screen position.<br/>
2538 <b>parameter: </b><em>int-y</em> - The y-coordinate of the screen position.<br/>
2539 <b>parameter: </b><em>int-width</em> - The width of the window.<br/>
2540 <b>parameter: </b><em>int-height</em> - The height of the window.<br/>
2541 <p></p>
2542  Creates a borderless window. Note that a borderless window may treat
2543  some hosted components differently from normal frames and dialogs.
2544
2545
2546 <p></p><center>- &sect; -</center><p></p>
2547 <a name="gs_window-closed"></a><h3><font color=#CC0000>gs:window-closed</font></h3>
2548 <b>syntax: (<font color=#CC0000>gs:window-closed</font> <em>sym-id</em> <em>sym-action</em>)</b><br/>
2549 <b>parameter: </b><em>sym-id</em> - The name of the frame or dialog.<br/>
2550 <b>parameter: </b><em>sym-action</em> - The action to perform when the frame or dialog closes.<br/>
2551 <p></p>
2552  A window or dialog window can be closed using the system close button in
2553  one of the corners of the window. In this case it is useful to specify
2554  a handler function which is called upon closing.
2555
2556
2557
2558
2559 <p></p><center>- &sect; -</center><p></p>
2560 <a name="gs_window-moved"></a><h3><font color=#CC0000>gs:window-moved</font></h3>
2561 <b>syntax: (<font color=#CC0000>gs:window-moved</font> <em>sym-id</em> <em>sym-action</em>)</b><br/>
2562 <b>parameter: </b><em>sym-id</em> - The name of the frame or dialog.<br/>
2563 <b>parameter: </b><em>sym-action</em> - The action to perform when the frame or dialog moves.<br/>
2564 <p></p>
2565  The event will carry the <em>sym-id</em> of the window or dialog and current <tt>X</tt> and <tt>Y</tt>
2566  coordinates on the screen.
2567 <p></p>
2568 <p></p><center>- &sect; -</center><p></p>
2569 <a name="gs_window-resized"></a><h3><font color=#CC0000>gs:window-resized</font></h3>
2570 <b>syntax: (<font color=#CC0000>gs:window-resized</font> <em>sym-id</em> <em>sym-action</em>)</b><br/>
2571 <b>parameter: </b><em>sym-id</em> - The name of the frame or dialog.<br/>
2572 <b>parameter: </b><em>sym-action</em> - The action to perform when the frame or dialog is resized.<br/>
2573 <p></p>
2574  The event will carry the <em>sym-id</em> of the window or dialog and current width and
2575  height.
2576
2577
2578
2579
2580
2581 <p></p><center>- &part; -</center><br/>
2582 <center><font face='Arial' size='-2' color='#444444'>
2583 generated with <a href="http://newlisp.org">newLISP</a>&nbsp;
2584 and <a href="http://newlisp.org/newLISPdoc.html">newLISPdoc</a>
2585 </font></center>
2586 </blockquote>
2587 </body>
2588 </html>