Class ScrollControl

Represents a base class for the controls that supports scrolling.

Inheritance

System.Object

ScrollControl

HybridScrollControl

Namespace: Syncfusion.Windows.Forms.Edit

Assembly: Syncfusion.Edit.Windows.dll

Syntax

public class ScrollControl : Control

Remarks

The ScrollControl class acts as a base class for controls that require the ability to scroll. To allow a control to display scroll bars as needed, set the AutoScroll property to true. To select which scroll bars should be visible, set the VScroll and HScroll properties.

You can also associate stand-alone scrollbars with the ScrollControl. The VertScrollBar and HorizScrollBar properties allow you to associate external scrollbars. This is of benefit if you want to share one scrollbar with a parent control. For example, if the ScrollControl is a view inside a workbook or dynamic splitter frame.

ScrollControl supports automatic scrolling when the user drags the mouse. In a grid when the user starts selecting cells the user can drag the mouse outside the grid area and the grid will automatically scroll. To enable auto scrolling, override the OnMouseDown event in your derived control and initialize the AutoScrolling, AutoScrollBounds and InsideScrollBounds properties.

When the user scrolls your control and holds down the mouse on the down or up arrow of the scrollbar, the scrolling speed will accelerate.

The FixRenderOrigin method will ensure correct initialization of the rendering origin for brushes and patterns. You can call FixRenderOrigin from your control's OnPaint method. ScrollControl supports scrolling with the mouse wheel and also cooperates fine with with the IntelliMouseDragScroll class.

If you want to provide context information about your control and change the cursor on the fly while the user moves the mouse, set the OverrideCursor property to the cursor you want to show. Instead you can also implement IMouseController and add the object to MouseControllerDispatcher.

Constructors

ScrollControl()

Initializes a new instance of ScrollControl class.

Declaration

public ScrollControl()

Properties

BorderStyle

Gets or sets the border style of the control.

Declaration

public BorderStyle BorderStyle { get; set; }

Property Value

Type
System.Windows.Forms.BorderStyle

CreateParams

Overriden. Changes System.Windows.Forms.CreateParams.Style to show or hide scrollbars and also consider the controls BorderStyle setting.

Declaration

protected override CreateParams CreateParams { get; }

Property Value

Type
System.Windows.Forms.CreateParams

DisableScrollWindow

Gets or sets a value indicating whether to specify the setting if the window should be scrolled when ScrollWindow is called.

Declaration

public bool DisableScrollWindow { get; set; }

Property Value

Type
System.Boolean

Remarks

If DisableScrollWindow is true any calls to the ScrollWindow method will simply invalidate the affect region. The rendering origin will still be recorded correctly and WindowScrolling and WindowScrolled events will be raised.

If DisableScrollWindow is false ScrollWindow will scroll the contents of the control.

If DisableScrollWindow will return true if BeginUpdate was called without the BeginUpdateOptions.ScrollWindow option.

See Also

ScrollControl.BeginUpdate

ScrollControl.Updating

ScrollControl.ScrollWindow

DiscardPaintMessagesAfterBeginUpdate

Gets or sets a value indicating Whether you can call BeginUpdate() the control by default that does not handle WM_PAINT messages. Only once you call EndUpdate they will be processed. If this causes problems in your application, you can set this static property to true. In such cases WM_PAINT messages will be simply discarded and any invalid regions will be validated.

Declaration

public static bool DiscardPaintMessagesAfterBeginUpdate { get; set; }

Property Value

Type
System.Boolean

Remarks

There is a problem with the default implementation of BeginUpdate. If a screen region is marked invalid the WndProc will be repeatedly called with WM_PAINT at the the top of the WndProc until EndUpdate is called. This can cause your application to freeze if another window gets created or if you make a web service call and WndProc messages need to be processed.

Setting DiscardPaintMessagesAfterBeginUpdate = true will help avoid these scenarios.

HasControlFocus

Gets or sets a value indicating whether the OnControlGotFocus() has been called. OnControlLostFocus() resets this flag.

Declaration

public bool HasControlFocus { get; }

Property Value

Type
System.Boolean

HorizontalScrollTips

Gets or sets a value indicating whether the control should show scroll tips while the user is dragging a horizontal scrollbars thumb.

Declaration

public virtual bool HorizontalScrollTips { get; set; }

Property Value

Type
System.Boolean

HorizontalThumbTrack

Gets or sets a value indicating whether the control should scroll while the user is dragging a horizontal scrollbars thumb.

Declaration

public virtual bool HorizontalThumbTrack { get; set; }

Property Value

Type
System.Boolean

HScroll

Gets or sets a value indicating whether the horizontal scroll bar is visible or not.

Declaration

public bool HScroll { get; set; }

Property Value

Type	Description
System.Boolean	true if the horizontal scroll bar is visible; otherwise, false.

See Also

System.Windows.Forms.ScrollableControl.HScroll

HScrollBar

Gets a reference to an object with horizontal scrollbar settings of the control.

Declaration

public ScrollBarWrapper HScrollBar { get; }

Property Value

Type
ScrollBarWrapper

IgnoreUICues

ScrollControlMouseController checks this to see if it should cancel existing mouse operation and call ScrollControlMouseController.CancelMode when a UICuesChanged event is sent. That can happen when user activates another application or simply when styles for a child window have changed.

Declaration

public bool IgnoreUICues { get; set; }

Property Value

Type
System.Boolean

InsideScrollMargins

Gets or sets the default margins for the scrolling area when the user moves the mouse to the margin between InsideScrollBounds and AutoScrollBounds.

Declaration

public Size InsideScrollMargins { get; set; }

Property Value

Type
System.Drawing.Size

IsActiveControl

Gets or sets a value indicating whether the OnEnter(EventArgs) has been called. OnLeave(EventArgs) resets this flag.

Declaration

public bool IsActiveControl { get; }

Property Value

Type
System.Boolean

IsDeactivated

Gets or sets a value indicating whether the OnDeactivated(EventArgs) has been called. OnEnter(EventArgs) resets this flag.

Declaration

public bool IsDeactivated { get; }

Property Value

Type
System.Boolean

IsValidated

Gets or sets a value indicating whether the OnValidated(EventArgs) method has been called. OnLeave(EventArgs) and OnEnter(EventArgs) reset this flag.

Declaration

public bool IsValidated { get; }

Property Value

Type
System.Boolean

IsValidating

Gets or sets a value indicating whether the OnValidating(CancelEventArgs) method has been called. OnLeave(EventArgs) and OnEnter(EventArgs) reset this flag.

Declaration

public bool IsValidating { get; }

Property Value

Type
System.Boolean

LastMousePosition

Gets or sets the mouse position point(Control.MousePosition) of the control. The variable is before any WM_MOUSE* messages are processed.

Declaration

public Point LastMousePosition { get; set; }

Property Value

Type
System.Drawing.Point

PaintPending

Gets or sets a value indicating whether it contains pending updates for the control when painting is suspended with BeginUpdate.

Declaration

public bool PaintPending { get; }

Property Value

Type
System.Boolean

PaneDesc

Gets the pane information.

Declaration

public virtual string PaneDesc { get; }

Property Value

Type
System.String

PreJitPaint

Lets you specify if the time the first time the control is drawn should be optimized by calling OnPaint before the control is made visible and so that all relevant code for drawing has been jitted.

Declaration

protected bool PreJitPaint { get; set; }

Property Value

Type
System.Boolean

Size

Gets or sets the size of Scrollable control.

Declaration

public Size Size { get; set; }

Property Value

Type
System.Drawing.Size

SupportsThumbTrack

Gets or sets a value indicating whether the control should scroll while the user is dragging a scrollbars thumb.

Declaration

