Theme intra component spacing

• Spacing in the Java API
• Spacing in a WComponents theme
  • Theme development
• Further information

Many WComponents create structures which create many HTML elements. Others are layout components which allow simple layouts to be created in Java. In both of these cases there are rules for separating HTML elements or content components within the structure.

See Margin for information about inter-component spacing.

Spacing in the Java API

Some components allow the space between content components to be specified within the application. This is normally done using properties gap (where only one of a vertical or horizontal space is appropriate), hgap (for horizontal spacing) and vgap (for vertical spacing).

The support for gap, hgap and vgap is as follows:

• WList applies gap as hgap if its type property is FLAT otherwise vgap;
• WPanel BorderLayout has support for both hgap and vgap;
• WPanel ColumnLayout has support for both hgap and vgap;
• WPanel FlowLayout applies gap as vgap if its align property is VERTICAL otherwise hgap;
• WPanel ListLayout applies gap as hgap if its type property is FLAT otherwise vgap;
• WRow support gap as hgap.

The gaps are set using a value of the Size enum.

Spacing in a WComponents theme

Some compound components which are not containers (for example WCheckBoxSelect) have spacing between components. This is an instrinsic part of the theme and should be created to meet the design standards for the applications being built using that theme. A typical example of this is the space between WFields within a WFieldLayout. It is strongly recommended that individual consuming applications do not change these spaces: they are there for a reason. Containers are usually Marginable so may have space put around them.

Theme development

The spaces internal to the default theme are set in a set of Sass variables (see Size for more information). The easiest and most consistent manner to change spaces is to change the value of one or more of these variables. It is suggested one ought avoid specifying an explicit space size within a component's Sass but there is nothing to stop one doing this.

The gap/hgap/vgap is applied as follows:

1. If gap, hgap or vgap (as appropriate) is not set then there will be no space between components. This may be overridden within a theme but default spacing is usually better determined on a case-by-case basis.
2. An arbitrary but coherent theme-determined value for each Size is set using Sass variables (see Size for more information).
3. Each of the gap types is indicated as a class name on the parent element of the items to be spaced. In a ColumnLayout, for example, vgap class names are applied to the ColumnLayout root as these apply to the rows in the layout whereas the hgap class is applied to the rows in the ColumnLayout as the hgap applies to the columns. This allows nested layouts without CSS selector cascade issues.
4. The CSS then uses these class names to set a coherent and consistent gap based on the applied design standards.

The class attribute values for hgap are (from small to large):

• wc-hgap-z (explicitly zero a default gap)
• wc-hgap-sm
• wc-hgap-med
• wc-hgap-lg
• wc-hgap-xl

The class attribute values for vgap are (from small to large):

• wc-vgap-z (explicitly zero a default gap)
• wc-vgap-sm
• wc-vgap-med
• wc-vgap-lg
• wc-vgap-xl

Further information

• Margin
• Size
• Creating a theme
• List of WComponents