chickadee » qobischeme-ui

Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

This page is maintained in the package's github repository.

QobiScheme UI

This egg is a port of the QobiScheme UI to Chicken. examples/define-application-example.scm provides an example of a UI. One minor incompatibility with QobiScheme is that abort is renamed to abort-gui to avoid a name clash with Chicken.

Commandline

(define-command (function-name {arguments}) {expression}+)procedure

Define a commandline application. The grammar for arguments and expressions is given below but it might be easier to look at the example instead. define-command produces error messages which print a usage line and explain why the input is incorrect.

define-command is slightly incompatible with QobiScheme's implementation. It expects arguments to be passed to it directly rather than through a list and it does not require the program name. It also fixes a bug where repeated arguments were provided in the wrong order.

 {arguments} ::= {keyword}* {required}* {optional}* [{rest}]
 {rest}     ::= (rest {defaulted-argument})
 {optional} ::= (optional {defaulted-argument})
 {required} ::= (required {defaulted-argument})
 {keyword} ::= (any-number {defaulted-keyword}*)
           |   (at-most-one {defaulted-keyword}*)
           |   (at-least-one {defaulted-keyword}+)
           |   (exactly-one {defaulted-keyword}+)
 {defaulted-keyword} ::= ({name} {supplied?} {defaulted-argument}*)
 {defaulted-argument} ::= ({variable} {doc} {type} {default})
 {type} ::= integer-argument | real-argument | string-argument

{name} and {doc} are strings. {doc} is only used for documentation. There can't be a {name} "usage" or "help". -usage and -help are created automatically. All of the {variable}s and {supplied?}s must be distinct. All of the {name}s must be distinct.

Note that any-number, at-least-one, rest, and required allow nondefaulted-keywords. This is to keep backward compatibility with QobiScheme but this version encourages using {defaulted-argument}s everywhere for simplicity.

You can define new {type}s as:

 (lambda (string) (if (ok? string) (string->value string) (usage {doc})))

An example that should make everything clear:

 (define-command
   (main (exactly-one ("file" file? (file "file" string-argument ""))
                      ("other-file" other-file?
                         (arg1 "pathname" string-argument "")
                         (arg2 "version" real-argument 0)))
         (at-most-one ("flag" flag?))
         (any-number ("more" more? (more "more" string-argument "")))
         (at-least-one ("alt" alt? (alt-arg "arg" string-argument "")))
         (required (needed "needed" string-argument ""))
         (optional (maybe "maybe" string-argument ""))
         (optional (another-maybe "another-maybe" string-argument ""))
         (rest (everything "everything" string-argument)))
   (pp (list file? file other-file? arg1 arg2 flag? more? more alt? alt-arg needed maybe another-maybe everything))(newline))

 (apply main command-line-arguments)

Without arguments, with incorrect arguments, with -usage, or -help this will print:

 usage: csi [-file file|-other-file pathname version] [-flag] [-more more]* [-alt arg]+ needed [maybe [another-maybe [everything]*]]

Graphical UI

(define-application display-pane-width display-pane-height transcript-lines button-rows button-columns pre-initialize-procedure post-initialize-procedure finalize-procedure redraw-procedure listener-procedure)syntax

The main way of defining GUI.

The GUI is composed of different regions: at the top we have buttons in the button pane, the main content of the application is displayed below in the display pane, below that are the transcript pane and echo pane which are used to output and input text, and at the bottom we have the status pane on the left and message pane on the right. Each pane is an X window embedded in the main X window of the application.

The display-pane-width and display-pane-height are in pixel units. When width is #f other arguments will determine the width of the application. The other panes automatically adjust their sizes. transcript-lines defines the number of lines in the transcript pane, can be #f. button-rows and button-columns set the size of the button grid in the button pane. Buttons will be automatically sized to take up the appropriate amount of space.

