WinForms

Code Examples Upgrade Guide User Guide Demos Support Forums Download
  • Code Examples
  • Upgrade Guide
  • User Guide
  • Demos
  • Support
  • Forums
  • Download
Class LayoutManager

    Show / Hide Table of Contents

    Class LayoutManager

    Defines the base class for Layout Managers.

    Inheritance
    System.Object
    LayoutManager
    BorderLayout
    CardLayout
    FlowLayout
    GridBagLayout
    GridLayout
    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 Description
    System.Boolean

    minimumSizes

    Declaration
    protected Hashtable minimumSizes
    Field Value
    Type Description
    System.Collections.Hashtable

    preferredSizes

    Declaration
    protected Hashtable preferredSizes
    Field Value
    Type Description
    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 Description
    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 Description
    System.ComponentModel.Design.IDesignerHost

    DesignerInTransaction

    Declaration
    protected bool DesignerInTransaction { get; }
    Property Value
    Type Description
    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 Description
    System.Int32

    LoadingDocument

    Declaration
    protected bool LoadingDocument { get; }
    Property Value
    Type Description
    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 Description
    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 Description
    System.Int32

    AdjustWidthForMargins(Int32)

    Declaration
    protected int AdjustWidthForMargins(int width)
    Parameters
    Type Name Description
    System.Int32 width
    Returns
    Type Description
    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 Description
    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 Description
    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

    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.

    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

    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.

    ShouldLayoutAutoLabel(AutoLabel)

    Declaration
    protected virtual bool ShouldLayoutAutoLabel(AutoLabel autoLabel)
    Parameters
    Type Name Description
    AutoLabel autoLabel
    Returns
    Type Description
    System.Boolean

    ShouldSerializeCustomLayoutBounds()

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

    Declaration
    protected virtual bool ShouldSerializeCustomLayoutBounds()
    Returns
    Type Description
    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 Description
    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 Description
    System.Boolean

    Events

    ContainerControlChanged

    This event is triggered when the ContainerControl property is changed.

    Declaration
    public event EventHandler ContainerControlChanged
    Event Type
    Type Description
    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 Description
    ProvideLayoutInformationEventHandler

    Implements

    System.ComponentModel.IExtenderProvider
    ILayoutManager
    System.ComponentModel.ISupportInitialize
    Back to top Generated by DocFX
    Copyright © 2001 - 2023 Syncfusion Inc. All Rights Reserved