Class LayoutManager

Defines the base class for Layout Managers.

Inheritance

System.Object

LayoutManager

Implements

System.ComponentModel.IExtenderProvider

ILayoutManager

System.ComponentModel.ISupportInitialize

Namespace: Syncfusion.Windows.Forms.Tools

Assembly: Syncfusion.Shared.Base.dll

Syntax

public abstract class LayoutManager : Component, IExtenderProvider, ILayoutManager, ISupportInitialize

Remarks

The FlowLayout, CardLayout, GridLayout, and GridBagLayout classes derive from this base class.

Use one of the above classes to include layout management support in your forms / controls.

The layout manager can be configured to operate in different modes.

By default, AutoLayout mode layout will be automatically triggered when the ContainerControl fires a System.Windows.Forms.Control.Layout event. If not in this mode, then you can call the LayoutContainer() method to trigger a layout.

By default, the ContainerControl's ClientRectangle will be used as the bounds for the layout. But, if the CustomLayoutBounds property is set to a value other than Rectangle.Empty then that rectangle area will be used as the layout bounds.

You can also lay out non-control based components as long as they derive from the LayoutItemBase class. The LayoutItemBase derived object can be used in any method call that expects a control instance because the LayoutItemBase has an implicit type-conversion operator that can convert itself to a control (use the ToControl() method in VB).

You can also specify / provide preferred and minimum sizes for the child components. The default layout logic uses the component's preferred size to lay them out. The LayoutManager also has the MinimumLayoutSize() and PreferredLayoutSize() methods that will let you query for the corresponding sizes.

There are different ways in which you can provide the preferred and minimum sizes for a component. The manager will first look for the IProvideLayoutInformation interface in your child component, which if found, will be used to obtain the sizes. Second, the manager will throw a ProvideLayoutInformation event for a specific child component, which if handled will then be used to obtain the sizes, if provided. Third, the sizes provided using the SetPreferredSize(Control, Size) / SetMinimumSize(Control, Size) method will be used to obtain the sizes. However if SetPreferredSize / SetMinimumSize was never called, the framework will call them with the current size of the component as the preferred / minimum size.

Take a look at the LayoutItemBase class documentation for sample code on how to create non-control based classes that can participate in Layout management.

Constructors

LayoutManager()

Constructor to be called by derived classes.

Declaration

protected LayoutManager()

Fields

initializing

Declaration

protected bool initializing

Field Value

Type
System.Boolean

minimumSizes

Declaration

protected Hashtable minimumSizes

Field Value

Type
System.Collections.Hashtable

preferredSizes

Declaration

protected Hashtable preferredSizes

Field Value

Type
System.Collections.Hashtable

Properties

AutoLayout

Indicates whether the manager should lay out automatically on Layout event.

Declaration

public bool AutoLayout { get; set; }

Property Value

Type	Description
System.Boolean	True indicates auto layout; False otherwise. Default is True.

Remarks

If True, the manager will listen to the ContainerControl control's Layout event and perform layout automatically. If False, you should call the manager's LayoutContainer() method to trigger layout.

BottomMargin

Gets or sets the bottom margin between the client rectangle and the layout rectangle.

Declaration

public int BottomMargin { get; set; }

Property Value

Type	Description
System.Int32	An integer value in pixels. Default is 4 pixels.

ComponentDesigner

Gets or sets the component designer.

Declaration

public IDesigner ComponentDesigner { get; set; }

Property Value

Type
System.ComponentModel.Design.IDesigner

ContainerControl

Gets or sets the container control that this manager will lay out.

Declaration

public Control ContainerControl { get; set; }

Property Value

Type	Description
System.Windows.Forms.Control	A control object.

Remarks

Changing this property will raise the ContainerControlChanged event.

CustomLayoutBounds

Gets or sets the custom layout bounds, if any, to be used for layout calculation instead of the container control's ClientRectangle.

Declaration

public Rectangle CustomLayoutBounds { get; set; }

Property Value

Type	Description
System.Drawing.Rectangle	A Rectangle specifying the custom bounds. Default is Rectangle.Empty.

Remarks

