chickadee » iup

Iup

Description

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

Author

Thomas Chust

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

(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-version) -> string? procedure

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-loop) -> void? procedure

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-flush) -> void? procedure

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

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

Determines the current main loop nesting depth.

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

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-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-focus) -> (or/c ihandle? #f) procedure
(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
(menu [child ihandle?] ... #:<name> <value> ...) -> ihandle? procedure

Creates a menu with the given children.

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

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

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

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?) -> boolean? 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/c procedure

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

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

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

License

BSD license

Contents »