[Obsolete("Use VerticalThumbTrack and HorizontalThumbTrack properties instead.")]
public bool SupportsThumbTrack { get; set; }

Property Value

Type
System.Boolean

TabIndex

Gets or sets the tab order of the control within its container.

Declaration

public int TabIndex { get; set; }

Property Value

Type
System.Int32

UpdateOptions

Gets the settings for the current BeginUpdate option.

Declaration

public virtual BeginUpdateOptions UpdateOptions { get; }

Property Value

Type
BeginUpdateOptions

Updating

Gets or sets a value indicating whether the BeginUpdate() has been called and the painting for a control is suspended.

Declaration

public bool Updating { get; }

Property Value

Type
System.Boolean

UseSharedScrollBars

Gets or sets a value indicating whether the shared scrollbars should be enabled or not. Use this if the control is not embedded in a container control that implements IScrollBarFrame and you want to provide your own scrollbars.

Declaration

public bool UseSharedScrollBars { get; set; }

Property Value

Type
System.Boolean

VerticalScrollTips

Gets or sets a value indicating whether the control should show scroll tips while the user is dragging a vertical scrollbars thumb.

Declaration

public virtual bool VerticalScrollTips { get; set; }

Property Value

Type
System.Boolean

VerticalThumbTrack

Gets or sets a value indicating whether the control should scroll while the user is dragging a vertical scrollbars thumb.

Declaration

public virtual bool VerticalThumbTrack { get; set; }

Property Value

Type
System.Boolean

VScroll

Gets or sets a value indicating whether the vertical scroll bar is visible or not.

Declaration

public bool VScroll { get; set; }

Property Value

Type	Description
System.Boolean	true if the vertical scroll bar is visible; otherwise, false.

See Also

System.Windows.Forms.ScrollableControl.HScroll

VScrollBar

Gets a reference to an object with vertical scrollbar settings of the control.

Declaration

public ScrollBarWrapper VScrollBar { get; }

Property Value

Type
ScrollBarWrapper

Methods

BeginUpdate()

Suspends the painting of the control until the EndUpdate method is called.

Declaration

public void BeginUpdate()

Remarks

When many paint are made to the appearance of a control you should invoke the BeginUpdate method to temporarily freeze the drawing of the control. This results in less distraction to the user, and a performance gain. After all updates have been made, invoke the EndUpdate method to resume drawing of the control.

BeginUpdate(BeginUpdateOptions)

Suspends the painting of the control until the EndUpdate method is called.

Declaration

public virtual void BeginUpdate(BeginUpdateOptions options)

Parameters

Type	Name	Description
BeginUpdateOptions	options	Specifies the painting support during the BeginUpdate, EndUpdate batch.

Remarks

When many paint are made to the appearance of a control you should invoke the BeginUpdate method to temporarily freeze the drawing of the control. This results in less distraction to the user, and a performance gain. After all updates have been made, invoke the EndUpdate method to resume drawing of the control.

Pass BeginUpdateOptions if you do not want to do a complete Refresh of the control and instead want to have certain regions of your control be invalidated or scroll the contents of control.

If you call BeginUpdate() and then later EndUpdate() the control will know if a paint is pending and only refresh the control if a paint is pending. Either call to ShouldPrepareUpdate, Invalidate or a WM_PAINT message during the BeginUpdate EndUpdate block will signal the control that a paint is pending.

See Also

ScrollControl.ShouldPrepareUpdate

ScrollControl.EndUpdate

CancelUpdate()

Cancels any prior BeginUpdate calls.

Declaration

public void CancelUpdate()

See Also

ScrollControl.BeginUpdate

Dispose(Boolean)

Releases the unmanaged resources used by the Control and its child controls and optionally releases the managed resources.

Declaration

protected override void Dispose(bool disposing)

Parameters

Type	Name	Description
System.Boolean	disposing	True to release both managed and unmanaged resources; false to release only unmanaged resources.