If this value is Rectangle.Empty, then the manager will use the container control's ClientRectangle. If other than Rectangle.Empty, then that value will be used.

When using CustomLayoutBounds, you might have to disable AutoLayout in most cases and instead manually reset CustomLayoutBounds and call LayoutContainer() in the container control's Layout event handler.

DesignerHost

Gets or sets the designer host.

Declaration

public IDesignerHost DesignerHost { get; set; }

Property Value

Type
System.ComponentModel.Design.IDesignerHost

DesignerInTransaction

Declaration

protected bool DesignerInTransaction { get; }

Property Value

Type
System.Boolean

HorzFarMargin

Gets or sets the right margin between the client rectangle and the layout rectangle.

Declaration

public int HorzFarMargin { get; set; }

Property Value

Type	Description
System.Int32	An integer value in pixels. Default is 4 pixels.

HorzNearMargin

Gets or sets the left margin between the client rectangle and the layout rectangle.

Declaration

public int HorzNearMargin { get; set; }

Property Value

Type	Description
System.Int32	An integer value in pixels. Default is 4 pixels.

LayoutControls

Returns the list of child components participating in layout.

Declaration

public ArrayList LayoutControls { get; }

Property Value

Type	Description
System.Collections.ArrayList	An ArrayList containing the child components.

Remarks

There are very specific cases when you have to access this list.

You should access this list to modify the position of the children in the child components list only when UseControlCollectionPosition property is False and you are laying out both control-based and LayoutItemBase-based components in the manager. Take a look at the UseControlCollectionPosition property documentation for information on this issue.

However, you should only use this property to change the position of child components, but never to effectively add or remove components (use the methods provided by the respective managers).

LeftMargin

This method has been replaced by HorzNearMargin. Please use that instead.

Declaration

[Obsolete("This method has been replaced by HorzNearMargin. Please use that instead.")]
public int LeftMargin { get; set; }

Property Value

Type
System.Int32

LoadingDocument

Declaration

protected bool LoadingDocument { get; }

Property Value

Type
System.Boolean

RightMargin

This method has been replaced by HorzFarMargin. Please use that instead.

Declaration

[Obsolete("This method has been replaced by HorzFarMargin. Please use that instead.")]
public int RightMargin { get; set; }

Property Value

Type
System.Int32

TopMargin

Gets or sets the top margin between the client rectangle and the layout rectangle.

Declaration

public int TopMargin { get; set; }

Property Value

Type	Description
System.Int32	An integer value in pixels. Default is 4 pixels.

UseControlCollectionPosition

Indicates whether the container control's System.Windows.Forms.Control.ControlCollection should be used as the order for laying out the child controls.

Declaration

public bool UseControlCollectionPosition { get; set; }

Property Value

Type	Description
System.Boolean	True to use the ControlCollection order; False to use the order in which the child components were added to the manager. Default value is true.

Remarks

This property matters only when the corresponding layout manager relies on the order of children in the child list in its layout logic. The FlowLayout, CardLayout and the GridLayout managers rely on the order, while the GridBagLayout managers do not.

Note that if you have both control-based and LayoutItemBase-based child components participating in the layout and this property is True, then the LayoutItemBase based child components will always be at the bottom of the list when layout is performed. In this case, if you want more control on the child order, set this property to False and use the LayoutControls list to modify the exisiting order.

Methods

AddLayoutComponent(Control, Object)

Adds a child component to the layout list with the specified constraints.

Declaration

public virtual void AddLayoutComponent(Control childControl, object constraints)

Parameters

Type	Name	Description
System.Windows.Forms.Control	childControl	The control to add to the list.
System.Object	constraints	The associated constraints.

Remarks

The type of constraints to be passed varies based on the layout manager. The CardLayout for example expects a string type while the GridBagLayout expects a GridBagConstraints type. The FlowLayout and the GridLayout do not expect anything which means you can specify NULL. Take a look at the individual layout manager's documentation for the type of constraints expected. The individual managers also provide custom type safe methods to let you specify the appropriate constraints.

You can also pass a LayoutItemBase derived class as the first argument because it has an implicit type-conversion operator that will provide its corresponding control object (a place-holder control that allows the LayoutItemBase to seamlessly participate in the layout framework). In VB, use the ToControl() method.

