# Table Layout
A framework-free table-based layout system, written in pure Rust. You feed in constraints for the desired layout and provide a boxed closure to realize the layout on a given layout element. Once you need to place everything, you call `impose` with the dimensions of the layout object. Based around Esoteric Software's *tablelayout* package, and maybe someday MIGLayout, but is built purely from the public specification and not from the source in any form.

Closures are given the `x`, `y`, `width` and `height` of the layout item. These are relevant to *that item within the table* and do not include any translations that might be applied to the table itself. This means you need to offset `x` and `y` if the table is not placed at `(0, 0)`.

Currently no `unsafe` blocks are used by the engine.

# Layout
Create cells with `CellProperties::new`, then populate them by using the builder pattern. If you wish to use cell, row or column defaults in the layout, use `CellProperties::with_defaults`.

## Expansion
Cells may expand either vertically or horizontally. Expansion means that if there is space left over after all cells receive their preferred size, extra space is distributed to rows and columns with an expand style set.

`.expand_horizontal`, `.expand_vertical` and `.expand` set these policies.

## Fill
If a column or row is made larger than expected (due to expansion rules of other cells in the same column or row), this leaves extra usable space within other cells. By default this space is wasted and the layout elements will be placed in this white space according to anchoring rules. A *fill* says that should extra space become available somehow, that space will be claimed. A fill is not an expand, it will not *cause* extra space to be used. Only space that serendipitously became available is claimed by a fill.

`.fill_horizontal`, `.fill_vertical` and `.fill` set these policies.

Note that fills respect maximum sizes of layout items. Should an element reach its maximum size and fill space is available, the layout item is subject to anchoring rules (albeit at its larger size.)

## Anchor
When a layout item is for any reason smaller than its available space, an anchor defines where it will be located within that white space.

`.anchor_top`, `.anchor_bottom`, and `.anchor_vertical_center` handle sticking layout items along the vertical domain.

`.anchor_left`, `.anchor_right`, and `.anchor_horizontal_center` handle sticking layout items along the horizontal domain.

Conflicting anchor specifications are not an error, but the layout engine is free to ignore conflicting requests as it sees fit.

## Padding
Padding intentionally wastes space around the edges of an element.

`.padding` allows you to provide your own `Rectangle` struct to specify all sides at once.

`.padding_all` sets all padding edges to the same value.

`.padding_top` sets the padding for the top edge.

`.padding_left` sets the padding for the left edge.

`.padding_right` sets the padding for the right edge.

`.padding_bottom` sets the padding for the bottom edge.

Padding is implemented as adding extra space around a cell's size preferences, yet not using that space when positioning an object at the final layout stage.

### Sacrificial padding
While not implemented, some layout engines will count padding as space that can be compacted when straining to fit a UI in a small space. 

## Uniform

All cells that are set uniform will have the same size. In practice, this policy is not actually implemented right now.

# Internals
You should use the builder pattern to prepare layouts and cells. Tampering with the internals directly is not advised (and they might be made non-public in a more stable version.)

Bit flags for centered placement might be removed; one can argue that attempting to anchor to ex. the left and right side simultaneously *is identical* to center anchoring, which frees up two flags for use elsewhere.

# Performance

A benchmark is provided (`cargo bench`) to test layout calculations. On my *AMD FX(tm)-6300 Six-Core Processor*:

```
test test::impose2x3 ... bench:       8,468 ns/iter (+/- 790)
```

Note that imposing layouts does *not* rely on multi-threading and only needs to be done when the table's width or height is disturbed.

# Changelog
## 0.2
Unit tests and implementation of cell padding.

## 0.1.1
Minor fixes and PRs.

## 0.1
Initial release.

# Reference
https://github.com/EsotericSoftware/tablelayout