This documentation is archived and is not being maintained.

IPropertyValueUIService Interface

Provides an interface to manage the images, ToolTips, and event handlers for the properties of a component displayed in a property browser.

For a list of all members of this type, see IPropertyValueUIService Members.

[Visual Basic]
Public Interface IPropertyValueUIService
[C#]
public interface IPropertyValueUIService
[C++]
public __gc __interface IPropertyValueUIService
[JScript]
public interface IPropertyValueUIService

Remarks

A component can use the IPropertyValueUIService interface to provide PropertyValueUIItem objects for any properties of the component. A PropertyValueUIItem associated with a property can provide an image, a ToolTip and an event handler for the event that is raised when the image associated with the property is clicked.

The IPropertyValueUIService interface provides methods to add, remove, and retrieve PropertyValueUIHandler delegates to or from an internal list. When the properties of a component are displayed in a property browser, each PropertyValueUIHandler in the list is given an opportunity to provide a PropertyValueUIItem for each property of the component.

When a property browser is set to display the properties of an object, it calls the GetPropertyUIValueItems method of this interface for each property of the component, passing a PropertyDescriptor that represents the property. The GetPropertyUIValueItems method calls each PropertyValueUIHandler that has been added to the service. Each PropertyValueUIHandler can add a PropertyValueUIItem to the ArrayList parameter passed in the valueUIItemList parameter to supply UI items for the property represented by the PropertyDescriptor passed in the propDesc parameter.

A PropertyValueUIItem can contain an image to display next to the property name, a ToolTip string, and an event handler to invoke when an image associated with the property is double-clicked.

Example

[Visual Basic, C#, C++] The following code example creates a component that obtains an instance of the IPropertyValueUIService interface and adds a PropertyValueUIHandler to the service. The handler provides a PropertyValueUIItem object for any properties of the component named HorizontalMargin or VerticalMargin. The PropertyValueUIItem for these properties provides an image, a ToolTip, and an event handler that displays a message box when the image for the property is clicked. The image and the ToolTip are displayed in a System.Windows.Forms.PropertyGrid when the grid is showing these properties of the component.

[Visual Basic] 
Imports System
Imports System.Collections
Imports System.ComponentModel
Imports System.ComponentModel.Design
Imports System.Drawing
Imports System.Drawing.Design
Imports System.IO
Imports System.Runtime.Serialization
Imports System.Runtime.Serialization.Formatters.Binary
Imports System.Windows.Forms
Imports System.Windows.Forms.Design

' This component obtains the IPropertyValueUIService and adds a
' PropertyValueUIHandler that provides PropertyValueUIItem objects
' which provide an image, tooltip and invoke event handler to
' any properties named HorizontalMargin and VerticalMargin, 
' such as the example integer properties on this component.    
Public Class PropertyUIComponent
    Inherits System.ComponentModel.Component

    ' Example property for which to provide PropertyValueUIItem.
    Public Property HorizontalMargin() As Integer
        Get
            Return hMargin
        End Get
        Set(ByVal Value As Integer)
            hMargin = Value
        End Set
    End Property

    ' Example property for which to provide PropertyValueUIItem.       
    Public Property VerticalMargin() As Integer
        Get
            Return vMargin
        End Get
        Set(ByVal Value As Integer)
            vMargin = Value
        End Set
    End Property

    ' Field storing the value of the HorizontalMargin property
    Private hMargin As Integer

    ' Field storing the value of the VerticalMargin property
    Private vMargin As Integer

    ' Base64-encoded serialized image data for image icon.
    Private imageBlob1 As String = "AAEAAAD/////AQAAAAAAAAAMAgAAAFRTeXN0ZW0uRHJhd2luZywgVmVyc2lvbj0xLjAuMzMwMC4wLCBDdWx0dXJlPW5ldXRyYWwsIFB1YmxpY0tleVRva2VuPWIwM2Y1ZjdmMTFkNTBhM2EFAQAAABVTeXN0ZW0uRHJhd2luZy5CaXRtYXABAAAABERhdGEHAgIAAAAJAwAAAA8DAAAA9gAAAAJCTfYAAAAAAAAANgAAACgAAAAIAAAACAAAAAEAGAAAAAAAAAAAAMQOAADEDgAAAAAAAAAAAAD///////////////////////////////////8AAAD///////////////8AAAD///////8AAAD///////////////8AAAD///////8AAAD///8AAAAAAAD///8AAAD///////8AAAD///8AAAAAAAD///8AAAD///////8AAAD///////////////8AAAD///////8AAAD///////////////8AAAD///////////////////////////////////8L"

    ' Constructor.
    Public Sub New(ByVal container As System.ComponentModel.IContainer)
        If Not (container Is Nothing) Then
            container.Add(Me)
        End If
        hMargin = 0
        vMargin = 0
    End Sub

    ' Default component constructor that specifies no container.
    Public Sub New()
        MyClass.New(Nothing)
    End Sub

    ' PropertyValueUIHandler delegate that provides PropertyValueUIItem
    ' objects to any properties named HorizontalMargin or VerticalMargin.
    Private Sub marginPropertyValueUIHandler(ByVal context As System.ComponentModel.ITypeDescriptorContext, ByVal propDesc As System.ComponentModel.PropertyDescriptor, ByVal itemList As ArrayList)
        ' A PropertyValueUIHandler added to the IPropertyValueUIService
        ' is queried once for each property of a component and passed
        ' a PropertyDescriptor that represents the characteristics of 
        ' the property when the Properties window is set to a new 
        ' component. A PropertyValueUIHandler can determine whether 
        ' to add a PropertyValueUIItem for the object to its ValueUIItem 
        ' list depending on the values of the PropertyDescriptor.
        If propDesc.DisplayName.Equals("HorizontalMargin") Then
            Dim img As Image = DeserializeFromBase64Text(imageBlob1)
            itemList.Add(New PropertyValueUIItem(img, New PropertyValueUIItemInvokeHandler(AddressOf Me.marginInvoke), "Test ToolTip"))
        End If
        If propDesc.DisplayName.Equals("VerticalMargin") Then
            Dim img As Image = DeserializeFromBase64Text(imageBlob1)
            img.RotateFlip(RotateFlipType.Rotate90FlipNone)
            itemList.Add(New PropertyValueUIItem(img, New PropertyValueUIItemInvokeHandler(AddressOf Me.marginInvoke), "Test ToolTip"))
        End If
    End Sub

    ' Invoke handler associated with the PropertyValueUIItem objects 
    ' provided by the marginPropertyValueUIHandler.
    Private Sub marginInvoke(ByVal context As System.ComponentModel.ITypeDescriptorContext, ByVal propDesc As System.ComponentModel.PropertyDescriptor, ByVal item As PropertyValueUIItem)
        MessageBox.Show("Test invoke message box")
    End Sub

    ' Component.Site override to add the marginPropertyValueUIHandler
    ' when the component is sited, and to remove it when the site is 
    ' set to null.
    Public Overrides Property Site() As System.ComponentModel.ISite
        Get
            Return MyBase.Site
        End Get
        Set(ByVal Value As System.ComponentModel.ISite)
            If Not (Value Is Nothing) Then
                MyBase.Site = Value
                Dim uiService As IPropertyValueUIService = CType(Me.GetService(GetType(IPropertyValueUIService)), IPropertyValueUIService)
                If Not (uiService Is Nothing) Then
                    uiService.AddPropertyValueUIHandler(New PropertyValueUIHandler(AddressOf Me.marginPropertyValueUIHandler))
                End If
            Else
                Dim uiService As IPropertyValueUIService = CType(Me.GetService(GetType(IPropertyValueUIService)), IPropertyValueUIService)
                If Not (uiService Is Nothing) Then
                    uiService.RemovePropertyValueUIHandler(New PropertyValueUIHandler(AddressOf Me.marginPropertyValueUIHandler))
                End If
                MyBase.Site = Value
            End If
        End Set
    End Property

    ' This method can be used to retrieve an Image from a block 
    ' of Base64-encoded text.
    Private Function DeserializeFromBase64Text(ByVal [text] As String) As Image
        Dim img As Image = Nothing
        Dim memBytes As Byte() = Convert.FromBase64String([text])
        Dim formatter = New BinaryFormatter()
        Dim stream As New MemoryStream(memBytes)
        img = CType(formatter.Deserialize(stream), Image)
        stream.Close()
        Return img
    End Function

End Class

[C#] 
using System;
using System.Collections;
using System.ComponentModel;
using System.ComponentModel.Design;
using System.Drawing;
using System.Drawing.Design;
using System.IO;
using System.Runtime.Serialization;
using System.Runtime.Serialization.Formatters.Binary;
using System.Windows.Forms;
using System.Windows.Forms.Design;

namespace PropertyValueUIServiceExample
{
    // This component obtains the IPropertyValueUIService and adds a
    // PropertyValueUIHandler that provides PropertyValueUIItem objects
    // which provide an image, ToolTip, and invoke event handler to
    // any properties named HorizontalMargin and VerticalMargin, 
    // such as the example integer properties on this component.    
    public class PropertyUIComponent : System.ComponentModel.Component
    {
        // Example property for which to provide a PropertyValueUIItem.
        public int HorizontalMargin 
        {
            get
            {
                return hMargin;
            }
            set
            {
                hMargin = value;
            }
        }
        // Example property for which to provide a PropertyValueUIItem.
        public int VerticalMargin
        {
            get
            {
                return vMargin;
            }
            set
            {
                vMargin = value;
            }
        }

        // Field storing the value of the HorizontalMargin property.
        private int hMargin;

        // Field storing the value of the VerticalMargin property.
        private int vMargin;        

        // Base64-encoded serialized image data for image icon.
        private string imageBlob1 = "AAEAAAD/////AQAAAAAAAAAMAgAAAFRTeXN0ZW0uRHJhd2luZywgVmVyc2lvbj0xLjAuMzMwMC4wLCBDdWx0dXJlPW5ldXRyYWwsIFB1YmxpY0tleVRva2VuPWIwM2Y1ZjdmMTFkNTBhM2EFAQAAABVTeXN0ZW0uRHJhd2luZy5CaXRtYXABAAAABERhdGEHAgIAAAAJAwAAAA8DAAAA9gAAAAJCTfYAAAAAAAAANgAAACgAAAAIAAAACAAAAAEAGAAAAAAAAAAAAMQOAADEDgAAAAAAAAAAAAD///////////////////////////////////8AAAD///////////////8AAAD///////8AAAD///////////////8AAAD///////8AAAD///8AAAAAAAD///8AAAD///////8AAAD///8AAAAAAAD///8AAAD///////8AAAD///////////////8AAAD///////8AAAD///////////////8AAAD///////////////////////////////////8L";
                
        // Constructor.
        public PropertyUIComponent(System.ComponentModel.IContainer container)
        {
            if( container != null )
                container.Add(this);
            hMargin = 0;        
            vMargin = 0;
        }

        // Default component constructor that specifies no container.
        public PropertyUIComponent() : this(null)
        {}

        // PropertyValueUIHandler delegate that provides PropertyValueUIItem
        // objects to any properties named HorizontalMargin or VerticalMargin.
        private void marginPropertyValueUIHandler(System.ComponentModel.ITypeDescriptorContext context, System.ComponentModel.PropertyDescriptor propDesc, ArrayList itemList)
        {
            // A PropertyValueUIHandler added to the IPropertyValueUIService
            // is queried once for each property of a component and passed
            // a PropertyDescriptor that represents the characteristics of 
            // the property when the Properties window is set to a new 
            // component. A PropertyValueUIHandler can determine whether 
            // to add a PropertyValueUIItem for the object to its ValueUIItem 
            // list depending on the values of the PropertyDescriptor.
            if( propDesc.DisplayName.Equals( "HorizontalMargin" ) )
            {
                Image img = DeserializeFromBase64Text(imageBlob1);
                itemList.Add( new PropertyValueUIItem( img, new PropertyValueUIItemInvokeHandler(this.marginInvoke), "Test ToolTip") );
            }
            if( propDesc.DisplayName.Equals( "VerticalMargin" ) )
            {
                Image img = DeserializeFromBase64Text(imageBlob1);
                img.RotateFlip(RotateFlipType.Rotate90FlipNone);
                itemList.Add( new PropertyValueUIItem( img, new PropertyValueUIItemInvokeHandler(this.marginInvoke), "Test ToolTip") );
            }
        }

        // Invoke handler associated with the PropertyValueUIItem objects 
        // provided by the marginPropertyValueUIHandler.
        private void marginInvoke(System.ComponentModel.ITypeDescriptorContext context, System.ComponentModel.PropertyDescriptor propDesc, PropertyValueUIItem item)
        {
            MessageBox.Show("Test invoke message box");
        }

        // Component.Site override to add the marginPropertyValueUIHandler
        // when the component is sited, and to remove it when the site is 
        // set to null.
        public override System.ComponentModel.ISite Site
        {
            get
            {
                return base.Site;
            }
            set
            {                
                if( value != null )
                {
                    base.Site = value;
                    IPropertyValueUIService uiService = (IPropertyValueUIService)this.GetService(typeof(IPropertyValueUIService));
                    if( uiService != null )                    
                        uiService.AddPropertyValueUIHandler( new PropertyValueUIHandler(this.marginPropertyValueUIHandler) );                                        
                }
                else
                {
                    IPropertyValueUIService uiService = (IPropertyValueUIService)this.GetService(typeof(IPropertyValueUIService));
                    if( uiService != null )                    
                        uiService.RemovePropertyValueUIHandler( new PropertyValueUIHandler(this.marginPropertyValueUIHandler) );                                        
                    base.Site = value;
                }
            }
        }

        // This method can be used to retrieve an Image from a block 
        // of Base64-encoded text.
        private Image DeserializeFromBase64Text(string text)
        {
            Image img = null;
            byte[] memBytes = Convert.FromBase64String(text);
            IFormatter formatter = new BinaryFormatter();
            MemoryStream stream = new MemoryStream(memBytes);
            img = (Image)formatter.Deserialize(stream);
            stream.Close();
            return img;
        }
    }
}

[C++] 
#using <mscorlib.dll>
#using <System.Windows.Forms.dll>
#using <System.Drawing.dll>
#using <System.dll>

using namespace System;
using namespace System::Collections;
using namespace System::ComponentModel;
using namespace System::ComponentModel::Design;
using namespace System::Drawing;
using namespace System::Drawing::Design;
using namespace System::IO;
using namespace System::Runtime::Serialization;
using namespace System::Runtime::Serialization::Formatters::Binary;
using namespace System::Windows::Forms;
using namespace System::Windows::Forms::Design;

namespace PropertyValueUIServiceExample {
   // This component obtains the IPropertyValueUIService and adds a
   // PropertyValueUIHandler that provides PropertyValueUIItem objects
   // which provide an image, ToolTip, and invoke event handler to
   // any properties named horizontalMargin and verticalMargin,
   // such as the example integer properties on this component.
public __gc class PropertyUIComponent : public System::ComponentModel::Component {
   // Example property for which to provide a PropertyValueUIItem.
public:
   __property int get_horizontalMargin() {
      return hMargin;
   }
   __property void set_horizontalMargin(int value) {
      hMargin = value;
   }

   // Example property for which to provide a PropertyValueUIItem.
   __property int get_verticalMargin() {
      return vMargin;
   }
   __property void set_verticalMargin(int value) {
      vMargin = value;
   }


private:
   // Field storing the value of the horizontalMargin property.
   int  hMargin;
   // Field storing the value of the verticalMargin property.
   int  vMargin;
   // Base64-encoded serialized image data for image icon.
   String* imageBlob1;

public:
   // Constructor.
   PropertyUIComponent(System::ComponentModel::IContainer* container) {
      imageBlob1 = S"AAEAAAD/////AQAAAAAAAAAMAgAAAFRTeXN0ZW0uRHJhd2luZywgVmVyc2lvbj0xLjAuMzMwMC4wLCBDdWx0dXJlPW5ldXRyYWwsIFB1YmxpY0tleVRva2VuPWIwM2Y1ZjdmMTFkNTBhM2EFAQAAABVTeXN0ZW0uRHJhd2luZy5CaXRtYXABAAAABERhdGEHAgIAAAAJAwAAAA8DAAAA9gAAAAJCTfYAAAAAAAAANgAAACgAAAAIAAAACAAAAAEAGAAAAAAAAAAAAMQOAADEDgAAAAAAAAAAAAD///////////////////////////////////8AAAD///////////////8AAAD///////8AAAD///////////////8AAAD///////8AAAD///8AAAAAAAD///8AAAD///////8AAAD///8AAAAAAAD///8AAAD///////8AAAD///////////////8AAAD///////8AAAD///////////////8AAAD///////////////////////////////////8L";
      if (container != 0)
         container->Add(this);
      hMargin = 0;
      vMargin = 0;
   }

   // Default component constructor that specifies no container.
   PropertyUIComponent(){
      imageBlob1 = S"AAEAAAD/////AQAAAAAAAAAMAgAAAFRTeXN0ZW0uRHJhd2luZywgVmVyc2lvbj0xLjAuMzMwMC4wLCBDdWx0dXJlPW5ldXRyYWwsIFB1YmxpY0tleVRva2VuPWIwM2Y1ZjdmMTFkNTBhM2EFAQAAABVTeXN0ZW0uRHJhd2luZy5CaXRtYXABAAAABERhdGEHAgIAAAAJAwAAAA8DAAAA9gAAAAJCTfYAAAAAAAAANgAAACgAAAAIAAAACAAAAAEAGAAAAAAAAAAAAMQOAADEDgAAAAAAAAAAAAD///////////////////////////////////8AAAD///////////////8AAAD///////8AAAD///////////////8AAAD///////8AAAD///8AAAAAAAD///8AAAD///////8AAAD///8AAAAAAAD///8AAAD///////8AAAD///////////////8AAAD///////8AAAD///////////////8AAAD///////////////////////////////////8L";
      hMargin = 0;
      vMargin = 0;
   }

   // PropertyValueUIHandler delegate that provides PropertyValueUIItem
   // objects to any properties named horizontalMargin or verticalMargin.
private:
   void marginPropertyValueUIHandler(System::ComponentModel::ITypeDescriptorContext* /*context*/, System::ComponentModel::PropertyDescriptor* propDesc, ArrayList* itemList) {
      // A PropertyValueUIHandler added to the IPropertyValueUIService
      // is queried once for each property of a component and passed
      // a PropertyDescriptor that represents the characteristics of
      // the property when the Properties window is set to a new
      // component. A PropertyValueUIHandler can determine whether
      // to add a PropertyValueUIItem for the object to its ValueUIItem
      // list depending on the values of the PropertyDescriptor.
      if (propDesc->DisplayName->Equals(S"horizontalMargin")) {
         Image* img = DeserializeFromBase64Text(imageBlob1);
         itemList->Add(new PropertyValueUIItem(img, new PropertyValueUIItemInvokeHandler(this, &PropertyUIComponent::marginInvoke), S"Test ToolTip"));
      }
      if (propDesc->DisplayName->Equals(S"verticalMargin")) {
         Image* img = DeserializeFromBase64Text(imageBlob1);
         img->RotateFlip(RotateFlipType::Rotate90FlipNone);
         itemList->Add(new PropertyValueUIItem(img, new PropertyValueUIItemInvokeHandler(this, &PropertyUIComponent::marginInvoke), S"Test ToolTip"));
      }
   }

   // Invoke handler associated with the PropertyValueUIItem objects
   // provided by the marginPropertyValueUIHandler.
   void marginInvoke(System::ComponentModel::ITypeDescriptorContext* /*context*/, System::ComponentModel::PropertyDescriptor* /*propDesc*/, PropertyValueUIItem* /*item*/) {
      MessageBox::Show(S"Test invoke message box");
   }

   // Component::Site  to add the marginPropertyValueUIHandler
   // when the component is sited, and to remove it when the site is
   // set to 0.
public:
   __property System::ComponentModel::ISite* get_Site() {
      return Component::get_Site();
   }
   __property void set_Site(System::ComponentModel::ISite* value) {
      if (value != 0) {
         Component::set_Site( value );
         IPropertyValueUIService* uiService = dynamic_cast<IPropertyValueUIService*>(this->GetService(__typeof(IPropertyValueUIService)));
         if (uiService != 0)
            uiService->AddPropertyValueUIHandler(new PropertyValueUIHandler(this, &PropertyUIComponent::marginPropertyValueUIHandler));
      } else {
         IPropertyValueUIService* uiService = dynamic_cast<IPropertyValueUIService*>(this->GetService(__typeof(IPropertyValueUIService)));
         if (uiService != 0)
            uiService->RemovePropertyValueUIHandler(new PropertyValueUIHandler(this, &PropertyUIComponent::marginPropertyValueUIHandler));
         Component::Site = value;
      }
   }


   // This method can be used to retrieve an Image from a block
   // of Base64-encoded text.
private:
   Image* DeserializeFromBase64Text(String* text) {
      Image* img = 0;
      Byte memBytes[] = Convert::FromBase64String(text);
      IFormatter* formatter = new BinaryFormatter();
      MemoryStream* stream = new MemoryStream(memBytes);
      img = dynamic_cast<Image*>(formatter->Deserialize(stream));
      stream->Close();
      return img;
   }
};
}

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Namespace: System.Drawing.Design

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family

Assembly: System.Drawing (in System.Drawing.dll)

See Also

IPropertyValueUIService Members | System.Drawing.Design Namespace | PropertyValueUIHandler | PropertyValueUIItem

Show: