libui-ng: a portable GUI library for C

Fork of andlabs/libui. This README is being written.

About

Simple and portable (but not inflexible) GUI library in C that uses the native GUI technologies of each platform it supports.

This repo has some messy quick patches to add some extra features to the linux part (gtk).

libui-ng is currently mid-alpha software.

Runtime Requirements

• Windows: Windows Vista SP2 with Platform Update or newer
• Unix: GTK+ 3.10 or newer
• Mac OS X: OS X 10.8 or newer

Build Requirements

• Meson 0.58.0 or newer
• Any of Meson's backends; this section assumes you are using Ninja, but there is no reason the other backends shouldn't work.

Quick Building Instructions

$ git clone https://github.com/mohad12211/libui-ng.git
$ cd libui-ng
$ meson setup build --buildtype=release --default-library=static 
$ ninja -C build

then copy libui.a that's inside build/meson-out into libs directory (replace it).

Building

libui-ng mainly uses the standard Meson build options.

$ # in the top-level libui-ng directory run:
$ meson setup build [options]
$ ninja -C build

Once this completes, everything will be under build/meson-out/.

libui-ng specific options:

• -Dtests=(true|false) controls whether tests are built; defaults to true
• -Dexamples=(true|false) controls whether examples are built; defaults to true

Most important Meson options:

• --buildtype=(debug|release|...) controls the type of build made; the default is debug. For a full list of valid values, consult the Meson documentation.
• --default-library=(shared|static) controls whether libui is built as a shared library or a static library; the default is shared. You currently cannot specify both, as the build process changes depending on the target type (though I am willing to look into changing things if at all possible).
• -Db_sanitize=which allows enabling the chosen sanitizer on a system that supports sanitizers. The list of supported values is in the Meson documentation.
• --backend=backend allows using the specified backend for builds instead of ninja (the default). A list of supported values is in the Meson documentation.
• --wrap-mode=(forcefallback|nofallback|nodownload|...) controls which cmocka library version to use in test enabled builds. The default is forcefallback to pull and build a local copy. Package maintainers may wish to choose nofallback to use the system's library and declare cmocka a build time dependency or nodownload, see the Meson documentation for more details.

Most other built-in options will work, though keep in mind there are a handful of options that cannot be overridden because libui depends on them holding a specific value; if you do override these, though, libui will warn you when you run meson.

The Meson website and documentation has more in-depth usage instructions.

For the sake of completeness, I should note that the default value of --layout is flat, not the usual mirror. This is done both to make creating the release archives easier as well as to reduce the chance that shared library builds will fail to start on Windows because the DLL is in another directory. You can always specify this manually if you want.

Backends other than ninja should work, but are untested by me.

Installation

Meson also supports installing from source; if you use Ninja, just do

$ ninja -C build install

When running meson, the --prefix option will set the installation prefix. The Meson documentation has more information, and even lists more fine-grained options that you can use to control the installation.

Arch Linux

Can be built from AUR: https://aur.archlinux.org/packages/libui-ng-git/

Documentation

Needs to be written. Consult ui.h and the examples for details for now.

Language Bindings

libui was originally written as part of my package ui for Go. Now that libui is separate, package ui has become a binding to libui. As such, package ui is the only official binding.

Other people have made bindings to other languages:

Language	Bindings
C++	libui-cpp, cpp-libui-qtlike
C# / .NET Framework	LibUI.Binding
C# / .NET Core	DevZH.UI, SharpUI, SimplexiDev.UI
CHICKEN Scheme	wasamasa/libui
Common Lisp	jinwoo/cl-ui
Crystal	libui.cr, hedron
D	DerelictLibui (flat API), libuid (object-oriented)
Euphoria	libui-euphoria
Harbour	hbui
Haskell	haskell-libui
Janet	JanetUI
JavaScript/Node.js	libui-node, libui.js (merged into libui-node?), proton-native, vuido
Julia	Libui.jl
Kotlin	kotlin-libui
Lua	libuilua, libui-lua, lui, lui
Nim	ui
Perl6	perl6-libui
PHP	ui
Python	pylibui
Ruby	libui-ruby, LibUI, Glimmer DSL for LibUI
Rust	libui-ng-sys, boing, libui-rs
Scala	scalaui
Swift	libui-swift

Frequently Asked Questions

Why does my program start in the background on OS X if I run from the command line?

OS X normally does not start program executables directly; instead, it uses Launch Services to coordinate the launching of the program between the various parts of the system and the loading of info from an .app bundle. One of these coordination tasks is responsible for bringing a newly launched app into the foreground. This is called "activation".

When you run a binary directly from the Terminal, however, you are running it directly, not through Launch Services. Therefore, the program starts in the background, because no one told it to activate! Now, it turns out there is an API that we can use to force our app to be activated. But if we use it, then we'd be trampling over Launch Services, which already knows whether it should activate or not. Therefore, libui does not step over Launch Services, at the cost of requiring an extra user step if running directly from the command line.

See also this and this.

Contributing

See CONTRIBUTING.md

Screenshots

From examples/controlgallery: