chickadee » libui

Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for 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 egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

libui

TOC »

Introduction

This egg provides an incomplete set of low-level bindings and a high-level SXML interface to the libui GUI library.

Author

Vasilij Schneidermann

Repository

https://depp.brause.cc/libui

Current state of the bindings

Requirements

To compile the egg successfully, you'll need to have libui installed. The egg itself requires matchable.

API

Setup and teardown

init!
init!procedure

Initializes the library. This must be used before creating widgets.

main
mainprocedure

Enters the main event loop. Note that all widgets must have been set up and displayed before this point, otherwise they will not appear.

uninit!
uninit!procedure

Frees all GUI resources.

quit!
quit!procedure

Terminates the main event loop.

Widget helpers

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

Sets PROC as handler for WIDGET and the event TYPE. If ARGS is specified, the given arguments will be passed to PROC when firing the handler. The following table describes the valid widget-type combinations and corresponding handlers:

Procedure signatureHandler signatureDescription
(handler-set! #f 'should-quit PROC [ARGS ...])(should-quit [ARGS ...])Fired on quit by menu item. Return #t to allow quit, otherwise #f
(handler-set WINDOW 'closing PROC [ARGS ...])(window-closing WINDOW [ARGS ...])Fired on window close. Return #t to allow window closing, otherwise #f
(handler-set BUTTON 'clicked PROC [ARGS ...])(button-clicked BUTTON [ARGS ...])Fired on button click
(handler-set SPINBOX 'changed PROC [ARGS ...])(spinbox-changed SPINBOX [ARGS ...])Fired on spinbox value changes
(handler-set SLIDER 'changed PROC [ARGS ...])(slider-changed SLIDER [ARGS ...])Fired on slider value changes
(handler-set COLOR-BUTTON 'changed PROC [ARGS ...])(color-button-changed COLOR-BUTTON [ARGS ...])Fired on color button value changes
margined?
margined?parameter
margined? MARGINED?parameter

Parameter describing whether margins are enabled for widgets by default. Defaults to #f. Affected widgets are windows, tabs and groups. Note that the default can be overridden by either using the widget-specific procedure or specifying a margined? attribute in the SXML interface.

padded?
padded?parameter
padded? PADDED?parameter

Parameter describing whether padding is enabled for widgets by default. Defaults to #f. Affected widgets are boxes, forms and grids. Note that the default can be overridden by either using the widget-specific procedure or specifying a padded? attribute in the SXML interface.

Widgets

Window widget
new-window
new-window TITLE WIDTH HEIGHT #!optional MENUBAR?procedure

Creates and returns a new window widget with TITLE as title and the dimensions WIDTH and HEIGHT. Note that the optional MENUBAR? argument doesn't have any effect yet as menu items cannot be created yet.

window-child-set!
window-child-set! WINDOW CONTROLprocedure

Sets WINDOW to contain CONTROL as its child.

window-margined?-set!
window-margined?-set! WINDOW MARGINED?procedure

Enables or disables margins for WINDOW, depending on whether MARGINED? is #t or #f.

Button widget
new-button
new-button TEXTprocedure

Creates and returns a new button widget with TEXT as label.

button-text / button-text-set!
button-text BUTTONprocedure
button-text-set! BUTTON TEXTprocedure
set! (button-text BUTTON) TEXTsetter

Retrieves or sets the text of BUTTON.

Box widget
new-horizontal-box
new-horizontal-boxprocedure

Creates and returns a new horizontal box widget.

new-vertical-box
new-vertical-boxprocedure

Creates and returns a new vertical box widget.

box-append!
box-append! BOX CONTROL #!optional STRETCHY?procedure

Appends CONTROL to BOX. If STRETCHY? is #t, the appended control will expand as much as possible instead of adhering to its natural size.

box-padded?-set!
box-padded?-set! BOX PADDED?procedure

Enables or disables padding for BOX, depending on whether PADDED? is #t or #f.

Checkbox widget
new-checkbox
new-checkbox TEXTprocedure

Creates and returns a new checkbox widget with TEXT as label.

Entry widget
new-entry
new-entryprocedure

Creates and returns a new entry widget.

new-password-entry
new-password-entryprocedure

Creates and returns a new password entry widget.

new-search-entry
new-search-entryprocedure

Creates and returns a new search entry widget.

entry-text / entry-text-set!
entry-text ENTRYprocedure
entry-text-set! ENTRY TEXTprocedure
set! (entry-text ENTRY) TEXTsetter

Retrieves or sets the text of ENTRY.

entry-read-only?-set!
entry-read-only?-set! ENTRY READ-ONLY?procedure

Enables or disables the read-only state of ENTRY, depending on whether READ-ONLY? is #t or #f.

Label widget
new-label
new-label TEXTprocedure

Creates and returns a new label widget with TEXT as label.

Tab widget
new-tab
new-tabprocedure

Creates and returns a new tab widget.

tab-append!
tab-append! TAB TEXT CONTROLprocedure

Appends CONTROL as tab page to TAB with TEXT as label.

tab-pages-length
tab-pages-length TABprocedure

Returns the number of tab pages for TAB.

tab-margined?-set!
tab-margined?-set! TAB INDEX MARGINED?procedure

Enables or disables margins for the tab page at INDEX on TAB, depending on whether MARGINED? is #t or #f.

Group widget
new-group
new-group TEXTprocedure

Creates and returns a new group widget with TEXT as label.

group-child-set!
group-child-set! GROUP CONTROLprocedure

Sets GROUP to contain CONTROL as its child.

group-margined?-set!
group-margined?-set! GROUP MARGINED?procedure

Enables or disables margins for GROUP, depending on whether MARGINED? is #t or #f.

Spinbox widget
new-spinbox
new-spinbox MIN MAXprocedure

Creates and returns a new spinbox widget with MIN and MAX as input boundaries.

spinbox-value / spinbox-value-set!
spinbox-value SPINBOXprocedure
spinbox-value-set! SPINBOX VALUEprocedure
set! (spinbox-value SPINBOX) VALUEsetter

Retrieves or sets the value of SPINBOX.

Slider widget
new-slider
new-slider MIN MAXprocedure

Creates and returns a slider widget with MIN and MAX as input boundaries.

slider-value / slider-value-set!
slider-value SLIDERprocedure
slider-value-set! SLIDER VALUEprocedure
set! (slider-value SLIDER) VALUEsetter

Retrieves or sets the value of SLIDER.

Progress bar widget
new-progress-bar
new-progress-barprocedure

Creates and returns a new progress bar widget. The input boundaries are 0 and 100. Note that the value -1 is interpreted specially and will result in a pulsating progress bar.

progress-bar-value / progress-bar-value-set!
progress-bar-value PROGRESS-BARprocedure
progress-bar-value-set! PROGRESS-BAR VALUEprocedure
set! (progress-bar-value PROGRESS-BAR) VALUEsetter

Retrieves or sets the value of PROGRESS-BAR.

Separator widget
new-horizontal-separator
new-horizontal-separatorprocedure

Creates and returns a new horizontal separator widget.

new-vertical-separator
new-vertical-separatorprocedure

Creates and returns a new vertical separator widget.

Combobox widget
new-combobox
new-comboboxprocedure

Creates and returns a new combobox widget.

combobox-append!
combobox-append! COMBOBOX TEXTprocedure

Appends a combobox item containing TEXT to COMBOBOX.

Editable combobox widget
new-editable-combobox
new-editable-comboboxprocedure

Creates and returns a new editable combobox widget.

editable-combobox-append!
editable-combobox-append! EDITABLE-COMBOBOX TEXTprocedure

Appends an editable combobox item containing TEXT to EDITABLE-COMBOBOX.

Radio buttons widget
new-radio-buttons
new-radio-buttonsprocedure

Creates and returns a new radio buttons widget.

radio-buttons-append!
radio-buttons-append! RADIO-BUTTONS TEXTprocedure

Appends an radio button item containing TEXT to RADIO-BUTTONS.

Date/time widgets
new-date-time-picker
new-date-time-pickerprocedure

Creates and returns a new date time picker widget.

new-date-picker
new-date-pickerprocedure

Creates and returns a new date picker widget.

new-time-picker
new-time-pickerprocedure

Creates and returns a new time picker widget.

Multiline entry widget
new-multiline-entry
new-multiline-entryprocedure

Creates and returns a new multiline entry widget.

new-non-wrapping-multiline-entry
new-non-wrapping-multiline-entryprocedure

Creates and returns a new non-wrapping multiline entry widget.

multiline-entry-append!
multiline-entry-append! MULTILINE-ENTRY TEXTprocedure

Appends TEXT to the contents of MULTILINE-ENTRY.

multiline-entry-read-only?-set!
multiline-entry-read-only?-set! MULTILINE-ENTRY READ-ONLY?procedure

Enables or disables the read-only state of MULTILINE-ENTRY, depending on whether READ-ONLY? is #t or #f.

Area widget
new-area
new-area AREA-HANDLERprocedure

Creates and returns a new area widget. AREA-HANDLER is a record as returned by new-area-handler.

area-queue-redraw-all!
area-queue-redraw-all! AREAprocedure

Triggers the AREA widget to redraw itself with its drawing handler as soon as possible.

new-area-handler
new-area-handler DRAW-HANDLER MOUSE-EVENT-HANDLER MOUSE-CROSSED-HANDLER DRAG-BROKEN-HANDLER KEY-EVENT-HANDLERprocedure

Creates a handler suitable for creating an area widget. The arguments to this procedure are procedures with the following signatures:

(draw-handler AREA-HANDLER AREA DRAW-PARAMS)
Run when the area widget is redrawn. DRAW-PARAMS contains the current drawing parameters.
(mouse-event-handler AREA-HANDLER AREA MOUSE-EVENT)
Run on mouse events with MOUSE-EVENT as argument.
(mouse-crossed-handler AREA-HANDLER AREA LEFT?)
Run when the mouse enters or leaves the area widget. LEFT? is #t if the mouse left it, otherwise #f.
(drag-broken-handler AREA-HANDLER AREA)
Run when dragging has been cancelled by the system.
(key-event-handler AREA-HANDLER AREA KEY-EVENT)
Run on key events with KEY-EVENT as argument.
mouse-event-x
mouse-event-x MOUSE-EVENTprocedure

Retrieves the x component of MOUSE-EVENT as emitted by a mouse event handler.

mouse-event-y
mouse-event-y MOUSE-EVENTprocedure

Retrieves the y component of MOUSE-EVENT as emitted by a mouse event handler.

mouse-event-area-width
mouse-event-area-width MOUSE-EVENTprocedure

Retrieves the area width of MOUSE-EVENT as emitted by a mouse event handler.

mouse-event-area-height
mouse-event-area-height MOUSE-EVENTprocedure

Retrieves the area height of MOUSE-EVENT as emitted by a mouse event handler.

draw-params-context
draw-params-context DRAW-PARAMSprocedure

Retrieves the context of DRAW-PARAMS as emitted by a draw handler.

draw-params-area-width
draw-params-area-width DRAW-PARAMSprocedure

Retrieves the area width of DRAW-PARAMS as emitted by a draw handler.

draw-params-area-height
draw-params-area-height DRAW-PARAMSprocedure

Retrieves the area height of DRAW-PARAMS as emitted by a draw handler.

Font button widget
new-font-button
new-font-buttonprocedure

Creates and returns a new font button widget.

Color button widget
new-color-button
new-color-buttonprocedure

Creates and returns a new color button widget.

color-button-color / color-button-color-set!
color-button-color COLOR-BUTTONprocedure
color-button-color-set! COLOR-BUTTON R G B Aprocedure
(set! (color-button-color COLOR-BUTTON) R G B A)setter

Retrieves or sets the color of COLOR-BUTTON. Its value is a list of the red, green, blue and alpha components as flonums between 0 and 1.

Form widget
new-form
new-formprocedure

Creates and returns a new form widget.

form-append!
form-append! FORM TEXT CONTROL #!optional STRETCHY?procedure

Appends CONTROL to FORM with TEXT as label. If STRETCHY? is #t, the appended control will expand as much as possible instead of adhering to its natural size.

form-padded?-set!
form-padded?-set! FORM PADDED?procedure

Enables or disables padding for FORM, depending on whether PADDED? is #t or #f.

Grid widget
new-grid
new-gridprocedure

Creates and returns a new grid widget.

grid-append!
(grid-append! GRID CONTROL LEFT TOP [XSPAN YSPAN HEXPAND HALIGN VEXPAND VALIGN])procedure

Appends CONTROL to GRID. LEFT and TOP are integer positions in the grid with 0 and 0 referring to the upper left corner. XSPAN and YSPAN control over how many cells the appended control will span and default to 1. If HEXPAND or HALIGN is #t, the control will expand to the entire cell size instead of its natural size. HALIGN and VALIGN control the alignment and must be one of (fill start center end), with fill being the default. See the GTK3 documentation for further details.

grid-padded?-set!
grid-padded?-set! GRID PADDED?procedure

Enables or disables padding for GRID, depending on whether PADDED? is #t or #f.

Controls

->control
->control WIDGETprocedure

Casts WIDGET to a control record. Used in procedures accepting controls.

control-destroy!
control-destroy! CONTROLprocedure

Destroys CONTROL and frees its resources.

control-show!
control-show! CONTROLprocedure

Displays CONTROL.

Dialogs

open-file
open-file PARENTprocedure

Opens an "Open File" dialog. PARENT is the widget the dialog belongs to, typically the main window.

save-file
save-file PARENTprocedure

Opens an "Save File" dialog. PARENT is the widget the dialog belongs to, typically the main window.

message-box
message-box PARENT TITLE DESCRIPTIONprocedure

Opens a message box dialog with TITLE and DESCRIPTION as labels. PARENT is the widget the dialog belongs to, typically the main window.

message-box-error
message-box-error PARENT TITLE DESCRIPTIONprocedure

Opens a message box error dialog with TITLE and DESCRIPTION as labels. PARENT is the widget the dialog belongs to, typically the main window.

SXML interface

widgets
widgets SXMLprocedure

Creates widgets as specified by SXML. Returns the created root widget of SXML. The tag name is equal to the widget type, the attributes are mapped to widget-specific procedure calls mutating these and the children are added to the widget if possible. Refer to the individual widget creation and setter procedures to know which attributes are mandatory and which are optional.

The following definition list describes the allowed attributes of all widgets not accepting children:

button
(text)
font-button
None
color-button
(color)
checkbox
(text)
entry, password-entry, search-entry
(text read-only?)
multiline-entry, non-wrapping-multiline-entry
(read-only?)
label
(text)
spinbox, slider
(min max value)
progress-bar
(value)
horizontal-separator, vertical-separator
None
date-picker, time-picker, date-time-picker
None

The remaining widgets can contain a child or children.

window
(title width height menubar? margined?)
window child
None
combobox, editable-combobox, radio-buttons
None
combobox, editable-combobox, radio-buttons children
Must be strings
hbox, vbox
(padded?)
hbox, vbox children
(stretchy?)
tab
None
tab children
(text margined?)
group
(text margined?)
group child
None
form
(padded?)
form children
(text stretchy?)
grid
(padded?)
grid children
(left top xspan yspan hexpand halign vexpand valign)

Additionally to that, one can use handler symbols as described in the documentation of handler-set! and a procedure to add a handler and the special id attribute on any widget to look it up with the widget-by-id procedure.

widget-by-id
widget-by-id IDprocedure

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

Drawing procedures

These are part of the separately loadable libui-draw module.

Brushes
new-solid-brush
new-solid-brush R G B Aprocedure

Creates a new solid brush from the color components R, G, B and A. Each component must be a flonum between 0 and 1.

brush-r / brush-r-set!
brush-r BRUSHprocedure
brush-r-set! BRUSH Rprocedure
set! (brush-r BRUSH) Rsetter

Retrieves or sets the red component of BRUSH.

brush-g / brush-g-set!
brush-g BRUSHprocedure
brush-g-set! BRUSH Gprocedure
set! (brush-g BRUSH) Gsetter

Retrieves or sets the green component of BRUSH.

brush-b / brush-b-set!
brush-b BRUSHprocedure
brush-b-set! BRUSH Bprocedure
set! (brush-b BRUSH) Bsetter

Retrieves or sets the blue component of BRUSH.

brush-a / brush-a-set!
brush-a BRUSHprocedure
brush-a-set! BRUSH Aprocedure
set! (brush-a BRUSH) Asetter

Retrieves or sets the alpha component of BRUSH.

Stroke parameters
new-stroke-params
(new-stroke-params #!key (cap: 'flat) (join: 'miter) (thickness: 2) (miter-limit: 10) (dashes: '()) (offset: 0))procedure

Creates new stroke parameters for use with stroke!. cap describes the shape of line ends and must be one of (flat round square), join the join style used between path segments and must be one of (miter round bevel). thickness is the line thickness, miter-limit a treshold for deciding whether to use bevel or miter joins for the miter join type. See the Cairo documentation for further information. Note that dashes are currently unimplemented, therefore the dashes and offset keywords have no effect.

Matrices
new-matrix
new-matrixprocedure

Creates and returns a new matrix.

matrix-identity-set!
matrix-identity-set! MATRIXprocedure

Sets MATRIX to the identity matrix.

matrix-translate!
matrix-translate! MATRIX X Yprocedure

Translates MATRIX by X and Y.

transform!
transform! CONTEXT MATRIXprocedure

Applies MATRIX to CONTEXT. In other words, after this operation all drawing operations on CONTEXT will be transformed as specified by MATRIX.

Paths
new-path
new-path #!optional ALTERNATE?procedure

Creates and returns a new path. If ALTERNATE? is #t, filling depends on the number of path intersections, otherwise on the path's winding.

path-free!
path-free! PATHprocedure

Release the resources associated with PATH. This doesn't need to be called after having dealt with PATH as it is run by a finalizer, but can help reducing GC pressure.

path-new-figure!
path-new-figure! PATH X Yprocedure

Starts a new figure to draw at X and Y for PATH.

path-new-figure-with-arc!
path-new-figure-with-arc! PATH XCENTER YCENTER RADIUS START-ANGLE SWEEP #!optional NEGATIVE?procedure

Starts a new figure that starts with an arc segment at XCENTER and YCENTER with RADIUS for PATH. START-ANGLE and SWEEP describe what angle to start from and the angular length of the arc in radians. If NEGATIVE? is #t, the arc will be drawn counter-clockwise, otherwise clockwise. Note that this is commonly used to draw circles.

path-line-to!
path-line-to! PATH X Yprocedure

Adds a line to the current figure of PATH ending at X and Y.

path-close-figure!
path-close-figure! PATHprocedure

Closes the current figure of PATH.

path-add-rectangle!
path-add-rectangle! PATH X Y WIDTH HEIGHTprocedure

Creates a new rectangle figure on PATH at X and Y with the dimensions WIDTH and HEIGHT.

path-end!
path-end! PATHprocedure

Ends PATH and inhibits adding any further figures or changes to them.

stroke!
stroke! CONTEXT PATH BRUSH STROKE-PARAMSprocedure

Strokes PATH on CONTEXT with BRUSH and STROKE-PARAMS.

fill!
fill! CONTEXT PATH BRUSHprocedure

Fills PATH on CONTEXT with BRUSH.

Examples

Basic "Hello World!" example.

(use (prefix libui ui:))

(ui:margined? #t)
(ui:padded? #t)

(ui:init!)

(define window (ui:new-window "Hello World" 180 60 #t))
(ui:handler-set! window 'closing (lambda (_window) (ui:quit!)))

(define (greet _button)
  (ui:message-box window "Greeting" "Hello World!"))

(define greet-button (ui:new-button "Click Me!"))
(ui:handler-set! greet-button 'clicked greet)

(define quit-button (ui:new-button "Quit"))
(ui:handler-set! quit-button 'clicked (lambda (_button) (ui:quit!)))

(define hbox (ui:new-horizontal-box))
(ui:box-append! hbox (ui:->control greet-button) #t)
(ui:box-append! hbox (ui:->control quit-button) #t)

(ui:window-child-set! window (ui:->control hbox))
(ui:control-show! (ui:->control window))
(ui:main)

Same example, but with the SXML interface:

(use (prefix libui ui:))

(ui:margined? #t)
(ui:padded? #t)

(ui:init!)

(define window #f)

(define (greet _button)
  (ui:message-box window "Greeting" "Hello World!"))

(ui:widgets
 `(window
   (@ (id main)
      (title "Hello World")
      (width 180)
      (height 60)
      (menubar? #t)
      (closing ,(lambda (_window) (ui:quit!))))
   (hbox
    (button
     (@ (stretchy? #t)
        (text "Click Me!")
        (clicked ,greet)))
    (button
     (@ (stretchy? #t)
        (text "Quit")
        (clicked ,(lambda (_button) (ui:quit!))))))))

(set! window (ui:widget-by-id 'main))
(ui:control-show! (ui:->control window))
(ui:main)

Further examples can be found in the repository.

License

Copyright (c) 2016, Vasilij Schneidermann

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Version history

0.5

0.4

0.3

0.2

0.1

Contents »