kiwi

This egg provides a fairly complete set of low-level bindings and a high-level SXML widget interface to the KiWi library. It is intended to be used in combination with the sdl2 egg to create simple user interfaces for games and GUI applications.

Author

Vasilij Schneidermann

Repository

https://depp.brause.cc/kiwi

Requirements

Both KiWi and SDL2 must be available on your machine. An Arch Linux PKGBUILD is available here. The bindings are based on everything up to commit 77ec0d, so they might break on API-incompatible changes introduced after 2018-08-20. Please contact me on the #chicken channel or open a GitHub issue if this happens to you.

The installation script tries autodetecting their location with cmake and sdl2-config. This can be overridden by using the KIWI_CFLAGS, KIWI_LDLIBS, SDL2_CFLAGS and SDL2_LDLIBS environment variables. The bindings themselves require the clojurian and matchable eggs.

API

Setup and teardown

create-sdl2-driver

[procedure] (create-sdl2-driver RENDERER WINDOW)

Creates and returns a SDL2-backed driver. RENDERER and WINDOW must be raw pointers to a SDL2 renderer and window and can be obtained by using the unwrap-renderer and unwrap-window procedures from the sdl2-internals module of the sdl2 egg.

driver?

[procedure] (driver? ARG)

Returns #t if ARG is an driver, otherwise #f.

driver-sdl2-renderer

[procedure] (driver-sdl2-renderer DRIVER)

Returns the raw SDL2 renderer pointer associated with DRIVER.

driver-sdl2-window

[procedure] (driver-sdl2-window DRIVER)

Returns the raw SDL2 window pointer associated with DRIVER.

release-driver!

[procedure] (release-driver! DRIVER)

Frees the resources of DRIVER. This is called implicitly as finalizer for driver records.

load-surface

[procedure] (load-surface DRIVER FILENAME)

Creates and returns a surface based on an image found at FILENAME. Supported image formats are the same as for the sdl2-image egg. If the image could not be loaded, an exception of the type (exn sdl2) is thrown.

surface?

[procedure] (surface? ARG)

Returns #t if ARG is an surface, otherwise #f.

release-surface!

[procedure] (release-surface! DRIVER SURFACE)

Frees the resources of SURFACE. This is called implicitly as finalizer for surface records.

load-font

[procedure] (load-font DRIVER FONTNAME SIZE)

Creates and returns a font based on the TTF font found at FILENAME with the font size SIZE. If the font could not be loaded, an exception of the type (exn sdl2) is thrown.

font?

[procedure] (font? ARG)

Returns #t if ARG is an font, otherwise #f.

release-font!

[procedure] (release-font! DRIVER FONT)

Frees the resources of FONT. This is called implicitly as finalizer for font records.

init!

[procedure] (init! DRIVER TILESET-SURFACE)

Initializes and returns a GUI. TILESET-SURFACE must be a surface to be used as tileset.

process-events!

[procedure] (process-events! GUI)

Process events for GUI and trigger all event handlers involved.

paint!

[procedure] (paint! GUI)

Repaint all widgets associated with GUI.

quit!

[procedure] (quit! GUI)

Terminates GUI and frees the resources of all associated widgets. This procedure must be called explicitly at the end of the program before terminating SDL2 and is therefore a candidate for an on-exit handler.

gui-driver / gui-driver-set!

[procedure] (gui-driver GUI)
[procedure] (gui-driver-set! GUI DRIVER)
[setter] (set! (gui-driver GUI) DRIVER)

Retrieves or sets the driver of GUI.

gui-font / gui-font-set!

[procedure] (gui-font GUI)
[procedure] (gui-font-set! GUI FONT)
[setter] (set! (gui-font GUI) FONT)

Retrieves or sets the font of GUI. Note that this is optional as KiWi comes baked in with Source Sans Pro as default font.

gui-text-color / gui-text-color-set!

[procedure] (gui-text-color GUI)
[procedure] (gui-text-color-set! GUI TEXT-COLOR)
[setter] (set! (gui-text-color GUI) TEXT-COLOR)

Retrieves or sets the text color of GUI.

gui-tileset-surface / gui-tileset-surface-set!

