Knowledge Base Article: KB05510

Summary

Infragistics controls for Windows Forms Applications are highly extensible. Through the use of UIElements, a developer can easily add functionality that isn't inherently supported by Infragistics controls.

Additional Information

Almost all Infragistics controls are composed of many levels of nested UIElements...

For example, an UltraTree control is made up of an UltraTreeUIElement, containing a NodeClientAreaUIElement, containing many TreeNodeUIElements and NodeConnectorUIElements. The TreeNodeUIElements are made up of PreNodeAreaUIElements and NodeSelectableAreaUIElements, which in turn can contain ExpansionIndicatorUIElements and NodeTexUIElements, respectively.

All of these UIElements can be manipulated to change their appearance and/or location through Creation Filters and Draw Filters. Creation Filters can also be used to remove existing UIElements or add new ones, including custom UIElements designed by the application developer.

This article explains and demonstrates how to create custom UIElements to be inserted into existing Infragistics controls in a Windows Forms user interface.

Step-By-Step Example

1. Implement a CreationFilter through the IUIElementCreationFilter interface.


The IUIElementCreationFilter interface can be implemented in any class, but for simplicity, this example implements this interface alone, in its own class.

IUIElementCreationFilter contains two methods: BeforeCreateChildElements and AfterCreateChildElements. The BeforeCreateChildElements method is called for each UIElement just after it's created. After this, the UIElement will, if appropriate create other "child" UIElements. After a "parent" has finished creating all of its child UIElements, the AfterCreateChildElements method is called.

VB.NET:


Imports Infragistics.Win.UltraWinExplorerBar Public Class MyUltraExplorerBarCreationFilter     Implements IUIElementCreationFilter     Public Sub AfterCreateChildElements(ByVal parent As UIElement) Implements IUIElementCreationFilter.AfterCreateChildElements         ' called for a UIElement (parent) after it creates its child elements.     End Sub     Public Function BeforeCreateChildElements(ByVal parent As UIElement) As Boolean Implements UIElementCreationFilter.BeforeCreateChildElements         ' called for a UIElement (parent) before it creates its child elements.         Return False     End Function End Class

C#:


using Infragistics.Win; public class MyUltraExplorerBarCreationFilter : IUIElementCreationFilter {     public void AfterCreateChildElements(UIElement parent)     {         // called for a UIElement (parent) after it creates its child elements.     }     public bool BeforeCreateChildElements(UIElement parent)     {         // called for a UIElement (parent) before it creates its child elements.         return false;     } }

2. Attach the CreationFilter to an Infragistics Control using its CreationFilter property.


All that's needed to cause a CreationFilter to handle the creation of all UIElements within a control is to set that control's CreationFilter property:

VB.NET:


Protected WithEvents theUltraExplorerBarCreationFilter As New MyUltraExplorerBarCreationFilter Private Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs) Handles MyBase.Load     UltraExplorerBar1.CreationFilter = theUltraExplorerBarCreationFilter End Sub

C#:


private MyUltraExplorerBarCreationFilter theUltraExplorerBarCreationFilter = new MyUltraExplorerBarCreationFilter(); private void Form1_Load(object sender, EventArgs e) {     ultraExplorerBar1.CreationFilter = theUltraExplorerBarCreationFilter; }

3. Create a custom UIElement class.

The custom UIElement will be designed to meet the needs of the application. As a starting point, choose a similar UIElement to inherit from. If a custom scrollbar is needed for an UltraTree, inherit Infragistics.Win.UltraWinTree.VerticalScrollbarUIElement or Infragistics.Win.UltraWinScrollBar.ScrollBarUIElement. This demonstration inherits from Infragistics.Win.ImageAndTextButtonUIElement to create an all-purpose clickable area with an image.


4. Write code in the custom UIElement class to define the behavior of the UIElement.


This is done mainly by overriding methods, but properties can also be overridden or added.

Following is a complete example of a custom UIElement class. Overrides are used to raise a click event, prevent the UIElement from drawing Borders, a BackColor, and Themed appearance. Overrides and an event are used to handle the UIElement's Click behavior. Properties are added to store and return data for the calling object (the CreationFilter).

VB.NET:


Imports Infragistics.Win Public Class MyUIElement     Inherits ImageAndTextButtonUIElement     Public Sub New(ByVal parent As UIElement)         MyBase.New(parent)     End Sub     Public Event MyClick(ByVal sender As Object, ByVal e As UIElementEventArgs)     Protected Overrides Function ButtonClick() As Boolean             RaiseEvent MyClick(Me, New UIElementEventArgs(Me))     End Function     Private _tag As Object     Private _altTag As Object     Public Property Tag() As Object         Get             Return _tag         End Get         Set(ByVal Value As Object)             _tag = Value         End Set     End Property     Public Property AltTag() As Object         Get             Return _altTag         End Get         Set(ByVal Value As Object)             _alttag = Value         End Set     End Property     Protected Overrides Function DrawTheme(ByRef drawParams As UIElementDrawParams) As Boolean         ' disable themes for this UIElement.         Return False     End Function     Protected Overrides Sub DrawBorders(ByRef drawParams As Infragistics.Win.UIElementDrawParams)         ' disable borders for this UIElement.         Return     End Sub     Protected Overrides Sub DrawBackColor(ByRef drawParams As UIElementDrawParams)         ' disable backcolor for this UIElement         Return     End Sub     Protected Overrides Sub OnDispose()         MyBase.Dispose()     End Sub End Class

C#:


using System; using Infragistics.Win; public delegate void MyClickEventHandler(object sender, UIElementEventArgs e); public class MyUIElement : ImageAndTextButtonUIElement {     public MyUIElement(UIElement parent) : base(parent)     {     }     public event MyClickEventHandler MyClick;     public void RaiseMyClick(object sender, UIElementEventArgs e)     {         this.MyClick(sender, e);     }     private object tag;     private object altTag;     public object Tag     {         get         {             return tag;         }         set         {             tag = value;         }     }     public object AltTag     {         get         {             return altTag;         }         set         {             altTag = value;         }     }          protected override bool DrawTheme(ref UIElementDrawParams drawParams)     {         // disable themes for this UIElement.         return false;     }     protected override void DrawBorders(ref UIElementDrawParams drawParams)     {         // disable borders for this UIElement.         return;     }     protected override void DrawBackColor(ref UIElementDrawParams drawParams)     {         // disable backcolor for this UIElement         return;     }     protected override bool ButtonClick()     {         this.MyClick(this, new UIElementEventArgs(this));         return false;     } }

Related Articles

HOWTO: Create Custom Row Expansion Indicators in WinGrid with Creation Filters (KB05684) HOWTO: Remove the Last AddNew Button In The WinGrid (KB06104) HOWTO: Create Custom UIElements and use CreationFilters to embed them in Infragistics Win Controls, Part 2 (KB05521) HOWTO: Create Custom UIElements and use CreationFilters to embed them in Infragistics Win Controls, Part 3 (KB05520)

Samples