AdjustHeightForMargins(Int32)

Declaration

protected int AdjustHeightForMargins(int height)

Parameters

Type	Name	Description
System.Int32	height

Returns

Type
System.Int32

AdjustWidthForMargins(Int32)

Declaration

protected int AdjustWidthForMargins(int width)

Parameters

Type	Name	Description
System.Int32	width

Returns

Type
System.Int32

BeginInit()

Starts designer initialization.

Declaration

public virtual void BeginInit()

CanExtend(Object)

Declaration

protected virtual bool CanExtend(object target)

Parameters

Type	Name	Description
System.Object	target

Returns

Type
System.Boolean

Dispose(Boolean)

Declaration

protected override void Dispose(bool disposing)

Parameters

Type	Name	Description
System.Boolean	disposing

EndInit()

Ends designer initialization.

Declaration

public virtual void EndInit()

ForcePreferredAndMinimumsSize()

Makes the current sizes of the child controls their minimum and preferred sizes.

Declaration

protected void ForcePreferredAndMinimumsSize()

GetAutoLabel(Control)

Declaration

protected AutoLabel GetAutoLabel(Control c)

Parameters

Type	Name	Description
System.Windows.Forms.Control	c

Returns

Type
AutoLabel

GetBounds()

Returns the layout bounds within which to perform layout.

Declaration

protected virtual Rectangle GetBounds()

Returns

Type	Description
System.Drawing.Rectangle	The Rectangle specifying the layout bounds.

Remarks

This takes into account the CustomLayoutBounds value, if not empty. If empty, the bounds are calculated based on the Container Control's ClientRectangle and the margins specified.

GetControls()

Returns the child components that participate in the layout.

Declaration

public virtual IList GetControls()

Returns

Type	Description
System.Collections.IList	The child control list.

Remarks

The order of child controls in the returned list will take into account the UseControlCollectionPosition property value.

GetDynamicSize(Control, LayoutInformationType, ref Size)

Returns the dynamic preferred or minimum size of a child component.

Declaration

protected virtual bool GetDynamicSize(Control control, LayoutInformationType type, ref Size size)

Parameters

Type	Name	Description
System.Windows.Forms.Control	control	The child control.
LayoutInformationType	type	The type of size required, preferred or minimum.
System.Drawing.Size	size	A reference value through which the size should be returned to the caller.

Returns

Type	Description
System.Boolean	True to indicate a dynamic size was found and that the size argument has a valid value. False otherwise.

Remarks

This function will first check if the child control has an IProvideLayoutInformation interface and if so returns the size provided by that interface. If not, it throws a ProvideLayoutInformation to obtain the dynamic size. The handlers, if any, for that event may provide the dynamic size which will be returned.

If none of the above cases succeeds then False will be returned.

GetMinimumSize(Control)

Retrieves the minimum size associated with the specified control.

Declaration

public virtual Size GetMinimumSize(Control control)

Parameters

Type	Name	Description
System.Windows.Forms.Control	control	The control for which to retrieve the minimum size.

Returns

Type	Description
System.Drawing.Size	The minimum size for the specified control.

Remarks

Take a look at the LayoutManager class documentation for information on the different ways in which the manager obtains and you can specify the preferred and minimum size information for a child component.

GetPreferredSize(Control)

Retrieves the preferred size associated with the specified control.

Declaration

public virtual Size GetPreferredSize(Control control)

Parameters

Type	Name	Description
System.Windows.Forms.Control	control	The control for which to retrieve the preferred size.

Returns

Type	Description
System.Drawing.Size	The preferred size for the specified control.

Remarks

GetStaticMinimumSize(Control)

Returns the minimum size provided with a call to SetMinimumSize.

Declaration

protected virtual Size GetStaticMinimumSize(Control control)

Parameters

Type	Name	Description
System.Windows.Forms.Control	control	The control whose minimum size is to be known.

Returns

Type	Description
System.Drawing.Size	The size, if any provided, or the current control size.

Remarks

Unlike GetMinimumSize, this does not throw an event or look for IProvideLayoutInformation in the child controls.

