WPanel Type CHROME
WPanel of Type.CHROMEis a special use WPanel and is being phased out in favour of WSection. It is strongly recommended that this Type of WPanel is no longer used.
Throughout this document a WPanel with the Type of CHROME is referred to as a CHROME panel.
Note: for almost all purposes it is better to use WSection than WPanel Type.CHROME.
The CHROME panel is used to delineate a major section of an application and is interchangeable with WSection. In most cases it is more appropriate to use a WSection.
The CHROME panel is sectioning content. It restarts the document tree and provides a section for assistive technologies. In this case the panel title is exposed as a heading and is a h1 element. This is done to make it easier to determine WHeading and WCollapsible HeadingLevel settings for parts of a complex UI where units of the UI are developed in isolation or reused.
CHROME panels should not be used as generic containers or as a replacement for WFieldSet to group form controls. In cases where the content consists of a semantically related group of label:input pairs a WFieldSet should be used to group the content.
CHROME panels and WSections may be nested to any depth but it is recommended that a screen have no more than three levels of these combined components.
The CHROME WPanel is a decorated panel which exposes a title. This is the only documentation of the appearance of WPanel Type.CHROME ever provided in the Java API. There is no indication of what this decoration is in the JAVA documentation because it is entirely in the remit of the theme. Illustrated below is a default theme implementation from version 1.2.6.
The heading of a CHROME panel is set from the WPanel's title and is a simple String. The heading cannot contain any other components and should not contain HTML. If other components are required in the heading then a WSection must be used.
The panel heading should provide an appropriate and meaningful title for the content of the WPanel and must be explicitly specified for each CHROME panel in a UI. The title property is mandatory for a CHROME panel. If a CHROME panel does not have a panel title it will still have a placeholder for the title. That placeholder is determined by the theme and will never be the title you want your panel to have.
Under some circumstances a WMenu of MenuType.BAR may be positioned so that it appears to be "docked" to the panel.
For more details see WMenu - docking menu bars.
If a WHeading or WCollapsible (with its HeadingLevel set) is placed into the WPanel it should have a HeadingLevel set appropriately. The highest level of heading must use HeadingLevel.H2. The WPanel title produces a h1 element which provides the context for the h2.