[procedure] (gui-tileset-surface GUI)
[procedure] (gui-tileset-surface-set! GUI TILESET-SURFACE)
[setter] (set! (gui-tileset-surface GUI) TILESET-SURFACE)

Retrieves or sets the tileset surface of GUI.

Rects

rect

[procedure] (rect X Y W H)

Creates and returns a rectangle at the coordinates X and Y with the dimensions W and H.

rect?

[procedure] (rect? ARG)

Returns #t if ARG is an rect, otherwise #f.

rect-x / rect-x-set!

[procedure] (rect-x RECT)
[procedure] (rect-x-set! RECT X)
[setter] (set! (rect-x RECT) X)

Retrieves or sets the x coordinate of RECT.

rect-y / rect-y-set!

[procedure] (rect-y RECT)
[procedure] (rect-y-set! RECT Y)
[setter] (set! (rect-y RECT) Y)

Retrieves or sets the y coordinate of RECT.

rect-w / rect-w-set!

[procedure] (rect-w RECT)
[procedure] (rect-w-set! RECT W)
[setter] (set! (rect-w RECT) W)

Retrieves or sets the width of RECT.

rect-h / rect-h-set!

[procedure] (rect-h RECT)
[procedure] (rect-h-set! RECT H)
[setter] (set! (rect-h RECT) H)

Retrieves or sets the height of RECT.

Rect helpers

rect-empty?

[procedure] (rect-empty? RECT)

Returns #t if RECT is empty, otherwise #f.

enclosing-rect

[procedure] (enclosing-rect RECTS)

Returns a rectangle enclosing all RECTS.

rect-center-in-parent!

[procedure] (rect-center-in-parent! PARENT INNER)

Centers INNER in PARENT vertically and horizontally by mutating the coordinates of INNER.

rect-center-in-parent-vertically!

[procedure] (rect-center-in-parent-vertically! PARENT INNER)

Centers INNER in PARENT vertically by mutating the coordinates of INNER.

rect-center-in-parent-horizontally!

[procedure] (rect-center-in-parent-horizontally! PARENT INNER)

Centers INNER in PARENT horizontally by mutating the coordinates of INNER.

rect-layout-vertically!

[procedure] (rect-layout-vertically! RECTS PADDING [HALIGN])

Layouts RECTS to be aligned as a vertical list with PADDING pixels between them by mutating their coordinates. HALIGN must be one of (left center right) if specified, otherwise the horizontal alignment of RECTS will not be changed.

rect-layout-horizontally!

[procedure] (rect-layout-horizontally! RECTS PADDING [VALIGN])

Layouts RECTS to be aligned as a horizontal list with PADDING pixels between them by mutating their coordinates. VALIGN must be one of (top middle bottom) if specified, otherwise the vertical alignment of RECTS will not be changed.

rect-fill-parent-vertically!

[procedure] (rect-fill-parent-vertically! PARENT RECTS WEIGHTS PADDING)

Layouts and resizes RECTS to fit PARENT by changing their coordinates and height. WEIGHTS is a list of fixnums mapped to RECTS. The higher the weight, the more space a rectangle will occupy. PADDING specifies the space in pixels between the rectangles. Note that this procedure does no rectangle aligning.

rect-fill-parent-horizontally!

[procedure] (rect-fill-parent-horizontally! PARENT RECTS WEIGHTS PADDING VALIGN)

Layouts and resizes RECTS to fit PARENT by changing their coordinates and width. WEIGHTS is a list of fixnums mapped to RECTS. The higher the weight, the more space a rectangle will occupy. PADDING specifies the space in pixels between the rectangles. VALIGN must be one of (top middle bottom).

rect-margin!

[procedure] (rect-margin! PARENT INNER MARGIN)

Resizes and repositions INNER to be centered inside PARENT with MARGIN pixels of margin.

Colors

color

[procedure] (color R G B A)

Creates and returns a color with the components R, G, B and A.

color?

[procedure] (color? ARG)

Returns #t if ARG is an color, otherwise #f.

color-r / color-r-set!

[procedure] (color-r COLOR)
[procedure] (color-r-set! COLOR R)
[setter] (set! (color-r COLOR) R)

Retrieves or sets the red component of COLOR. R must be a fixnum between 0 and 255 (inclusive).

color-g / color-g-set!

