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.
TOC »
Iup
Description
Bindings to the IUP "portable user interface" GUI library.
Author
Requirements
- srfi-42
- ffcall (sudo apt-get install libffcall1-dev)
- iup
Documentation
or - alternatively - the individual modules below.
Iup Design Principles
Iup programs consist of dialogs which communicate whith each other. They should be destroyed after its use (which destroys the included widgets as well).
Each dialog contains only one widget, usually a container widget, which in turn can contain other widgets, containers included. This nesting of widgets, positioning widgets among them, defines the geometry of the dialog, no widget is ever positioned by explicit coordinates. Only after a dialog is shown anything appears on the screen.
The appearance of dialogs and widgets is governed by attributes, their behaviour by callbacks. Their names are keywords in Chicken, which can be set by name-value-arguments in the constructor, or by attribute-set! and callback-set! programmatically at runtime. Their values can be returned by the attribute and callback routines respectively.
Callbacks are procedures which return a symbol, 'default in most cases, 'close, 'ignore, 'continue in others ('close will usually close the whole dialog). All callbacks should have at least one argument, self in general, which is the widget to which the callback belongs. The signature (in C) of other callbacks can be found in the file iupcbs.h of the original Iup distribution.
Each dialog and each widget accepts its own set of attributes and callbacks, which can be looked up in the original C documentation after having added the Iup prefix (but note, that some have different names in Scheme, listbox and textbox instead of List and Text for example). Nevertheless, there are some common attibutes and callbacks. Here they are:
Common attributes
- #:active
- #:bgcolor
- #:fgcolor
- #:font
- #:visible
- #:clientsize
- #:clientoffset
- #:expand
- #:maxsize
- #:minsize
- #:rastersize
- #:size
- #:floating
- #:position
- #:screenposition
- #:name
- #:tip
- #:title
- #:value
- #:wid
- #:zorder
Common callbacks
- #:default-action
- #:idle-action
- #:destroy-cb
- #:enterwindow-cb
- #:getfocus-cb
- #:help-cb
- #:k-any
- #:killfocus-cb
- #:leavewindow-cb
- #:map-cb
- #:unmap-cb
- #:action
Module iup-base
Usage
(require-extension iup-base)
Basic IUP library support. Initializes the IUP and IUP Image libraries when loaded.
Data Types
- (ihandle? [v any/c]) -> boolean?procedure
Check whether a value is an IUP object handle.
System Functions
[thread-watchdog (or/c ihandle? #f)]
When the base module is loaded it initializes the IUP library if necessary. If the library had to be initialized, a timer is created that triggers yields to other Scheme threads from time to time while IUP's main loop is running. A handle for the timer object is accessible through this variable.
- iup-versionprocedure
Determines the version of the running IUP library.
- (load/led [file path-string?]) -> void?procedure
Loads a LED GUI definition file into memory.
Attribute Functions
- (attribute [handle (or/c ihandle? #f)] [name (or/c symbol? string?)]) -> (or/c string? #f)procedure
Gets the value of an attribute. If the handle is #f, a global attribute is accessed. Attribute values are always returned as strings, which is the native form in which they are stored.
- (attribute-set! [handle (or/c ihandle? #f)] [name (or/c symbol? string?)] [value any/c]) -> void?procedure
Sets the value of an attribute. If the handle is #f, a global attribute is accessed. If the new value is not a string, it is converted as follows:
- #f -> NULL
- #t -> "YES"
- Handle -> Possibly autogenerated global handle name
- Any other value -> string encoding of the value
Alternatively:
(set! (attribute [handle (or/c ihandle? #f)] [name (or/c symbol? string?)]) [value any/c])
- (attribute-reset! [handle (or/c ihandle? #f)] [name (or/c symbol? string?)]) -> void?procedure
Resets the value of an attribute to its default. If the handle is #f, a global attribute is accessed.
- (handle-name [handle ihandle?]) -> (or/c symbol? string? #f)procedure
Gets the global name associated with a handle, if any.
- (handle-name-set! [handle ihandle?] [name (or/c symbol? string? #f)]) -> (or/c ihandle? #f)procedure
Sets the global name associated with a handle, if any. Returns any handle previously associated with the same name, if any.
Alternatively:
(set! (handle-name [handle ihandle?]) [name (or/c symbol? string? #f)])
- (handle-ref [name (or/c symbol? string?)) -> (or/c ihandle? #f)procedure
Gets the handle associated with a global name, if any.
Event functions
- main-loopprocedure
Runs the IUP main loop until it's done.
- (main-loop-step [poll? any/c]) -> (or/c boolean? symbol? integer?)procedure
Runs a step of the IUP main loop and returns the status code from the processing. If poll? is true, the call returns immediately with a false result in case there are no events to process. If poll? is false, the call does not return until at least one event has been processed.
- main-loop-flushprocedure
Runs the main loop until all pending events have been processed.
- main-loop-levelprocedure
Determines the current main loop nesting depth.
- main-loop-exitprocedure
Signals the main loop to exit.
- (callback [handle ihandle?] [name (or/c symbol? string?)]) -> (or/c procedure? pointer? #f)procedure
Gets the procedure, if any, associated with a callback of an object.
Note that in the current CHICKEN implementation, callbacks installed by native code will be returned as pointers while callbacks installed by Scheme code will be unwrapped into Scheme procedures.
- (callback-set! [handle ihandle?] [name (or/c symbol? string?)] [proc (or/c procedure? pointer? #f)]) -> void?procedure
Associates a procedure with a callback of an object.
Alternatively:
(set! (callback [handle ihandle?] [name (or/c symbol? string?)]) [proc (or/c procedure? pointer? #f)])
Note that the current CHICKEN implementation allows native pointers to be passed as callback procedures.
Layout Functions
- (make-constructor-procedure [proc procedure?]) -> procedure?procedure
Wraps an IUP object constructor such that it accepts keyword arguments that are turned into attribute or callback settings and passes positional arguments through to the original procedure.
This procedure also accepts a keyword argument of the form #:apply-args [proc (-> list? list?)] that allows you to preprocess the positional argument list before it is handed to the wrapped procedure.
Not re-exported from the main module.
- (create [class (or/c symbol? string?)] #:<name> <value> ...) -> ihandle?procedure
Creates an instance of the named IUP object class.
- (destroy! [handle ihandle?]) -> void?procedure
Destroys an IUP object instance and all its children. Object destruction is explicit since native resources may be associated with objects that should not necessarily be reclaimed even if a Scheme handle to the object goes out of scope.
- (map-peer! [handle ihandle?]) -> void?procedure
Ensures that necessary native resources are allocated to the given object.
- (unmap-peer! [handle ihandle?]) -> void?procedure
Ensures that no native resources are allocated to the given object.
- (class-name [handle ihandle?]) -> (or/c symbol? string?)procedure
Determines the class name of the given object.
- (class-type [handle ihandle?]) -> (or/c symbol? string?)procedure
Determines the class category of the given object.
- (save-attributes! [handle ihandle?]) -> void?procedure
Ensures that attributes of an object stored in its native resources are also present in the object itself.
- (parent [handle ihandle?]) -> (or/c ihandle? #f)procedure
Gets the parent of the given object, if any.
- (parent-dialog [handle ihandle?]) -> (or/c ihandle? #f)procedure
Gets the containing dialog of the given object, if any.
- (sibling [handle ihandle?]) -> (or/c ihandle? #f)procedure
Gets the next sibling of the given object, if any.
- (child-add! [child ihandle?] [container ihandle?] [anchor (or/c ihandle? #f) #f]) -> ihandle?procedure
Inserts a child into a container, optionally specifying another child before which the new element should be placed. Returns the container to which the child was actually added.
- (child-remove! [child ihandle?]) -> void?procedure
Removes the child from any container it may be in.
- (child-move! [child ihandle?] [parent ihandle?] [ref-child (or/c ihandle? #f) #f]) -> void?procedure
Moves the child from its current container into another one. Optionally an existing child of the new container may be specified after which the moved child will be placed.
- (child-ref [parent ihandle?] [id (or/c integer? symbol? name?)]) -> (or/c ihandle? #f)procedure
Finds a child by index or name.
- (child-pos [child ihandle?]) -> (or/c integer? #f)procedure
Gets the position of the child in its container, if any.
- (child-x/y->pos [parent ihandle?] [x integer?] [y integer?]) -> (or/c integer? #f)procedure
Determines the index of the parent's child that is located at the given coordinates, if any.
- (child-count [parent ihandle?]) -> integer?procedure
Counts the number of children in a given container.
- (children [parent ihandle?]) -> (listof? ihandle?)procedure
Gets all children of a given container as a list. If you plan to iterate over the children, you may also consider using in-children or :children.
- (refresh [handle ihandle?]) -> void?procedure
Updates the size and layout of controls after changing size attributes.
- (redraw [handle ihandle?] #:children? [children? any/c #f] #:sync? [sync? any/c #f]) -> void?procedure
Causes the element to be redrawn. If children? is true, child elements are also redrawn. If sync? is true, the redrawing is forced to happen immediately before the call returns.
Dialog Functions
- (show [handle ihandle?] #:x [x (or/c symbol? integer?) 'current] #:y [y (or/c symbol? integer?) 'current] #:modal? [modal? any/c #f]) -> (or/c boolean? symbol? integer?)procedure
Shows a dialog. The x and y arguments determine where the dialog is placed on the screen and default to the current position. Apart from pixel coordinates the following values are acceptable: 'center, 'start, 'top, 'left, 'end, 'bottom, 'right, 'mouse, 'parent-center, 'current.
If modal? is true, the dialog is shown as a modal dialog and the call only returns after the dialog is dismissed.
- (hide [handle ihandle?]) -> void?procedure
Hides a dialog.
Composition Functions
- (dialog [child (or/c ihandle? #f)] #:<name> <value> ...) -> ihandle?procedure
Creates a new dialog with the given child.
- (fill #:<name> <value> ...) -> ihandle?procedure
Creates a new fill element.
- (hbox [child ihandle?] ... #:<name> <value> ...) -> ihandle?procedure
Creates a new horizontal box with the given children.
- (vbox [child ihandle?] ... #:<name> <value> ...) -> ihandle?procedure
Creates a new vertical box with the given children.
- (zbox [child ihandle?] ... #:<name> <value> ...) -> ihandle?procedure
Creates a new box superimposing the given children.
- (cbox [child ihandle?] ... #:<name> <value> ...) -> ihandle?procedure
Creates a new box with explicit placement of the given children.
- (sbox [child ihandle?] #:<name> <value> ...) -> ihandle?procedure
Creates a box that resizes its child dynamically.
- (radio [child ihandle?] #:<name> <value> ...) -> ihandle?procedure
Creates the radio element for grouping mutual exclusive toggles.
- (normalizer [child ihandle?] ... #:<name> <value> ...) -> ihandle?procedure
Normalizes all controls from a list so their natural size to be the biggest natural size among them.
- (split [child0 ihandle?] [child1 ihandle?] #:<name> <value> ...) -> ihandle?procedure
Creates a container that splits its client area in two.
Image Resource Functions
- (image/palette [width integer?] [height integer?] [pixels blob?] #:<name> <value> ...) -> ihandle?procedure
Creates an image to be shown on a label, button, toggle, or as a cursor from binary data in color index mode.
- (image/rgb [width integer?] [height integer?] [pixels blob?] #:<name> <value> ...) -> ihandle?procedure
Creates an image to be shown on a label, button, toggle, or as a cursor from binary data in RGB mode.
- (image/rgba [width integer?] [height integer?] [pixels blob?] #:<name> <value> ...) -> ihandle?procedure
Creates an image to be shown on a label, button, toggle, or as a cursor from binary data in RGBA mode.
- (image/file [file path-string?] #:<name> <value> ...) -> ihandle?procedure
Creates an image to be shown on a label, button, toggle, or as a cursor from data in a file.
- (image/blob [data bytes?] #:<name> <value> ...) -> ihandle?procedure
Creates an image to be shown on a label, button, toggle, or as a cursor from data in memory. Data can be passed as a string or blob.
- (image-save [handle ihandle?] [file path-string?] [format (or/c symbol? string?)]) -> void?procedure
Saves an image to a file in the given format.
Focus Functions
- current-focusprocedure
- (current-focus [handle (or/c ihandle? #f)]) -> (or/c ihandle? #f)procedure
Gets or sets the object that currently has the input focus. When setting the focus the element that previously held the focus is returned.
- (focus-next [handle (or/c ihandle? #f) (current-focus)]) -> (or/c ihandle? #f)procedure
Moves the focus from the given element to the next in sequence. Returns the element that received the focus, if any.
- (focus-previous [handle (or/c ihandle? #f) (current-focus)]) -> (or/c ihandle? #f)procedure
Moves the focus from the given element to the previous in sequence. Returns the element that received the focus, if any.
Menu Functions
Creates a menu with the given children.
Creates a menu item with the given title and submenu or action callback name.
Creates a menu separator.
Miscellaneous Resource Functions
- (clipboard #:<name> <value> ...) -> ihandle?procedure
Instantiates a representation of the system's clipboard.
- (timer #:<name> <value> ...) -> ihandle?procedure
Creates a timer object.
- (send-url [url string?]) -> void?procedure
Open the given URL in an external browser.
- (in-children [handle ihandle?]) -> sequence?procedure
Sequence generator to iterate over the children of an IUP object.
CHICKEN Specifics
The base module only exports checking type conversion functions instead of foreign types since the latter cannot be exported. To define the types ihandle, nonnull-ihandle, ihandle-list, istatus, iname/upcase and iname/downcase in your own module, include the file "iup-types.scm"
- ((ihandle->pointer [nonnull? any/c]) [handle (or/c ihandle? #f)]) -> (or/c pointer? #f)procedure
Checking conversion from handles to pointers.
Not re-exported from the main module.
- ((pointer->ihandle [nonnull? any/c]) [handle (or/c pointer? #f)]) -> (or/c ihandle? #f)procedure
Checking conversion from pointers to handles.
Not re-exported from the main module.
- (ihandle-list->pointer-vector [handles (listof ihandle?)]) -> pointer-vector?procedure
Checking conversion from a list of handles into a NULL-terminated vector of pointers.
Not re-exported from the main module.
- (istatus->integer [status (or/c boolean? symbol? integer?)]) -> integer?procedure
Checking conversion from possibly symbolic to numeric status codes.
Not re-exported from the main module.
- (integer->istatus [status integer?]) -> (or/c boolean? symbol? integer?)procedure
Checking conversion from numeric to possibly symbolic status codes.
Not re-exported from the main module.
- ((iname->string [default-case (one-of/c 'upcase 'downcase)]) [name (or/c symbol? string? #f)]) -> (or/c string? #f)procedure
Checking conversion from possibly symbolic names to strings.
Not re-exported from the main module.
- ((string->iname [default-case (one-of/c 'upcase 'downcase)]) [name (or/c string? #f)]) -> (or/c symbol? string? #f)procedure
Checking conversion from strings to possibly symbolic names.
Not re-exported from the main module.
- (optional-args [name default] ...)syntax
Convenience syntax to create a procedure suitable to supply to the
#:apply-args argument of make-constructor-procedure which recognizes the given arguments with defaults and returns them in a list.
Not re-exported from the main module.
- (:children var [handle ihandle?])syntax
SRFI-42 sequence generator to iterate over the children of an IUP object.
Module iup-controls
Usage
(require-extension iup-controls)
Support for IUP's controls. Initializes the IUP Controls library when loaded.
Standard Controls
- (canvas [action (or/c symbol? string? #f) #f] #:<name> <value> ...) -> ihandle?procedure
Creates a canvas interface element with an action callback name. The action is triggered when the canvas needs to be redrawn.
- (frame [action (or/c symbol? string? #f) #f] #:<name> <value> ...) -> ihandle?procedure
Creates a frame element with a title around a given child.
- (tabs [child ihandle?] ... #:<name> <value> ...) -> ihandle?procedure
Creates a tabs element with the given children.
- (label [action (or/c symbol? string? #f) #f] #:<name> <value> ...) -> ihandle?procedure
Creates a label interface element, which displays a separator, a text or an image.
- (button [title (or/c string? #f) #f] [action (or/c symbol? string? #f) #f] #:<name> <value> ...) -> ihandle?procedure
Creates a button element with the given title and action callback name.
- (toggle [title (or/c string? #f) #f] [action (or/c symbol? string? #f) #f] #:<name> <value> ...) -> ihandle?procedure
Creates a toggle button element with the given title and action callback name.
- (spin #:<name> <value> ...) -> ihandle?procedure
Create a spin control with two buttons, one with an up arrow and the other with a down arrow, to be used to increment and decrement values.
- (spinbox [child (or/c ihandle? #f)] #:<name> <value> ...) -> ihandle?procedure
Creates a box with a spin control around a given child.
- (valuator [type string? "HORIZONTAL"] #:<name> <value> ...) -> ihandle?procedure
Creates a valuator control with the given orientation.
- (textbox [action (or/c symbol? string? #f) #f] #:<name> <value> ...) -> ihandle?procedure
Creates an editable text field with a given action callback name.
- (listbox [action (or/c symbol? string? #f) #f] #:<name> <value> ...) -> ihandle?procedure
Creates an interface element that displays a list of items with a given action callback name.
- (treebox #:<name> <value> ...) -> ihandle?procedure
Creates a tree containing nodes of branches or leaves.
- (progress-bar #:<name> <value> ...) -> ihandle?procedure
Creates a progress bar control.
Extended Controls
- (matrix [action (or/c symbol? string? #f) #f] #:<name> <value> ...) -> ihandle?procedure
Creates a matrix of alphanumeric fields with a given action callback name.
- (cells #:<name> <value> ...) -> ihandle?procedure
Creates an element containing a grid of cells.
- (color-bar #:<name> <value> ...) -> ihandle?procedure
Creates a color palette to enable a color selection from several samples.
- (color-browser #:<name> <value> ...) -> ihandle?procedure
Creates an element for selecting a color.
- (dial [type string? "HORIZONTAL"] #:<name> <value> ...) -> ihandle?procedure
Creates a dial for regulating a given angular variable with the given orientation.
Module iup-dialogs
Usage
(require-extension iup-dialogs)
Support for platform standard dialogs.
Note, that most of these dialogs are modal. Hence they must be shown with the #:modal? keyword set.
Standard Dialogs
- (file-dialog #:<name> <value> ...) -> ihandle?procedure
Creates a file selection dialog.
- (message-dialog #:<name> <value> ...) -> ihandle?procedure
Creates a message or confirmation dialog.
- (color-dialog #:<name> <value> ...) -> ihandle?procedure
Creates a color selection dialog.
- (font-dialog #:<name> <value> ...) -> ihandle?procedure
Creates a font selection dialog.
- (layout-dialog [dialog (or/c ihandle? #f) #f] #:<name> <value> ...) -> ihandle?procedure
Creates a layout editor dialog.
- (element-properties-dialog [element ihandle?] #:<name> <value> ...) -> ihandle?procedure
Creates a property editor dialog.
Module iup-dynamic
Usage
(require-extension iup-dynamic)
Allows access to the GUI library bindings at runtime iff the library is available.
Procedures
- iup-available?procedure
Checks whether the IUP library can be loaded. Returns the version of the IUP library in case of success, #f otherwise.
- (iup-dynamic-require [sym symbol?]) -> any/cprocedure
Obtains the binding of a symbol in the main module dynamically or signals an error if the binding is unavailable.
Module iup-glcanvas
Usage
(require-extension iup-glcanvas)
OpenGL graphics support. Initializes the IUP GLCanvas library when loaded.
OpenGL Canvas Control
- (glcanvas [action (or/c symbol? string? #f) #f] #:<name> <value> ...) -> ihandle?procedure
Creates a new OpenGL canvas with an action callback name. The action is triggered when the canvas needs to be redrawn.
OpenGL Context Functions
- (call-with-glcanvas [handle ihandle?] [proc (-> ihandle? any)] #:swap? [swap? any/c #f] #:sync? [sync? any/c #f]) -> anyprocedure
Calls the given procedure with the given OpenGL canvas handle and ensures that the OpenGL context of the canvas is active during the call. Returns whatever the given procedure returns.
If swap? is true, the double buffers of the OpenGL context are swapped before the call returns.
If sync? is true, the state of the windowing system and OpenGL is synchronized before entry into and after exit from the given procedure.
- (glcanvas-is-current? [handle ihandle?]) -> boolean?procedure
Checks whether the OpenGL context of the given canvas is the current one.
- (glcanvas-palette-set! [handle ihandle?] [index integer?] [red real?] [green real?] [blue real?]) -> void?procedure
Defines a palette color for the OpenGL context of the given canvas.
- (glcanvas-font-set! [handle ihandle?] [first integer?] [count integer?] [list-base integer?]) -> void?procedure
Creates a bitmap display list from the current FONT attribute.
Module iup-pplot
Usage
(require-extension iup-pplot)
Plotting support. Initializes the IUP PPlot library when loaded.
PPlot Control
- (pplot #:<name> <value> ...) -> ihandle?procedure
Creates a plotting canvas.
Plotting Functions
- (call-with-pplot [handle ihandle?] [proc (-> ihandle? any)] #:x-string? [x-string? any/c #f]) -> anyprocedure
Calls the given procedure with the given plotting canvas handle and ensures that the canvas is ready to receive data in the given x-axis mode. Returns whatever the given procedure returns.
- (pplot-add! [handle ihandle?] [x (or/c string? real?)] [y real?] [sample-index (or/c integer? #f) #f] [index (or/c integer? #f) #f]) -> void?procedure
Adds a sample to the given plotting canvas. Whether x must be a string or a real number depends on the setting of the xdata-string? argument to the call-with-pplot invocation that created the dataset.
If sample-index is #f, the sample is appended to the dataset and the call to pplot-add! must be within the dynamic context of a call to call-with-pplot.
If sample-index is a number, the sample is inserted into the dataset before the given sample index. The call to pplot-add! does not have to be within the dynamic context of a call to call-with-pplot in this case. The dataset to which the new sample should be added may be specified explicitly by its index through the index argument. If the index argument is false, the current dataset of the plotting canvas is used.
Auxiliary Functions
- (pplot-x/y->pixel-x/y [handle ihandle?] [x real?] [y real?]) -> (values integer? integer?)procedure
Transforms plot coordinates into pixel coordinates.
- (pplot-paint-to [handle ihandle?] [canvas canvas?]) -> void?procedure
Paints the plot's contents into a canvas other than the one belonging to the plot control itself. canvas should be a pointer to a canvas object created using the CD graphics library.
Module iup-web
Usage
(require-extension iup-web)
Web browsing support. Initializes the IUP Web library when loaded.
Web Browser Control
- (web-browser #:<name> <value> ...) -> ihandle?procedure
Creates a web browser widget.
Examples
See Tutorial on the Iup GUI toolkit