1. Iup
    1. Description
    2. Author
    3. Repository
    4. Requirements
    5. Documentation
      1. Iup Design Principles
        1. Common attributes
        2. Common callbacks
      2. Module iup-base
        1. Usage
        2. Data Types
        3. System Functions
        4. Attribute Functions
        5. Event functions
        6. Layout Functions
        7. Dialog Functions
        8. Composition Functions
        9. Image Resource Functions
        10. Focus Functions
        11. Menu Functions
        12. Miscellaneous Resource Functions
        13. CHICKEN Specifics
      3. Module iup-controls
        1. Usage
        2. Standard Controls
      4. Module iup-dialogs
        1. Usage
        2. Standard Dialogs
      5. Module iup-dynamic
        1. Usage
        2. Procedures
      6. Module iup-glcanvas
        1. Usage
        2. OpenGL Canvas Control
        3. OpenGL Context Functions
      7. Module iup-pplot
        1. Usage
        2. PPlot Control
        3. Plotting Functions
        4. Auxiliary Functions
      8. Module iup-web
        1. Usage
        2. Web Browser Control
    6. Examples
    7. License

Iup

Description

Bindings to the IUP "portable user interface" GUI library.

Author

Thomas Chust

Repository

https://chust.org/repos/scheme-iup

Requirements

Documentation

See the official API docs

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
Common callbacks

Module iup-base
Usage

(import iup-base)

Basic IUP library support. Initializes the IUP and IUP Image libraries when loaded.

Data Types
[procedure] (ihandle? [v any/c]) -> boolean?

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.

[procedure] (iup-version) -> string?

Determines the version of the running IUP library.

[procedure] (load/led [file path-string?]) -> void?

Loads a LED GUI definition file into memory.

