SHIP:BoxModel

The box node is the fundamental building block of your visual GUI layout in SHIP; the box node has many properties to support pixel accurate positioning, margins, padding, borders, and more.

boxes can be nested to create groupings, and the child boxes are relatively positioned inside the parent box.

Some other layout node types, such as the page and display share many of the same properties as the box.

This common set of properties are known in SHIP as the "box model":

Outer

The most obvious set of properties in the box model describes the outer dimensions and location of the container:

Box Model Outer Properties

Property	Data Type	Description
ot	Dimension	Top edge of a box model node.
ob	Dimension	Bottom edge of a box model node.
oh	Dimension	Height of a box model node.
ol	Dimension	Left edge of a box model node.
or	Dimension	Right edge of a box model node.
ow	Dimension	Width of a box model node.

Alignment

The valign and halign properties can position a box within its parent container very easily. When not set, the outer properties govern the position of the box, but when set these override positioning set using the outer properties.

Box Model Vertical and Horizontal Alignment Properties

Property	Data Type	Description
valign	VALIGN	Vertical alignment of a box model node within its parent container's inner dimensions.
halign	HALIGN	Horizontal alignment a box model node within its parent container's inner dimensions.

Margins

Within the outer dimensions of the box model container, each of the four sides can have an optional and separate margin thickness. When a value is unset, there is no margin on that edge. The four margin properties are:

Box Model Margin Properties

Property	Data Type	Description
mt	Dimension	Top margin thickness of a box; not present on lightweight box model nodes such as frame and textframe.
mb	Dimension	Bottom margin width of a box; not present on lightweight box model nodes such as frame and textframe.
ml	Dimension	Left margin width of a box; not present on lightweight box model nodes such as frame and textframe
mr	Dimension	Right margin width of a box; not present on lightweight box model nodes such as frame and textframe

Borders

Inside the margin, there is an optional border area. The thickness, in pixels, of the border on each of the four sides is set independently, as is the optional color used to fill the border. Therefore there are 4 pairs of border properties, with each pair being the thickness and color of the border. The color, like other colors in SHIP, can be fully transparent if desired.

Box Model Border Properties

Property	Data Type	Description
bt	Dimension	Top border thickness of a box; not present on lightweight box model nodes such as frame and textframe.
bct	Color	Top border color of a box; not present on lightweight box model nodes such as frame and textframe.
bb	Dimension	Bottom border thickness of a box; not present on lightweight box model nodes such as frame and textframe.
bcb	Color	Bottom border color of a box; not present on lightweight box model nodes such as frame and textframe.
bl	Dimension	Left border thickness of a box; not present on lightweight box model nodes such as frame and textframe.
bcl	Color	Left border color of a box; not present on lightweight box model nodes such as frame and textframe.
br	Dimension	Right border thickness of a box; not present on lightweight box model nodes such as frame and textframe.
bcr	Color	Right border color of a box; not present on lightweight box model nodes such as frame and textframe.

Padding

Within the border of the box model container, each of the four sides can have an optional and separate padding thickness. When a value is unset, there is no padding on that edge. The four padding properties are:

Box Model Padding Properties

Property	Data Type	Description
pt	Dimension	Top padding thickness of a box; not present on lightweight box model nodes such as frame and textframe.
pb	Dimension	Bottom padding thickness of a box; not present on lightweight box model nodes such as frame and textframe.
pl	Dimension	Left padding thickness of a box; not present on lightweight box model nodes such as frame and textframe.
pr	Dimension	Right padding thickness of a box; not present on lightweight box model nodes such as frame and textframe.

Inner

The final rectangular area within a container extends to the inside of the padding. This is called the "inner" area of a box model container and is calculated by taking the outer dimensions of the container and reducing it down by the margins, border, and padding. Nodes within the container will be positioned and displayed relative to this inner area.

These are read-only properties, and cannot be set in SHIPTide or at run-time in SHIPEngine.

Box Model Inner Dimension Properties

Property	Data Type	Description
it	Dimension	Inner area top coordinate of a box model node relative to the display.
ib	Dimension	Inner area bottom coordinate of a box model node relative to the display.
ih	Dimension	Inner area height of a box model node.
il	Dimension	Inner area left coordinate of a box model node relative to the display.
ir	Dimension	Inner area right coordinate of a box model node, relative to the display.
iw	Dimension	Inner area width of a box model node.

Colors

The outer, margin, and inner areas of the box can be each be filled with a flood color. These areas are rendered in order, so any alpha blending will occur as expected. The three relevant properties are:

Box Model Background, Fill, Inner Color Properties

Property	Data Type	Description
bgcolor	Color	Background color of a Box Model Node, filling the container completely to the outer edges.
fillcolor	Color	Fill color of a box, filling the box completely within the margin area; not present on lightweight box model nodes such as frame and textframe.
innercolor	Color	Inner color of a box, filling the box completely within the inner area after padding is applied; not present on lightweight box model nodes such as frame and textframe.

Attached Image and Canvas Offsets

If the box has an attached image or canvas node, this image will be displayed inside the inner area of the box. By default, the image/canvas will be centered as best as possible within the inner area, and if larger in either direction than the inner area will be clipped. However, this positioning can be overridden and manipulated at run-time using these properties:

Box Model Attached Image/Canvas Offset Properties

Property	Data Type	Description
xoffset	Dimension	The horizontal offset of an attached image or canvas within the inner area of a a Box Model Node. May be positive or negative or 0.
yoffset	Dimension	The vertical offset of an attached image or canvas within the inner area of a a Box Model Node. May be positive or negative or 0.

Rendering and Calculation Order

The order of the box rendering/calculation is as follows:

• The "outer" is established (ol,or,ow,ot,ob,oh)
• Background color is flood filled (bgcolor)
• Margins are applied (ml,mr,mt,mb)
• Attached image object is rendered, centered in margins
• Borders are drawn (bl,br,bt,bb)
• Fill color is flood filled with the borders (fillcolor)
• Padding is applied (pl,pr,pt,pb)
• Inner color is flood filled within the padding area (innercolor)
• Contents of the box drawn