All the following procedures take no arguments. pre-initialize-procedure code to run before the application is ready. This is typically where you define UI elements. post-initialize-procedure code to run right after the UI is ready. finalize-procedure runs after the UI exists. redraw-procedure runs as needed to redraw the UI. listener-procedure runs when return is pressed in the transcript pane.

 (use qobischeme-ui)
 (define-application main #f 480 5 2 6
  (lambda ()
   (define-button 0 0 "Help" #f help-command)
   (define-button 5 0 "Quit" #f quit-gui)
   (define-radio-buttons *object* (lambda () #f)
    (1 0 line-segment "Line")
    (2 0 ellipse "Ellipse"))
   (define-toggle-button 0 1 "Flag" *flag?*
    (lambda () (say (format #f "Flag=~s" *flag?*))))
   (define-cycle-button 1 1 *mode*
    (lambda () (say (format #f "Mode=~s" *mode*)))
    (a "A")
    (b "B")
    (c "C"))
   (define-integer-range-buttons 2 1 3 1 *k* 0 9
    (lambda () (format #f "-K ~s" *k*))
    (lambda () (format #f "+K ~s" *k*))
    (lambda () (say (format #f "K=~s" *k*))))
   (define-key (list (control #\x) (control #\c)) "Quit" quit-gui)
   (define-key (control #\h) "Help" help-command))
  (lambda () #f)
  (lambda () #f)
  (lambda () #f))
 (main '())

(define-display-pane-application display-pane-width display-pane-height pre-initialize-procedure post-initialize-procedure finalize-procedure redraw-procedure)syntax

Define a stripped-down UI which will only show a display pane. See define-application for details.

High-level UI

xremove-expose-eventsprocedure

It is generally a good idea to call this at the beginning of your redraw-procedure. It cleans up the X event queue.

say stringprocedure

status stringprocedure

message stringprocedure

Write to the transcript, status, and message panes.

redraw-buttonsprocedure

redraw-display-paneprocedure

redraw-transcript-paneprocedure

redraw-echo-paneprocedure

redraw-status-paneprocedure

redraw-message-paneprocedure

Redraw one of the panes.

define-button-specific-region button state-mask state x y width height methodprocedure

Call method with an x y coordinate when the given X button is pressed masked by an X state mask.

define-button column row name bold?-procedure methodprocedure

Display a button in the button pane at the given column and row. name is either a string or a procedure which takes no arugments and returns a string. bold?-procedure is either #f or a procedure which takes no arguments and returns a boolean. method will be called with no arugments when the button is pressed.

define-sized-button x y size offset text-procedure bold?-procedure methodprocedure

Like define-button but takes a size and offset which are used to define buttons with non-standard sizes.

(define-toggle-button column row name variable method)syntax

Define a toggle button. A wrapper around define-button which you can look to for details. Will flip the truth value of the variable variable and call method with no arguments.

(define-radio-buttons variable method (column row symbol string)+)syntax

Display buttons which let you select the state of variable. Will call method with no arguments when the state changes. Any number of quads can be provided. Each quad defines a column and row for a button, the symbol to which to set variable, and the string to display as the text for that button.

(define-cycle-button column row variable method (symblol text)+)syntax

Display a button which cycles through a range of values for variable. method will be called with no arguments when the state changes. Any number of tuples can be provided. Each tuple consists of the symbol to which to set the variable to and the text to display on the button.

(define-integer-range-buttons column1 row1 column2 row2 variable min max name1 name2 method)syntax

Define two buttons, the first increments and the second decrements variable.

define-spinner-buttons row column name f-up f-down f-printprocedure

Define two spinner buttons side-by-side on the same row.

quit-guiprocedure

abort-guiprocedure

Call the quit or abort handlers.

pnm->pixmap pnmprocedure

free-pixmap pixmapprocedure

draw-pixmap pixmap x yprocedure

Convert a PNM to a pixmap, free a pixmap or draw a pixmap given coordinates for the top left hand corner of the image.

draw-clickable-pixmap-from-pnm pixmap pnm x y scale handlerprocedure

Draw a clickable pixmap which calls handler with the x and y position of the mouse click.

define-key character documentation commandprocedure

Define a shortcut for a given character. command is a function with no arugments that will be called when the keystroke is used. documentation will be displayed in the help overlay.

control characterprocedure

meta characterprocedure

Apply a modifier to a chacter.

define-region x y width height methodprocedure

Any mouse presses in the given region of the display pane will result in calls to method with the x and y coordinates of the mouse press. Note that regions are not permanent, they need to be reset every redraw.

tracking-pointer twice? press? trackerprocedure

Track the position of the mouse calling tracker with the x and y coordinates of the mouse.

define-structure tree-node width height offset text bold? procedure daughtersrecord

tree->tree-node treeprocedure

draw-tree-node tree-node x yprocedure

tree-height treeprocedure

draw-tree tree x yprocedure

Store, draw, and manipulate trees.

define-structure alist-node width height offset keys valuesrecord

alist->alist-node alistprocedure

draw-alist-node alist-node x yprocedure

alist-height alistprocedure

draw-alist alist x yprocedure

Store, draw, and manipulate alists.

help-commandprocedure

Show the help overlay. Will be automatically populated by all keybindings.

help-scroll-up-line-commandprocedure

help-scroll-down-line-commandprocedure

help-scroll-up-page-commandprocedure

help-scroll-down-page-commandprocedure

help-scroll-beginning-commandprocedure

help-scroll-end-commandprocedure

Scrolls the help overlay.

draw-ellipse display drawable gc ellipseprocedure

Draw an ellipse with the given GC context.

draw-clickable-strings-with-scroll-bar first-line set-first-line! left middle right strings xmin xmax ymin ymaxprocedure

draw-clickable-strings-with-optional-scroll-bar first-line set-first-line! left middle right strings xmin xmax ymin ymax font font-gc-fprocedure

Draw a list of strings to the UI with scroll bars or optional scroll balls. first-line is an index into a list of strings, set-first-list! is a procedure which is used to update the position in the list.

Low-level UI

set-background-task-enabler! procedureprocedure

set-background-task-disabler! procedureprocedure

pauseprocedure

set-pause! pprocedure

Enable, disable, and pause background tasks.

process-eventsprocedure

Process pending X events.

set-window-method! window event-type methodprocedure

Attach a method to a window. method will be called with a variable number of arguments depending on the event sent. event-type is a symbol.

send window event-type #!rest &restprocedure

Send an event to a window. event-type is a symbol and rest contains arguments that will be passed to the handler method.

Misc

define stalin? #fprocedure

char-alphanumeric? charprocedure

beginning-of-word? string positionprocedure

end-of-word? string positionprocedure

string-backward-word string positionprocedure

string-kill-word string positionprocedure

string-forward-word string positionprocedure

string-backward-kill-word string positionprocedure

string-insert-character characterprocedure

string-beginning-of-line string positionprocedure

string-backward-char string positionprocedure

string-delete-char string positionprocedure

string-end-of-line string positionprocedure

string-forward-char string positionprocedure

string-kill-line string positionprocedure

string-backward-delete-char string positionprocedure

Miscellaneous functions. These probably belong elsewhere.

define *frame-rate* 30.0procedure

pnm-movie->pixmaps pnm-movieprocedure

draw-pixmaps pixmaps x yprocedure

free-pixmaps pixmapsprocedure

Legacy. Use the ffmpeg-video egg instead.

echo-pane-command editorprocedure

echo-pane-insert-character-command characterprocedure

echo-pane-beginning-of-line-commandprocedure

echo-pane-backward-char-commandprocedure

echo-pane-delete-char-commandprocedure

echo-pane-end-of-line-commandprocedure

echo-pane-forward-char-commandprocedure

echo-pane-kill-line-commandprocedure

echo-pane-backward-delete-char-commandprocedure

echo-pane-backward-word-commandprocedure

echo-pane-kill-word-commandprocedure

echo-pane-command string-kill-wordprocedure

echo-pane-forward-word-commandprocedure

echo-pane-backward-kill-word-commandprocedure

Modify the content of the echo pane. These are internal functions.

abort?procedure

character->pretty-name characterprocedure

prefix-string prefixprocedure

region-handler x y button stateprocedure

define-structure region button state-mask state x y width height methodprocedure

allocate-color-cube! reds greens bluesprocedure

abort-commandprocedure

kill-applicationprocedure

set-kill-application! procedureprocedure

License

Written by Jeffrey Mark Siskind and part of QobiScheme.

Maintainer: Andrei Barbu, andrei@0xab.com

  Copyright 1993-1995 University of Toronto. All rights reserved.
  Copyright 1996 Technion. All rights reserved.
  Copyright 1996 and 1997 University of Vermont. All rights reserved.
  Copyright 1997-2001 NEC Research Institute, Inc. All rights reserved.
  Copyright 2002-2013 Purdue University. All rights reserved.
  This program is free software: you can redistribute it and/or modify
  it under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.
  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU Lesser General Public License for more details.
  You should have received a copy of the GNU Lesser General Public License
  along with this program.  If not, see http://www.gnu.org/licenses.