IUP

Documentation
Login

base Module

Synopsis

Racket

(require iup/base)
CHICKEN (require-extension iup-base)
CHICKEN 5 (require-library iup)
(import iup-base)

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

Data Types

(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.

(iup-version) → string?

Determines the version of the running IUP library.

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

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)

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.

(attributes [handle (or/c ihandle? #f)]) → (listof string?)

Gets a list of all user-defined attributes set on a given handle. If the handle is #f, the global attributes are examined.

(attribute-set! [handle (or/c ihandle? #f)] [name (or/c symbol? string?)] [value any/c]) → void?
(set! (attribute [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:

Scheme Value

Native Value
#f NULL
#t "YES"
Handle Possibly autogenerated global handle name
Any other value A string encoding of the value

(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.

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

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)
(set! (handle-name [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.

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

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

Event functions

(main-loop) → void?

Runs the IUP main loop until it's done.

(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.

(main-loop-flush) → void?

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

(main-loop-level) → integer?

Determines the current main loop nesting depth.

(main-loop-exit) → void?

Signals the main loop to exit.

(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.

In the Racket implementation, a non-NULL return value is always converted into a procedure.

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

Associates a procedure with a callback of an object.

Note that the current CHICKEN implementation allows native pointers to be passed as callback procedures while the Racket implementation always expects procedures.

Layout Functions

(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.

Since CHICKEN's FFI has less argument preprocessing capabilities than Racket's, the CHICKEN version of 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?

Creates an instance of the named IUP object class.

(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.

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

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

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

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

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

Determines the class name of the given object.

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

Determines the class category of the given object.

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

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)

Gets the parent of the given object, if any.

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

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

(sibling [handle ihandle?]) → (or/c ihandle? #f)

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

(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.

(child-remove! [child ihandle?]) → void?

Removes the child from any container it may be in.

(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.

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

Finds a child by index or name.

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

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)

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

(child-count [parent ihandle?]) → integer?

Counts the number of children in a given container.

(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.

(refresh [handle ihandle?]) → void?

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?

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

Shows a dialog or popup menu. 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 (using IupPopup). Otherwise the function returns immediately after making the dialog visible (using IupShowXY).

(hide [handle ihandle?]) → void?

Hides a dialog.

Composition Functions

(dialog [child (or/c ihandle? #f)] #:<name> <value> ...) → ihandle?

Creates a new dialog with the given child.

(fill #:<name> <value> ...) → ihandle?

Creates a new fill element.

(gridbox [child ihandle?] ... #:<name> <value> ...) → ihandle?

Creates a new grid box with the given children.

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

Creates a new horizontal box with the given children.

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

Creates a new vertical box with the given children.

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

Creates a new box superimposing the given children.

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

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

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

Creates a box that resizes its child dynamically.

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

Creates the radio element for grouping mutually exclusive toggles.

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

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

(backgroundbox [child ihandle?] #:<name> <value> ...) → ihandle?

Creates a simple native container with no decorations.

(detachbox [child ihandle?] #:<name> <value> ...) → ihandle?

Creates a detachable void container.

(expandbox [child ihandle?] #:<name> <value> ...) → ihandle?

Creates a void container that can interactively show or hide its child.

(scrollbox [child ihandle?] #:<name> <value> ...) → ihandle?

Creates a native container that allows its child to be scrolled.

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

Creates a container that splits its client area in two.

Image Resource Functions

(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.

(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.

(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.

(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.

(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.

(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

(current-focus) → (or/c ihandle? #f)
(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.

(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.

(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.

Menu Functions

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

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?

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

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

Creates a menu separator.

Miscellaneous Resource Functions

(clipboard #:<name> <value> ...) → ihandle?

Instantiates a representation of the system's clipboard.

(timer #:<name> <value> ...) → ihandle?

Creates a timer object.

(send-url [url string?]) → void?

Open the given URL in an external browser.

Racket Specifics

[_ihandle ctype?]
[_ihandle/null ctype?]

Foreign type of IUP object handles, which may optionally be NULL.

Not re-exported from the main module.

[_istatus ctype?]

Foreign type of IUP status return values.

Not re-exported from the main module.

[_iname/upcase ctype?]

Foreign type of IUP symbolic names, for example for attributes and callbacks.

Not re-exported from the main module.

[_iname/downcase ctype?]

Foreign type of IUP symbolic names, for example for classes, class types and global handle names.

Not re-exported from the main module.

(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"

((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.

((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.

(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.

(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.

(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.

((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.

((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.

(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.

(:children var [handle ihandle?])

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