Using Batch Placement

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

Overview

When more than one table is present in a layout, fitting all the tables into the available space can be very challenging, and the code to do it is messy and repetitious. Like automatic placement for printed content, the "batch placement" mechanism exists to simplify the positioning of those tables.

Batch placement can only be used on visual elements within layouts. Each of these element types manages internal logic to support batch placement, so you can use the mechanism whenever it suits your needs. Batch placement assumes that you are placing a progression of visual elements in a vertical arrangement, with each successive element appearing beneath the previous element. If you need a more complicated arrangement, for example one using multiple columns, it's likely easiest to split the content up into one layout for each column.

How It Works

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 or scene). The list of elements for placement is built, and once finalized, the elements are placed all at once to most efficiently use the space in the area.

Addition of individual elements is performed via the "batchadd" target reference. Each placement can specify a gap that should appear between the new element and the one previously placed, which enables appropriate spacing between visual elements. Once all elements are added, the "batchplace" target reference is used to trigger automatic positioning of the elements.

As with automatic placement, 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 batch placement of the remaining visual elements. You can also place elements automatically and then retrieve the bounds of the remaining unused space, after which you can manually place visual elements in that space.

The Rules

Like automatic placement, batch placement is very easy to use and very intuitive in how it handles various situations. However, in the interest of clarity, the following specific rules 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 the batch is being processed, each portal or template is immediately rendered upon completion. This ensures that the sizing of that element is updated so that the correct amount of space is used.
3. When batch placed, visual elements have their height set to the maximum value possible without unfairly starving any element of height, and without exceeding the space available. The following caveats apply:
   1. When a non-table portal is batch placed within a layout (e.g. a label), it will always use exactly as much space as it needs, and will never be shrunk.
   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 batch placement of tables works smoothly, without the need for any special handling.
4. Tables will never be shrunk so far that they become unusable. There will always be enough height reserved for each table to display a usable scroller thumb, if it has more than one element.
5. If there are too many elements to fit in the available space, the space needed is automatically extended to the minimum size needed. You can find out how far it extended by checking the "autobottom" target.
6. If a table is placed and it does not fully fit in the remaining space, as many items as will fit are output.
7. Any non-visible element is not considered for placement.
8. Until at least one visual element with actual contents is successfully placed within the region, 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.