chickadee » libui

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://github.com/wasamasa/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
(main) procedure

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 [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 CONTROL) procedure

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 TEXT) procedure

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

button-text / button-text-set!
(button-text BUTTON) procedure
(button-text-set! BUTTON TEXT) procedure
(set! (button-text BUTTON) TEXT) setter

Retrieves or sets the text of BUTTON.

Box widget
new-horizontal-box
(new-horizontal-box) procedure

Creates and returns a new horizontal box widget.

new-vertical-box
(new-vertical-box) procedure

Creates and returns a new vertical box widget.

box-append!
(box-append! BOX CONTROL [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 TEXT) procedure

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

Entry widget
new-entry
(new-entry) procedure

Creates and returns a new entry widget.

new-password-entry
(new-password-entry) procedure

Creates and returns a new password entry widget.

new-search-entry
(new-search-entry) procedure

Creates and returns a new search entry widget.

entry-text / entry-text-set!
(entry-text ENTRY) procedure
(entry-text-set! ENTRY TEXT) procedure
(set! (entry-text ENTRY) TEXT) setter

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 TEXT) procedure

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

Tab widget
new-tab
(new-tab) procedure

Creates and returns a new tab widget.

tab-append!
(tab-append! TAB TEXT CONTROL) procedure

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

tab-pages-length
(tab-pages-length TAB) procedure

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 TEXT) procedure

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

group-child-set!
(group-child-set! GROUP CONTROL) procedure

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 MAX) procedure

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

spinbox-value / spinbox-value-set!
(spinbox-value SPINBOX) procedure
(spinbox-value-set! SPINBOX VALUE) procedure
(set! (spinbox-value SPINBOX) VALUE) setter

Retrieves or sets the value of SPINBOX.

Slider widget
new-slider
(new-slider MIN MAX) procedure

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

slider-value / slider-value-set!
(slider-value SLIDER) procedure
(slider-value-set! SLIDER VALUE) procedure
(set! (slider-value SLIDER) VALUE) setter

Retrieves or sets the value of SLIDER.

Progress bar widget
new-progress-bar
(new-progress-bar) procedure

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-BAR) procedure
(progress-bar-value-set! PROGRESS-BAR VALUE) procedure
(set! (progress-bar-value PROGRESS-BAR) VALUE) setter

Retrieves or sets the value of PROGRESS-BAR.

Separator widget
new-horizontal-separator
(new-horizontal-separator) procedure

Creates and returns a new horizontal separator widget.

new-vertical-separator
(new-vertical-separator) procedure

Creates and returns a new vertical separator widget.

Combobox widget
new-combobox
(new-combobox) procedure

Creates and returns a new combobox widget.

combobox-append!
(combobox-append! COMBOBOX TEXT) procedure

Appends a combobox item containing TEXT to COMBOBOX.

Editable combobox widget
new-editable-combobox
(new-editable-combobox) procedure

Creates and returns a new editable combobox widget.

editable-combobox-append!
(editable-combobox-append! EDITABLE-COMBOBOX TEXT) procedure

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

Radio buttons widget
new-radio-buttons
(new-radio-buttons) procedure

Creates and returns a new radio buttons widget.

radio-buttons-append!
(radio-buttons-append! RADIO-BUTTONS TEXT) procedure

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

Date/time widgets
new-date-time-picker
(new-date-time-picker) procedure

Creates and returns a new date time picker widget.

new-date-picker
(new-date-picker) procedure

Creates and returns a new date picker widget.

new-time-picker
(new-time-picker) procedure

Creates and returns a new time picker widget.

Multiline entry widget
new-multiline-entry
(new-multiline-entry) procedure

Creates and returns a new multiline entry widget.

new-non-wrapping-multiline-entry
(new-non-wrapping-multiline-entry) procedure

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

multiline-entry-append!
(multiline-entry-append! MULTILINE-ENTRY TEXT) procedure

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-HANDLER) procedure

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! AREA) procedure

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-HANDLER) procedure

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-EVENT) procedure

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

mouse-event-y
(mouse-event-y MOUSE-EVENT) procedure

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

mouse-event-area-width
(mouse-event-area-width MOUSE-EVENT) procedure

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

mouse-event-area-height
(mouse-event-area-height MOUSE-EVENT) procedure

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

draw-params-context
(draw-params-context DRAW-PARAMS) procedure

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

draw-params-area-width
(draw-params-area-width DRAW-PARAMS) procedure

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

draw-params-area-height
(draw-params-area-height DRAW-PARAMS) procedure

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

Font button widget
new-font-button
(new-font-button) procedure

Creates and returns a new font button widget.

Color button widget
new-color-button
(new-color-button) procedure

Creates and returns a new color button widget.

color-button-color / color-button-color-set!
(color-button-color COLOR-BUTTON) procedure
(color-button-color-set! COLOR-BUTTON R G B A) procedure
(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-form) procedure

Creates and returns a new form widget.

form-append!
(form-append! FORM TEXT CONTROL [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-grid) procedure

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 WIDGET) procedure

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

control-destroy!
(control-destroy! CONTROL) procedure

Destroys CONTROL and frees its resources.

control-show!
(control-show! CONTROL) procedure

Displays CONTROL.

Dialogs

open-file
(open-file PARENT) procedure

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

save-file
(save-file PARENT) procedure

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

message-box
(message-box PARENT TITLE DESCRIPTION) procedure

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 DESCRIPTION) procedure

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 SXML) procedure

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 ID) procedure

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 A) procedure

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 BRUSH) procedure
(brush-r-set! BRUSH R) procedure
(set! (brush-r BRUSH) R) setter

Retrieves or sets the red component of BRUSH.

brush-g / brush-g-set!
(brush-g BRUSH) procedure
(brush-g-set! BRUSH G) procedure
(set! (brush-g BRUSH) G) setter

Retrieves or sets the green component of BRUSH.

brush-b / brush-b-set!
(brush-b BRUSH) procedure
(brush-b-set! BRUSH B) procedure
(set! (brush-b BRUSH) B) setter

Retrieves or sets the blue component of BRUSH.

brush-a / brush-a-set!
(brush-a BRUSH) procedure
(brush-a-set! BRUSH A) procedure
(set! (brush-a BRUSH) A) setter

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-matrix) procedure

Creates and returns a new matrix.

matrix-identity-set!
(matrix-identity-set! MATRIX) procedure

Sets MATRIX to the identity matrix.

matrix-translate!
(matrix-translate! MATRIX X Y) procedure

Translates MATRIX by X and Y.

transform!
(transform! CONTEXT MATRIX) procedure

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 [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! PATH) procedure

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 Y) procedure

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 [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 Y) procedure

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

path-close-figure!
(path-close-figure! PATH) procedure

Closes the current figure of PATH.

path-add-rectangle!
(path-add-rectangle! PATH X Y WIDTH HEIGHT) procedure

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

path-end!
(path-end! PATH) procedure

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

stroke!
(stroke! CONTEXT PATH BRUSH STROKE-PARAMS) procedure

Strokes PATH on CONTEXT with BRUSH and STROKE-PARAMS.

fill!
(fill! CONTEXT PATH BRUSH) procedure

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 »