UIControl Class

public abstract class UIControl : ScrollableControl, IUIControl, IUIElement, ILogicalTreeNode, IDpiAwareElement, IDisposable

public UIControl()

[Browsable(false)]
public int ActualHeight { get; }

Property Value

int

Remarks

This is determined by the layout system after Arrange(Rectangle) has completed. This is only valid if IsArrangeValid is true.

[Browsable(false)]
public int ActualWidth { get; }

Property Value

int

Remarks

This is determined by the layout system after Arrange(Rectangle) has completed. This is only valid if IsArrangeValid is true.

[Browsable(false)]
public override Color BackColor { get; set; }

Property Value

Color:

A Color that represents the background color of the control. The default is the value of the DefaultBackColor property.

[Browsable(false)]
public override Image? BackgroundImage { get; set; }

Property Value

Image:

An Image that represents the image to display in the background of the control.

protected virtual bool CaptureMouseWhenPressed { get; }

Property Value

bool:

true if the mouse should automatically be captured when the element is pressed; otherwise, false.

[Browsable(false)]
public virtual Rectangle ClipBounds { get; }

Property Value

Rectangle

[Browsable(false)]
public Size DesiredSize { get; }

Property Value

Size

Remarks

This is only valid if IsMeasureValid is true.

[Browsable(false)]
public SizeF DpiScaleFactor { get; }

Property Value

SizeF

See Also

• DpiScaleChanged(SizeF)

[Browsable(false)]
public override Font Font { get; set; }

Property Value

Font:

The Font to apply to the text displayed by the control. The default is the value of the DefaultFont property.

[Browsable(false)]
public override Color ForeColor { get; set; }

Property Value

Color:

The foreground Color of the control. The default is the value of the DefaultForeColor property.

[Browsable(false)]
public bool IsArrangeValid { get; }

Property Value

bool:

true if the value of the DesiredSize property and position of child elements is valid; otherwise, false.

Remarks

A developer can force arrangement to be invalidated by calling InvalidateArrange(). IsArrangeValid and IsMeasureValid are related, in that arrangement cannot be valid without measurement first being valid.

[Browsable(false)]
public bool IsMeasureValid { get; }

Property Value

bool:

true if the value of the DesiredSize property is valid; otherwise, false.

Remarks

A developer can force arrangement to be invalidated by calling InvalidateMeasure(). IsArrangeValid and IsMeasureValid are related, in that arrangement cannot be valid without measurement first being valid.

[Browsable(false)]
public bool IsPaintValid { get; }

Property Value

bool:

true if the control has rendered itself and doesn't have any invalidated paint regions; otherwise, false.

[Browsable(false)]
public bool IsRightToLeft { get; }

Property Value

bool:

true if the element is using a right-to-left layout; otherwise, false.

protected MouseButtons LastMouseUpButton { get; }

Property Value

MouseButtons

[Browsable(false)]
public bool PaintingSuspended { get; }

Property Value

bool:

true if the control is painting itself; otherwise, false.

Remarks

If this flag is set, calls to the OnPaint method will be ignored.

protected virtual bool UseControlGraphicsForMeasure { get; }

Property Value

bool:

true if the control's CreateGraphics method should be called; otherwise, false. The default value is true.

protected virtual bool UseExtendedDoubleBuffering { get; }

Property Value

bool:

true if extended double buffering should be used; otherwise, false.

protected bool AddPendingGraphicsInversion(Rectangle bounds)

Parameter	Type	Description
bounds	Rectangle	The bounds to invert.

Returns

bool:

true if the inversion operation was added successfully; otherwise, false.

protected bool AddPendingScrollOperation(Rectangle bounds, int xAmount, int yAmount)

Parameter	Type	Description
bounds	Rectangle	The bounds to scroll.
xAmount	int	The amount to scroll horizontally.
yAmount	int	The amount to scroll vertically.

Returns

bool:

true if the scroll operation was added successfully; otherwise, false.

protected bool AddPendingScrollOperation(Rectangle bounds, Orientation orientation, int amount)

Parameter	Type	Description
bounds	Rectangle	The bounds to scroll.
orientation	Orientation	The direction to scroll.
amount	int	The amount to scroll.

Returns

bool:

true if the scroll operation was added successfully; otherwise, false.

public void AddToInvalidatedRegion()

