<@component name="Box"> A container element for grouping other controls in an absolutely positioned box.
Implements generic boxed object with no specific functionality (see remarks).

A dialog or an HTML frame can use boxed objects to arrange the contents using absolute positioning.

A boxed object is an HTML element that can participate in automatic dialog/frame layout made by @lib:Global!LAYOUT_BOX method Having a hierarchy of boxed objects allows to arrange the dialog/frame contents automatically by a single call to 'layout' method (e.g. by invoking @lib:Dialog!layout method).

Typically, the layout is done during HTML initializaiton or on ~body resize by calling to ~layout method of the tompost boxed object. The simplest method to achieve proper size calculation is to use @lib:Dialog! component, as the topmost element in the page. The Dialog component automatically takes entire document client area, listens on window intialization and resizing events and arranges all elements in the document automatically. If you need to resize some boxed object at later time, use @lib:Global!SET_BOX (do not setting the ~box attribute dynamically).

The following shows a skeleton of a typical HTML page with boxed objects and automatic layout calculation: #USING[lib:Global.js] #USING[lib:Dialog.htc] #USING[lib:Box.htc] ... ... ... ...

There are several types of boxed objects: Any simple HTML element. Lightweight HTC. Heavyweight HTC.

Note: IFRAME cannot be boxed object. To achieve proper positioning of IFRAME, the hosting dialog/frame must manually adjust IFRAME's position (via standard HTML style attributes). Typically, this is done during host dialog/frame initialization and on each resize.

In order to allow recursive layout calculation to go over the entire boxed objects hierarchy without stopping at any level, it is important to define each boxed object correctly, depending on boxed object type:

A simple HTML element. Set element's 'box' attribute (@lib:Global!BOUNDING_BOX) to one of the possible correct values If the element contains other boxed elements, set element's ~hasChildBoxes attrubute to ~true Lighweight HTC, system-defined (all components implemented in ~core.lib package) Set element's 'box' attribute (@lib:Global!BOUNDING_BOX) to one of the possible correct values Lighweight HTC, custom-made Set element's 'box' attribute (@lib:Global!BOUNDING_BOX) to one of the possible correct values. If your custom HTC can have child elements which are also boxed objects, add the following property to your HTC:
<PUBLIC:PROPERTY name="hasChildBoxes" value="yes" />
Heavyweight HTC, custom-made (see also additional remarks below) Set element's 'box' attribute (@lib:Global!BOUNDING_BOX) to one of the possible correct values. Implement the following public HTC property (see also @lib:Box!box):
<PUBLIC:PROPERTY name="box" get="getBox" put="setBox" />
Implement the following public HTC property (see also @lib:Box!box):
<PUBLIC:PROPERTY name="hasOwnLayout" value="yes" />
Implement the following public HTC method (see @lib:Box!layout):
<PUBLIC:METHOD name="layout" />

Additional guidelines regarding heavyweight HTC components

Heavyweight HTC component has its own HTML markup (specifially, it has <BODY> with some inner HTML). Typically the body should have root @lib:Box! component that takes care of the inner layout. It is incorrect to put @lib:Dialog! component as the root element, because there should be only one @lib:Dialog! in the HTML document, and this root Dialog was already created by the host HTML (see above) The custom HTC ~layout method should first call to a @lib:Global!LAYOUT_BOX method to resize the HTC element itself, and then call to a ~layout method of the root Box element. The second call is necessary because recursive layout calculation inside ~LAYOUT_BOX doesn't have access to element's children (e.g. to root Box)

The following shows a skeleton of a typical heavyweight HTC which is a boxed object: #USING[lib:Global.js] #USING[lib:Box.htc] ... ... ...

If one heavyweight HTC is used by another heavyweight HTC, then the automatic layout, invoked by tompost Dialog element during HTML initialization, might not work, because innermost HTC was not yet loaded (heavyweight HTC are loaded asynchronously). In such case, you need to attach the outermost HTC to the ~ondocumentready event (~ondocumentready is fired from bottom to top, so that parent element is only ready when all child elements are ready).

The following shows typical heavyweight HTC which includes another heavyweight HTC: ... function init() { elmInner.layout(); } ... ... ...