[procedure] (color-g COLOR)
[procedure] (color-g-set! COLOR G)
[setter] (set! (color-g COLOR) G)

Retrieves or sets the green component of COLOR. G must be a fixnum between 0 and 255 (inclusive).

color-b / color-b-set!

[procedure] (color-b COLOR)
[procedure] (color-b-set! COLOR B)
[setter] (set! (color-b COLOR) B)

Retrieves or sets the blue component of COLOR. B must be a fixnum between 0 and 255 (inclusive).

color-a / color-a-set!

[procedure] (color-a COLOR)
[procedure] (color-a-set! COLOR A)
[setter] (set! (color-a COLOR) A)

Retrieves or sets the alpha component of COLOR. A must be a fixnum between 0 and 255 (inclusive).

frame

[procedure] (frame GUI PARENT GEOMETRY)

Creates and returns a frame widget. PARENT must either be a widget or #f to create a top-level widget. GEOMETRY is a rectangle describing the position and dimensions of the widget.

frame?

[procedure] (frame? ARG)

Returns #t if ARG is an frame widget, otherwise #f.

scrollbox

[procedure] (scrollbox GUI PARENT GEOMETRY)

Creates and returns a scrollbox widget. PARENT must either be a widget or #f to create a top-level widget. GEOMETRY is a rectangle describing the position and dimensions of the widget.

scrollbox?

[procedure] (scrollbox? ARG)

Returns #t if ARG is an scrollbox widget, otherwise #f.

scrollbox-vertical-scroll!

[procedure] (scrollbox-vertical-scroll! SCROLLBOX AMOUNT)

Scroll SCROLLBOX vertically by AMOUNT pixels.

scrollbox-horizontal-scroll!

[procedure] (scrollbox-horizontal-scroll! SCROLLBOX AMOUNT)

Scroll SCROLLBOX horizontally by AMOUNT pixels.

label

[procedure] (label GUI PARENT TEXT GEOMETRY)

Creates and returns a label widget. PARENT must either be a widget or #f to create a top-level widget. TEXT is a string to be used as the label's text. GEOMETRY is a rectangle describing the position and dimensions of the widget.

label?

[procedure] (label? ARG)

Returns #t if ARG is an label widget, otherwise #f.

label-text-set!

[procedure] (label-text-set! LABEL TEXT)

Sets the text of LABEL to TEXT.

label-icon-set!

[procedure] (label-icon-set! LABEL CLIP)

Sets an icon for LABEL. CLIP is a rectangle that will be clipped out of the currently active tileset for the icon.

label-alignment-set!

[procedure] (label-alignment-set! LABEL HALIGN HOFFSET VALIGN VOFFSET)

Sets the alignment of LABEL. HALIGN must be one of (left center right) and VALIGN one of (top middle bottom). HOFFSET and VOFFSET specify the horizontal and vertical offset in pixels.

label-style-set!

[procedure] (label-style-set! LABEL STYLE)

Sets the text style of LABEL. STYLE must be one of (normal bold italic underline strikethrough).

label-font / label-font-set!

[procedure] (label-font LABEL)
[procedure] (label-font-set! LABEL FONT)
[setter] (set! (label-font LABEL) FONT)

Retrieves or sets the font of LABEL.

label-text-color / label-text-color-set!

[procedure] (label-text-color LABEL)
[procedure] (label-text-color-set! LABEL TEXT-COLOR)
[setter] (set! (label-text-color LABEL) TEXT-COLOR)

Retrieves or sets the text color of LABEL. Note that this will default to black.

label-text-color-set?

[procedure] (label-text-color-set? LABEL)

Returns #t if the text color of LABEL has been set by the user.

button

[procedure] (button GUI PARENT TEXT GEOMETRY)

Creates and returns a button widget. PARENT must either be a widget or #f to create a top-level widget. TEXT is a string to be used for creating the button's label. GEOMETRY is a rectangle describing the position and dimensions of the widget.

button*

[procedure] (button* GUI PARENT LABEL GEOMETRY)

Creates and returns a button widget. PARENT must either be a widget or #f to create a top-level widget. LABEL is a label to be associated with the button and can be #f to have none. GEOMETRY is a rectangle describing the position and dimensions of the widget.

button?

[procedure] (button? ARG)

