In This Article

UIControl Class

Provides base functionality for controls that wish to work with IUIElement objects.

public abstract class UIControl : ScrollableControl, IUIControl, IUIElement, ILogicalTreeNode, IDisposable
Inheritance:
Object Object
Derived:
BarDockArea StatusBar ToolBar ColorPalettePicker AutoHideTabStripPanel DockContainer TabbedMdiContainer TabbedMdiRootContainer TabStrip MarkupLabel NavigationBar NavigationBarPanel ScrollBar CommandButton IntelliPromptCodeSnippetSelector IntelliPromptCompletionList SearchViewBase SyntaxEditor TextStylePreview
Implements:
IUIControl IUIElement ILogicalTreeNode IDisposable

Constructors

UIControl()

Initializes a new instance of the UIControl class.

public UIControl()

Remarks

The default constructor initializes all fields to their default values.

Properties

ActualHeight

Gets the actual height of the element.

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.

ActualWidth

Gets the actual width of the element.

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.

BackColor

Gets or sets the background color for the control.

public override Color BackColor { get; set; }

Property Value

Color:

A Color that represents the background color of the control.

BackgroundImage

Gets or sets the background image displayed in 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.

CaptureMouseWhenPressed

Indicates whether to automatically capture the mouse when the element is pressed.

protected virtual bool CaptureMouseWhenPressed { get; }

Property Value

Boolean:

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

ClipBounds

Gets a Rectangle specifying the clip bounds when drawing the element.

public virtual Rectangle ClipBounds { get; }

Property Value

Rectangle:

A Rectangle specifying the clip bounds when drawing the element.

DesiredSize

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

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.

Font

Gets or sets the font of the text displayed by the control.

public override Font Font { get; set; }

Property Value

Font:

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

ForeColor

Gets or sets the foreground color for the control.

public override Color ForeColor { get; set; }

Property Value

Color:

A Color that represents the foreground color of the control.

IsArrangeValid

Gets whether the value of the DesiredSize property and position of child elements is valid.

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.

IsMeasureValid

Gets whether the value of the DesiredSize property is 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.

IsPaintValid

Gets whether the control has rendered itself and doesn't have any invalidated paint regions.

public bool IsPaintValid { get; }

Property Value

Boolean:

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

IsRightToLeft

Gets whether the control is using a right-to-left layout.

public bool IsRightToLeft { get; }

Property Value

Boolean:

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

LastMouseUpButton

Gets the MouseButtons indicating the last mouse button that was released.

protected MouseButtons LastMouseUpButton { get; }

Property Value

MouseButtons:

The MouseButtons indicating the last mouse button that was released.

PaintingSuspended

Gets whether the control is painting itself.

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.

UseControlGraphicsForMeasure

Gets or sets whether to use a call to the control's CreateGraphics method to obtain the Graphics used for measure routines.

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.

UseExtendedDoubleBuffering

Gets or sets whether to use extended double buffering for rendering.

protected virtual bool UseExtendedDoubleBuffering { get; }

Property Value

Boolean:

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

Methods

AddPendingGraphicsInversion(Rectangle)

Inverts the canvas using XOR at the end of the current or next drawing operation.

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.

AddPendingScrollOperation(Rectangle, Int32, Int32)

Scrolls the canvas the specified amount at the beginning of the next drawing operation.

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.

AddPendingScrollOperation(Rectangle, Orientation, Int32)

Scrolls the canvas the specified amount at the beginning of the next drawing operation.

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.

AddToInvalidatedRegion()

Adds the bounds of the control to the invalidated region.

public void AddToInvalidatedRegion()

AddToInvalidatedRegion(Rectangle)

Adds a Rectangle to the invalidated region.

public void AddToInvalidatedRegion(Rectangle rect)
Parameter Type Description
rect Rectangle

The Rectangle to add to the invalidated region.

Arrange(Rectangle)

Positions child elements and determines a size for the IUIElement.

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.

ArrangeOverride(Size)

Positions child elements and determines an arrange size.

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.

ContainsLocation(Point)

Used with hit-testing, returning whether this element's bounds contains the specified location.

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.

CreateChildren()

Invoked when the collection of child elements is to be created.

protected virtual IList CreateChildren()

Returns

IList:

The IList that should be assigned to the Children property.

Remarks

By default no child collection is created.

Dispose(Boolean)

Disposes any resources used by the object.

protected override void Dispose(bool disposing)
Parameter Type Description
disposing Boolean

Whether the object is being disposed.

GetCursor(Point)

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

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.

Invalidate(InvalidationLevels, InvalidationTypes)

Invalidates the specified states for the element or its related elements.

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.

InvalidateArrange()

Invalidates the layout of the element.

public void InvalidateArrange()

InvalidateMeasure()

Invalidates the measurement of the element.

public void InvalidateMeasure()

Measure(Graphics, Size)

Measures the element and updates the DesiredSize property.

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.

MeasureOverride(Graphics, Size)

Measures the size in layout required for child elements and determines a size for the element itself.

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.

OnClick(EventArgs)

Raises the Click event.

protected override void OnClick(EventArgs e)
Parameter Type Description
e EventArgs

An EventArgs that contains the event data.

OnDoubleClick(EventArgs)

Raises the DoubleClick event.

protected override void OnDoubleClick(EventArgs e)
Parameter Type Description
e EventArgs

An EventArgs that contains the event data.

OnHandleCreated(EventArgs)

Raises the HandleCreated event.

protected override void OnHandleCreated(EventArgs e)
Parameter Type Description
e EventArgs

An EventArgs that contains the event data.

OnLayout(LayoutEventArgs)

Raises the Layout event.

protected override void OnLayout(LayoutEventArgs e)
Parameter Type Description
e LayoutEventArgs

An LayoutEventArgs that contains the event data.

OnLocationChanged(EventArgs)

Raises the LocationChanged event.

protected override void OnLocationChanged(EventArgs e)
Parameter Type Description
e EventArgs

An EventArgs that contains the event data.

OnMouseDown(MouseEventArgs)

Raises the MouseDown event.

protected override void OnMouseDown(MouseEventArgs e)
Parameter Type Description
e MouseEventArgs

A MouseEventArgs that contains the event data.

OnMouseEnter(EventArgs)

Raises the MouseEnter event.

protected override void OnMouseEnter(EventArgs e)
Parameter Type Description
e EventArgs

An EventArgs that contains the event data.

OnMouseHover(EventArgs)

Raises the MouseHover event.

protected override void OnMouseHover(EventArgs e)
Parameter Type Description
e EventArgs

A MouseEventArgs that contains the event data.

OnMouseLeave(EventArgs)

Raises the MouseLeave event.

protected override void OnMouseLeave(EventArgs e)
Parameter Type Description
e EventArgs

An EventArgs that contains the event data.

OnMouseMove(MouseEventArgs)

Raises the MouseMove event.

protected override void OnMouseMove(MouseEventArgs e)
Parameter Type Description
e MouseEventArgs

A MouseEventArgs that contains the event data.

OnMouseUp(MouseEventArgs)

Raises the MouseUp event.

protected override void OnMouseUp(MouseEventArgs e)
Parameter Type Description
e MouseEventArgs

A MouseEventArgs that contains the event data.

OnMouseWheel(MouseEventArgs)

Raises the MouseWheel event.

protected override void OnMouseWheel(MouseEventArgs e)
Parameter Type Description
e MouseEventArgs

A MouseEventArgs that contains the event data.

OnPaint(PaintEventArgs)

Raises the Paint event.

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.

OnPaintBackground(PaintEventArgs)

Raises the PaintBackground event.

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.

OnParentChanged()

Invoked when logical parent is changed. This is invoked after the parent has changed, and the purpose is to allow elements to perform actions based on the changed parent.

protected virtual void OnParentChanged()

OnRender(PaintEventArgs)

Renders the element.

protected virtual void OnRender(PaintEventArgs e)
Parameter Type Description
e PaintEventArgs

A PaintEventArgs that contains the event data.

OnRenderChildElements(PaintEventArgs)

Renders the child elements.

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.

OnResize(EventArgs)

Raises the Resize event.

protected override void OnResize(EventArgs e)
Parameter Type Description
e EventArgs

An EventArgs that contains the event data.

OnRightToLeftChanged(EventArgs)

Raises the RightToLeftChanged event.

protected override void OnRightToLeftChanged(EventArgs e)
Parameter Type Description
e EventArgs

An EventArgs that contains the event data.

OnVisibleChanged(EventArgs)

Raises the VisibleChanged event.

protected override void OnVisibleChanged(EventArgs e)
Parameter Type Description
e EventArgs

An EventArgs that contains the event data.

Render(PaintEventArgs)

Renders the element.

public void Render(PaintEventArgs e)
Parameter Type Description
e PaintEventArgs

A PaintEventArgs that contains the event data.

ResetDoubleBufferCanvas(Boolean)

Resets the double-buffer canvas.

public void ResetDoubleBufferCanvas(bool recurse)
Parameter Type Description
recurse Boolean

Whether to recurse down into the child control tree.

