This documentation is archived and is not being maintained.

ScrollableControl.AutoScrollMargin Property

Gets or sets the size of the auto-scroll margin.

[Visual Basic]
Public Property AutoScrollMargin As Size
[C#]
public Size AutoScrollMargin {get; set;}
[C++]
public: __property Size get_AutoScrollMargin();
public: __property void set_AutoScrollMargin(Size);
[JScript]
public function get AutoScrollMargin() : Size;
public function set AutoScrollMargin(Size);

Property Value

A Size object that represents the height and width of the auto-scroll margin in pixels.

Exceptions

Exception Type Condition
ArgumentException The Height or Width value assigned is less than 0.

Remarks

The auto-scroll margin is the distance between any child controls and the edges of the scrollable parent control. The AutoScrollMargin size is added to the size of any child controls contained in the scrollable control to determine whether or not scroll bars are needed. The AutoScrollMargin property is evaluated when the parent scrollable control is resized or the individual child controls are brought into view, and is used to determine if scroll bars need to be displayed. Docked controls are excluded from the calculations that determine if scroll bars need to be displayed.

Note   If a docked control's Dock property is set to DockStyle.Fill, the control fills the parent scrollable control and the docked control is ignored when using the AutoScrollMargin to determine whether scroll bars are needed.

If the distance from the edge of a child control to the parent scrollable control is less than the value assigned to the AutoScrollMargin property and the AutoScroll property is set to true, the appropriate scroll bar is displayed.

Note   It is advisable, when docking controls within a scrollable control, to add a child scrollable control such as a Panel to contain any other controls that might require scrolling. The child Panel control should be added to the scrollable control and its Dock property set to DockStyle.Fill and its AutoScroll property set to true. The AutoScroll property of the parent scrollable control should be set to false.

Example

[Visual Basic, C#, C++] The following example uses the derived class, Panel. The example evaluates the location of a text box and changes the appearance and behavior of its parent container, the panel control. This example assumes a Panel control, TextBox, and Button have been instantiated. Place the text box on the panel so that it overlaps at least one of the panel's edges. Call this subprocedure on the click of a button to see the difference in the panel's behavior and appearance.

[Visual Basic] 
Private Sub SetAutoScrollMargins()
    ' If the text box is outside the panel's bounds,
    ' turn on auto-scrolling and set the margin. 
    If (text1.Location.X > panel1.Location.X) Or _
        (text1.Location.Y > panel1.Location.Y) Then
        panel1.AutoScroll = True
        ' If the AutoScrollMargin is set to less
        ' than (5,5), set it to 5,5. 
        If (panel1.AutoScrollMargin.Width < 5) Or _
            (panel1.AutoScrollMargin.Height < 5) Then
            
            panel1.SetAutoScrollMargin(5, 5)
        End If
    End If
End Sub


[C#] 
private void SetAutoScrollMargins()
 {
    /* If the text box is outside the panel's bounds, 
       turn on auto-scrolling and set the margin. */  
    if (text1.Location.X > panel1.Location.X || 
       text1.Location.Y > panel1.Location.Y)
    {
       panel1.AutoScroll = true;
       /* If the AutoScrollMargin is set to less 
          than (5,5), set it to 5,5. */
       if( panel1.AutoScrollMargin.Width < 5 || 
          panel1.AutoScrollMargin.Height < 5)
       {
          panel1.SetAutoScrollMargin(5, 5);
       }
    }
 }
 

[C++] 
private:
void SetAutoScrollMargins()
 {
    /* If the text box is outside the panel's bounds, 
       turn on auto-scrolling and set the margin. */  
    if (text1->Location.X > panel1->Location.X || 
       text1->Location.Y > panel1->Location.Y)
    {
       panel1->AutoScroll = true;
       /* If the AutoScrollMargin is set to less 
          than (5,5), set it to 5,5. */
       if( panel1->AutoScrollMargin.Width < 5 || 
          panel1->AutoScrollMargin.Height < 5)
       {
          panel1->SetAutoScrollMargin(5, 5);
       }
    }
 }
 

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family

See Also

ScrollableControl Class | ScrollableControl Members | System.Windows.Forms Namespace | AutoScroll | SetAutoScrollMargin | AutoScrollPosition | AutoScrollMinSize

Show: