Using Automatic Placement

[Context: HL Kit … Basic Concepts and Terminology … Manipulation of Visual Elements]

In an effort to make things as easy as possible, the Kit provides a mechanism called "automatic placement" that makes positioning certain visual elements significantly easier. Although primarily intended for use within sheets, automatic placement can also be used in various places with on-screen visual elements.

Automatic placement can only be used on visual elements within layouts, panels, and sheets. Every one of these element types manages internal logic to support automatic placement, so you can use the mechanism whenever it suits your needs. Automatic placement assumes that you are placing a progression of visual elements in a vertical arrangement, with each successive element appearing beneath the previous element.

All placement is performed within a rectangular region. Before anything is placed, the bounds of this region are initialized to be the full height and width of the visual container (i.e. the layout, panel, or sheet). When placement begins, each new placement consumes vertical space within the region. This automatically shrinks the region, moving the top of the region downward to the bottom of each new visual element that is placed.

Automatic placement is performed via the "autoplace" target reference. Each placement can specify a gap that should appear between the new element and the one previously placed. Additional target references provide the author with complete control over the bounds of the region within which automatic placement is performed. This makes it possible to place specific elements at the top and/or bottom of the visual container, then adjust the automatic placement region accordingly, and finally perform automatic placement of the remaining visual elements. You can also place elements automatically and then retrieve the bounds of the remaining unused space, in which you can manually place visual elements.

In general, automatic placement is very easy to use and very intuitive in how it handles various situations. However, in the interest of clarity, the following are the specific rules that govern how automatic placement behaves.

1. When an element is automatically placed, the width of that element is set to the width of the automatic placement region for the visual container. In other words, each element is sized to take up the full width of the container.
2. When a layout or template is automatically placed, that element is immediately rendered upon completion. This ensures that the sizing of that element is updated so that the top of the region can be accurately moved to the bottom of the element.
3. When automatically placed, most visual elements have their height set to the full remaining height of the automatic placement region. The following caveats apply:
   1. The lone exception to this rule is when a non-table portal is automatically placed within a layout (e.g. a label). In such cases, the height of the portal is assumed to be whatever default height is initialized.
   2. Since the height is set to the full region during automatic placement, it is assumed that every visual element being placed will properly truncate its height as part of its rendering. For example, a template placed within a layout or a layout placed within a sheet must properly set its height at the end of the Position script, basing the height on the extent of the bottommost item within the element.
   3. Table portals automatically determine their extent, so automatic placement of tables works smoothly, without the need for any special handling.

Until at least one visual element with actual contents is successfully placed within the container, the gap is always considered to be zero. This ensures that the first item actually placed in the container always starts at the top, regardless of how many elements render no contents.

   -When automatic placement attempt to place a visual element that will not
       fully fit in the remaining space, the region is considered to be fully
       utilized and no further elements can be placed
   -If a table is placed and it does not fully fit in the remaining space, as
       many items as will fit are output, with all remaining items being treated
       as "spillover" for rendering in subsequent tables
   -Any visual element that is not displayed at all is designated as non-visible
       -Tables that contain zero items are non-visible
       -Templates and layout that do not fully fit are non-visible