WPanel BorderLayout
BorderLayout is used to arrange content in a WPanel into up to five segments based on compass points. Each WComponent added to the BorderLayout occupies one point in the layout.
NOTE that BorderLayout was originally designed as an emulation of a Java AWT or Swing BorderLayout. It has no real use-case in web applications and should not be used. If we were able to design this from scratch rather than inheriting an 11 year-old Swing-like API we would not have this layout and it is now deprecated.
- Diagram information
- Using BorderLayout
- Layout configuration
- Empty Cells
- Related Components
- Further information
In the diagrams illustrating the various settings for BorderLayout the BorderLayout content is comprised of WPanels each of which has a border; this is done to provide easy recognition of the area boundaries.
The short answer is don't use BorderLayout.
BorderLayout is a layout which was inherited from JAVA desktop UI frameworks and is rarely used even there. There are very few circumstances where a BorderLayout is intrinsically useful. The most common use case for a BorderLayout is to implement only EAST and WEST to have a line of components where some controls are left aligned and some are right such as the button collection illustrated below. Even in this use-case it is better to use a ColumnLayout.
BorderLayout is a predetermined content layout mechanism, therefore it has few options for styling. The space between the NORTH cell and following cell(s), the SOUTH cell and preceding cells(s) and between each of the WEST, CENTER and EAST cells are able to be specified.
The content of all cells in the grid is vertically aligned to the top of the cell (NORTH, SOUTH) or row of cells (WEST, CENTER, EAST).
All content is left aligned except in the EAST cell in which content is right aligned.
The hgap property specifies the horizontal space between WEST, CENTER and EAST. Half of the hgap is applied to the right of WEST and the left of EAST and to any side of CENTER adjacent to an output WEST or EAST.
The hgap is applied as described in Theme intra component spacing. The hgap class values are applied to the BorderLayout's middle row div element.
In WComponents 1.1.3 and before the hgap was applied as a number of pixels as inline CSS on every cell in the middle row. This change was made because by moving the hgap from inline CSS to a small set of class attribute values the gaps may be more easily manipulated at the application level. The use of a small set of classes also improves UI consistency and application of a standard style to a suite of applications.
The vgap property specifies the space between the NORTH cell and following cells and the SOUTH cell and preceding cells. When NORTH and SOUTH are the only cells in the BorderLayout the hgap collapses so that the space between the cells is hgap rather than 2×hgap.
The vgap is applied as described in Theme intra component spacing. The vgap class values are applied to the BorderLayout root div.
In WComponents 1.1.3 and before the vgap was applied as a number of pixels as inline CSS on the NORTH and SOUTH cells. This change was made because by moving vgap from inline CSS to a small set of class attribute values the gaps may be more easily manipulated at the application level. The use of a small set of classes also improves UI consistency and application of a standard style to a suite of applications.
A BorderLayout may contain empty cells. These cells are produced when a WComponent is added to a BorderLayout but that WComponent has no output. This may be because the WComponent has no UI consequence or because it is not yet available to the UI.
In this case the cell will be output to the UI but will be empty. If the missing cells are any (but not all) of WEST, CENTER and EAST then the width of those cells present is modified as explained in content width above.
It would be extremely unusual to specify a BorderLayout which did not contain at least two of WEST, CENTER and EAST. A BorderLayout containing zero or one of these is similar in appearance to a vertical FlowLayout but has slightly more weight in the page source and DOM tree.
BorderLayout with missing cells:
-
No NORTH
-
No SOUTH
-
No WEST
-
No CENTER
-
No WEST, CENTER or EAST
-
Only WEST and EAST