ResumePainting()

Allows the control to paint itself by clearing the PaintingSuspended flag.

public void ResumePainting()

See Also

SuspendPainting()

Prevents the control from painting itself by setting the PaintingSuspended flag.

public void SuspendPainting()

See Also

TransformToAncestor(IUIElement)

Returns a GeneralTransform from this element to an ancestor element.

public GeneralTransform TransformToAncestor(IUIElement ancestor)
Parameter Type Description
ancestor IUIElement

The ancestor IUIElement.

Returns

GeneralTransform:

A GeneralTransform from this element to a ancestor element.

TransformToDescendant(IUIElement)

Returns a GeneralTransform from this element to a descendant 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.

UpdateLayout()

Call this method to ensure that the whole subtree of elements that includes this UIElement is properly updated.

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.

Explicit Interface Implementations

IUIControl.AddPendingGraphicsInversion(Rectangle)

Inverts the canvas using XOR at the end of the current or next drawing operation.

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.

IUIControl.AddPendingScrollOperation(Rectangle, Int32, Int32)

Scrolls the canvas the specified amount at the beginning of the next drawing operation.

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.

IUIControl.AddPendingScrollOperation(Rectangle, Orientation, Int32)

Scrolls the canvas the specified amount at the beginning of the next drawing operation.

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.

IUIControl.AddToInvalidatedRegion(Rectangle)

Adds a Rectangle to the invalidated region.

void IUIControl.AddToInvalidatedRegion(Rectangle rect)
Parameter Type Description
rect Rectangle

The Rectangle to add to the invalidated region.

IUIControl.Capture

Gets or sets a value indicating whether the control has captured the mouse.

bool IUIControl.Capture { get; set; }

Returns

Boolean:

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

IUIControl.MouseCaptureElement

Indicates the IUIElement for which mouse capture is being performed.

IUIElement IUIControl.MouseCaptureElement { get; set; }

Returns

IUIElement:

The IUIElement for which mouse capture is being performed.

IUIElement.Bounds

Gets a Rectangle specifying the bounds of the element.

Rectangle IUIElement.Bounds { get; }

Returns

Rectangle:

A Rectangle specifying the bounds of the element.

IUIElement.CreateGraphics()

Graphics IUIElement.CreateGraphics()

Returns

Graphics

IUIElement.GetDrawState()

Gets the UIElementDrawState for the element.

UIElementDrawState IUIElement.GetDrawState()

Returns

UIElementDrawState:

The UIElementDrawState for the element.

Remarks

The default implementation of this method returns UIElementDrawState.None.

IUIElement.HitTest(PointHitTestParameters)

Hit tests to find the IUIElement that contains the specified coordinates.

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.

IUIElement.HitTest(PointHitTestParameters, Func<IUIElement, PointHitTestParameters, Boolean>)

Hit tests to find the IUIElement that contains the specified coordinates.

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.

IUIElement.HitTestRecursive(PointHitTestParameters)

Recursively hit tests to find the IUIElement that contains the specified coordinates.

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.

IUIElement.HitTestRecursive(PointHitTestParameters, Func<IUIElement, PointHitTestParameters, Boolean>)

Recursively hit tests to find the IUIElement that contains the specified coordinates.

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.

IUIElement.NotifyChildDesiredSizeChanged()

Notifies that a child object's desired size has changed.

void IUIElement.NotifyChildDesiredSizeChanged()

IUIElement.NotifyMouseLeaveEvent()

Notifies the object of a a mouse leave event.

void IUIElement.NotifyMouseLeaveEvent()

Remarks

This enables the object to cancel hot state tracking.

IUIElement.Size

Gets the actual size of the element.

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.

IUIElement.Visibility

Gets or sets the Visibility of the element.

Visibility IUIElement.Visibility { get; set; }

Returns

Visibility:

The Visibility of the element.

IUIElement.VisualOffset

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

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.

ILogicalTreeNode.Children

Gets the collection of child objects.

IList ILogicalTreeNode.Children { get; }

Returns

IList:

The collection of child objects.

ILogicalTreeNode.FindAncestor(Type)

Loops up the parent chain to locate an ancestor of the specified Type.

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.GetCommonAncestor(ILogicalTreeNode)

Gets the common ancestor of the two object.

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.

ILogicalTreeNode.IsAncestorOf(ILogicalTreeNode)

Gets whether the object is an ancestor to the specified object.

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.

ILogicalTreeNode.IsDescendantOf(ILogicalTreeNode)

Gets whether the object is a descendant of the specified object.

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.Parent

Gets or sets the object that is parent to this object.

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.