UIControl Class

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

public UIControl()

Remarks

The default constructor initializes all fields to their default values.

public int ActualHeight { get; }

Property Value

Int32:

The actual height of the element.

Remarks

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

public int ActualWidth { get; }

Property Value

Int32:

The actual width of the element.

Remarks

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

public override Color BackColor { get; set; }

Property Value

Color:

A Color that represents the background color of the control.

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

Boolean:

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

public virtual Rectangle ClipBounds { get; }

Property Value

Rectangle:

A Rectangle specifying the clip bounds when drawing the element.

public Size DesiredSize { get; }

Property Value

Size:

The desired size of the element as computed by Measure(Graphics, Size).

Remarks

This is only valid if IsMeasureValid is true.

public SizeF DpiScaleFactor { get; }

Property Value

SizeF:

A SizeF where Width is applied to the x-axis, and Height is applied to the y-axis.

See Also

• DpiScaleChanged(SizeF)

public override Font Font { get; set; }

Property Value

Font:

The Font object to apply to the text displayed by the control.

public override Color ForeColor { get; set; }

Property Value

Color:

A Color that represents the foreground color of the control.

public bool IsArrangeValid { get; }

Property Value

Boolean:

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.

public bool IsMeasureValid { get; }

Property Value

Boolean:

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.

public bool IsPaintValid { get; }

Property Value

Boolean:

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

public bool IsRightToLeft { get; }

Property Value

Boolean:

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

protected MouseButtons LastMouseUpButton { get; }

Property Value

MouseButtons:

The MouseButtons indicating the last mouse button that was released.

public bool PaintingSuspended { get; }

Property Value

Boolean:

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

Boolean:

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

protected virtual bool UseExtendedDoubleBuffering { get; }

Property Value

Boolean:

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

protected bool AddPendingGraphicsInversion(Rectangle bounds)

Parameter	Type	Description
bounds	Rectangle	A Rectangle specifying the bounds to invert.

Returns

Boolean:

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	Int32	The amount to scroll horizontally.
yAmount	Int32	The amount to scroll vertically.

Returns

Boolean:

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	Int32	The amount to scroll.

Returns

Boolean:

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	The final bounds of the element, relative to its parent.

Remarks

Override the ArrangeOverride(Size) method with custom arrange logic.

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

Boolean:

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 CreateChildren()

Returns

IList:

The IList 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	Boolean	Whether the object is being disposed.

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:

The Cursor that should be used when the mouse is over the element at the specified Point.

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 MeasureOverride(Graphics, Size) 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 virtual void OnDpiChangedAfterParent(EventArgs e)

Parameter	Type	Description
e	EventArgs	The event data.

protected virtual void OnDpiChangedBeforeParent(EventArgs e)

Parameter	Type	Description
e	EventArgs	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	An LayoutEventArgs that contains the event data.

