Not logged in▾
Log In Register
Forgot Password Resend Validation E-mail
In This Article

UIElement Class

Namespace:
ActiproSoftware.UI.WinForms.Controls.Primitives
Assembly:
ActiproSoftware.Shared.WinForms.dll

Represents a base object that has a user interface and implements IUIElement.

public class UIElement : LogicalTreeNodeBase, IInputElement, IUIElement, ILogicalTreeNode, IDpiAwareElement, IDisposable
Inheritance:
object MarshalByRefObject MarshalByRefDisposableObject LogicalTreeNodeBase object
Derived:
BarCommandLink DockableToolBar DockableToolBarRow StatusBarPanel AutoHideTab AutoHideTabGroup DockContainerTitleBarButton TabStripButton TabStripTab MarkupLabelUIElement NavigationBarOverflowMenuButton NavigationPaneButton CanvasControl ScrollBarButton ScrollBarThumb CollapsedRegionAdornment EditorViewHost EditorViewMarginBase EditorViewSelectionGripper EditorViewSplitter PrinterViewMarginBase ScrollBarBlock ScrollBarSplitter TextView UIElementComponent WizardButtonContainer WizardInteriorPageHeader
Implements:
IInputElement IUIElement ILogicalTreeNode IDpiAwareElement IDisposable

Constructors

UIElement()

Initializes an instance of the class.

public UIElement()

Properties

ActualHeight

The actual height of the element.

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

ActualWidth

The actual width of the element.

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

Bounds

A Rectangle specifying the bounds of the element.

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

Property Value

Rectangle

CaptureMouseWhenPressed

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

protected virtual bool CaptureMouseWhenPressed { get; }

Property Value

bool:

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

ClipBounds

A Rectangle specifying the clip bounds when drawing the element.

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

Property Value

Rectangle

DesiredSize

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

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

Property Value

Size

Remarks

This is only valid if IsMeasureValid is true.

DpiScaleFactor

The current DPI-based scale factor to be applied when rendering the element, where Width is applied to the x-axis, and Height is applied to the y-axis.

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

Property Value

SizeF

See Also

InvalidateOnMouseEvents

Indicates whether to invalidate the element when mouse events occur.

protected virtual bool InvalidateOnMouseEvents { get; }

Property Value

bool:

true if the element should be invalidated when mouse events occur; otherwise, false.

IsArrangeValid

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

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

IsMeasureValid

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

IsMouseCaptured

Indicates whether the element is currently capturing the mouse.

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

Property Value

bool:

true if the element is currently capturing the mouse; otherwise, false.

IsMouseDirectlyOver

Indicates whether the mouse is directly over the element.

protected bool IsMouseDirectlyOver { get; }

Property Value

bool:

true if the mouse is directly over the element; otherwise, false.

IsRightToLeft

Indicates whether the element is using a right-to-left layout.

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

Property Value

bool:

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

Size

The actual size of the element.

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

Property Value

Size

Remarks

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

VisualOffset

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

[Browsable(false)]
public Point VisualOffset { get; }

Property Value

Point

Remarks

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

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

The bounds to invert.

Returns

bool:

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

AddPendingScrollOperation(Rectangle, int, int)

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

AddPendingScrollOperation(Rectangle, Orientation, int)

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 int

The amount to scroll.

Returns

bool:

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

Arrange(Rectangle)

Positions child elements and determines a size for the IUIElement.

public void Arrange(Rectangle finalRect)
Parameter Type Description
finalRect Rectangle

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.

CaptureMouse()

Attaches the mouse capture to the element.

public void CaptureMouse()

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

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.

CreateGraphics()

Creates the Graphics object for the use with the object.

public Graphics? CreateGraphics()

Returns

Graphics

Dispose(bool)

Releases the unmanaged resources used by the object and optionally releases the managed resources.

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.

Remarks

This method is called by the public Dispose method and the Finalize method. Dispose invokes this method with the disposing parameter set to true. Finalize invokes this method with disposing set to false.

DpiScaleChanged(SizeF)

Called when the DPI-based scale factor of the element changes.

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

GetCursor(Point)

Returns 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

GetDrawState()

