Class ControlHelper

Provides utility methods for working with Windows Forms controls and window management operations.

Inheritance

System.Object

ControlHelper

Inherited Members

System.Object.ToString()

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

Namespace: Telerik.WinControls

Assembly: Telerik.WinControls.dll

Syntax

public static class ControlHelper

Remarks

ControlHelper contains static helper methods for common control tree operations, window ordering, mouse hit testing, and control hierarchy management. These utilities are used throughout the Telerik WinControls framework for low-level control manipulation.

The class provides functionality for Z-order management, non-client area invalidation, control disposal checking, and mouse position tracking that are essential for advanced control behaviors and window management.

Methods

BeginUpdate(Control)

Sends a WM_SETREDRAW message to the control, preventing any paint operation afterwards.

Declaration

public static void BeginUpdate(Control control)

Parameters

System.Windows.Forms.Control control

BringToFront(IntPtr, Boolean)

Brings a window to the front of the Z-order, optionally activating it.

Declaration

public static void BringToFront(IntPtr handle, bool activate)

Parameters

System.IntPtr handle The window handle to bring to front.

System.Boolean activate true to activate the window (give it focus); false to only change its Z-order position.

Remarks

This method positions the specified window at the top of the Z-order stack, making it visible above all other windows. When activate is true, the window also receives focus and becomes the active window.

This is commonly used for bringing popup windows, dialogs, or notification windows to the user's attention without necessarily stealing focus from the current application.

EndUpdate(Control, Boolean)

Resumes Control's painting, previously suspended by a BeginUpdate call.

Declaration

public static void EndUpdate(Control control, bool invalidate)

Parameters

System.Windows.Forms.Control control

System.Boolean invalidate

EnumChildControls(Control, Boolean)

Enumerates all child controls of the specified parent and optionally traverses the entire tree using Depth-first approach.

Declaration

public static IEnumerable<Control> EnumChildControls(Control parent, bool recursive)

Parameters

System.Windows.Forms.Control parent

System.Boolean recursive

Returns

System.Collections.Generic.IEnumerable<System.Windows.Forms.Control>

EnumChildControls(Control, Boolean, Predicate<Control>)

Enumerates all child controls of the specified parent and optionally traverses the entire tree using Depth-first approach.

Declaration

public static IEnumerable<Control> EnumChildControls(Control parent, bool recursive, Predicate<Control> parentFilter)

Parameters

System.Windows.Forms.Control parent

System.Boolean recursive

System.Predicate<System.Windows.Forms.Control> parentFilter

Returns

System.Collections.Generic.IEnumerable<System.Windows.Forms.Control>

FilterChildControls(Control, Filter, Boolean)

Enumerates the Control tree, starting from the provided parent as a root, and collects all the child controls that match the specified filter.

Declaration

public static List<Control> FilterChildControls(Control parent, Filter filter, bool recursive)

Parameters

System.Windows.Forms.Control parent

Filter filter

System.Boolean recursive

Returns

System.Collections.Generic.List<System.Windows.Forms.Control>

FindAncestor<T>(Control)

Searches up the parent chain of controls, looking for an ancestor of the specified type.

Declaration

public static T FindAncestor<T>(Control child)
    where T : Control

Parameters

System.Windows.Forms.Control child

Returns

T

Type Parameters

T

FindDescendant(Control, Type)

Declaration

public static Control FindDescendant(Control parent, Type descendantType)

Parameters

System.Windows.Forms.Control parent

System.Type descendantType

Returns

System.Windows.Forms.Control

FindDescendant<T>(Control)

Searches down the control tree, using breadth-first approach, for a descendant of the specified type.

Declaration

public static T FindDescendant<T>(Control parent)
    where T : Control

Parameters

System.Windows.Forms.Control parent

Returns

T

Type Parameters

T

GetAnyDisposingInHierarchy(Control)

Determines whether any control in the hierarchy from the specified child control up to the root is disposing or disposed.

Declaration

public static bool GetAnyDisposingInHierarchy(Control child)

Parameters

System.Windows.Forms.Control child The starting control to check, along with its parent hierarchy.

Returns

System.Boolean true if any control in the hierarchy is disposed or currently disposing; otherwise, false.

Remarks

This method walks up the control hierarchy from the specified child control to the root, checking each control's System.Windows.Forms.Control.IsDisposed and System.Windows.Forms.Control.Disposing properties. It's useful for determining whether it's safe to perform operations on a control.

This check is important in scenarios where controls might be disposed asynchronously or where you need to ensure that parent controls are still valid before performing operations.

GetChildControls<T>(Control)

Declaration

public static List<T> GetChildControls<T>(Control parent)
    where T : Control

Parameters

System.Windows.Forms.Control parent

Returns

System.Collections.Generic.List<T>

Type Parameters

T

GetChildControls<T>(Control, Boolean)

Collects all child controls of given type.

Declaration

public static List<T> GetChildControls<T>(Control parent, bool recursive)
    where T : Control

Parameters

System.Windows.Forms.Control parent

System.Boolean recursive

Returns

System.Collections.Generic.List<T>

Type Parameters

T

GetControlStyle(Control, ControlStyles)

Determines whether the specified ControlStyle is applied to the provided control.

Declaration

public static bool GetControlStyle(Control instance, ControlStyles style)

Parameters

System.Windows.Forms.Control instance

System.Windows.Forms.ControlStyles style

Returns

System.Boolean

GetControlUnderMouse()

Gets the Windows Forms control that is currently under the mouse cursor.

Declaration

public static Control GetControlUnderMouse()

Returns

System.Windows.Forms.Control The System.Windows.Forms.Control instance under the mouse cursor, or null if no control is found.

Remarks

This method uses the current mouse position and Windows API calls to determine which control the mouse is currently over. It first gets the window handle at the mouse position using WindowFromPoint, then converts that handle to a managed Control reference.

This is useful for drag-and-drop operations, hit testing, and determining context for mouse-related operations when you need to identify the target control dynamically.

GetFirstControl<T>(Control, Boolean)

Gets the first Control of Type T, which is descendant of the specified Parent.

Declaration

public static T GetFirstControl<T>(Control parent, bool recursive)
    where T : Control

Parameters

System.Windows.Forms.Control parent

System.Boolean recursive

Returns

T

Type Parameters

T

GetFocusedControl()

Gets the Control instance that currently contains the Keyboard focus.

Declaration

public static Control GetFocusedControl()

Returns

System.Windows.Forms.Control

GetLastControl<T>(Control, Boolean)

Gets the last Control of Type T, which is descendant of the specified Parent.

Declaration

public static T GetLastControl<T>(Control parent, bool recursive)
    where T : Control

Parameters

System.Windows.Forms.Control parent

System.Boolean recursive

Returns

T

Type Parameters

T

GetNextControl<T>(Control, T, Boolean, Boolean, Boolean)

Gets the Control of type T that is descendant of the specified parent and is anchored to the specified current T instance.

Declaration

public static T GetNextControl<T>(Control parent, T curr, bool recursive, bool forward, bool wrap)
    where T : Control

Parameters

System.Windows.Forms.Control parent The parent control, which descendants are to be examined.

T curr The current T instance to start the search from.

System.Boolean recursive True to perform depth-first traversal of the Control Tree, false to look-up direct children only.

System.Boolean forward True to search for a T instance that is next to the current specified one, false to search for a T instance that is previous to the current specified one.

System.Boolean wrap True to start the search from the beginning when end of the search is reached.

Returns

T

Type Parameters

T A Control of Type T.

InvalidateNonClient(Control, Boolean)

Forces the non-client area of the specified Control instance to be re-evaluated.

Declaration

public static void InvalidateNonClient(Control frame, bool activate)

Parameters

System.Windows.Forms.Control frame

System.Boolean activate

IsDescendant(Control, Control)

Determines whether the specified Child is contained within the specified Parent's Control Tree.

Declaration

public static bool IsDescendant(Control parent, Control child)

Parameters

System.Windows.Forms.Control parent

System.Windows.Forms.Control child

Returns

System.Boolean

SendToBack(IntPtr, Boolean)

Sends a window to the back of the Z-order, optionally activating it.

Declaration

public static void SendToBack(IntPtr handle, bool activate)

Parameters

System.IntPtr handle The window handle to send to back.

System.Boolean activate true to activate the window; false to only change its Z-order position.

Remarks

This method positions the specified window at the bottom of the Z-order stack, making it appear behind all other windows. This is typically used to minimize the visual impact of background windows or utility windows.

Note that activating a window that's sent to back may cause visual inconsistencies, so activate is usually set to false for this operation.