de.winterdrache.layout
Class MSBLayout.Gap

java.lang.Object
  de.winterdrache.layout.MSBLayout.Gap

Enclosing class:

MSBLayout

public static class MSBLayout.Gap
extends Object

The Gap class contains constants that can be used as margin constraints instead of fixed pixel values to get automatic context-dependent gaps.

When using MSBLayout there are several ways to specify gaps between Components. MSBLayout.glue(int, int, int, int, int, int) offers complete control over the size and resizing behaviour of a gap. However it is tedious to manually add glues everywhere. Constraints offer a simpler alternative via the use of margins. Because they can be set once in a ConstraintsFactory and will apply to a complete class of Components, they allow you to add gaps to a dialog automatically. While you can create nice-looking dialogs with statically defined margins, there is still room for improvement. For instance it usually makes sense to have larger gaps between components that have no logical relationship and smaller gaps between components that are logically related. You may also want gaps between a container's borders and the contained components to be different from gaps between components. Sometimes it may even make sense to have the size of a gap depend on the kind of components surrounding it.

Layouting details like this are encapsulated in the LayoutStyle class. MSBLayout will use either the global LayoutStyle returned by LayoutStyle.getInstance() or the one set by MSBLayout.setLayoutStyle(LayoutStyle) to translate the constants specified in this Gap class into actual pixel values.

NOTE: Although LayoutStyle's methods require JComponents, MSBLayout uses it for plain AWT Components, too. Whenever a plain Component is involved in a gap computation it will be replaced (for purposes of calling LayoutStyle's methods) by a dummy JComponent. While this does not allow controlling the gaps based on the types of the components (e.g. Button or Checkbox), it still retains the ability to distinguish between related, unrelated and container gaps. It also means that you don't need to provide your own LayoutStyle. You will get a reasonable default spacing from the Swing LAF even when working with plain AWT.

Because all components and even hboxes and vboxes have their own Constraints, it is possible that two adjacent (or, if h/vboxes are involved, even overlapping) margins specify conflicting gaps. The following rules are used to resolve these conflicts:

• Context-independent gaps (i.e. actual pixel values) will override overlapping context-dependent gaps from enclosing h/vboxes.
• Context-independent gaps will not interact with adjacent context-dependent gaps. The margin with the context-dependent gap will get half of the pixel size for the respective type of gap. The margin with the context-independent gap will simply get its size as set.
• Context-independent gaps will never override each other (even if overlapping). They simply add up.
• UNRELATED overrides adjacent or overlapping RELATED
• WEAK_UNRELATED overrides adjacent or overlapping WEAK_RELATED
• UNRELATED and RELATED override both WEAK_UNRELATED and WEAK_RELATED
• DEFER is overridden by every other value.

Additionally you should take the following into account. You will understand these rules better if you keep in mind that LayoutStyle returns gap values either between 2 actual (J)Components or between a (J)Component and its Container and that the distinction between unrelated and related gaps is not supported for container gaps.

• For a context-dependent gap between the border of the container (or a background container added e.g. via MSBLayout.hbox(Container)) and a component, the gap's type is irrelevant. Even DEFER will cause the gap to be computed according to LayoutStyle.getContainerGap(JComponent, int, Container).
• glues are not actual components and do not support context-dependent gaps, except for container gaps. If a context-dependent gap is set on a margin of a glue, it is treated as if it were a context-independent gap of 0, unless the margin touches the Container's edge. Usually it does not make much sense to assign non-0 margins to a glue, anyway, because MSBLayout.glue(int, int, int, int, int, int) allows the creation of glues with any size.
• hboxes and vboxes can have context-dependent gaps assigned to their margins, but these will only be used to affect (according to the overriding rules) the margins of the contained components that touch the respective edges. If you have, for instance, 2 empty adjacent hboxes with context-dependent gaps set on the adjacent margins, this will not cause the creation of a gap, because there are no actual components for the gap to be between.
• An empty hbox or vbox between 2 components may prevent the formation of the proper context-dependent gap between these components. This applies even if all of the box's margins are set to DEFER. Empty hboxes/vboxes are similar to glues in this respect.
• When 2 adjacent components have context-dependent gaps set on their adjacent margins, half of the resulting gap will be assigned to each margin. If the size is odd, the 1 pixel that cannot be split will be assigned in a consistent manner (e.g. always to the left or top component). These are technical details that seldom matter.

Author:

Matthias S. Benkmann

See Also:

MSBLayout.setLayoutStyle(LayoutStyle), MSBLayout.recomputeMargins()

Field Summary

static int	DEFER Usually used only on hboxes/vboxes and means that the margin should not participate in gap computation.
static int	RELATED Specifies a gap between Components that are logically related in a dialog, such as a textfield and its label.
static int	UNRELATED Specifies a gap between Components that are not logically related in a dialog.
static int	WEAK_RELATED Like RELATED, but when a WEAK_ gap and a non-WEAK_ gap conflict, the non-WEAK_ gap overrides.
static int	WEAK_UNRELATED Like UNRELATED, but when a WEAK_ gap and a non-WEAK_ gap conflict, the non-WEAK_ gap overrides.

Method Summary

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFER

public static final int DEFER

Usually used only on hboxes/vboxes and means that the margin should not participate in gap computation. In other words, DEFER will be overridden by everything else. Numeric value -1. As a general rule smaller (i.e. "more negative") constants override larger ones.

See Also:

Constant Field Values

WEAK_RELATED

public static final int WEAK_RELATED

Like RELATED, but when a WEAK_ gap and a non-WEAK_ gap conflict, the non-WEAK_ gap overrides. Numeric value -2. As a general rule smaller (i.e. "more negative") constants override larger ones.

See Also:

Constant Field Values

WEAK_UNRELATED

public static final int WEAK_UNRELATED

Like UNRELATED, but when a WEAK_ gap and a non-WEAK_ gap conflict, the non-WEAK_ gap overrides. Numeric value -3. As a general rule smaller (i.e. "more negative") constants override larger ones.

See Also:

Constant Field Values

RELATED

public static final int RELATED

Specifies a gap between Components that are logically related in a dialog, such as a textfield and its label. Numeric value -4. As a general rule smaller (i.e. "more negative") constants override larger ones.

See Also:

Constant Field Values

UNRELATED

public static final int UNRELATED

Specifies a gap between Components that are not logically related in a dialog. Numeric value -5. As a general rule smaller (i.e. "more negative") constants override larger ones.

See Also:

Constant Field Values