Window parenting and positioning

The window type determines what positioning rules are applied to a child window once the window joins a group. A window's type also determines whether or not it can parent another window.

The following window properties are relative to the parent window:

A child window is visible only when the associated parent window is visible.
The z-order of a child window is relative to the parent window. For example, a positive value will place the child on top of (or above) its associated parent window. Conversely, a negative z-order puts the child window underneath the parent window.
The position of the child window is relative to the position of the parent. Any translation of the parent also affects the child.
The size of the child is relative to the parent. Any scaling applied to the parent is also applied to the child.
The global alpha of a child window is combined with the global alpha of the parent.

Application windows

An application window is positioned according to absolute screen coordinates. Therefore, an application window cannot be the parent of another application window. An application window is implicitly part of a group that is owned by the window manager if the application window has registered with Screen.

Child windows

A child window is not visible until it has become the child of an application window. It does so by using the function, screen_join_window_group() to join the window group created by its parent application window.

Embedded windows

An embedded window can join a window group whose parent is an application window or a child window. An embedded window behaves like child window except that it is clipped to the parent window's destination rectangle.

The embedded window type provides the illusion that the contents of both the parent and child window represent a single logical view. When you scroll, the view of the content in the parent window and the position of the embedded window are updated synchronously.

When you zoom in the parent window, the embedded window will change size and be repositioned independently, without the need for the parent to update the embedded window. Thus, the position and size of embedded windows are relative to the source rectangle and the virtual viewport of the associated parent window.

When you pan the source rectangle of the parent window within a larger buffer, the position of any embedded window will be updated automatically. Alternatively, an application can move a virtual viewport instead of the source rectangle and achieve the same effect without requiring a window buffer that is larger than the source size.

All of these rules were created to abstract window managers and group parents from the underlying window hierarchy. The window manager can move, fade, or scale a window, and the results will be the same whether the window is a single window or a more complex hierarchy of several windows.