Returns #t if ARG is an button widget, otherwise #f.

button-label / button-label-set!

[procedure] (button-label BUTTON)
[procedure] (button-label-set! BUTTON LABEL)
[setter] (set! (button-label BUTTON) LABEL)

Retrieves or sets the label of BUTTON. The latter returns the old label.

editbox

[procedure] (editbox GUI PARENT TEXT GEOMETRY)

Creates and returns a editbox widget. PARENT must either be a widget or #f to create a top-level widget. TEXT is a string to be used as the button's text. GEOMETRY is a rectangle describing the position and dimensions of the widget.

editbox?

[procedure] (editbox? ARG)

Returns #t if ARG is an editbox widget, otherwise #f.

editbox-text / editbox-text-set!

[procedure] (editbox-text EDITBOX)
[procedure] (editbox-text-set! EDITBOX TEXT)
[setter] (set! (editbox-text EDITBOX) TEXT)

Retrieves or sets the text of EDITBOX.

editbox-cursor-position / editbox-cursor-position-set!

[procedure] (editbox-cursor-position EDITBOX)
[procedure] (editbox-cursor-position-set! EDITBOX POS)
[setter] (set! (editbox-cursor-position EDITBOX) POS)

Retrieves or sets the cursor position of EDITBOX. POS must be a fixnum specifying a valid index into the existing editbox text.

editbox-font / editbox-font-set!

[procedure] (editbox-font EDITBOX)
[procedure] (editbox-font-set! EDITBOX FONT)
[setter] (set! (editbox-font EDITBOX) FONT)

Retrieves or sets the font of EDITBOX.

editbox-text-color / editbox-text-color-set!

[procedure] (editbox-text-color EDITBOX)
[procedure] (editbox-text-color-set! EDITBOX TEXT-COLOR)
[setter] (set! (editbox-text-color EDITBOX) TEXT-COLOR)

Retrieves or sets the text color of EDITBOX. Note that this will default to black.

editbox-text-color-set?

[procedure] (editbox-text-color-set? EDITBOX)

Returns #t if the text color of EDITBOX has been set by the user.

toggle

[procedure] (toggle GUI PARENT GEOMETRY)

Creates and returns a toggle widget. PARENT must either be a widget or #f to create a top-level widget. GEOMETRY is a rectangle describing the position and dimensions of the widget.

toggle-checked? / toggle-checked?-set!

[procedure] (toggle-checked? TOGGLE)
[procedure] (toggle-checked?-set! TOGGLE CHECKED?)
[setter] (set! (toggle-checked? TOGGLE) CHECKED?)

Retrieves or sets the activation state of TOGGLE. CHECKED? must be either #t or #f.

[procedure] (widget? ARG)

Returns #t if ARG is an widget, otherwise #f.

[procedure] (widget-type WIDGET)

Returns a symbol describing the widget type. It will be one of (frame scrollbox label button editbox).

[procedure] (widget-gui WIDGET)

Returns the GUI associated with WIDGET. This is a convenience procedure intended for use in event handlers.

[procedure] (widget-driver WIDGET)

Returns the driver associated with WIDGET. This is a convenience procedure intended for use in event handlers.

[procedure] (widget-tileset-surface WIDGET)
[procedure] (widget-tileset-surface-set! WIDGET TILESET-SURFACE)
[setter] (set! (widget-tileset-surface WIDGET) TILESET-SURFACE)

Retrieves or sets the tileset surface of WIDGET.

[procedure] (widget-parent WIDGET)

Returns the parent widget of WIDGET or #f if WIDGET is a top-level widget.

[procedure] (widget-children WIDGET)

Returns the children widgets of WIDGET as list. If WIDGET has no children, an empty list is returned.

[procedure] (reparent-widget! WIDGET PARENT)

Changes the parent of WIDGET to PARENT. Note that this will not update the geometry of WIDGET. To make WIDGET a top-level widget, use #f as value for PARENT.

[procedure] (bring-widget-to-front! WIDGET)

Modifies the widget tree to make WIDGET appear on the front.

[procedure] (widget-focus-set! WIDGET)

Sets the GUI focus to WIDGET.

[procedure] (widget-clip-children?-set! WIDGET FLAG)