Calling this will in turn call SetMinimumSize with the current control size, if there is no size available.

GetStaticPreferredSize(Control)

Returns the preferred size provided with a call to SetPreferredSize.

Declaration

protected virtual Size GetStaticPreferredSize(Control control)

Parameters

Type	Name	Description
System.Windows.Forms.Control	control	The control whose preferred size is to be known.

Returns

Type	Description
System.Drawing.Size	The size, if any, provided or the current control size.

Remarks

Unlike GetPreferredSize, this does not throw an event or look for IProvideLayoutInformation in the child controls.

Calling this will in turn call SetPreferredSize with the current control size, if there is no size available.

IsInit()

Indicates whether the layout manager is in a state where it can start laying out components.

Declaration

protected virtual bool IsInit()

Returns

Type	Description
System.Boolean	True indicates its ready for layout; False otherwise.

Remarks

This will return True if it has a valid ContainerControl and at least one child component to be laid out. If you override this method, make sure to call the base class.

IsVisible(Control)

Indicates the Visible state of the child control or LayoutItemBase.

Declaration

protected bool IsVisible(Control control)

Parameters

Type	Name	Description
System.Windows.Forms.Control	control	The control whose visibility is to be determined.

Returns

Type	Description
System.Boolean	The visibility state.

Remarks

Use this instead of checking the Visible property of the control directly, because if this control is a place-holder control for a LayoutItemBase, the Visibility state will be stored elsewhere.

LayoutContainer()

Triggers a layout of the child components.

Declaration

public abstract void LayoutContainer()

Remarks

Use this when you want to manually trigger a layout. This will automatically be called by the framework when AutoLayout is True and a Layout event occurs on the ContainerControl.

MakeDirty()

Declaration

protected void MakeDirty()

MinimumLayoutSize()

Returns the minimum size for the ContainerControl.

Declaration

public abstract Size MinimumLayoutSize()

Returns

Type	Description
System.Drawing.Size	A size value representing the minimum size required.

Remarks

This value is calculated based on the minimum size requirement for the child controls.

OnContainerControlChanged(EventArgs)

Raises the ContainerControlChanged event.

Declaration