public void AddToInvalidatedRegion(Rectangle rect)

Parameter	Type	Description
rect	Rectangle	The Rectangle to add to the invalidated region.

public void Arrange(Rectangle finalRect)

Parameter	Type	Description
finalRect	Rectangle

protected virtual Size ArrangeOverride(Size finalSize)

Parameter	Type	Description
finalSize	Size	The final area within the parent that this element should use to arrange itself and its children.

Returns

Size:

The actual size used.

Remarks

Element authors should override this method, call Arrange(Rectangle) on each visible child element and position each child element. It is required that a parent element calls Arrange(Rectangle) on each child or they won't be rendered.

public virtual bool ContainsLocation(Point location)

Parameter	Type	Description
location	Point	The Point location to examine.

Returns

bool:

true if this element's bounds contains the specified location; otherwise, false.

Remarks

Override this method to prevent certain portions of the element's bounds from being included in hit-testing.

protected virtual IList<ILogicalTreeNode>? CreateChildren()

Returns

IList<ILogicalTreeNode>:

The list that should be assigned to the Children property.

Remarks

By default, no child collection is created.

protected override void Dispose(bool disposing)

Parameter	Type	Description
disposing	bool	true to release both managed and unmanaged resources; false to release only unmanaged resources.

public virtual void DpiScaleChanged(SizeF scaleFactor)

Parameter	Type	Description
scaleFactor	SizeF	The new scale factor where Width is applied to the x-axis, and Height is applied to the y-axis.

See Also

• DpiScaleFactor

public virtual Cursor? GetCursor(Point point)

Parameter	Type	Description
point	Point	The Point to examine.

Returns

Cursor

protected PointHitTestResult HitTest(PointHitTestParameters hitTestParams, Func<IUIElement, PointHitTestParameters, bool>? filter = null)

Parameter	Type	Description
hitTestParams	PointHitTestParameters	A PointHitTestParameters containing hit test parameters.
filter	Func<IUIElement, PointHitTestParameters, bool>	Optionally defines a filter which must return true for an element to match the hit test.

Returns

PointHitTestResult:

A PointHitTestResult containing the hit test result.

protected PointHitTestResult HitTestRecursive(PointHitTestParameters hitTestParams, Func<IUIElement, PointHitTestParameters, bool>? filter = null)

Parameter	Type	Description
hitTestParams	PointHitTestParameters	A PointHitTestParameters containing hit test parameters.
filter	Func<IUIElement, PointHitTestParameters, bool>	Optionally defines a filter which must return true for an element to match the hit test.

Returns

PointHitTestResult:

A PointHitTestResult containing the hit test result.

public void Invalidate(InvalidationLevels levels, InvalidationTypes types)

Parameter	Type	Description
levels	InvalidationLevels	The hierarchy levels at which to invalidate.
types	InvalidationTypes	The types of invalidation to perform.

public void InvalidateArrange()

public void InvalidateMeasure()

public void Measure(Graphics? g, Size availableSize)

Parameter	Type	Description
g	Graphics	The Graphics object to use for measurement.
availableSize	Size	The available size that parent can give to the child. The child can return bigger in hopes that the parent will become scrollable. The value may also be infinity to indicate that the desired measurements of the element are wanted.

Remarks

The Measure(Graphics?, Size) method should be called by parents on their children. Internally, Measure(Graphics?, Size) calls the MeasureCore override on the same object, giving it opportunity to compute its DesiredSize. This method will return immediately if the child's measurements are valid, previously measured and availableSize is the same as cached. This method also resets the IsMeasureValid bit on the child.

protected virtual Size MeasureOverride(Graphics? g, Size availableSize)

Parameter	Type	Description
g	Graphics	The Graphics object to use for measurement.
availableSize	Size	The available size that this element can give to child elements. Infinity can be specified as a value to indicate that the element will size to whatever content is available.

Returns

Size:

The size that this element determines it needs during layout, based on its calculations of child element sizes.

Remarks

Element authors should override this method, call Measure(Graphics?, Size) on each visible child element and determine the total size required.

protected override void OnClick(EventArgs e)

Parameter	Type	Description
e	EventArgs	An EventArgs that contains the event data.

protected override void OnDoubleClick(EventArgs e)

Parameter	Type	Description
e	EventArgs	An EventArgs that contains the event data.

protected override void OnDpiChangedAfterParent(EventArgs e)

