Positioning Portals Within Templates
[Context: HL Kit … Basic Concepts and Terminology … Manipulation of Visual Elements]
Overview
Due to the way the Kit is designed, the single most common thing you will find yourself doing with visual elements is positioning portals within templates. To better streamline development, the Kit has a number of special optimizations that can be used to efficiently position portals within templates. The topics below discuss some of these shortcuts.
IMPORTANT! The various target references described below are only usable on portals within templates. If you attempt to use them on portals within layouts (e.g. tables and choosers), they will not work.
Automatic Sizing
The HL engine includes logic that will intelligently determine the dimensions of portals. For example, a label portal will have its size calculated to match the text its contains, an image portal will be sized to match the image it contains, etc. If an appropriate default size cannot be determined, then something safe is used instead.
This mechanism is referred to as automatic sizing and is accessible at any time via scripts. In addition, you can trigger the default sizing logic to be applied to only a single dimension instead of both width and height. As an example, if you change the style of a portal and thereby change the font size used, you will need to re-size the portal based on the new style. Using the automatic sizing logic is a quick and easy way to handle it.
Default Sizing
At the beginning of the visual positioning logic, every portal is assigned an appropriate default size. This is achieved by determining the automatic sizing characteristics for the portal, as described above. As a result of this default sizing, you often don't have to worry about setting the dimensions of portals and can simply focus on positioning them.
Size of Contents
For text portals especially, but sometimes for other portals, you will want to explicitly retrieve facets of their contents. There are three different types of sizing information that can be retrieved. The first is the "text width", which retrieves the width necessary to contain the full text on a single line. The second is the "font height", which retrieves the height of a single line of text, based on the font characteristics established by the current style assigned to the portal. The third is the "text height", which calculates the number of lines of text needed to display all of the text contents and the full vertical extent of that text.
The "alignedge" Target Reference
When positioning portals, a few will be positioned based on the edge of the template, with the rest being positioned relative to the other portals. When you need to position a portal relative to an edge of the template, you can use the "alignedge" target reference. You identify the portal, the edge (left, top, right, bottom), and the offset to use. The offset makes it easy to leave gaps from the edge if you need them.
The "alignrel" Target Reference
Once you've positioned the initial portals relative to the edges of the template, it's now time to start positioning portals relative to each other. To simplify this process, the "alignrel" target reference is provided. You start with the portal to be positioned and then specify the portal to position relative to. You then add the positioning relationship to be used and any offset to be inserted. The positioning relationship identifies both the edge of the portal being placed and the edge of the reference portal, and any combination is allowed. For example, a "left to right" relationship means that the left edge of the portal being placed is positioned relative to the right edge of the reference portal. If an offset of 10 is given, then the portal would be placed 10 pixels to the right of the reference portal.
The "centerhorz" and "centervert" Target References
You will quite often need to center portals along one axis within the template. To accomplish this, all you need to do is invoke the "centerhorz" or "centervert" target reference on the appropriate portals. The HL engine will calculate the relative dimensions and properly position the portal to be centered along the specified axis.
The "centeron" Target Reference
There are times when you need to center multiple portals along a common central axis. In a situation like this, you must first position one portal where it needs to be. After that, you can position the remaining portals relative to the original portal by using the "centeron" target reference. The HL engine will calculate the center line for both portals and position the new portal appropriately.
The "centerpoint" Target Reference
When setting up columnar tables, you will sometimes want to center data within columns. There are two ways of handling this. First, you can configure each portal to center its contents within itself and then set the width of each portal to match the column width being used. The drawback to this is that the default sizing logic will set each portal to an appropriate width based on its contents, and that means that you'll need to reset the width of every portal and position it properly.
The alternative is to calculate the center position of the column. Once you have that, you can simply use the "centerpoint" target reference to position each portal. The HL engine will determine the width/height of the portal and position it so that it is centered on the point specified.
