You can edit this page using wiki syntax for markup.

Article contents:== Outdated egg! This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for [[/eggref/5/kiwi|the CHICKEN 5 version of this egg]], if it exists. If it does not exist, there may be equivalent functionality provided by another egg; have a look at the [[https://wiki.call-cc.org/chicken-projects/egg-index-5.html|egg index]]. Otherwise, please consider porting this egg to the current version of CHICKEN. == kiwi [[toc:]] === Introduction This egg provides a fairly complete set of low-level bindings and a high-level SXML widget interface to the [[https://github.com/mobius3/KiWi|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://github.com/wasamasa/kiwi]] === Requirements Both KiWi and SDL2 must be available on your machine. An Arch Linux PKGBUILD is available [[https://github.com/wasamasa/pkgbuilds/blob/master/kiwi-git/PKGBUILD|here]]. The bindings are based on everything up to commit [[https://github.com/mobius3/KiWi/commit/de9c5d2211ac57c199570a1776aa4634db32a5fb|de9c5d]], so they might break on API-incompatible changes introduced after 2016-06-04. 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_FLAGS}} and {{SDL2_FLAGS}} environment variables. The bindings themselves require the [[clojurian]] and [[matchable]] eggs. === API ==== Setup and teardown ===== create-sdl2-driver <procedure>(create-sdl2-driver RENDERER WINDOW)</procedure> 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 [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/using-sdl2-internals.md|sdl2-internals]] module of the [[sdl2]] egg. ===== driver? <procedure>(driver? ARG)</procedure> Returns {{#t}} if {{ARG}} is an driver, otherwise {{#f}}. ===== driver-sdl2-renderer <procedure>(driver-sdl2-renderer DRIVER)</procedure> Returns the raw SDL2 renderer pointer associated with {{DRIVER}}. ===== driver-sdl2-window <procedure>(driver-sdl2-window DRIVER)</procedure> Returns the raw SDL2 window pointer associated with {{DRIVER}}. ===== release-driver! <procedure>(release-driver! DRIVER)</procedure> Frees the resources of {{DRIVER}}. This is called implicitly as finalizer for driver records. ===== load-surface <procedure>(load-surface DRIVER FILENAME)</procedure> 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)</procedure> Returns {{#t}} if {{ARG}} is an surface, otherwise {{#f}}. ===== release-surface! <procedure>(release-surface! DRIVER SURFACE)</procedure> Frees the resources of {{SURFACE}}. This is called implicitly as finalizer for surface records. ===== load-font <procedure>(load-font DRIVER FONTNAME SIZE)</procedure> 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)</procedure> Returns {{#t}} if {{ARG}} is an font, otherwise {{#f}}. ===== release-font! <procedure>(release-font! DRIVER FONT)</procedure> Frees the resources of {{FONT}}. This is called implicitly as finalizer for font records. ===== init! <procedure>(init! DRIVER TILESET-SURFACE)</procedure> Initializes and returns a GUI. {{TILESET-SURFACE}} must be a surface to be used as tileset. ===== process-events! <procedure>(process-events! GUI)</procedure> Process events for {{GUI}} and trigger all event handlers involved. ===== paint! <procedure>(paint! GUI)</procedure> Repaint all widgets associated with {{GUI}}. ===== quit! <procedure>(quit! GUI)</procedure> 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> <procedure>(gui-driver-set! GUI DRIVER)</procedure> <setter>(set! (gui-driver GUI) DRIVER)</setter> Retrieves or sets the driver of {{GUI}}. ===== gui-font / gui-font-set! <procedure>(gui-font GUI)</procedure> <procedure>(gui-font-set! GUI FONT)</procedure> <setter>(set! (gui-font GUI) FONT)</setter> 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> <procedure>(gui-text-color-set! GUI TEXT-COLOR)</procedure> <setter>(set! (gui-text-color GUI) TEXT-COLOR)</setter> Retrieves or sets the text color of {{GUI}}. ===== gui-tileset-surface / gui-tileset-surface-set! <procedure>(gui-tileset-surface GUI)</procedure> <procedure>(gui-tileset-surface-set! GUI TILESET-SURFACE)</procedure> <setter>(set! (gui-tileset-surface GUI) TILESET-SURFACE)</setter> Retrieves or sets the tileset surface of {{GUI}}. ==== Rects ===== rect <procedure>(rect X Y W H)</procedure> Creates and returns a rectangle at the coordinates {{X}} and {{Y}} with the dimensions {{W}} and {{H}}. ===== rect? <procedure>(rect? ARG)</procedure> Returns {{#t}} if {{ARG}} is an rect, otherwise {{#f}}. ===== rect-x / rect-x-set! <procedure>(rect-x RECT)</procedure> <procedure>(rect-x-set! RECT X)</procedure> <setter>(set! (rect-x RECT) X)</setter> Retrieves or sets the x coordinate of {{RECT}}. ===== rect-y / rect-y-set! <procedure>(rect-y RECT)</procedure> <procedure>(rect-y-set! RECT Y)</procedure> <setter>(set! (rect-y RECT) Y)</setter> Retrieves or sets the y coordinate of {{RECT}}. ===== rect-w / rect-w-set! <procedure>(rect-w RECT)</procedure> <procedure>(rect-w-set! RECT W)</procedure> <setter>(set! (rect-w RECT) W)</setter> Retrieves or sets the width of {{RECT}}. ===== rect-h / rect-h-set! <procedure>(rect-h RECT)</procedure> <procedure>(rect-h-set! RECT H)</procedure> <setter>(set! (rect-h RECT) H)</setter> Retrieves or sets the height of {{RECT}}. ==== Rect helpers ===== rect-empty? <procedure>(rect-empty? RECT)</procedure> Returns {{#t}} if {{RECT}} is empty, otherwise {{#f}}. ===== enclosing-rect <procedure>(enclosing-rect RECTS)</procedure> Returns a rectangle enclosing all {{RECTS}}. ===== rect-center-in-parent! <procedure>(rect-center-in-parent! PARENT INNER)</procedure> 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)</procedure> Centers {{INNER}} in {{PARENT}} vertically by mutating the coordinates of {{INNER}}. ===== rect-center-in-parent-horizontally! <procedure>(rect-center-in-parent-horizontally! PARENT INNER)</procedure> Centers {{INNER}} in {{PARENT}} horizontally by mutating the coordinates of {{INNER}}. ===== rect-layout-vertically! <procedure>(rect-layout-vertically! RECTS PADDING [HALIGN])</procedure> 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])</procedure> 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)</procedure> 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)</procedure> 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)</procedure> Resizes and repositions {{INNER}} to be centered inside {{PARENT}} with {{MARGIN}} pixels of margin. ==== Colors ===== color <procedure>(color R G B A)</procedure> Creates and returns a color with the components {{R}}, {{G}}, {{B}} and {{A}}. ===== color? <procedure>(color? ARG)</procedure> Returns {{#t}} if {{ARG}} is an color, otherwise {{#f}}. ===== color-r / color-r-set! <procedure>(color-r COLOR)</procedure> <procedure>(color-r-set! COLOR R)</procedure> <setter>(set! (color-r COLOR) R)</setter> 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> <procedure>(color-g-set! COLOR G)</procedure> <setter>(set! (color-g COLOR) G)</setter> 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> <procedure>(color-b-set! COLOR B)</procedure> <setter>(set! (color-b COLOR) B)</setter> 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> <procedure>(color-a-set! COLOR A)</procedure> <setter>(set! (color-a COLOR) A)</setter> Retrieves or sets the alpha component of {{COLOR}}. {{A}} must be a fixnum between 0 and 255 (inclusive). ==== Frame widget ===== frame <procedure>(frame GUI PARENT GEOMETRY)</procedure> 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)</procedure> Returns {{#t}} if {{ARG}} is an frame widget, otherwise {{#f}}. ==== Scrollbox widget ===== scrollbox <procedure>(scrollbox GUI PARENT GEOMETRY)</procedure> 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)</procedure> Returns {{#t}} if {{ARG}} is an scrollbox widget, otherwise {{#f}}. ===== scrollbox-vertical-scroll! <procedure>(scrollbox-vertical-scroll! SCROLLBOX AMOUNT)</procedure> Scroll {{SCROLLBOX}} vertically by {{AMOUNT}} pixels. ===== scrollbox-horizontal-scroll! <procedure>(scrollbox-horizontal-scroll! SCROLLBOX AMOUNT)</procedure> Scroll {{SCROLLBOX}} horizontally by {{AMOUNT}} pixels. ==== Label widget ===== label <procedure>(label GUI PARENT TEXT GEOMETRY)</procedure> 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)</procedure> Returns {{#t}} if {{ARG}} is an label widget, otherwise {{#f}}. ===== label-text-set! <procedure>(label-text-set! LABEL TEXT)</procedure> Sets the text of {{LABEL}} to {{TEXT}}. ===== label-icon-set! <procedure>(label-icon-set! LABEL CLIP)</procedure> 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)</procedure> 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)</procedure> 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> <procedure>(label-font-set! LABEL FONT)</procedure> <setter>(set! (label-font LABEL) FONT)</setter> Retrieves or sets the font of {{LABEL}}. ===== label-text-color / label-text-color-set! <procedure>(label-text-color LABEL)</procedure> <procedure>(label-text-color-set! LABEL TEXT-COLOR)</procedure> <setter>(set! (label-text-color LABEL) TEXT-COLOR)</setter> 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)</procedure> Returns {{#t}} if the text color of {{LABEL}} has been set by the user. ==== Button widget ===== button <procedure>(button GUI PARENT TEXT GEOMETRY)</procedure> 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)</procedure> 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)</procedure> Returns {{#t}} if {{ARG}} is an button widget, otherwise {{#f}}. ===== button-label / button-label-set! <procedure>(button-label BUTTON)</procedure> <procedure>(button-label-set! BUTTON LABEL)</procedure> <setter>(set! (button-label BUTTON) LABEL)</setter> Retrieves or sets the label of {{BUTTON}}. The latter returns the old label. ==== Editbox widget ===== editbox <procedure>(editbox GUI PARENT TEXT GEOMETRY)</procedure> 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)</procedure> Returns {{#t}} if {{ARG}} is an editbox widget, otherwise {{#f}}. ===== editbox-text / editbox-text-set! <procedure>(editbox-text EDITBOX)</procedure> <procedure>(editbox-text-set! EDITBOX TEXT)</procedure> <setter>(set! (editbox-text EDITBOX) TEXT)</setter> Retrieves or sets the text of {{EDITBOX}}. ===== editbox-cursor-position / editbox-cursor-position-set! <procedure>(editbox-cursor-position EDITBOX)</procedure> <procedure>(editbox-cursor-position-set! EDITBOX POS)</procedure> <setter>(set! (editbox-cursor-position EDITBOX) POS)</setter> 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> <procedure>(editbox-font-set! EDITBOX FONT)</procedure> <setter>(set! (editbox-font EDITBOX) FONT)</setter> Retrieves or sets the font of {{EDITBOX}}. ===== editbox-text-color / editbox-text-color-set! <procedure>(editbox-text-color EDITBOX)</procedure> <procedure>(editbox-text-color-set! EDITBOX TEXT-COLOR)</procedure> <setter>(set! (editbox-text-color EDITBOX) TEXT-COLOR)</setter> 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)</procedure> Returns {{#t}} if the text color of {{EDITBOX}} has been set by the user. ==== Toggle widget ===== toggle <procedure>(toggle GUI PARENT GEOMETRY)</procedure> 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> <procedure>(toggle-checked?-set! TOGGLE CHECKED?)</procedure> <setter>(set! (toggle-checked? TOGGLE) CHECKED?)</setter> Retrieves or sets the activation state of {{TOGGLE}}. {{CHECKED?}} must be either {{#t}} or {{#f}}. ==== Widget helpers ===== widget? <procedure>(widget? ARG)</procedure> Returns {{#t}} if {{ARG}} is an widget, otherwise {{#f}}. ===== widget-type <procedure>(widget-type WIDGET)</procedure> Returns a symbol describing the widget type. It will be one of {{(frame scrollbox label button editbox)}}. ===== widget-gui <procedure>(widget-gui WIDGET)</procedure> Returns the GUI associated with {{WIDGET}}. This is a convenience procedure intended for use in event handlers. ===== widget-driver <procedure>(widget-driver WIDGET)</procedure> Returns the driver associated with {{WIDGET}}. This is a convenience procedure intended for use in event handlers. ===== widget-tileset-surface / widget-tileset-surface-set! <procedure>(widget-tileset-surface WIDGET)</procedure> <procedure>(widget-tileset-surface-set! WIDGET TILESET-SURFACE)</procedure> <setter>(set! (widget-tileset-surface WIDGET) TILESET-SURFACE)</setter> Retrieves or sets the tileset surface of {{WIDGET}}. ===== widget-parent <procedure>(widget-parent WIDGET)</procedure> Returns the parent widget of {{WIDGET}} or {{#f}} if {{WIDGET}} is a top-level widget. ===== widget-children <procedure>(widget-children WIDGET)</procedure> Returns the children widgets of {{WIDGET}} as list. If {{WIDGET}} has no children, an empty list is returned. ===== reparent-widget! <procedure>(reparent-widget! WIDGET PARENT)</procedure> 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}}. ===== bring-widget-to-front! <procedure>(bring-widget-to-front! WIDGET)</procedure> Modifies the widget tree to make {{WIDGET}} appear on the front. ===== widget-focus-set! <procedure>(widget-focus-set! WIDGET)</procedure> Sets the GUI focus to {{WIDGET}}. ===== widget-clip-children?-set! <procedure>(widget-clip-children?-set! WIDGET FLAG)</procedure> Change whether the children of {{WIDGET}} should be clipped to its geometry. {{FLAG}} must be either {{#t}} or {{#f}}. ===== destroy-widget! <procedure>(destroy-widget! WIDGET [CHILDREN?])</procedure> 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. ===== hide-widget! <procedure>(hide-widget! WIDGET)</procedure> Hides {{WIDGET}} and its children. This is equivalent to {{(enable-widget-hint! WIDGET 'hidden #t)}}. ===== show-widget! <procedure>(show-widget! WIDGET)</procedure> Displays {{WIDGET}} and its children again. This is equivalent to {{(disable-widget-hint! WIDGET 'hidden #t)}}. ===== widget-hidden? <procedure>(widget-hidden? WIDGET)</procedure> Returns {{#t}} if {{WIDGET}} is hidden, otherwise {{#f}}. This is equivalent to {{(query-widget-hint WIDGET 'hidden)}}. ===== block-widget-input-events! <procedure>(block-widget-input-events! WIDGET)</procedure> Blocks {{WIDGET}} and its children from receiving events. This is equivalent to {{(enable-widget-hint! WIDGET 'block-input-events #f)}}. ===== unblock-widget-input-events! <procedure>(unblock-widget-input-events WIDGET)</procedure> Unblocks input event blocking for {{WIDGET}}. This is equivalent to {{(disable-widget-hint! WIDGET 'block-input-events #f)}}. ===== widget-input-events-blocked? <procedure>(widget-input-events-blocked? WIDGET)</procedure> Returns {{#t}} if events are blocked for {{WIDGET}}, otherwise {{#f}}. This is equivalent to {{(query-widget-hint WIDGET 'block-input-events)}}. ===== enable-widget-hint! <procedure>(enable-widget-hint! WIDGET HINT RECUR?)</procedure> 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)}}. ===== disable-widget-hint! <procedure>(disable-widget-hint! WIDGET HINT RECUR?)</procedure> 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)}}. ===== query-widget-hint <procedure>(query-widget-hint WIDGET HINT)</procedure> 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)}}. ===== widget-geometry / widget-geometry-set! <procedure>(widget-geometry WIDGET)</procedure> <procedure>(widget-geometry-set! WIDGET GEOMETRY)</procedure> <setter>(set! (widget-geometry WIDGET) GEOMETRY)</setter> Retrieves or sets the geometry of {{WIDGET}}. ===== widget-absolute-geometry <procedure>(widget-absolute-geometry WIDGET)</procedure> Returns the absolute geometry of {{WIDGET}}. Its coordinates are relative to the root instead of the parent widget. ===== widget-composed-geometry <procedure>(widget-composed-geometry WIDGET)</procedure> 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. ===== widget-center-in-parent! <procedure>(widget-center-in-parent! PARENT INNER)</procedure> Centers {{INNER}} in {{PARENT}} vertically and horizontally. ===== widget-center-in-parent-vertically! <procedure>(widget-center-in-parent-vertically! PARENT INNER)</procedure> Centers {{INNER}} in {{PARENT}} vertically. ===== widget-center-in-parent-horizontally! <procedure>(widget-center-in-parent-horizontally! PARENT INNER)</procedure> Centers {{INNER}} in {{PARENT}} horizontally. ===== widget-layout-vertically! <procedure>(widget-layout-vertically! WIDGETS PADDING [HALIGN])</procedure> Layouts {{WIDGETS}} as a vertical list. See {{rect-layout-vertically!}} for further details. ===== widget-layout-horizontally! <procedure>(widget-layout-horizontally! WIDGETS PADDING [VALIGN])</procedure> Layouts {{WIDGETS}} as horizontal list. See {{rect-layout-horizontally!}} for further details. ===== widget-fill-parent-vertically! <procedure>(widget-fill-parent-vertically! PARENT RECTS WEIGHTS PADDING)</procedure> Layouts and resizes {{WIDGETS}} to fit {{PARENT}}. See {{rect-fill-parent-vertically!}} for further details. ===== widget-fill-parent-horizontally! <procedure>(widget-fill-parent-horizontally! PARENT RECTS WEIGHTS PADDING VALIGN)</procedure> Layouts and resizes {{WIDGETS}} to fit {{PARENT}}. See {{rect-fill-parent-horizontally!}} for further details. ===== rect-margin! <procedure>(widget-margin! PARENT INNER MARGIN)</procedure> Resizes and repositions {{INNER}} to be centered inside {{PARENT}} with {{MARGIN}} pixels of margin. ==== Handlers ===== handler-set! <procedure>(handler-set! WIDGET TYPE PROC)</procedure> 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)</procedure> 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)</procedure> 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 ===== widget-by-id <procedure>(widget-by-id ID)</procedure> 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): <enscript highlight="scheme"> (use (prefix sdl2 sdl2:) (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!) </enscript> Same example, but with the SXML interface: <enscript highlight="scheme"> (use (prefix sdl2 sdl2:) (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!) </enscript> Further examples can be found in [[https://github.com/wasamasa/kiwi/examples|the repository]] and contain [[https://github.com/mobius3/KiWi/tree/master/examples|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 [[https://github.com/mobius3/KiWi/tree/master/src|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 [[https://github.com/mobius3/KiWi/raw/master/examples/tileset/tileset.xcf|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 [[http://wiki.call-cc.org/eggref/4/sdl2#ensuring-proper-clean-up|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 ==== 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 Description of your changes:

I would like to authenticate

Spam control

What do you get when you subtract 14 from 17?