Layout
Introduction
Layouting is a mechanism in Zaplib to position components on the screen.
A core philosophy of the Zaplib layouting model is its simplicity and speed, by having only a single pass to do layouting. Contrast this with systems like CSS Flexbox, which use a constraint satisfaction system to lay out your widgets. Instead, we make a single pass, but do sometimes shift over individual elements after the fact. When doing this we can regard it as a "1.5-pass" rendering.
- The core concept is a "box" - entity having a current draw position and a "sandbox" where it can draw in.
- Boxes can be nested, so we have a stack of boxes.
- The boxes are defined imperatively: new boxes are pushed to the stack using various
begin_*methods and popped using correspondingend_*methods. - The last box in the stack is the "active" one and all rendering calls are added to that box's sandbox.
- When the active box is ended it's sandbox content is pushed into its parent's sandbox (potentially shifted when using alignments) and then parent draw position is moved accordingly.
For the examples on how to use the Layout API, follow the UI Layout tutorial.
API Overview
begin_row / end_row
Defines a box that has its nested elements layed out horizontally (as a row).
begin_column / end_column
Defines a box that has it nested elements layed out vertically (as a column).
begin_absolute_box / end_absolute_box
Defines a box that is absolutely positioned starting at (0, 0) coordinate. Normally the new box starts at the current draw position of the active box. This method allows to bypass that and use absolute coordinates on the screen.
begin_padding_box / end_padding_box
Defines a box that has padding inside.
begin_wrapping_box / end_wrapping_box
Defines a box that is wrapping its content inside. This is only supported for horizontal direction. This is defined in terms of child boxes, meaning that if any of the immediately nested boxes goes beyond the bounds, it would be wrapped to new line). Text has its own wrapping mechanism via TextInsProps::wrapping.
begin_right_box / end_right_box
Defines a box that will be aligned to the right by x axis within last box.
begin_bottom_box / end_bottom_box
Defines a box that will be aligned to the bottom by y axis within last box.
begin_center_x_align / end_center_x_align
Defines a box that fills up all remaining space by x axis and will be aligned to center by x axis within last box.
begin_center_y_align / end_center_y_align
Defines a box that fills up all remaining space by y axis and will be aligned to center by y axis within last box.
begin_center_x_and_y_align / end_center_x_and_y_align
Defines a box that fills up all remaining space by x and y axises and will be aligned to center by both x and y axises within last box.
get_box_rect
Returns the full rect corresponding to current box. It counts all available_width/height plus padding.
get_width_left / get_height_left
Returns the amount of width / height left within the current box.
get_width_total / get_height_total
Get some notion of the total width / height of the active box. If the width/ height is well defined, then we return it. If it's computed, then we return the bound (including padding) of how much we've drawn so far. And if we haven't drawn anything, we return 0.
get_box_bounds
Get the bounds of what the box has actually drawn, including any padding that the layout of the active box specifies.
get_box_origin
Returns the starting position of the active box in absolute coordinates.
get_draw_pos
Returns the current draw position of the active box in absolute coordinates.
add_box
Moves the current draw position of the active box as if the new box with provided dimensions was drawn inside.
move_draw_pos
Manually move the current draw position of the active box. Warning! Does not update bounds like add_box does; might result in unexpected behavior.
set_draw_pos
Manually set the current draw position of the active box. Warning! Does not update bounds like add_box does; might result in unexpected behavior.