EndUpdate()

Resumes the painting of the control suspended by calling the BeginUpdate method.

Declaration

public void EndUpdate()

Remarks

When many paint are made to the appearance of a control you should invoke the BeginUpdate method to temporarily freeze the drawing of the control. This results in less distraction to the user, and a performance gain. After all updates have been made, invoke the EndUpdate method to resume drawing of the control.

See Also

ScrollControl.BeginUpdate

EndUpdate(Boolean)

Resumes the painting of the control suspended by calling the BeginUpdate method.

Declaration

public virtual void EndUpdate(bool update)

Parameters

Type	Name	Description
System.Boolean	update	Updated when set to true.

Remarks

When many paint are made to the appearance of a control you should invoke the BeginUpdate method to temporarily freeze the drawing of the control. This results in less distraction to the user, and a performance gain. After all updates have been made, invoke the EndUpdate method to resume drawing of the control.

EnsurePaintCodeJitted(Boolean)

This method checks if the control is visible, a window handle has been created and if it has not been drawn before, it calls OnEnsurePaintCodeJitted().

Declaration

public void EnsurePaintCodeJitted(bool ignoreVisible)

Parameters

Type	Name	Description
System.Boolean	ignoreVisible	Set this true if you want to force a call to OnEnsurePaintCodeJitted() even if the control is not visible and/or no window handle has been created.

FixRenderOrigin(Graphics)

Call this method from your controls OnPaint method to ensure correct rendering origin for brushes and patterns.

Declaration

protected void FixRenderOrigin(Graphics g)

Parameters

Type	Name	Description
System.Drawing.Graphics	g	The graphics object.

LastMousePositionToClient()

Computes the location of the specified screen point into client coordinates.

Declaration

public Point LastMousePositionToClient()

Returns

Type	Description
System.Drawing.Point	PointToClient(LastMousePosition).

OnBeginUpdateScrollBars()

Call BeginUpdate() for both scrollbars.

Declaration

protected virtual void OnBeginUpdateScrollBars()

OnControlAdded(ControlEventArgs)

Performs control adding-related operations.

Declaration

protected override void OnControlAdded(ControlEventArgs e)

Parameters

Type	Name	Description
System.Windows.Forms.ControlEventArgs	e	ControlEventArgs.

OnControlGotFocus()

Raises the System.Windows.Forms.Control.GotFocus event. This method is called when the control or any child control got focus and this control did not have focus before.

Declaration

protected virtual void OnControlGotFocus()

Remarks

Inheriting classed should override this method instead of overriding System.Windows.Forms.Control.OnGotFocus(System.EventArgs) because OnControlGotFocus() is also called when child controls got focus and it is not called when focus is moved within child controls of this control.

OnControlLostFocus()

Raises the System.Windows.Forms.Control.LostFocus event. This method is called when the control or any child control looses focus and the new focused control is not a child of this control.

Declaration

protected virtual void OnControlLostFocus()

Remarks

Inheriting classed should override this method instead of overriding System.Windows.Forms.Control.OnLostFocus(System.EventArgs) because OnControlLostFocus() is also called when child controls loose focus and it is not called when focus is moved within child controls of this control.

OnControlRemoved(ControlEventArgs)

Performs control removing-related operations.

Declaration

protected override void OnControlRemoved(ControlEventArgs e)

Parameters

Type	Name	Description
System.Windows.Forms.ControlEventArgs	e	ControlEventArgs.

OnDeactivated(EventArgs)

Raises the Deactivated event.

Declaration

protected virtual void OnDeactivated(EventArgs e)

Parameters

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

OnEndUpdateScrollBars()

Call EndUpdate() for both scrollbars.

Declaration

protected virtual void OnEndUpdateScrollBars()

OnEnsurePaintCodeJitted()

This method is called to reduce the time the first time the control is drawn. Calling OnPaint before the control is made visible ensures that all relevant code for drawing has been jitted.