Parameter	Type	Description
e	EventArgs	An DpiChangedEventArgs that contains the event data.

protected override void OnHandleCreated(EventArgs e)

Parameter	Type	Description
e	EventArgs	An EventArgs that contains the event data.

protected override void OnLayout(LayoutEventArgs e)

Parameter	Type	Description
e	LayoutEventArgs

protected override void OnLocationChanged(EventArgs e)

Parameter	Type	Description
e	EventArgs	An EventArgs that contains the event data.

protected override void OnMouseCaptureChanged(EventArgs e)

Parameter	Type	Description
e	EventArgs	An EventArgs that contains the event data.

protected override void OnMouseDown(MouseEventArgs e)

Parameter	Type	Description
e	MouseEventArgs	A MouseEventArgs that contains the event data.

protected override void OnMouseEnter(EventArgs e)

Parameter	Type	Description
e	EventArgs	An EventArgs that contains the event data.

protected override void OnMouseHover(EventArgs e)

Parameter	Type	Description
e	EventArgs	An EventArgs that contains the event data.

protected override void OnMouseLeave(EventArgs e)

Parameter	Type	Description
e	EventArgs	An EventArgs that contains the event data.

protected override void OnMouseMove(MouseEventArgs e)

Parameter	Type	Description
e	MouseEventArgs	A MouseEventArgs that contains the event data.

protected override void OnMouseUp(MouseEventArgs e)

Parameter	Type	Description
e	MouseEventArgs	A MouseEventArgs that contains the event data.

protected override void OnMouseWheel(MouseEventArgs e)

Parameter	Type	Description
e	MouseEventArgs	A MouseEventArgs that contains the event data.

protected override sealed void OnPaint(PaintEventArgs e)

Parameter	Type	Description
e	PaintEventArgs	A PaintEventArgs that contains the event data.

protected override sealed void OnPaintBackground(PaintEventArgs e)

Parameter	Type	Description
e	PaintEventArgs	The event data.

Exceptions

Type	Condition
ArgumentNullException	.NET 5 and later versions only: e is null.

protected virtual void OnParentChanged()

protected override void OnParentChanged(EventArgs e)

Parameter	Type	Description
e	EventArgs	An EventArgs that contains the event data.

protected virtual void OnRender(PaintEventArgs e)

Parameter	Type	Description
e	PaintEventArgs	The event data.

protected virtual void OnRenderChildElements(PaintEventArgs e)

Parameter	Type	Description
e	PaintEventArgs	The event data.

Remarks

This method should not generally be overridden. The default implementation of this method calls the Render(PaintEventArgs) method on all child elements.

protected override void OnResize(EventArgs e)

Parameter	Type	Description
e	EventArgs	An EventArgs that contains the event data.

protected override void OnRightToLeftChanged(EventArgs e)

Parameter	Type	Description
e	EventArgs	An EventArgs that contains the event data.

protected override void OnVisibleChanged(EventArgs e)

Parameter	Type	Description
e	EventArgs	An EventArgs object that contains the event data.

public void Render(PaintEventArgs e)

Parameter	Type	Description
e	PaintEventArgs	The event data.

public void ResetDoubleBufferCanvas(bool recurse)

Parameter	Type	Description
recurse	bool	Whether to recurse down into the child control tree.

public void ResumePainting()

See Also

• PaintingSuspended

public void SuspendPainting()

See Also

• PaintingSuspended

public GeneralTransform TransformToAncestor(IUIElement ancestor)

Parameter	Type	Description
ancestor	IUIElement	The ancestor IUIElement.

Returns

GeneralTransform

public GeneralTransform TransformToDescendant(IUIElement descendant)

Parameter	Type	Description
descendant	IUIElement	The descendant IUIElement.

Returns

GeneralTransform

protected void UpdateCursor()

protected void UpdateCursor(Point position)

Parameter	Type	Description
position	Point

public virtual void UpdateLayout()

Remarks

This ensures that UIElement objects with invalid measure or arrange states will get a call to their Measure(Graphics?, Size) and Arrange(Rectangle) methods, and all computed sizes will be validated. This method does nothing if layout is clean but it does work if layout is not clean so avoid calling it after each change in the element tree. It makes sense to either never call it (system will do this in a deferred manner) or only call it if you absolutely need updated sizes and positions after you do all changes.