protected virtual void OnContainerControlChanged(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	An EventArgs that contains the event data.

Remarks

The OnContainerControlChanged method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

Note to Inheritors: When overriding OnContainerControlChanged in a derived class, be sure to call the base class's OnContainerControlChanged method so that registered delegates receive the event.

OnControlAdded(Object, ControlEventArgs)

The handler for the container's ControlAdded event.

Declaration

protected virtual void OnControlAdded(object sender, ControlEventArgs e)

Parameters

Type	Name	Description
System.Object	sender	The container into which a control was added.
System.Windows.Forms.ControlEventArgs	e	An ControlEventArgs that contains the event data.

Remarks

This is an easy way for the derived classes to know when a child gets added to the ContainerControl.

OnControlRemoved(Object, ControlEventArgs)

The handler for the container's ControlRemoved event.

Declaration

protected virtual void OnControlRemoved(object sender, ControlEventArgs e)

Parameters

Type	Name	Description
System.Object	sender	The container into which a control was added.
System.Windows.Forms.ControlEventArgs	e	An ControlEventArgs that contains the event data.

Remarks

This is an easy way for the derived classes to know when a child gets removed from the ContainerControl.

OnDockStyleChanged(Object, EventArgs)

Declaration

protected virtual void OnDockStyleChanged(object sender, EventArgs e)

Parameters

Type	Name	Description
System.Object	sender
System.EventArgs	e

OnProvideLayoutInformation(ProvideLayoutInformationEventArgs)

Raises the ProvideLayoutInformation event.

Declaration

protected virtual void OnProvideLayoutInformation(ProvideLayoutInformationEventArgs args)

Parameters

Type	Name	Description
ProvideLayoutInformationEventArgs	args	A ProvideLayoutInformationEventArgs that contains the event data.

Remarks

The OnProvideLayoutInformation method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

Note to Inheritors: When overriding OnProvideLayoutInformation in a derived class, be sure to call the base class's OnProvideLayoutInformation method so that registered delegates receive the event.

PreferredLayoutSize()

Returns the preferred size for the ContainerControl.

Declaration

public abstract Size PreferredLayoutSize()

Returns

Type	Description
System.Drawing.Size	A size value representing the preferred size.

Remarks

This value is calculated based on the preferred size requirement for the child controls.

RemoveLayoutComponent(Control)

Removes a child component from the layout list.

Declaration

public virtual void RemoveLayoutComponent(Control childControl)

Parameters

Type	Name	Description
System.Windows.Forms.Control	childControl	The control to be removed.

Remarks

You can also pass a LayoutItemBase derived class as the first argument because it has an implicit type-conversion operator that will provide its corresponding control object (a place-holder control that allows the LayoutItemBase to participate in the layout framework seemlessly). In VB, use the LayoutItemBase.ToControl method.

ResetCustomLayoutBounds()

Sets the CustomLayoutBounds property to Rectangle.Empty.

Declaration

protected virtual void ResetCustomLayoutBounds()

ResetLayoutInfo()

Removes any references to the container control and handlers for events in that control. Will also remove references to the child control.

Declaration

protected virtual void ResetLayoutInfo()

Remarks

Will be called when the user sets the ContainerControl to NULL and from Dispose. Make sure to call the base class to perform normal operations when you override this method.

ResetMinimumSize(Control)

Removes any custom minimum size set for the specified control.

Declaration

public virtual void ResetMinimumSize(Control control)

Parameters

Type	Name	Description
System.Windows.Forms.Control	control

ResetPreferredSize(Control)

Removes any custom preferred size set for the specified control.

Declaration

public virtual void ResetPreferredSize(Control control)

Parameters

Type	Name	Description
System.Windows.Forms.Control	control

SetMinimumSize(Control, Size)

Associates a minimum size with the specified control.

Declaration

public virtual void SetMinimumSize(Control control, Size value)

Parameters

Type	Name	Description
System.Windows.Forms.Control	control	The control to associate the minimum size with.
System.Drawing.Size	value	The minimum size of the control.

Remarks

Take a look at the LayoutManager class documentation for information on the different ways in which the manager obtains, and you can specify, the preferred and minimum size information for a child component.

SetPreferredSize(Control, Size)

Associates a preferred size with the specified control.

Declaration

public virtual void SetPreferredSize(Control control, Size value)

Parameters

Type	Name	Description
System.Windows.Forms.Control	control	The control to associate the preferred size with.
System.Drawing.Size	value	The preferred size of the control.

Remarks

ShouldLayoutAutoLabel(AutoLabel)

Declaration

protected virtual bool ShouldLayoutAutoLabel(AutoLabel autoLabel)

Parameters

Type	Name	Description
AutoLabel	autoLabel

Returns

Type
System.Boolean

ShouldSerializeCustomLayoutBounds()

Indicates whether the CustomLayoutBounds property is a value other than Rectangle.Empty.

Declaration

protected virtual bool ShouldSerializeCustomLayoutBounds()

Returns

Type
System.Boolean

ShouldSerializeMinimumSize(Control)

Indicates whether the MinimumSize property is a value other than Rectangle.Empty.

Declaration

public virtual bool ShouldSerializeMinimumSize(Control control)

Parameters

Type	Name	Description
System.Windows.Forms.Control	control

Returns

Type
System.Boolean

ShouldSerializePreferredSize(Control)

Indicates whether the PreferredSize property is a value other than Rectangle.Empty.

Declaration

public virtual bool ShouldSerializePreferredSize(Control control)

Parameters

Type	Name	Description
System.Windows.Forms.Control	control

Returns

Type
System.Boolean

Events

ContainerControlChanged

This event is triggered when the ContainerControl property is changed.

Declaration

public event EventHandler ContainerControlChanged

Event Type

Type
System.EventHandler

ProvideLayoutInformation

This event is triggered to obtain preferred size information for a child control during layout.

Declaration

public event ProvideLayoutInformationEventHandler ProvideLayoutInformation

Event Type

Type
ProvideLayoutInformationEventHandler

Implements

System.ComponentModel.IExtenderProvider

ILayoutManager

System.ComponentModel.ISupportInitialize