The Basics

playbit-ui is an immediate-mode styled API. The UI is composed of a tree of 2D boxes. Boxes are persisted across frames using a stable key.

Box Construction

Boxes can be created with the following API:

UIBox* UIBoxMakeFromString(UIBoxFlags flags, PBStrSlice string);

By default, each box starts with no styles and will not render anything.

You must explicitly turn on features you want with the flags property.

For example:

UIBox *box = UIBoxMakeFromString(UIBoxFlag_DrawText|UIBoxFlag_DrawBackground, PBStrLit("hello"));
box->style.backgroundColor = UI_rgb(1, 0, 0);
box->style.width  = UI_px(40);
box->style.height = UI_px(40);

Box Flags

Here are the box flags:

UIBoxFlag_FixedWidth       // box width must be _exactly_ fixedSize.x
UIBoxFlag_FixedHeight      // box height must be _exactly_ fixedSize.y
UIBoxFlag_FloatingX        // remove box from layout along the X-axis and position absolutely with fixedPosition.x
UIBoxFlag_FloatingY        // remove box from layout along the Y-axis and position absolutely with fixedPosition.y

UIBoxFlag_AllowOverflowX   // allow children to overflow on the X-axis
UIBoxFlag_AllowOverflowY   // allow children to overflow on the Y-axis
UIBoxFlag_SkipViewOffsetX  // ignore parent's scroll offset along the X-axis
UIBoxFlag_SkipViewOffsetY  // ignore parent's scroll offset along the Y-axis

UIBoxFlag_DrawText         // draw box text
UIBoxFlag_DrawBackground   // draw box background
UIBoxFlag_DrawBorder       // draw box border
UIBoxFlag_DrawShadow       // draw box shadow

UIBoxFlag_Clip             // clip children contents to parent's viewport

UIBoxFlag_NoPointerEvents  // box will pass-through all mouse events and not be clickable

//
// in addition, the following compound flags are available:
//

UIBoxFlag_Floating       // PBUIBoxFlag_FloatingX | PBUIBoxFlag_FloatingY
UIBoxFlag_FixedSize      // PBUIBoxFlag_FixedWidth | PBUIBoxFlag_FixedHeight
UIBoxFlag_AllowOverflow  // PBUIBoxFlag_AllowOverflowX | PBUIBoxFlag_AllowOverflowY
UIBoxFlag_SkipViewOffset // PBUIBoxFlag_SkipViewOffsetX | PBUIBoxFlag_SkipViewOffsetY
UIBoxFlag_Draw           // all draw flags turned on

UIState

One UIState corresponds to a single UI tree. Your app may have multiple UI trees if needed. Each UI tree is completely isolated from another.

UI Root

Every UI tree has a single root box, which takes up the width and height of the layout dimensions specified.

You can access it with UIRoot().

Parent Stack

There is an implicit parent stack and when you create a new box it will be attached to the current parent.

The top-most parent is the root.

UIBox* parent = UIBoxMakeFromString(0, PBStrLit("<parent>"));
UIPushParent(parent);
{
    // boxes in this scope will be added as children of parent
    UIBox *child = UIBoxMakeFromString(0, PBStrLit("<child>"));
}
UIPopParent(parent);

To query for the top-parent, you can use:

UITopParent();