Declaration

protected virtual void OnEnsurePaintCodeJitted()

OnEnter(EventArgs)

Performs mouse entering-related operations.

Declaration

protected override void OnEnter(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	EventArgs.

OnGotFocus(EventArgs)

OnGotFocus.

Declaration

protected override void OnGotFocus(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	EventArgs.

OnHandleCreated(EventArgs)

Performs handle creating-related operations.

Declaration

protected override void OnHandleCreated(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	EventArgs.

OnHScroll(Object, ScrollEventArgs)

Called when horizontal scrolling is being performed.

Declaration

protected virtual void OnHScroll(object sender, ScrollEventArgs se)

Parameters

Type	Name	Description
System.Object	sender	Sender.
System.Windows.Forms.ScrollEventArgs	se	ScrollEventArgs.

OnInvalidated(InvalidateEventArgs)

Overriden. See System.Windows.Forms.Control.Invalidated event.

Declaration

protected override void OnInvalidated(InvalidateEventArgs e)

Parameters

Type	Name	Description
System.Windows.Forms.InvalidateEventArgs	e	An System.Windows.Forms.InvalidateEventArgs that contains the event data.

OnLeave(EventArgs)

Performs mouse leaving-related operations.

Declaration

protected override void OnLeave(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	EventArgs

OnLocationChanged(EventArgs)

Performs location changing-related operations.

Declaration

protected override void OnLocationChanged(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	EventArgs.

OnLostFocus(EventArgs)

Performs focus loosing-related operations.

Declaration

protected override void OnLostFocus(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	EventArgs.

OnPaint(PaintEventArgs)

Performs painting-related operations.

Declaration

protected override void OnPaint(PaintEventArgs e)

Parameters

Type	Name	Description
System.Windows.Forms.PaintEventArgs	e	PaintEventArgs.

OnParentChanged(EventArgs)

Performs parent changing-related operations.

Declaration

protected override void OnParentChanged(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	EventArgs.

OnScrollbarsVisibleChanged(EventArgs)

This method fires the ScrollbarsVisibleChanged

Declaration

protected virtual void OnScrollbarsVisibleChanged(EventArgs e)

Parameters

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

OnSizeChanged(EventArgs)

Performs size changing-related operations.

Declaration

protected override void OnSizeChanged(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	EventArgs.

OnUpdatingChanged(EventArgs)

Raises the UpdatingChanged event.

Declaration

protected virtual void OnUpdatingChanged(EventArgs e)

Parameters

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

Remarks

The event handler for this event can check Updating to determine if ScrollControl.BeginUpdate or ScrollControl.EndUpdate was called.

OnValidated(EventArgs)

Performs validating-related operations.

Declaration

protected override void OnValidated(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	EventArgs.

OnValidating(CancelEventArgs)

Performs validating-related operations.

Declaration

protected override void OnValidating(CancelEventArgs e)

Parameters

Type	Name	Description
System.ComponentModel.CancelEventArgs	e	CancelEventArgs.

OnValidatingLostFocus()

This method is called if the controls OnControlLostFocus() notification occurs while handling a System.Windows.Forms.Control.Validating event. This typically occurs if a message box is displayed from a System.Windows.Forms.Control.Validating event handler.

Declaration

protected virtual void OnValidatingLostFocus()

OnVisibleChanged(EventArgs)

Performs visibility changing-related operations.

Declaration

protected override void OnVisibleChanged(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	EventArgs.

OnVScroll(Object, ScrollEventArgs)

Called when vertical scrolling is being performed.

Declaration

protected virtual void OnVScroll(object sender, ScrollEventArgs se)

Parameters

Type	Name	Description
System.Object	sender	Sender.
System.Windows.Forms.ScrollEventArgs	se	ScrollEventArgs.

ProcessMouseWheel(MouseEventArgs)

Raises the System.Windows.Forms.Control.MouseWheel event.

Declaration

public void ProcessMouseWheel(MouseEventArgs e)

Parameters

Type	Name	Description
System.Windows.Forms.MouseEventArgs	e	A MouseEventArgs that holds event data.

Remarks

public class GridTextBox: RichTextBox
{
	private GridTextBoxCell parent;
	protected override void OnMouseWheel(MouseEventArgs e)
	{
		parent.Grid.ProcessMouseWheel(e);
	}
}

QueryFocusInside()

Determines whether this control contains focus. Override this method if you want to show dropdown windows and indicate the control has not lost focus when the dropdown is shown.

Declaration

public virtual bool QueryFocusInside()

Returns

Type	Description
System.Boolean	true if the control or any child control has focus; false otherwise.

ScrollWindow(Int32, Int32, Rectangle, Rectangle)

Scrolls the contents of the control like the ScrollWindow Windows API.

Declaration

public Rectangle ScrollWindow(int xAmount, int yAmount, Rectangle rect, Rectangle clipRect)

Parameters

Type	Name	Description
System.Int32	xAmount	Amount to scroll by x.
System.Int32	yAmount	Amount to scroll by y.
System.Drawing.Rectangle	rect	Rectangle to scroll.
System.Drawing.Rectangle	clipRect	Clip.

Returns

Type	Description
System.Drawing.Rectangle	Updated rectangle.

Remarks

The method will raise a WindowScrolling event before the contents are scrolled and a WindowScrolled event after the contents have been scrolled.

If DisableScrollWindow is true any calls to the ScrollWindow method will simply invalidate the affect region. The rendering origin will still be recorded correctly and WindowScrolling and WindowScrolled events will be raised.

If DisableScrollWindow is false ScrollWindow will scroll the contents of the control.

ShouldPrepareUpdate()

Call this method to check if you should do any update calculations for the view in your control and to notify scrollcontrol that the controls content need to be updated.

Declaration

public bool ShouldPrepareUpdate()

Returns

Type	Description
System.Boolean	true if you should invalidate areas that need to be redrawn; false if a complete Refresh for the control is pending and therefore invalidating the view is not necessary.

ShouldPrepareUpdate(Boolean)

Call this method to check if you should do any update calculations for the view in your control and to notify scrollcontrol that the controls content need to be updated.

Declaration

public bool ShouldPrepareUpdate(bool markPaintPending)

Parameters

Type	Name	Description
System.Boolean	markPaintPending	If markPaintPending is true ScrollControl will assume the control needs to be repainted in a subsequent EndUpdate call.

Returns

Type	Description
System.Boolean	true if you should Invalidate regions to be repainted in your control. It will return false if a complete Refresh of the control is pending and you don't need to invalidate individual regions of your control.

UpdateScrollBars()

Update scrollbars to reflect recent changes in scroll position, minimum and maximum scroll position values.

Declaration

public virtual void UpdateScrollBars()

WndProc(ref Message)

Processes Windows messages.

Declaration

protected override void WndProc(ref Message msg)

Parameters

Type	Name	Description
System.Windows.Forms.Message	msg	The Windows Message to process.

Events

Deactivated

Occurs when both OnControlLostFocus() and OnLeave(EventArgs) occured.

Declaration

public event EventHandler Deactivated

Event Type

Type
System.EventHandler

HorizontalScroll

Occurs when horizontal scrolling is being performed.

Declaration

public event ScrollEventHandler HorizontalScroll

Event Type

Type
System.Windows.Forms.ScrollEventHandler

UpdatingChanged

Occurs when ScrollControl.BeginUpdate has been called the first time or ScrollControl.EndUpdate has been called the last time.

Declaration

public event EventHandler UpdatingChanged

Event Type

Type
System.EventHandler

VerticalScroll

Occurs when vertical scrolling is being performed.

Declaration

public event ScrollEventHandler VerticalScroll

Event Type

Type
System.Windows.Forms.ScrollEventHandler