layout

Layout

A simple/fast stacking box layout library. It's useful for calculating layouts for things like 2D user interfaces. It compiles as C99 or C++. It's tested with gcc (mingw64), VS2015, and clang/LLVM. You only need one file to use it in your own project: layout.h.

Use Layout in Your Project

To use Layout in your own project, copy layout.h into your project's source tree and define LAY_IMPLEMENTATION in exactly one .c or .cpp file that includes layout.h.

The includes in your one special file should look like this:

#include ...
#include ...
#define LAY_IMPLEMENTATION
#include "layout.h"

All other files in your project should not define LAY_IMPLEMENTATION, and can include layout.h like normal.

Requirements and Extras

Layout has no external dependencies, but by default it does use assert.h, stdlib.h and string.h for assert, realloc and memset. If your own project does not or cannot use these, you can easily exchange them for something else by using preprocessor definitions. See the section below about the available customizations.

Layout can be built as C99 or C++ if you are using GCC or Clang, but must be built as C++ if you are using MSVC. This requirement exists because the Layout implementation code uses the vector_size extension in GCC and Clang, which does not exist in MSVC. C++ operator overloading is used to simulate this feature in MSVC. The code generated by all three compilers is not too different -- the vector_size extension is used mostly to keep the syntax of the implementation easier to read.

Layout is based on the nice library oui by duangle. Unlike oui, Layout does not handle anything related to user input, focus, or UI state.

Building the tests and benchmarks is handled by the tool.bash script, or by GENie. See the section below about building the tests and benchmarks. There's also an example of using Layout as a Lua .dll module. However, you don't need any of that to use Layout in your own project.

Options

You can choose to build Layout to use either integer (int16) or floating point (float) coordinates. Integer is the default, because UI and other 2D layouts do not often use units smaller than a single point when aligning and positioning elements. You can choose to use floating point instead of integer by defining LAY_FLOAT.

• LAY_FLOAT, when defined, will use float instead of int16 for coordinates.

In addition to the LAY_FLOAT preprocessor option, other behavior in Layout can be customized by setting preprocessor definitions. Default behavior will be used for undefined customizations.

• LAY_ASSERT will replace the use of assert.h's assert

• LAY_REALLOC will replace the use of stdlib.h's realloc

• LAY_MEMSET will replace the use of string.h's memset

If you define LAY_REALLOC, you will also need to define LAY_FREE.

Example

…

Building the Tests and Benchmarks

If you have bash and are on a POSIX system, you can use the tool.bash script to build Layout's standalone tests and benchmarks programs. Run tool.bash to see the options.

Using GENie

Instead of using the tool.bash script, you can use GENie to generate a Visual Studio project file, or any of the other project and build system output types it supports. The GENie generator also lets you build the example Lua module.

Directions for acquiring and using GENie

The genie.lua script is mostly tested on Windows, so if you use it on another platform, you might need to tweak it.

You will first need to get (or make) a GENie binary and place it in your path or at the root of this repository.

Download GENie

Linux:
https://github.com/bkaradzic/bx/raw/master/tools/bin/linux/genie

OSX:
https://github.com/bkaradzic/bx/raw/master/tools/bin/darwin/genie

Windows:
https://github.com/bkaradzic/bx/raw/master/tools/bin/windows/genie.exe

Visual Studio 2015/2017

genie.exe vs2015
start build/vs2015/layout.sln

Replace vs2015 with vs2017 if you want to use Visual Studio 2017.

GCC/MinGW/Clang

./genie gmake

and then run your make in the directory build/gmake. You will need to specify a target and config. Here is an example for building the tests target in Windows with the 64-bit release configuration using mingw64 in a bash-like shell (for example, git bash):

./genie.exe gmake && mingw32-make.exe -C build/gmake tests config=release64

If you want to use float coordinates instead of integer, you can use an option in the build script which will define LAY_FLOAT for you:

./genie gmake --coords=float

or if you want to specify integer (the default):

./genie gmake --coords=integer