SUI.Box
A SUI.Box represents a box structure and is the basic building block of the SUI library.
SUI.Box is the basic building block of the SUI library. SUI.Box are objects that represent absolutely positioned div elements and implement the functionality for the framework to size and display them as required. SUI.Boxes are basically wrappers for HTML elements and the method el() will return the box's element (SUI.Box#el).
Because we like to work with absolute distances measured in pixels you'll find the properties common to the style attributes of HTML elements like top, width, etc. (re)defined as fields of the SUI.Box class. However in the SUI.Box class no CSS lengths but only integer values are supported to simplify layout arithmetic.
To support the layout mechanism you'll find two methods: layOut (SUI.Box#layOut) and display (SUI.Box#display). These methods will be called when rendering box objects on the browser's client area. The basic idea is that the layOut method will calculate the size and position of the box (or an object that inherits SUI.Box) and the display method will actually set the CSS properties to the size and position that was calculated by the layOut method during the lay out phase.
The reason to separate between these two operations is that it is possible that layout operations interact: trying to set a box to a certain width might be readjusted later in the layout process due to a child box that has a larger minimum width set. We first want to fully calculate the layout before starting the rendering process. It is expected that this will result in a snappier GUI experience and that's what we're after.
Boxes can be anchored. This only has meaning if the box is a child box of a SUI.AnchorLayout. When anchored a child box of a container will set its size and position relative to the container's sides for the given anchor.
Suppose all sides (left, top, bottom, right) of a box are set to 10 and the box is anchored to all sides of the container box ({left: true, right: true, top: true, bottom: true}). The result will be a box on the container's client area with a 10 pixel margin, no matter how the parent container is (and will be) sized, thus ignoring the box's width and height settings. Setting the bottom anchor to false will keep the box 10 pixels from the top, right and left sides of the container but the box height setting will now be respected.
SUI.Box objects also offer a way to a attach events. More complex derivatives of SUI.Box will use these: f.i. an subclass of SUI.Box might implement an 'onLoad' event because it loads its contents using an XHR request.
Defined in: Box.js
| Attr. | Name / Description |
|---|---|
| public |
SUI.Box(arg) A SUI.Box represents a box structure and is the basic building block of the SUI library. |
| Attr. | Type | Name | Description |
|---|---|---|---|
| private | SUI.Border |
The box's border. |
|
| private | int |
The bottom position of the box. |
|
| private | HTMLElementNode |
The box's element node. |
|
| private | int |
The height of the box. |
|
| private | int |
The left position of the box. |
|
| private | int |
The listeners array. |
|
| private | int |
The maximum height of the box. |
|
| private | int |
The maximum width of the box. |
|
| private | int |
The minimum height of the box. |
|
| private | int |
The minimum width of the box. |
|
| private | SUI.Padding |
The box's padding. |
|
| private | SUI.Box |
The box's parent element. |
|
| private | int |
The right position of the box. |
|
| private | int |
The top position of the box. |
|
| private | int |
The width of the box. |
| Attr. | Type | Name / Description |
|---|---|---|
| public |
absPos() Get the absolute position (top/left) of this box on the page. Note: You can only use this function if the HTML content of the page is fully rendered. |
|
| public |
addClass(cls) Add a CSS class name to the class list of the HTML element associated with the box. |
|
| public |
addListener(type, listener) Add/register a listener function. This way it is possible to register more than one listener function on one target. |
|
| public | SUI.Border |
border(b) Get or set the border definition of the box. |
| public | int |
bottom(b) Get or set the bottom of the box. |
| public |
callListener(type) Call a listener function. Execute the default and additional listener functions. Note: the framework should not execute the default listeners directly but always through this method to ensure the execution of additional listener functions. |
|
| public | int |
Get the client height of the box. The client height is the height of the box minus the top and bottom border and padding width. |
| public | int |
Get the client width of the box. The client width is the width of the box minus the left and right border and padding width. |
| public |
display() Display the box. Set the CSS positions of the element's box(es) and of the children of the box. |
|
| public |
draw() Draw the box on the screen. It executes a two phase process: a layout phase in which the size and positions of the box (and of it's contents, for more complex derivatives) is calculated and a display phase in which the CSS size and position of the box's (and possible it's child elements) is set. |
|
| public | HTMLElementNode |
el() Get the HTML element node of the box. |
| public | int |
height(h) Get or set the height of the box. |
| public |
layOut() Lay out the box. Calculate the position of the box and its contents. The layOut function of a simple box does nothing, but it's important for more complex objects extended from SUI.Box. The layOut mechanism will set the size and position of the child boxes of the box based on the on the available space and within the restrictions of the box's minimum and maximum width and height. So the job of the overridden layOut method is to recalculate the size and position of all the child elements of the box when the layout manager sets the size of the box and calls the box's layOut method. |
|
| public | int |
left(l) Get or set the left of the box. |
| public | int |
maxHeight(mh) Get or set the maximum height of the box. |
| public | int |
maxWidth(mw) Get or set the maximum width of the box. |
| public | int |
minHeight(mh) Get or set the minimum height of the box. |
| public | int |
minWidth(mw) Get or set the minimum width of the box. |
| public | SUI.Padding |
padding(p) Get or set the padding definition of the box. |
| public | SUI.Box |
parent(p) Get or set the parent box of the box. When setting the parent the box's element node will be appended to the parent box's HTML element node. |
| public |
Remove a box from the DOM tree. |
|
| public |
removeClass(cls) Remove a CSS class name from the class list of the HTML element associated with the box. |
|
| public | int |
right(r) Get or set the right of the box. |
| public |
setDim() Set the CSS dimensions of this box and it's borders and padding. This is typically used in display functions to display boxes at the size and position that was calculated during layout. |
|
| public |
setPos() Set the CSS postion of this box. This is typically used in display functions to display boxes at position that was calculated during layout. Note: use setDim if you want to set the position and size of the box. |
|
| public |
setRect(t, l, w, h) Set the top, left, width and height of a box in one go. |
|
| public | int |
top(t) Get or set the top of the box. |
| public | int |
width(w) Get or set the width of the box. |
Constructor
- public SUI.Box( object arg)
-
Create a SUI.Box component.
Parameters:
Name Type Argument Default Description Object arg.elemAttr <optional>
Additional (element) attributes for the box's element given as an object containing name and value pairs. Object arg.anchor <optional>
{left: true, top: true} The anchors for the box. SUI.Border arg.border <optional>
new SUI.Border() the border (width) of the box. Note: don't edit the border's members, you'll edit the boxes prototype. Assign a new SUI.Border object instead. int arg.bottom <optional>
0 The bottom position of the box. int arg.height <optional>
0 The height of the box. int arg.id <optional>
auto generated The id of the HTML element of the box. int arg.left <optional>
0 The left position of the box. int arg.maxHeight <optional>
1000000 The maximum height of the box. int arg.minHeight <optional>
0 The minimal height of the box. int arg.maxWidth <optional>
100000 The maximal width of the box. int arg.minWidth <optional>
0 The minimal width of the box. SUI.Padding arg.padding <optional>
new SUI.Padding() the padding of the box. Note: don't edit the padding's members, you'll edit the boxes prototype. Assign a new SUI.Padding object instead. SUI.Box arg.parent <optional>
the parent box of the box. int arg.right <optional>
0 The right position of the box. String arg.tag <optional>
"DIV" An alternative tag name for the box. int arg.top <optional>
0 The top position of the box. int arg.width <optional>
0 The width of the box.
Members
- private SUI.Border _border
-
The box's border.
- private int _bottom
-
The bottom position of the box.
- private HTMLElementNode _el
-
The box's element node.
- private int _height
-
The height of the box.
- private int _left
-
The left position of the box.
- private int _listeners
-
The listeners array.
- private int _maxHeight
-
The maximum height of the box.
- private int _maxWidth
-
The maximum width of the box.
- private int _minHeight
-
The minimum height of the box.
- private int _minWidth
-
The minimum width of the box.
- private SUI.Padding _padding
-
The box's padding.
- private SUI.Box _parent
-
The box's parent element.
- private int _right
-
The right position of the box.
- private int _top
-
The top position of the box.
- private int _width
-
The width of the box.
Methods
- public absPos()
-
Get the absolute position (top/left) of this box on the page. Note: You can only use this function if the HTML content of the page is fully rendered.
- public addClass( String cls)
-
Add a CSS class name to the class list of the HTML element associated with the box.
Parameters:
Name Type Description String cls the CSS class name to add - public addListener( String type, Function listener)
-
Add/register a listener function. This way it is possible to register more than one listener function on one target.
Parameters:
Name Type Description String type The listener type (i.e. "onClick", "onOK", etc). Function listener The listener function. - public SUI.Border border( SUI.Border b)
-
Get or set the border definition of the box.
Parameters:
Name Type Argument Description SUI.Border b <optional>
The new border definition (or none to use this method as a getter). Returns:
SUI.Border the border definition of the box (or null if this method was used as a setter).
- public int bottom( int b)
-
Get or set the bottom of the box.
Parameters:
Name Type Argument Description int b <optional>
The new bottom of the box (or none to use this method as a getter). Returns:
int The bottom of the box (or null if this method was used as a setter).
- public callListener( String type)
-
Call a listener function. Execute the default and additional listener functions. Note: the framework should not execute the default listeners directly but always through this method to ensure the execution of additional listener functions.
Parameters:
Name Type Description String type The listener type (i.e. "onClick", "onOK", etc). - public int clientHeight()
-
Get the client height of the box. The client height is the height of the box minus the top and bottom border and padding width.
Returns:
int The client height of the box.
- public int clientWidth()
-
Get the client width of the box. The client width is the width of the box minus the left and right border and padding width.
Returns:
int The client width of the box.
- public display()
-
Display the box. Set the CSS positions of the element's box(es) and of the children of the box.
- public draw()
-
Draw the box on the screen. It executes a two phase process: a layout phase in which the size and positions of the box (and of it's contents, for more complex derivatives) is calculated and a display phase in which the CSS size and position of the box's (and possible it's child elements) is set.
- public HTMLElementNode el()
-
Get the HTML element node of the box.
Returns:
HTMLElementNode the HTML element node of the box.
- public int height( int h)
-
Get or set the height of the box.
Parameters:
Name Type Argument Description int h <optional>
The new height of the box (or none to use this method as a getter). Returns:
int The height of the box (or null if this method was used as a setter).
- public layOut()
-
Lay out the box. Calculate the position of the box and its contents. The layOut function of a simple box does nothing, but it's important for more complex objects extended from SUI.Box. The layOut mechanism will set the size and position of the child boxes of the box based on the on the available space and within the restrictions of the box's minimum and maximum width and height. So the job of the overridden layOut method is to recalculate the size and position of all the child elements of the box when the layout manager sets the size of the box and calls the box's layOut method.
- public int left( int l)
-
Get or set the left of the box.
Parameters:
Name Type Argument Description int l <optional>
The new left of the box (or none to use this method as a getter). Returns:
int The left of the box (or null if this method was used as a setter).
- public int maxHeight( int mh)
-
Get or set the maximum height of the box.
Parameters:
Name Type Argument Description int mh <optional>
The new maximum height of the box (or none to use this method as a getter). Returns:
int The maximum height of the box (or null if this method was used as a setter).
- public int maxWidth( int mw)
-
Get or set the maximum width of the box.
Parameters:
Name Type Argument Description int mw <optional>
The new maximum width of the box (or none to use this method as a getter). Returns:
int The maximum width of the box (or null if this method was used as a setter).
- public int minHeight( int mh)
-
Get or set the minimum height of the box.
Parameters:
Name Type Argument Description int mh <optional>
The new minimum height of the box (or none to use this method as a getter). Returns:
int The minimum height of the box (or null if this method was used as a setter).
- public int minWidth( int mw)
-
Get or set the minimum width of the box.
Parameters:
Name Type Argument Description int mw <optional>
The new minimum width of the box (or none to use this method as a getter). Returns:
int The minimum width of the box (or null if this method was used as a setter).
- public SUI.Padding padding( SUI.Padding p)
-
Get or set the padding definition of the box.
Parameters:
Name Type Argument Description SUI.Padding p <optional>
The new padding definition (or none to use this method as a getter). Returns:
SUI.Padding The padding definition of the box (or null if this method was used as a setter).
- public SUI.Box parent( SUI.Box p)
-
Get or set the parent box of the box. When setting the parent the box's element node will be appended to the parent box's HTML element node.
Parameters:
Name Type Description SUI.Box p The parent box for this box (or none to use this method as a getter). Returns:
SUI.Box The parent box of the box (or null if this method was used as a setter).
- public removeBox()
-
Remove a box from the DOM tree.
- public removeClass( String cls)
-
Remove a CSS class name from the class list of the HTML element associated with the box.
Parameters:
Name Type Description String cls The CSS class name to remove. - public int right( int r)
-
Get or set the right of the box.
Parameters:
Name Type Description int r The new right of the box (or none to use this method as a getter). Returns:
int The right of the box (or null if this method was used as a setter).
- public setDim()
-
Set the CSS dimensions of this box and it's borders and padding. This is typically used in display functions to display boxes at the size and position that was calculated during layout.
- public setPos()
-
Set the CSS postion of this box. This is typically used in display functions to display boxes at position that was calculated during layout. Note: use setDim if you want to set the position and size of the box.
- public setRect( int | SUI.Box t, int l, int w, int h)
-
Set the top, left, width and height of a box in one go.
Parameters:
Name Type Argument Description int | SUI.Box t The new top of the box or another reference box to copy the values from. int l <optional>
The new left of the box (if the t parameter wasn't a reference Box). int w <optional>
The new width of the box (if the t parameter wasn't a reference Box). int h <optional>
The new length of the box (if the t parameter wasn't a reference Box). - public int top( int t)
-
Get or set the top of the box.
Parameters:
Name Type Argument Description int t <optional>
The new top of the box (or none to use this method as a getter). Returns:
int The top of the box (or null if this method was used as a setter).
- public int width( int w)
-
Get or set the width of the box.
Parameters:
Name Type Argument Description int w <optional>
The new width of the box (or none to use this method as a getter). Returns:
int The width of the box (or null if this method was used as a setter).
