Gaia Depth Management
From Gaia Framework Wiki
Contents |
Introduction To Gaia's Depth Management
Gaia uses an easy depth management system for managing the z-indexing of pages and visual assets. Its 3-tiered system provides a simple way to manage depths for nearly all use cases, and can be easily customized and/or bypassed for precision depth management.
Primary Depth Containers
The three primary depths are top, middle and bottom.
By default, all pages and assets are loaded into the middle depth, with the exception of index, which is loaded into the bottom depth by default. Assets automatically inherit their page's depth unless you specify otherwise.
If pages and assets are set to load in the same depth container, they will be stacked in the order they are loaded in the site.xml branch.
Top
The top depth is the top-most container in the display stack.
Middle
The middle depth is below top and above bottom.
Bottom
The bottom depth is the bottom-most container in the display stack.
Targeting Depth Containers
To target the depth containers, use the API method getDepthContainer().
Special Depth Containers
The preloader depth is used for preloaders and is settable in the site.xml. In AS3, there is a special nested depth.
Preloader
The preloader depth is a dynamically settable attribute in the <site> node in the site.xml. Its z-position is one level above whatever the preloaderDepth container it is set to. By default, it is set to top so it is above the top container. If you set the preloaderDepth to middle, it will be below top and above middle. If you set the preloaderDepth to bottom, it will be below middle and above bottom.
Nested (AS3 only)
The nested depth is a special depth. If you use the nested depth, the page or asset will be put inside of its parent page in the site.xml. This means that your nested pages and assets will move, scale, mask and otherwise be affected by properties of the parent page, including visible, alpha, etc.
By default, assets automatically inherit their page's depth container, so if an asset's page has its depth="nested", so will the asset, meaning it will load into the page's content clip. If you want an asset of a nested page to load into one of Gaia's depth containers, you will need to explicitly set its depth to one of the four containers.
Customized Depth Management
You can manage depths manually with Actionscript either within the constraints of Gaia's depth containers or not. Gaia's depth management system provides a simple foundation from which you can expand on.
If you want to bypass Gaia's depth management altogether, don't set the depth of any pages or assets and they will all load into the middle container, giving you complete freedom.