protected override void OnLocationChanged(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	A MouseEventArgs 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	An PaintEventArgs that contains the event data.

Remarks

The default implementation of this event sets up a double-buffering canvas and simply calls the OnRender(PaintEventArgs) method.
It is sealed to prevent implementors from implementing it. All drawing code should be placed in the OnRender(PaintEventArgs) method.

protected override sealed void OnPaintBackground(PaintEventArgs e)

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

Remarks

The default implementation of this event does nothing.
It is sealed to prevent implementors from implementing it. All drawing code should be placed in the OnRender(PaintEventArgs) method.

protected virtual void OnParentChanged()

protected override void OnParentChanged(EventArgs e)

Parameter	Type	Description
e	EventArgs

protected virtual void OnRender(PaintEventArgs e)

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

protected virtual void OnRenderChildElements(PaintEventArgs e)

Parameter	Type	Description
e	PaintEventArgs	A PaintEventArgs that contains 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 that contains the event data.

public void Render(PaintEventArgs e)

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

protected virtual void RescaleConstantsForDpi(int deviceDpiOld, int deviceDpiNew)

Parameter	Type	Description
deviceDpiOld	Int32	The device DPI before the change.
deviceDpiNew	Int32	The device DPI after the change.

public void ResetDoubleBufferCanvas(bool recurse)

Parameter	Type	Description
recurse	Boolean	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:

A GeneralTransform from this element to a ancestor element.

public GeneralTransform TransformToDescendant(IUIElement descendant)

Parameter	Type	Description
descendant	IUIElement	The descendant IUIElement.

Returns

GeneralTransform:

A GeneralTransform from this element to a descendant element.

protected void UpdateCursor()

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.

protected override void WndProc(ref Message m)

Parameter	Type	Description
m	Message	Information about the message.

public event EventHandler DpiChangedAfterParent

Event Type

EventHandler

public event EventHandler DpiChangedBeforeParent

Event Type

EventHandler

bool IUIControl.AddPendingGraphicsInversion(Rectangle bounds)

Parameter	Type	Description
bounds	Rectangle	A Rectangle specifying the bounds to invert.

Returns

Boolean:

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

bool IUIControl.AddPendingScrollOperation(Rectangle bounds, int xAmount, int yAmount)

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

Returns

Boolean:

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

bool IUIControl.AddPendingScrollOperation(Rectangle bounds, Orientation orientation, int amount)

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

Returns

Boolean:

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

void IUIControl.AddToInvalidatedRegion(Rectangle rect)

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

bool IUIControl.Capture { get; set; }

Returns

Boolean:

true if the control has captured the mouse; otherwise, false.

IUIElement IUIControl.MouseCaptureElement { get; set; }

Returns

IUIElement:

The IUIElement for which mouse capture is being performed.

Rectangle IUIElement.Bounds { get; }

Returns

Rectangle:

A Rectangle specifying the bounds of the element.

Graphics IUIElement.CreateGraphics()

Returns

Graphics

UIElementDrawState IUIElement.GetDrawState()

Returns

UIElementDrawState:

The UIElementDrawState for the element.

Remarks

The default implementation of this method returns UIElementDrawState.None.

PointHitTestResult IUIElement.HitTest(PointHitTestParameters hitTestParams)

Parameter	Type	Description
hitTestParams	PointHitTestParameters	A PointHitTestParameters containing hit test parameters.

Returns

PointHitTestResult:

A PointHitTestResult containing the hit test result.

PointHitTestResult IUIElement.HitTest(PointHitTestParameters hitTestParams, Func<IUIElement, PointHitTestParameters, bool> filter)

Parameter	Type	Description
hitTestParams	PointHitTestParameters	A PointHitTestParameters containing hit test parameters.
filter	Func<IUIElement, PointHitTestParameters, Boolean>	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.

PointHitTestResult IUIElement.HitTestRecursive(PointHitTestParameters hitTestParams)

Parameter	Type	Description
hitTestParams	PointHitTestParameters	A PointHitTestParameters containing hit test parameters.

Returns

PointHitTestResult:

A PointHitTestResult containing the hit test result.

PointHitTestResult IUIElement.HitTestRecursive(PointHitTestParameters hitTestParams, Func<IUIElement, PointHitTestParameters, bool> filter)

Parameter	Type	Description
hitTestParams	PointHitTestParameters	A PointHitTestParameters containing hit test parameters.
filter	Func<IUIElement, PointHitTestParameters, Boolean>	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.

void IUIElement.NotifyChildDesiredSizeChanged()

void IUIElement.NotifyMouseLeaveEvent()

Remarks

This enables the object to cancel hot state tracking.

Size IUIElement.Size { get; }

Returns

Size:

The actual size of the element.

Remarks

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

Visibility IUIElement.Visibility { get; set; }

Returns

Visibility:

The Visibility of the element.

Point IUIElement.VisualOffset { get; }

Returns

Point:

The X/Y offset of the element relative to its parent element's coordinate system.

Remarks

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

IList ILogicalTreeNode.Children { get; }

Returns

IList:

The collection of child objects.

object ILogicalTreeNode.FindAncestor(Type type)

Parameter	Type	Description
type	Type	The Type of ancestor to located.

Returns

Object:

The Object ancestor that matches the Type.

ILogicalTreeNode ILogicalTreeNode.GetCommonAncestor(ILogicalTreeNode value)

Parameter	Type	Description
value	ILogicalTreeNode	The ILogicalTreeNode to compare.

Returns

ILogicalTreeNode:

The ILogicalTreeNode that is a common ancestor of both objects; otherwise null.

bool ILogicalTreeNode.IsAncestorOf(ILogicalTreeNode value)

Parameter	Type	Description
value	ILogicalTreeNode	The ILogicalTreeNode to compare.

Returns

Boolean:

true if the object is an ancestor of the specified object; otherwise, false.

bool ILogicalTreeNode.IsDescendantOf(ILogicalTreeNode value)

Parameter	Type	Description
value	ILogicalTreeNode	The ILogicalTreeNode to compare.

Returns

Boolean:

true if the object is a descendant of the specified object; otherwise, false.

ILogicalTreeNode ILogicalTreeNode.Parent { get; set; }

Returns

ILogicalTreeNode:

The object that is parent to this object.

Remarks

The setter of this property is reserved for internal use only.