Structure

Overview

Here we provide a high level documentation of pyglui classes and elements.

UI

The UI class is a user interface context that must be created within a system window. We have designed pyglui to be used with glfw, but it should also work with other window managers. It is a manager of ui elements and the top level control layer of the UI.

UI elements can be appended to the UI context just like how you would interact with a normal list in Python. For example you can append a new menu element to the ui with ui.append(menu), extend the ui with ui.extend or remove elements with ui.remove.

Since the UI class has access to all elements, it can also globally control attributes like scale - so that you can increase or decrease the size of each UI element with ui.scale.

FitBox

The FitBox is the key building block...or box...of pyglui. It is used in almost every class to define a two dimensional rectangular context or 'box'. A FitBox is defined by two 2D vectors, position (x,y) and size (width,height), and fits itself into a context (hence the name fit + box). Typically the context is defined by another 'parent' FitBox, except for the case of the UI class where the context is the window created by glfw itself. We'll demonstrate this a bit later.

Position and Size Vectors

The position and size vectors of the FitBox class define the rules for how it fits into its parent context. design_org and design_size are attributes of the FitBox class that store the design position and size rules of each FitBox.

The actual pixel position and pixel size (org and size respectively) of a FitBox relative to its parent context are computed when the compute() method is called - this is discussed in Nesting.

Diagram of a glfw window with the origin (0,0) at the top left hand corner. In this example, the boundaries of the window diagram are considered the context. A positive position vector (x,y) defines the top left corner position of the box. A positive size defines the width and height of the box from the position vector.

Position = 0 - A 0 value for position will fit the box to the boundary of the parent context, and clamp it to the parent boundary edge. In this example the x value is 0, therefore the box is clamped to the parent context's left most edge at the specified y position.

Position = 0 - A 0 value for position y value abides by the same rule. In this example the y value is 0, and the box is clamped to the parent context's top most edge at the specified x position.

Position = Negative Value - A negative value for position will position the box relative to the opposite side of the parent context. In this example we have a (large) negative y value for position. This will position the box at a fixed distance from the bottom edge of the parent context even if the parent context were to resize.

Position = Negative Value - A negative value for x will position the box relative to the opposite side of the parent context. In this example a negative x value constrains the box to be at the specified distance from the right side of the parent context.

Size = 0 - A 0 value for size will fit the box to the maximum boundary of the parent context, and clamp it to the parent boundary edge. In this example both the x and y values are 0, therefore the box is clamped to the parent context's bottom right corner.

Size = Negative Value - A negative value for size will fit the box to the maximum boundary of the parent context minus the value specified. In this example, the y value is negative, therefore the box will be always be spaced above the bottom edge of the parent bottom boundary by the specified value.

Nesting

In the above example, we used the term 'parent' to determine the relationship between FitBox and context, where the parent was the boundary of the window and the child was the FitBox. We can extend this parent-child hierarchy such that each FitBox can also be a 'parent' to another FitBox.

The parent child relationship is made by calling the FitBox compute method - child.compute(parent) - the design rules of the child FitBox are translated and fitted into the parent's context, resulting in the org (position) and size in pixel space.

In this example the design rules for position and size (design_org and design_size) are specified. After calling child.compute.parent the design rules are applied and the child FitBox becomes related to the parent context and the org and size describe it's position within the global context. Take note of negative size of design_size.

In this example the design rules for position and size (design_org and design_size) are specified. After calling child.compute.parent the design rules are applied and the child FitBox becomes related to the parent context and the org and size describe it's position within the global context. Note the negative x value of design_org and negative height or y value of design_size. This child FitBox would be clamped to the right hand side of the parent FitBox and 50 pixels from the bottom and 190 pixels from the right hand boundary of the parent FitBox.