Change whether the children of WIDGET should be clipped to its geometry. FLAG must be either #t or #f.

[procedure] (destroy-widget! WIDGET [CHILDREN?])

Destroys WIDGET and frees its resources. If CHILDREN? is #t, destroy its children as well, otherwise reparent them to the parent of WIDGET. While this procedure can be used to remove widgets while the GUI is still running, consider hiding them instead.

[procedure] (hide-widget! WIDGET)

Hides WIDGET and its children. This is equivalent to (enable-widget-hint! WIDGET 'hidden #t).

[procedure] (show-widget! WIDGET)

Displays WIDGET and its children again. This is equivalent to (disable-widget-hint! WIDGET 'hidden #t).

[procedure] (widget-hidden? WIDGET)

Returns #t if WIDGET is hidden, otherwise #f. This is equivalent to (query-widget-hint WIDGET 'hidden).

[procedure] (block-widget-input-events! WIDGET)

Blocks WIDGET and its children from receiving events. This is equivalent to (enable-widget-hint! WIDGET 'block-input-events #f).

[procedure] (unblock-widget-input-events WIDGET)

Unblocks input event blocking for WIDGET. This is equivalent to (disable-widget-hint! WIDGET 'block-input-events #f).

[procedure] (widget-input-events-blocked? WIDGET)

Returns #t if events are blocked for WIDGET, otherwise #f. This is equivalent to (query-widget-hint WIDGET 'block-input-events).

[procedure] (enable-widget-hint! WIDGET HINT RECUR?)

Enables the widget hint HINT for WIDGET. If RECUR? is #t, enable it recursively. HINT must be one of (allow-tile-stretch block-input-events ignore-input-events frameless hidden).

[procedure] (disable-widget-hint! WIDGET HINT RECUR?)

Disables the widget hint HINT for WIDGET. If RECUR? is #t, disable it recursively. HINT must be one of (allow-tile-stretch block-input-events ignore-input-events frameless hidden).

[procedure] (query-widget-hint WIDGET HINT)

Query WIDGET for HINT, returning either #t if enabled or #f if disabled. HINT must be one of (allow-tile-stretch block-input-events ignore-input-events frameless hidden).

[procedure] (widget-geometry WIDGET)
[procedure] (widget-geometry-set! WIDGET GEOMETRY)
[setter] (set! (widget-geometry WIDGET) GEOMETRY)

Retrieves or sets the geometry of WIDGET.

[procedure] (widget-absolute-geometry WIDGET)

Returns the absolute geometry of WIDGET. Its coordinates are relative to the root instead of the parent widget.

[procedure] (widget-composed-geometry WIDGET)

Returns the composed geometry of WIDGET. Its coordinates are relative to the root widget and its dimensions are equivalent to those of a rectangle enclosing it and its children.

[procedure] (widget-center-in-parent! PARENT INNER)

Centers INNER in PARENT vertically and horizontally.

[procedure] (widget-center-in-parent-vertically! PARENT INNER)

Centers INNER in PARENT vertically.

[procedure] (widget-center-in-parent-horizontally! PARENT INNER)

Centers INNER in PARENT horizontally.

[procedure] (widget-layout-vertically! WIDGETS PADDING [HALIGN])

Layouts WIDGETS as a vertical list. See rect-layout-vertically! for further details.

[procedure] (widget-layout-horizontally! WIDGETS PADDING [VALIGN])

Layouts WIDGETS as horizontal list. See rect-layout-horizontally! for further details.

[procedure] (widget-fill-parent-vertically! PARENT RECTS WEIGHTS PADDING)

Layouts and resizes WIDGETS to fit PARENT. See rect-fill-parent-vertically! for further details.

[procedure] (widget-fill-parent-horizontally! PARENT RECTS WEIGHTS PADDING VALIGN)

Layouts and resizes WIDGETS to fit PARENT. See rect-fill-parent-horizontally! for further details.

rect-margin!

[procedure] (widget-margin! PARENT INNER MARGIN)

Resizes and repositions INNER to be centered inside PARENT with MARGIN pixels of margin.

Handlers

handler-set!

[procedure] (handler-set! WIDGET TYPE PROC)

Sets an event handler of TYPE for WIDGET to PROC. TYPE must be one of (mouse-over mouse-leave mouse-down mouse-up focus-gain focus-lose text-input drag-start drag-stop drag). Depending on TYPE, PROC must be a procedure accepting the corresponding argument list:

mouse-over: (lambda (widget) ...)
mouse-leave: (lambda (widget) ...)
mouse-down: (lambda (widget button) ...)
mouse-up: (lambda (widget button) ...)
focus-gain: (lambda (widget) ...)
focus-lose: (lambda (widget) ...)
text-input: (lambda (widget text) ...)
drag-start: (lambda (widget x y) ...)
drag-stop: (lambda (widget x y) ...)
drag: (lambda (widget x y relx rely) ...)

handler-remove!

[procedure] (handler-remove! WIDGET TYPE)

Removes an event handler of TYPE for WIDGET. TYPE must be one of (mouse-over mouse-leave mouse-down mouse-up focus-gain focus-lose text-input drag-start drag-stop drag).

SXML interface

widgets

[procedure] (widgets GUI [PARENT] SXML)

Creates widgets based on SXML. If PARENT is specified, use that widget as the parent of the newly created widgets, otherwise create top-level widgets.

Elements must be one of (frame scrollbox label button editbox toggle). Each element has mandatory attributes that correspond to their constructor procedures and optional attributes that correspond to their other setter procedures plus generic setter procedures. The following definition lists summarizes them for quick reference:

Mandatory attributes for all widget types:

x: X coordinate
y: Y coordinate
w: width
h: height

Mandatory attributes for specific widget types:

text: Text for label, button and editbox widgets

Optional attributes for all widget types:

tileset: Tileset surface
hidden?: Hide widget, value must be #t
id: Symbol identifier for lookup with widget-by-id
<event handler type>: Procedure, see handler-set! for the attribute name and function signature of the value

Optional attributes for specific widget types:

icon: List of x, y, w and h attributes for label widgets
align: List as specified in label-alignment-set! for label widgets
style: Style symbol as specified in label-style-set! for label widgets
font: Font for label and editbox widgets
color: Color for label and editbox widgets
position: Index for editbox widgets
checked?: Activation state for toggle widgets

[procedure] (widget-by-id ID)

Returns either a widget that has been defined previously with the widgets procedure and an id attribute or #f if it couldn't be found.

Examples

Frame with "Hello World!" label (requires a tileset.png and Fontin-Regular.ttf in your cwd):

(import scheme)
(import (chicken base))
(import (prefix sdl2 sdl2:))
(import (prefix kiwi kw:))
(import (only sdl2-internals unwrap-renderer unwrap-window))

(sdl2:set-main-ready!)
(sdl2:init! '(everything))

(define width 320)
(define height 240)

(define-values (window renderer)
  (sdl2:create-window-and-renderer! width height))

(sdl2:render-draw-color-set! renderer (sdl2:make-color 100 100 100))

(define driver (kw:create-sdl2-driver (unwrap-renderer renderer)
                                      (unwrap-window window)))

(define tileset (kw:load-surface driver "tileset.png"))
(define gui (kw:init! driver tileset))

(define font (kw:load-font driver "Fontin-Regular.ttf" 12))
(kw:gui-font-set! gui font)

(define geometry (kw:rect 0 0 width height))
(define frame (kw:frame gui #f geometry))
(define label (kw:label gui frame "Hello World!" geometry))

(let loop ()
  (when (not (sdl2:quit-requested?))
    (sdl2:render-clear! renderer)
    (kw:process-events! gui)
    (kw:paint! gui)
    (sdl2:delay! 1)
    (sdl2:render-present! renderer)
    (loop)))

(kw:quit! gui)
(sdl2:quit!)

Same example, but with the SXML interface:

(import scheme)
(import (chicken base))
(import (prefix sdl2 sdl2:))
(import (prefix kiwi kw:))
(import (only sdl2-internals unwrap-renderer unwrap-window))

(sdl2:set-main-ready!)
(sdl2:init! '(everything))

(define width 320)
(define height 240)

(define-values (window renderer)
  (sdl2:create-window-and-renderer! width height))

(sdl2:render-draw-color-set! renderer (sdl2:make-color 100 100 100))

(define driver (kw:create-sdl2-driver (unwrap-renderer renderer)
                                      (unwrap-window window)))

(define tileset (kw:load-surface driver "tileset.png"))
(define gui (kw:init! driver tileset))

(define font (kw:load-font driver "Fontin-Regular.ttf" 12))
(kw:gui-font-set! gui font)

(kw:widgets gui
 `(frame
   (@ (x 0) (y 0) (w ,width) (h ,height))
   (label
    (@ (x 0) (y 0) (w ,width) (h ,height)
       (text "Hello World!")))))

(let loop ()
  (when (not (sdl2:quit-requested?))
    (sdl2:render-clear! renderer)
    (kw:process-events! gui)
    (kw:paint! gui)
    (sdl2:delay! 1)
    (sdl2:render-present! renderer)
    (loop)))

(kw:quit! gui)
(sdl2:quit!)

Further examples can be found in the repository and contain the original set of examples as well as two new ones, a more advanced "Hello World!" and a simple image viewer. The sdl2 and sdl2-image eggs are required to compile and run them.

Notes

Unlike many other GUI toolkits, KiWi requires you to use your own resources. Make sure your tileset can be found when running your application, otherwise it will segfault.
There is no ready-made main loop implementation, therefore you'll have to write your own. While this is sort of a hassle, it allows for more flexibility and better integration with your application than with GUI toolkits not offering that option.
Increase the delay time in your main loop to lower the FPS and overall CPU usage.
It's strongly recommended to use top-level definitions for the driver, GUI and its font and tileset to avoid references to them being garbage-collected early, possibly resulting in a segfault.
Refer to the KiWi headers for documentation on details not covered in this wiki page, such as how geometries work, creation of custom widgets and any functionality without bindings.
If you want to create a new tileset, use tileset.xcf from the KiWi repository as basis.
It's strongly recommended to use the (on-exit) and (current-exception-handler) parameters during development to exit the application properly at all times. This has been omitted from the examples for brevity. See the relevant sdl2 egg section for further details.

License

Copyright (c) 2016, Vasilij Schneidermann

This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not
   claim that you wrote the original software. If you use this software
   in a product, an acknowledgement in the product documentation would be
   appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be
   misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.

Version history

1.0.1

Print build script call, abort on non-zero exit

1.0

C5 port
Sync to newer version of the library
Support for checkbox, debug, cursor state, debug-gizmos, toggle functions
Added widgets example

0.3

Simplified examples
Improve memory management for color and rectangle types
Support for toggle widget, new button API and default font
Added rect-margin! and widget-margin! helper

0.2

Fix compilation warning (thanks, evhan!)
Minor code cleanup

0.1

Initial release

Introduction

Author

Repository

Requirements

API

Setup and teardown

create-sdl2-driver

driver?

driver-sdl2-renderer

driver-sdl2-window

release-driver!

load-surface

surface?

release-surface!

load-font

font?

release-font!

init!

process-events!

paint!

quit!

gui-driver / gui-driver-set!

gui-font / gui-font-set!

gui-text-color / gui-text-color-set!

gui-tileset-surface / gui-tileset-surface-set!

Rects

rect

rect?

rect-x / rect-x-set!

rect-y / rect-y-set!

rect-w / rect-w-set!

rect-h / rect-h-set!

Rect helpers

rect-empty?

enclosing-rect

rect-center-in-parent!

rect-center-in-parent-vertically!

rect-center-in-parent-horizontally!

rect-layout-vertically!

rect-layout-horizontally!

rect-fill-parent-vertically!

rect-fill-parent-horizontally!

rect-margin!

Colors

color

color?

color-r / color-r-set!

color-g / color-g-set!

color-b / color-b-set!

color-a / color-a-set!

Frame widget

frame

frame?

Scrollbox widget

scrollbox

scrollbox?

scrollbox-vertical-scroll!

scrollbox-horizontal-scroll!

Label widget

label

label?

label-text-set!

label-icon-set!

label-alignment-set!

label-style-set!

label-font / label-font-set!

label-text-color / label-text-color-set!

label-text-color-set?

Button widget

button

button*

button?

button-label / button-label-set!

Editbox widget

editbox

editbox?

editbox-text / editbox-text-set!

editbox-cursor-position / editbox-cursor-position-set!

editbox-font / editbox-font-set!