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 <q ref="core.lib:Global!LAYOUT_BOX">LAYOUT_BOX</q> 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 <q ref="core.lib:Dialog!layout">layout</q> method). Typically, the layout is done during HTML initializaiton or on <code>body</code> resize by calling to <code>layout</code> method of the tompost boxed object. The simplest method to achieve proper size calculation is to use <q ref="core.lib:Dialog">Dialog</q> 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 <q ref="core.lib:Global!SET_BOX">SET_BOX</q> (do not setting the <code>box</code> attribute dynamically). The following shows a skeleton of a typical HTML page with boxed objects and automatic layout calculation: <pre> <HTML xmlns:STB="urn:guimachine-com:storyboard"> #USING[lib:Global.js] #USING[lib:Dialog.htc] #USING[lib:Box.htc] ... <BODY> <STB:DIALOG id="elmDialog"> <STB:BOX box="0 0 W 100">...</STB:BOX> <STB:BOX box="0 100 W H-100">...</STB:BOX> ... </STB:DIALOG> </BODY> </HTML> </pre> There are several types of boxed objects: <ul><li>Any simple HTML element. </li><li>Lightweight HTC. </li><li>Heavyweight HTC. </li></ul> 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. <ul><li>Set element's 'box' attribute (<q ref="core.lib:Global!BOUNDING_BOX">BOUNDING_BOX</q>) to one of the possible correct values </li><li>If the element contains other boxed elements, set element's <code>hasChildBoxes</code> attrubute to <code>true</code> </li></ul> Lighweight HTC, system-defined (all components implemented in <code>core.lib</code> package) <ul><li>Set element's 'box' attribute (<q ref="core.lib:Global!BOUNDING_BOX">BOUNDING_BOX</q>) to one of the possible correct values </li></ul> Lighweight HTC, custom-made <ul><li>Set element's 'box' attribute (<q ref="core.lib:Global!BOUNDING_BOX">BOUNDING_BOX</q>) to one of the possible correct values. </li><li>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" /> </li></ul> Heavyweight HTC, custom-made (see also additional remarks below) <ul><li>Set element's 'box' attribute (<q ref="core.lib:Global!BOUNDING_BOX">BOUNDING_BOX</q>) to one of the possible correct values. </li><li>Implement the following public HTC property (see also <q ref="core.lib:Box!box">box</q>): <PUBLIC:PROPERTY name="box" get="getBox" put="setBox" /> </li><li>Implement the following public HTC property (see also <q ref="core.lib:Box!box">box</q>): <PUBLIC:PROPERTY name="hasOwnLayout" value="yes" /> </li><li>Implement the following public HTC method (see <q ref="core.lib:Box!layout">layout</q>): <PUBLIC:METHOD name="layout" /> </li></ul> Additional guidelines regarding heavyweight HTC components <ul><li>Heavyweight HTC component has its own HTML markup (specifially, it has <BODY> with some inner HTML). Typically the body should have root <q ref="core.lib:Box">Box</q> component that takes care of the inner layout. </li><li>It is incorrect to put <q ref="core.lib:Dialog">Dialog</q> component as the root element, because there should be only one <q ref="core.lib:Dialog">Dialog</q> in the HTML document, and this root Dialog was already created by the host HTML (see above) </li><li>The custom HTC <code>layout</code> method should first call to a <q ref="core.lib:Global!LAYOUT_BOX">LAYOUT_BOX</q> method to resize the HTC element itself, and then call to a <code>layout</code> method of the root Box element. The second call is necessary because recursive layout calculation inside <code>LAYOUT_BOX</code> doesn't have access to element's children (e.g. to root Box) </li></ul> The following shows a skeleton of a typical heavyweight HTC which is a boxed object: <pre> <PUBLIC:COMPONENT tagname="MYTAG"> <PUBLIC:DEFAULTS viewLinkContent="true"/> <PUBLIC:PROPERTY name="box" get="getBox" put="setBox"/> <PUBLIC:PROPERTY name="hasOwnLayout" value="yes"/> <PUBLIC:METHOD name="layout"/> <HTML xmlns:stb="urn:guimachine-com:storyboard"> <HEAD> #USING[lib:Global.js] #USING[lib:Box.htc] <SCRIPT> function getBox() { return GET_BOX(element); } function setBox(val) { SET_BOX(element, val); } function layout() { LAYOUT_BOX(element); elmBox.layout(); } </SCRIPT> </HEAD> <BODY> <STB:BOX id="elmBox" box="0 0 W H"> <STB:BOX box="0 0 W 100">...</STB:BOX> <STB:BOX box="0 100 W H-100">...</STB:BOX> ... </STB:BOX> </BODY> </HTML> </PUBLIC:COMPONENT> </pre> 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 <code>ondocumentready</code> event (<code>ondocumentready</code> 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: <pre> <PUBLIC:COMPONENT tagname="OUTER"> <PUBLIC:ATTACH event="ondocumentready" onevent="init()"/> ... function init() { elmInner.layout(); } ... <BODY> <STB:BOX id="elmBox" box="0 0 W H"> <STB:INNER box="0 0 W H"/> ... </STB:BOX> </BODY> ... </PUBLIC:COMPONENT> </pre> (c) SAP AG 2003-2006. All rights reserved.

Gets or sets the bounding box of the control.

Gets or sets the control styling glyph.

Gets or sets whether the box is visible.

Hides the box.

Lays out the box and all its contained boxes.

To efficiently layout a tesselated display use a hierarchy of boxes without any intervening elements, and call this method only on the outermost box.

Shows the box.

Fires whenever the box is moved/resized.