Labs/Thunderhead/TheBook

The Thunderhead "Book"

As I've been hacking on Thunderhead (aka "Th") I have various things I need to write down, but I haven't decided on a doc format for Th, so just going to record the stuff here.

Component System Overview

Th is a GUI toolkit. Its components are built on top of a small OO library called JSTraits, which in turn is inspired by John Resig's post on JS OO libraries, which in turn was inspired by... you get the idea.

Any Th component must extend th.Component.

Box Model

Th components use the CSS box model for rendering, not for layout. That is, Th components have a margin, a border, padding, and content. Important: note that the margin is where the rendering and layout models conflate. The CSS layout mechanism collapses adjacent margins.

Th doesn't (consistently) collapse component margins because in Th, layout is pluggable--so layout managers can decide on an individual basis want to do with margin.

All of Th's default layout managers do not collapse margins.

Insets

The "insets" of a component is the size of the border and the padding of a component along each size; it is of this shape:

{ top: 10, right: 10, bottom: 10, left: 10 }

Component Notes

ScrollPane

Provides scrolling services to one component. Can contain a vertical scrollbar or a horizontal one, or both. The scrollbars can have little nibs that make them draggable. These are triggered by the following CSS properties:

• overflow-x: "hidden", "scroll", and "auto" supported; "visible" not supported (one of the worst things about CSS)
• overflow-y: same as overflow-x
• overflow: short-cut for x and y
• -th-nib-y: "visible", "none"; if "visible", this causes a panel with nibs at the top and bottom to show up
• -th-nib-x: "visible", "none"

The nib panel changes the preferred size of the scroll pane as it is moved and requests a re-layout by the scrollpane's parent.

Layout

A Th container uses a layout manager to work out where to put its children components and how big to make them.

Some layout managers rely on the components themselves to provide hints as to how to size them. These hints are provided by the following three methods:

• getMinimumSize
• getPreferredSize
• getMaximumSize

Layout managers may use none or more of these methods to work out how to size the components in a container. These methods should return an object of this shape:

{ height: 100, width: 100 }

Default implementations of these methods are provided to every component; they are as follows:

• getPreferredSize: returns left + right insets for width and top + bottom insets for height
• getMinimumSize: returns getPreferredSize
• getMaximumSize: returns getPreferredSize