The UIElementDrawState for the element.

public virtual UIElementDrawState GetDrawState()

Returns

UIElementDrawState

Remarks

The default implementation of this method returns None.

Invalidate()

Invalidates the area of the object and causes it to be repainted.

public void Invalidate()

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.

Invalidate(Rectangle)

Invalidates an area in the object and causes it to be repainted.

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

The bounds of the rectangle to invalidate.

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

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

Raises the Click event.

protected virtual void OnClick(MouseEventArgs e)
Parameter Type Description
e MouseEventArgs

The event data.

OnDoubleClick(MouseEventArgs)

Raises the DoubleClick event.

protected virtual void OnDoubleClick(MouseEventArgs e)
Parameter Type Description
e MouseEventArgs

The event data.

OnMouseCaptureLost(EventArgs)

Raises the MouseCaptureLost event.

protected virtual void OnMouseCaptureLost(EventArgs e)
Parameter Type Description
e EventArgs

The event data.

OnMouseDown(MouseEventArgs)

Raises the MouseDown event.

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

The event data.

OnMouseEnter(MouseEventArgs)

Raises the MouseEnter event.

protected virtual void OnMouseEnter(MouseEventArgs e)
Parameter Type Description
e MouseEventArgs

The event data.

OnMouseHover(MouseEventArgs)

Raises the MouseHover event.

protected virtual void OnMouseHover(MouseEventArgs e)
Parameter Type Description
e MouseEventArgs

The event data.

OnMouseLeave(MouseEventArgs)

Raises the MouseLeave event.

protected virtual void OnMouseLeave(MouseEventArgs e)
Parameter Type Description
e MouseEventArgs

The event data.

OnMouseMove(MouseEventArgs)

Raises the MouseMove event.

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

The event data.

OnMouseUp(MouseEventArgs)

Raises the MouseUp event.

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

The event data.

OnMouseWheel(MouseEventArgs)

Raises the MouseWheel event.

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

The event data.

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 override void OnParentChanged()

OnRender(PaintEventArgs)

Renders the element.

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

The event data.

OnRenderChildElements(PaintEventArgs)

Renders the child elements.

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.

OnResize(EventArgs)

Raises the Resize event.

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

The event data.

PostArrangeOverride()

Allows custom logic to be executed following a successful call to the ArrangeOverride(Size) method.

protected virtual void PostArrangeOverride()

ReleaseMouseCapture()

Releases the mouse capture, if any.

public void ReleaseMouseCapture()

Render(PaintEventArgs)

Renders the element.

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

The event data.

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

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

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.

Events

Click

Occurs when the object is clicked.

public event MouseEventHandler? Click

Event Type

MouseEventHandler

DoubleClick

Occurs when the object is double-clicked.

public event MouseEventHandler? DoubleClick

Event Type

MouseEventHandler

MouseCaptureLost

Occurs when the mouse loses capture.

public event EventHandler? MouseCaptureLost

Event Type

EventHandler

MouseDown

Occurs when the mouse pointer is over the object and a mouse button is pressed.

public event MouseEventHandler? MouseDown

Event Type

MouseEventHandler

MouseEnter

Occurs when the mouse pointer enters the object.

public event MouseEventHandler? MouseEnter

Event Type

MouseEventHandler

MouseHover

Occurs when the mouse pointer hovers over the object.

public event MouseEventHandler? MouseHover

Event Type

MouseEventHandler

MouseLeave

Occurs when the mouse pointer leaves the object.

public event MouseEventHandler? MouseLeave

Event Type

MouseEventHandler

MouseMove

Occurs when the mouse pointer is moved over the object.

public event MouseEventHandler? MouseMove

Event Type

MouseEventHandler

MouseUp

Occurs when the mouse pointer is over the object and a mouse button is released.

public event MouseEventHandler? MouseUp

Event Type

MouseEventHandler

MouseWheel

Occurs when the mouse wheel moves while the object has focus.

public event MouseEventHandler? MouseWheel

Event Type

MouseEventHandler

Resize

Occurs when the object is resized.

public event EventHandler? Resize

Event Type

EventHandler

Inherited Members

Extension Methods