How Visual Elements Behave

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

Overview

Visual elements share a number of behaviors that are common across most, if not all, different visual types. These common behaviors are discussed in the topics below.

Rectangular Region

Every visual element represents a rectangular region, whether it be on the screen or on the printed page. As such, each element possesses both dimensions and a position. The dimensions are a simple width and height. The position is given as the location of the top left corner of the visual element within its containing visual element.

The position is always relative to the containing element and consists of two values. It represents a number of pixels along the X axis and a number of pixels along the Y axis. Values along the X axis increase as you move from the left to the right. Values along the Y axis increase as you move from the top to the bottom. By convention, a position always lists the adjustment along the X axis first, so a position of (7,42) indicates 7 pixels to the right along the X axis and 42 pixels down along the Y axis.

As an example, consider a portal that is placed at position of (10,0) within a template. Then the template is placed at a position of (5,0) within a layout. The layout is placed at a position of (2,0) within a panel. Putting it all together yields an effective position of (17,0) for the portal within the panel.

When modifying the rectangular region for a visual element, there are two different ways to accomplish it, and each yields different results. The first method is to set the width and/or height for the element. This keeps the top left position anchored in place and merely moves the bottom right position. The alternative is to directly modify the right and/or bottom edges of the rectangle, which implicitly changes the dimensions assigned to the visual element.

Margins

All visual elements that can contain other elements possess margins. The margin is a gap that is maintained between the outer edges of the visual element and the interior region where child elements are positioned. A vertical margin is maintained separately from any horizontal margin, and both default to zero.

For the purposes of placing child elements within a visual container, the zero position is equal to any margin value. Normally, when placing a portal at a position of 5 within a template, the portal appears at the position of 5. However, if the template has a margin of 3, that gets added to the specified position. This yields an effective position of 8 for the portal within the template.

Margins accumulate at every level within the hierarchy. Let's return to the example used in the previous topic about a portal within a template within a layout within a panel. If each of the visual contains has a margin of 3, then each successive child element is shifted 3 pixels further to adjust for the margin. This yields an effective position of 26 for the portal within the panel.

Visibility

Every visual element has a visibility state, which can either be visible or hidden. By default, all visual elements start out as visible. However, you can set the visibility dynamically within any script that positions a portal. If a visual element is designated as hidden (i.e. not visible), then all visual elements within that element are hidden as well. This continues down through the hierarchy. Consequently, setting a layout to non-visible implicitly hides all templates and portals within the layout, plus it also hides all portals within the now-hidden templates.

There will be many places where you will want to control the visibility of visual elements.