Attribute Functions
[procedure] (attribute [handle (or/c ihandle? #f)] [name (or/c symbol? string?)]) -> (or/c string? #f)

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.

[procedure] (attribute-set! [handle (or/c ihandle? #f)] [name (or/c symbol? string?)] [value any/c]) -> void?

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:

Alternatively:

(set! (attribute [handle (or/c ihandle? #f)] [name (or/c symbol? string?)]) [value any/c])

[procedure] (attribute-reset! [handle (or/c ihandle? #f)] [name (or/c symbol? string?)]) -> void?

Resets the value of an attribute to its default. If the handle is #f, a global attribute is accessed.

[procedure] (handle-name [handle ihandle?]) -> (or/c symbol? string? #f)

Gets the global name associated with a handle, if any.

[procedure] (handle-name-set! [handle ihandle?] [name (or/c symbol? string? #f)]) -> (or/c ihandle? #f)

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)])

[procedure] (handle-ref [name (or/c symbol? string?)]) -> (or/c ihandle? #f)

Gets the handle associated with a global name, if any.

Event functions
[procedure] (main-loop) -> void?

Runs the IUP main loop until it's done.

[procedure] (main-loop-step [poll? any/c]) -> (or/c boolean? symbol? integer?)

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.

[procedure] (main-loop-flush) -> void?

Runs the main loop until all pending events have been processed.

[procedure] (main-loop-level) -> integer?

Determines the current main loop nesting depth.

[procedure] (main-loop-exit) -> void?

Signals the main loop to exit.

[procedure] (callback [handle ihandle?] [name (or/c symbol? string?)]) -> (or/c procedure? pointer? #f)

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.

[procedure] (callback-set! [handle ihandle?] [name (or/c symbol? string?)] [proc (or/c procedure? pointer? #f)]) -> void?

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
[procedure] (make-constructor-procedure [proc 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.

[procedure] (create [class (or/c symbol? string?)] #:<name> <value> ...) -> ihandle?

Creates an instance of the named IUP object class.

[procedure] (destroy! [handle ihandle?]) -> void?

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.

[procedure] (map-peer! [handle ihandle?]) -> void?

Ensures that necessary native resources are allocated to the given object.

[procedure] (unmap-peer! [handle ihandle?]) -> void?

Ensures that no native resources are allocated to the given object.

[procedure] (class-name [handle ihandle?]) -> (or/c symbol? string?)

Determines the class name of the given object.

[procedure] (class-type [handle ihandle?]) -> (or/c symbol? string?)

Determines the class category of the given object.

[procedure] (save-attributes! [handle ihandle?]) -> void?

Ensures that attributes of an object stored in its native resources are also present in the object itself.

[procedure] (parent [handle ihandle?]) -> (or/c ihandle? #f)

Gets the parent of the given object, if any.

[procedure] (parent-dialog [handle ihandle?]) -> (or/c ihandle? #f)

Gets the containing dialog of the given object, if any.

[procedure] (sibling [handle ihandle?]) -> (or/c ihandle? #f)

Gets the next sibling of the given object, if any.

[procedure] (child-add! [child ihandle?] [container ihandle?] [anchor (or/c ihandle? #f) #f]) -> ihandle?

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.

[procedure] (child-remove! [child ihandle?]) -> void?

Removes the child from any container it may be in.

[procedure] (child-move! [child ihandle?] [parent ihandle?] [ref-child (or/c ihandle? #f) #f]) -> void?

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.

[procedure] (child-ref [parent ihandle?] [id (or/c integer? symbol? name?)]) -> (or/c ihandle? #f)

Finds a child by index or name.

[procedure] (child-pos [child ihandle?]) -> (or/c integer? #f)

Gets the position of the child in its container, if any.

[procedure] (child-x/y->pos [parent ihandle?] [x integer?] [y integer?]) -> (or/c integer? #f)

Determines the index of the parent's child that is located at the given coordinates, if any.

[procedure] (child-count [parent ihandle?]) -> integer?

Counts the number of children in a given container.

[procedure] (children [parent ihandle?]) -> (listof? ihandle?)

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.

[procedure] (refresh [handle ihandle?]) -> void?

Updates the size and layout of controls after changing size attributes.

[procedure] (redraw [handle ihandle?] #:children? [children? any/c #f] #:sync? [sync? any/c #f]) -> void?

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
[procedure] (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?)

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.

[procedure] (hide [handle ihandle?]) -> void?

Hides a dialog.

Composition Functions
[procedure] (dialog [child (or/c ihandle? #f)] #:<name> <value> ...) -> ihandle?

Creates a new dialog with the given child.

[procedure] (fill #:<name> <value> ...) -> ihandle?

Creates a new fill element.

[procedure] (hbox [child ihandle?] ... #:<name> <value> ...) -> ihandle?

Creates a new horizontal box with the given children.

[procedure] (vbox [child ihandle?] ... #:<name> <value> ...) -> ihandle?

Creates a new vertical box with the given children.

[procedure] (zbox [child ihandle?] ... #:<name> <value> ...) -> ihandle?

Creates a new box superimposing the given children.

[procedure] (cbox [child ihandle?] ... #:<name> <value> ...) -> ihandle?

Creates a new box with explicit placement of the given children.

[procedure] (sbox [child ihandle?] #:<name> <value> ...) -> ihandle?

Creates a box that resizes its child dynamically.

[procedure] (radio [child ihandle?] #:<name> <value> ...) -> ihandle?

Creates the radio element for grouping mutual exclusive toggles.

[procedure] (normalizer [child ihandle?] ... #:<name> <value> ...) -> ihandle?

Normalizes all controls from a list so their natural size to be the biggest natural size among them.

[procedure] (split [child0 ihandle?] [child1 ihandle?] #:<name> <value> ...) -> ihandle?

Creates a container that splits its client area in two.

Image Resource Functions
[procedure] (image/palette [width integer?] [height integer?] [pixels blob?] #:<name> <value> ...) -> ihandle?

Creates an image to be shown on a label, button, toggle, or as a cursor from binary data in color index mode.

[procedure] (image/rgb [width integer?] [height integer?] [pixels blob?] #:<name> <value> ...) -> ihandle?

Creates an image to be shown on a label, button, toggle, or as a cursor from binary data in RGB mode.

[procedure] (image/rgba [width integer?] [height integer?] [pixels blob?] #:<name> <value> ...) -> ihandle?

Creates an image to be shown on a label, button, toggle, or as a cursor from binary data in RGBA mode.

[procedure] (image/file [file path-string?] #:<name> <value> ...) -> ihandle?

Creates an image to be shown on a label, button, toggle, or as a cursor from data in a file.

[procedure] (image/blob [data bytes?] #:<name> <value> ...) -> ihandle?

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.

[procedure] (image-save [handle ihandle?] [file path-string?] [format (or/c symbol? string?)]) -> void?

Saves an image to a file in the given format.

Focus Functions
[procedure] (current-focus) -> (or/c ihandle? #f)
[procedure] (current-focus [handle (or/c ihandle? #f)]) -> (or/c ihandle? #f)

Gets or sets the object that currently has the input focus. When setting the focus the element that previously held the focus is returned.

[procedure] (focus-next [handle (or/c ihandle? #f) (current-focus)]) -> (or/c ihandle? #f)

Moves the focus from the given element to the next in sequence. Returns the element that received the focus, if any.

[procedure] (focus-previous [handle (or/c ihandle? #f) (current-focus)]) -> (or/c ihandle? #f)

Moves the focus from the given element to the previous in sequence. Returns the element that received the focus, if any.

[procedure] (menu [child ihandle?] ... #:<name> <value> ...) -> ihandle?

Creates a menu with the given children.

[procedure] (menu-item [title (or/c string? #f)] [action/menu (or/c ihandle? symbol? string? #f)] #:<name> <value> ...) -> ihandle?

Creates a menu item with the given title and submenu or action callback name.

[procedure] (menu-separator #:<name> <value> ...) -> ihandle?

Creates a menu separator.

Miscellaneous Resource Functions
[procedure] (clipboard #:<name> <value> ...) -> ihandle?

Instantiates a representation of the system's clipboard.

[procedure] (timer #:<name> <value> ...) -> ihandle?

Creates a timer object.

[procedure] (send-url [url string?]) -> void?

Open the given URL in an external browser.

[procedure] (in-children [handle ihandle?]) -> sequence?

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"

[procedure] ((ihandle->pointer [nonnull? any/c]) [handle (or/c ihandle? #f)]) -> (or/c pointer? #f)

Checking conversion from handles to pointers.

Not re-exported from the main module.

[procedure] ((pointer->ihandle [nonnull? any/c]) [handle (or/c pointer? #f)]) -> (or/c ihandle? #f)

Checking conversion from pointers to handles.

Not re-exported from the main module.

[procedure] (ihandle-list->pointer-vector [handles (listof ihandle?)]) -> pointer-vector?

Checking conversion from a list of handles into a NULL-terminated vector of pointers.

Not re-exported from the main module.

[procedure] (istatus->integer [status (or/c boolean? symbol? integer?)]) -> integer?

Checking conversion from possibly symbolic to numeric status codes.

Not re-exported from the main module.

[procedure] (integer->istatus [status integer?]) -> (or/c boolean? symbol? integer?)

Checking conversion from numeric to possibly symbolic status codes.

Not re-exported from the main module.

[procedure] ((iname->string [default-case (one-of/c 'upcase 'downcase)]) [name (or/c symbol? string? #f)]) -> (or/c string? #f)

Checking conversion from possibly symbolic names to strings.

Not re-exported from the main module.

[procedure] ((string->iname [default-case (one-of/c 'upcase 'downcase)]) [name (or/c string? #f)]) -> (or/c symbol? string? #f)

Checking conversion from strings to possibly symbolic names.

Not re-exported from the main module.

[syntax] (optional-args [name default] ...)

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.

[syntax] (:children var [handle ihandle?])

SRFI-42 sequence generator to iterate over the children of an IUP object.

Module iup-controls
Usage

(import iup-controls)

Support for IUP's controls. Initializes the IUP Controls library when loaded.

Standard Controls
[procedure] (canvas [action (or/c symbol? string? #f) #f] #:<name> <value> ...) -> ihandle?

Creates a canvas interface element with an action callback name. The action is triggered when the canvas needs to be redrawn.

[procedure] (frame [action (or/c symbol? string? #f) #f] #:<name> <value> ...) -> ihandle?

Creates a frame element with a title around a given child.

[procedure] (tabs [child ihandle?] ... #:<name> <value> ...) -> ihandle?

Creates a tabs element with the given children.

[procedure] (label [action (or/c symbol? string? #f) #f] #:<name> <value> ...) -> ihandle?

Creates a label interface element, which displays a separator, a text or an image.

[procedure] (button [title (or/c string? #f) #f] [action (or/c symbol? string? #f) #f] #:<name> <value> ...) -> ihandle?

Creates a button element with the given title and action callback name.

[procedure] (toggle [title (or/c string? #f) #f] [action (or/c symbol? string? #f) #f] #:<name> <value> ...) -> ihandle?

Creates a toggle button element with the given title and action callback name.

[procedure] (spin #:<name> <value> ...) -> ihandle?

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.

[procedure] (spinbox [child (or/c ihandle? #f)] #:<name> <value> ...) -> ihandle?

Creates a box with a spin control around a given child.

[procedure] (valuator [type string? "HORIZONTAL"] #:<name> <value> ...) -> ihandle?

Creates a valuator control with the given orientation.

[procedure] (textbox [action (or/c symbol? string? #f) #f] #:<name> <value> ...) -> ihandle?

Creates an editable text field with a given action callback name.

[procedure] (listbox [action (or/c symbol? string? #f) #f] #:<name> <value> ...) -> ihandle?

Creates an interface element that displays a list of items with a given action callback name.

[procedure] (treebox #:<name> <value> ...) -> ihandle?

Creates a tree containing nodes of branches or leaves.

[procedure] (progress-bar #:<name> <value> ...) -> ihandle?

Creates a progress bar control.

Extended Controls

[procedure] (matrix [action (or/c symbol? string? #f) #f] #:<name> <value> ...) -> ihandle?

Creates a matrix of alphanumeric fields with a given action callback name.

[procedure] (cells #:<name> <value> ...) -> ihandle?

Creates an element containing a grid of cells.

[procedure] (color-bar #:<name> <value> ...) -> ihandle?

Creates a color palette to enable a color selection from several samples.

[procedure] (color-browser #:<name> <value> ...) -> ihandle?

Creates an element for selecting a color.

[procedure] (dial [type string? "HORIZONTAL"] #:<name> <value> ...) -> ihandle?

Creates a dial for regulating a given angular variable with the given orientation.

Module iup-dialogs
Usage

(import 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
[procedure] (file-dialog #:<name> <value> ...) -> ihandle?

Creates a file selection dialog.

[procedure] (message-dialog #:<name> <value> ...) -> ihandle?

Creates a message or confirmation dialog.

[procedure] (color-dialog #:<name> <value> ...) -> ihandle?

Creates a color selection dialog.

[procedure] (font-dialog #:<name> <value> ...) -> ihandle?

Creates a font selection dialog.

[procedure] (layout-dialog [dialog (or/c ihandle? #f) #f] #:<name> <value> ...) -> ihandle?

Creates a layout editor dialog.

[procedure] (element-properties-dialog [element ihandle?] #:<name> <value> ...) -> ihandle?

Creates a property editor dialog.

Module iup-dynamic
Usage

(import iup-dynamic)

Allows access to the GUI library bindings at runtime iff the library is available.

Procedures
[procedure] (iup-available?) -> boolean?

Checks whether the IUP library can be loaded. Returns the version of the IUP library in case of success, #f otherwise.

[procedure] (iup-dynamic-require [sym symbol?]) -> any/c

Obtains the binding of a symbol in the main module dynamically or signals an error if the binding is unavailable.

Module iup-glcanvas
Usage

(import iup-glcanvas)

OpenGL graphics support. Initializes the IUP GLCanvas library when loaded.

OpenGL Canvas Control
[procedure] (glcanvas [action (or/c symbol? string? #f) #f] #:<name> <value> ...) -> ihandle?

Creates a new OpenGL canvas with an action callback name. The action is triggered when the canvas needs to be redrawn.

OpenGL Context Functions
[procedure] (call-with-glcanvas [handle ihandle?] [proc (-> ihandle? any)] #:swap? [swap? any/c #f] #:sync? [sync? any/c #f]) -> any

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.

[procedure] (glcanvas-is-current? [handle ihandle?]) -> boolean?

Checks whether the OpenGL context of the given canvas is the current one.

[procedure] (glcanvas-palette-set! [handle ihandle?] [index integer?] [red real?] [green real?] [blue real?]) -> void?

Defines a palette color for the OpenGL context of the given canvas.

[procedure] (glcanvas-font-set! [handle ihandle?] [first integer?] [count integer?] [list-base integer?]) -> void?

Creates a bitmap display list from the current FONT attribute.

Module iup-pplot
Usage

(import iup-pplot)

Plotting support. Initializes the IUP PPlot library when loaded.

PPlot Control
[procedure] (pplot #:<name> <value> ...) -> ihandle?

Creates a plotting canvas.

Plotting Functions
[procedure] (call-with-pplot [handle ihandle?] [proc (-> ihandle? any)] #:x-string? [x-string? any/c #f]) -> any

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.

[procedure] (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?

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
[procedure] (pplot-x/y->pixel-x/y [handle ihandle?] [x real?] [y real?]) -> (values integer? integer?)

Transforms plot coordinates into pixel coordinates.

[procedure] (pplot-paint-to [handle ihandle?] [canvas canvas?]) -> void?

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

(import iup-web)

Web browsing support. Initializes the IUP Web library when loaded.

Web Browser Control
[procedure] (web-browser #:<name> <value> ...) -> ihandle?

Creates a web browser widget.

Examples

See Tutorial on the Iup GUI toolkit

License

BSD license