UIControl Class
Provides base functionality for controls that wish to work with IUIElement objects.
public abstract class UIControl : ScrollableControl, IUIControl, IUIElement, ILogicalTreeNode, IDpiAwareElement, IDisposable
- Inheritance:
- object MarshalByRefObject Component Control ScrollableControl object
- Derived:
- BarDockArea StatusBar ToolBar ColorPalettePicker AutoHideTabStripPanel DockContainer TabStrip TabbedMdiContainer TabbedMdiRootContainer MarkupLabel NavigationBar NavigationBarPanel ScrollBar OverlayPaneBase CommandButton IntelliPromptCodeSnippetSelector IntelliPromptCompletionList SearchViewBase SyntaxEditor TextStylePreview
- Implements:
- IUIControl IUIElement ILogicalTreeNode IDpiAwareElement 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.
[Browsable(false)]
public int ActualHeight { get; }
Property Value
- int:
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.
[Browsable(false)]
public int ActualWidth { get; }
Property Value
- int:
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.
[Browsable(false)]
public override Color BackColor { get; set; }
Property Value
BackgroundImage
Gets or sets the background image displayed in the control.
[Browsable(false)]
public override Image BackgroundImage { get; set; }
Property Value
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
Gets a Rectangle specifying the clip bounds when drawing the element.
[Browsable(false)]
public virtual Rectangle ClipBounds { get; }
Property Value
DesiredSize
Gets the desired size of the element as computed by Measure(Graphics, Size).
[Browsable(false)]
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
.
DpiScaleFactor
Gets 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
See Also
Font
Gets or sets the font of the text displayed by the control.
[Browsable(false)]
public override Font Font { get; set; }
Property Value
ForeColor
Gets or sets the foreground color for the control.
[Browsable(false)]
public override Color ForeColor { get; set; }
Property Value
IsArrangeValid
Gets 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
Gets 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.
IsPaintValid
Gets whether the control has rendered itself and doesn't have any invalidated paint regions.
[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
.
IsRightToLeft
Gets whether the control is using a right-to-left layout.
[Browsable(false)]
public bool IsRightToLeft { get; }
Property Value
- bool:
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.
[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.
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
- bool:
true
if the control'sCreateGraphics
method should be called; otherwise,false
. The default value istrue
.
UseExtendedDoubleBuffering
Gets or sets whether to use extended double buffering for rendering.
protected virtual bool UseExtendedDoubleBuffering { get; }
Property Value
- bool:
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 |
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
.
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 |
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
- 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.
CreateChildren()
Invoked when the collection of child elements is to be created.
protected virtual IList CreateChildren()
Returns
Remarks
By default no child collection is created.
Dispose(bool)
Disposes any resources used by the object.
protected override void Dispose(bool disposing)
Parameter | Type | Description |
---|---|---|
disposing | bool | Whether the object is being disposed. |
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)
public virtual Cursor GetCursor(Point point)
Parameter | Type | Description |
---|---|---|
point | Point | The Point to examine. |
Returns
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 |
OnDoubleClick(EventArgs)
Raises the DoubleClick
event.
protected override void OnDoubleClick(EventArgs e)
Parameter | Type | Description |
---|---|---|
e | EventArgs | An |
OnDpiChangedAfterParent(EventArgs)
Raises the DpiChangedAfterParent event.
protected override void OnDpiChangedAfterParent(EventArgs e)
Parameter | Type | Description |
---|---|---|
e | EventArgs | An DpiChangedEventArgs that contains the event data. |
OnHandleCreated(EventArgs)
Raises the HandleCreated
event.
protected override void OnHandleCreated(EventArgs e)
Parameter | Type | Description |
---|---|---|
e | EventArgs | An |
OnLayout(LayoutEventArgs)
Raises the Layout
event.
protected override void OnLayout(LayoutEventArgs e)
Parameter | Type | Description |
---|---|---|
e | LayoutEventArgs | An |
OnLocationChanged(EventArgs)
Raises the LocationChanged
event.
protected override void OnLocationChanged(EventArgs e)
Parameter | Type | Description |
---|---|---|
e | EventArgs | An |
OnMouseCaptureChanged(EventArgs)
Raises the MouseCaptureChanged
event.
protected override void OnMouseCaptureChanged(EventArgs e)
Parameter | Type | Description |
---|---|---|
e | EventArgs | The |
OnMouseDown(MouseEventArgs)
Raises the MouseDown
event.
protected override void OnMouseDown(MouseEventArgs e)
Parameter | Type | Description |
---|---|---|
e | MouseEventArgs | A |
OnMouseEnter(EventArgs)
Raises the MouseEnter
event.
protected override void OnMouseEnter(EventArgs e)
Parameter | Type | Description |
---|---|---|
e | EventArgs | An |
OnMouseHover(EventArgs)
Raises the MouseHover
event.
protected override void OnMouseHover(EventArgs e)
Parameter | Type | Description |
---|---|---|
e | EventArgs | A |
OnMouseLeave(EventArgs)
Raises the MouseLeave
event.
protected override void OnMouseLeave(EventArgs e)
Parameter | Type | Description |
---|---|---|
e | EventArgs | An |
OnMouseMove(MouseEventArgs)
Raises the MouseMove
event.
protected override void OnMouseMove(MouseEventArgs e)
Parameter | Type | Description |
---|---|---|
e | MouseEventArgs | A |
OnMouseUp(MouseEventArgs)
Raises the MouseUp
event.
protected override void OnMouseUp(MouseEventArgs e)
Parameter | Type | Description |
---|---|---|
e | MouseEventArgs | A |
OnMouseWheel(MouseEventArgs)
Raises the MouseWheel
event.
protected override void OnMouseWheel(MouseEventArgs e)
Parameter | Type | Description |
---|---|---|
e | MouseEventArgs | A |
OnPaint(PaintEventArgs)
Raises the Paint
event.
protected override sealed void OnPaint(PaintEventArgs e)
Parameter | Type | Description |
---|---|---|
e | PaintEventArgs | An |
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 |
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()
OnParentChanged(EventArgs)
Raises the ParentChanged event.
protected override void OnParentChanged(EventArgs e)
Parameter | Type | Description |
---|---|---|
e | EventArgs | An EventArgs that contains the event data. |
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 |
OnRightToLeftChanged(EventArgs)
Raises the RightToLeftChanged
event.
protected override void OnRightToLeftChanged(EventArgs e)
Parameter | Type | Description |
---|---|---|
e | EventArgs | An |
OnVisibleChanged(EventArgs)
Raises the VisibleChanged
event.
protected override void OnVisibleChanged(EventArgs e)
Parameter | Type | Description |
---|---|---|
e | EventArgs | An |
Render(PaintEventArgs)
Renders the element.
public void Render(PaintEventArgs e)
Parameter | Type | Description |
---|---|---|
e | PaintEventArgs | A PaintEventArgs that contains the event data. |
ResetDoubleBufferCanvas(bool)
Resets the double-buffer canvas.
public void ResetDoubleBufferCanvas(bool recurse)
Parameter | Type | Description |
---|---|---|
recurse | bool | Whether to recurse down into the child control tree. |
ResumePainting()
Allows the control to paint itself by clearing the PaintingSuspended flag.
SuspendPainting()
Prevents the control from painting itself by setting the PaintingSuspended flag.
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.
UpdateCursor()
Updates the Cursor
property based on the current mouse position.
protected void UpdateCursor()
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.
Inherited Members
- MarshalByRefObject.GetLifetimeService()
- MarshalByRefObject.InitializeLifetimeService()
- MarshalByRefObject.MemberwiseClone(bool)
- object.GetType()
- object.MemberwiseClone()
- object.ToString()
- object.Equals(object)
- object.Equals(object, object)
- object.ReferenceEquals(object, object)
- object.GetHashCode()
Extension Methods
- DpiAwareElementExtensions.AutoScaleFont(IDpiAwareElement, Font)
- DpiAwareElementExtensions.AutoScaleFontSize(IDpiAwareElement, float)
- DpiAwareElementExtensions.ScaleLogicalValue(IDpiAwareElement, Padding)
- DpiAwareElementExtensions.ScaleLogicalValue(IDpiAwareElement, Point)
- DpiAwareElementExtensions.ScaleLogicalValue(IDpiAwareElement, Rectangle)
- DpiAwareElementExtensions.ScaleLogicalValue(IDpiAwareElement, Size)
- DpiAwareElementExtensions.ScaleLogicalValue(IDpiAwareElement, SizeF)
- DpiAwareElementExtensions.ScaleLogicalValue(IDpiAwareElement, int)
- DpiAwareElementExtensions.ScaleLogicalValue(IDpiAwareElement, float)
- DpiAwareElementExtensions.ScaleLogicalValue(IDpiAwareElement, Padding)
- DpiAwareElementExtensions.SynchronizeScaleFactorWithChildren(IDpiAwareElement)
- ControlExtensions.FindAncestorOrSelf<T>(Control)
- ControlExtensions.FindAncestorOrSelf<T>(Control, Predicate<T>)
- ControlExtensions.FindAncestor<T>(Control)
- ControlExtensions.FindAncestor<T>(Control, Predicate<T>)