How to: Implement a HelpLabel Extender Provider

An extender provider is a component that provides properties to other components. For example, the ToolTip control is implemented as an extender provider. When you add a ToolTip control to a Form, all other controls on the Form have a ToolTip property added to their properties list.

The following sample demonstrates how to build an extender provider by creating the HelpLabel control. It shows the implementation of the CanExtend method and the HelpText property. The CanExtend method is used by the Windows Forms Designer to determine whether to extend this property to a given control. The HelpLabel control extends the HelpText property for use with the controls on a form. The Help text for a control is displayed in a panel when the control has focus.

The sample includes a nested designer that is described in How to: Implement a Designer for a Control.

The sample demonstrates the following items:

  • The extender provider HelpLabel implements IExtenderProvider.

  • The HelpLabel control uses the ProvidePropertyAttribute to specify the name of the provided property, as well as the type of components that may receive the property.

  • HelpLabel is itself a Windows Forms control and hence derives from Control.

  • The CanExtend method returns true for any control except HelpLabel, because it is not meaningful to extend a property on itself.

  • HelpLabel has a method named GetHelpText that gets the property that HelpLabel makes available to other controls. The SetHelpText method sets the value of the property.

    Note Note

    The extended property is provided by the GetHelpText and SetHelpText methods, and HelpLabel does not expose a property named HelpText.

The HostApp class uses the HelpLabel control on a form.

namespace Microsoft.Samples.WinForms.Cs.HelpLabel 
{
	using System;
	using System.Collections;
	using System.ComponentModel;
	using System.ComponentModel.Design;
	using System.Drawing;
	using System.Windows.Forms;
	using System.Windows.Forms.Design;

	// 
	// <doc> 
	// <desc> 
	// Help Label offers an extender property called 
	// "HelpText".  It monitors the active control
	// and displays the help text for the active control. 
	// </desc> 
	// </doc> 
	//
	[
	ProvideProperty("HelpText",typeof(Control)),
	Designer(typeof(HelpLabel.HelpLabelDesigner))
	]
	public class HelpLabel : Control, System.ComponentModel.IExtenderProvider 
	{
		/// <summary> 
		///    Required designer variable. 
		/// </summary> 
		private System.ComponentModel.Container components;
		private Hashtable helpTexts;
		private System.Windows.Forms.Control activeControl;

		// 
		// <doc> 
		// <desc> 
		//      Creates a new help label object. 
		// </desc> 
		// </doc> 
		// 
		public HelpLabel() 
		{
			// 
			// Required for Windows Form Designer support 
			//
			InitializeComponent();

			helpTexts = new Hashtable();
		}

		/// <summary> 
		///    Clean up any resources being used. 
		/// </summary> 
		protected override void Dispose(bool disposing) 
		{
			if (disposing) 
			{
				components.Dispose();
			}
			base.Dispose(disposing);
		}

		/// <summary> 
		///    Required method for Designer support - do not modify 
		///    the contents of this method with the code editor. 
		/// </summary> 
		private void InitializeComponent() 
		{
			this.components = new System.ComponentModel.Container ();
			this.BackColor = System.Drawing.SystemColors.Info;
			this.ForeColor = System.Drawing.SystemColors.InfoText;
			this.TabStop = false;
		}

		// 
		// <doc> 
		// <desc> 
		//      Overrides the text property of Control.  This label ignores 
		//      the text property, so we add additional attributes here so the 
		//      property does not show up in the properties window and is not 
		//      persisted. 
		// </desc> 
		// </doc> 
		//
		[
		Browsable(false),
		EditorBrowsable(EditorBrowsableState.Never),
		DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)
		]
		public override string Text 
		{
			get 
			{
				return base.Text;
			}
			set 
			{
				base.Text = value;
			}
		}

		// 
		// <doc> 
		// <desc> 
		//      This implements the IExtenderProvider.CanExtend method.  The 
		//      help label provides an extender property, and the design time 
		//      framework will call this method once for each component to determine 
		//      if we are interested in providing our extended properties for the 
		//      component.  We return true here if the object is a control and is 
		//      not a HelpLabel (since it would be silly to add this property to 
		//      ourselves). 
		// </desc> 
		// </doc> 
		// 
		bool IExtenderProvider.CanExtend(object target) 
		{
			if (target is Control &&
				!(target is HelpLabel)) 
			{

				return true;
			}
			return false;
		}

		// 
		// <doc> 
		// <desc> 
		//      This is the extended property for the HelpText property.  Extended 
		//      properties are actual methods because they take an additional parameter 
		//      that is the object or control to provide the property for. 
		// </desc> 
		// </doc> 
		//
		[
		DefaultValue(""),
		]
		public string GetHelpText(Control control) 
		{
			string text = (string)helpTexts[control];
			if (text == null) 
			{
				text = string.Empty;
			}
			return text;
		}

		// 
		// <doc> 
		// <desc> 
		//      This is an event handler that responds to the OnControlEnter 
		//      event.  We attach this to each control we are providing help 
		//      text for. 
		// </desc> 
		// </doc> 
		// 
		private void OnControlEnter(object sender, EventArgs e) 
		{
			activeControl = (Control)sender;
			Invalidate();
		}

		// 
		// <doc> 
		// <desc> 
		//      This is an event handler that responds to the OnControlLeave 
		//      event.  We attach this to each control we are providing help 
		//      text for. 
		// </desc> 
		// </doc> 
		// 
		private void OnControlLeave(object sender, EventArgs e) 
		{
			if (sender == activeControl) 
			{
				activeControl = null;
				Invalidate();
			}
		}

		// 
		// <doc> 
		// <desc> 
		//      This is the extended property for the HelpText property. 
		// </desc> 
		// </doc> 
		// 
		public void SetHelpText(Control control, string value) 
		{
			if (value == null) 
			{
				value = string.Empty;
			}

			if (value.Length == 0) 
			{
				helpTexts.Remove(control);

				control.Enter -= new EventHandler(OnControlEnter);
				control.Leave -= new EventHandler(OnControlLeave);
			}
			else 
			{
				helpTexts[control] = value;

				control.Enter += new EventHandler(OnControlEnter);
				control.Leave += new EventHandler(OnControlLeave);
			}

			if (control == activeControl) 
			{
				Invalidate();
			}
		}

		// 
		// <doc> 
		// <desc> 
		//      Overrides Control.OnPaint.  Here we draw our 
		//      label. 
		// </desc> 
		// </doc> 
		// 
		protected override void OnPaint(PaintEventArgs pe) 
		{

			// Let the base draw.  This will cover our back 
			// color and set any image that the user may have 
			// provided. 
			// 
			base.OnPaint(pe);

			// Draw a rectangle around our control. 
			//
			Rectangle rect = ClientRectangle;

			Pen borderPen = new Pen(ForeColor);
			pe.Graphics.DrawRectangle(borderPen, rect);
			borderPen.Dispose();

			// Finally, draw the text over the top of the 
			// rectangle. 
			// 
			if (activeControl != null) 
			{
				string text = (string)helpTexts[activeControl];
				if (text != null && text.Length > 0) 
				{
					rect.Inflate(-2, -2);
					Brush brush = new SolidBrush(ForeColor);
					pe.Graphics.DrawString(text, Font, brush, rect);
					brush.Dispose();
				}
			}
		}

		// <doc> 
		// <desc> 
		//     Returns true if the backColor should be persisted in code gen.  We 
		//      override this because we change the default back color. 
		// </desc> 
		// <retvalue> 
		//     true if the backColor should be persisted. 
		// </retvalue> 
		// </doc> 
		// 
		public bool ShouldSerializeBackColor() 
		{
			return(!BackColor.Equals(SystemColors.Info));
		}

		// <doc> 
		// <desc> 
		//     Returns true if the foreColor should be persisted in code gen.  We 
		//      override this because we change the default foreground color. 
		// </desc> 
		// <retvalue> 
		//     true if the foreColor should be persisted. 
		// </retvalue> 
		// </doc> 
		// 
		public bool ShouldSerializeForeColor() 
		{
			return(!ForeColor.Equals(SystemColors.InfoText));
		}

		// 
		// <doc> 
		// <desc> 
		//      This is a designer for the HelpLabel.  This designer provides 
		//      design time feedback for the label.  The help label responds 
		//      to changes in the active control, but these events do not 
		//      occur at design time.  In order to provide some usable feedback 
		//      that the control is working the right way, this designer listens 
		//      to selection change events and uses those events to trigger active 
		//      control changes. 
		// </desc> 
		// </doc> 
		//
        [System.Security.Permissions.PermissionSet(System.Security.Permissions.SecurityAction.Demand, Name = "FullTrust")] 
		public class HelpLabelDesigner : System.Windows.Forms.Design.ControlDesigner 
		{

			private bool trackSelection = true;

			/// <summary> 
			/// This property is added to the control's set of properties in the method 
			/// PreFilterProperties below.  Note that on designers, properties that are 
			/// explictly declared by TypeDescriptor.CreateProperty can be declared as 
			/// private on the designer.  This helps to keep the designer's publi 
			/// object model clean. 
			/// </summary>
            [DesignerSerializationVisibility( DesignerSerializationVisibility.Hidden )]
			private bool TrackSelection
			{
				get
				{
					return trackSelection;
				}
				set
				{
					trackSelection = value;
					if (trackSelection)
					{
						ISelectionService ss = (ISelectionService)GetService(typeof(ISelectionService));
						if (ss != null)
						{
							UpdateHelpLabelSelection(ss);
						}
					}
					else
					{
						HelpLabel helpLabel = (HelpLabel)Control;
						if (helpLabel.activeControl != null)
						{
							helpLabel.activeControl = null;
							helpLabel.Invalidate();
						}
					}
				}
			}

			public override DesignerVerbCollection Verbs
			{
				get
				{
					DesignerVerb[] verbs = new DesignerVerb[] {
																  new DesignerVerb("Sample Verb", new EventHandler(OnSampleVerb))
															  };
					return new DesignerVerbCollection(verbs);
				}
			}

			// 
			// <doc> 
			// <desc> 
			//      Overrides Dispose.  Here we remove our handler for the selection changed 
			//      event.  With designers, it is critical that they clean up any events they 
			//      have attached.  Otherwise, during the course of an editing session many 
			//      designers may get created and never destroyed. 
			// </desc> 
			// </doc> 
			// 
			protected override void Dispose(bool disposing) 
			{
				if (disposing) 
				{
					ISelectionService ss = (ISelectionService)GetService(typeof(ISelectionService));
					if (ss != null) 
					{
						ss.SelectionChanged -= new EventHandler(OnSelectionChanged);
					}
				}

				base.Dispose(disposing);
			}

			// 
			// <doc> 
			// <desc> 
			//       Overrides initialize.  Here we add an event handler to the selection service. 
			//      Notice that we are very careful not to assume that the selection service is 
			//      available.  It is entirely optional that a service is available and you should 
			//      always degrade gracefully if a service could not be found. 
			// </desc> 
			// </doc> 
			// 
			public override void Initialize(IComponent component) 
			{
				base.Initialize(component);

				ISelectionService ss = (ISelectionService)GetService(typeof(ISelectionService));
				if (ss != null) 
				{
					ss.SelectionChanged += new EventHandler(OnSelectionChanged);
				}
			}

			private void OnSampleVerb(object sender, EventArgs e)
			{
				MessageBox.Show("You have just invoked a sample verb.  Normally, this would do something interesting.");
			}

			// 
			// <doc> 
			// <desc> 
			//      Our handler for the selection change event.  Here we update the active control within 
			//      the help label. 
			// </desc> 
			// </doc> 
			// 
			private void OnSelectionChanged(object sender, EventArgs e) 
			{
				if (trackSelection)
				{
					ISelectionService ss = (ISelectionService)sender;
					UpdateHelpLabelSelection(ss);
				}
			}

			protected override void PreFilterProperties(IDictionary properties)
			{
				// Always call base first in PreFilter* methods, and last in PostFilter* 
				// methods. 
				base.PreFilterProperties(properties);

				// We add a design-time property called "TrackSelection" that is used to track
				// the active selection.  If the user sets this to true (the default), then 
				// we will listen to selection change events and update the control's active 
				// control to point to the current primary selection.
				properties["TrackSelection"] = TypeDescriptor.CreateProperty(
					this.GetType(),        // the type this property is defined on 
					"TrackSelection",    // the name of the property 
					typeof(bool),        // the type of the property 
					new Attribute[] {CategoryAttribute.Design});    // attributes
			}

			/// <summary> 
			/// This is a helper method that, given a selection service, will update the active control 
			/// of our help label with the currently active selection. 
			/// </summary> 
			/// <param name="ss"></param>
			private void UpdateHelpLabelSelection(ISelectionService ss)
			{
				Control c = ss.PrimarySelection as Control;
				HelpLabel helpLabel = (HelpLabel)Control;
				if (c != null)
				{
					helpLabel.activeControl = c;
					helpLabel.Invalidate();
				}
				else
				{
					if (helpLabel.activeControl != null)
					{
						helpLabel.activeControl = null;
						helpLabel.Invalidate();
					}
				}
			}
		}
	}
}
namespace Microsoft.Samples.WinForms.Cs.HostApp 
{
	using System;
	using System.ComponentModel;
	using System.Drawing;
	using System.Windows.Forms;
	using Microsoft.Samples.WinForms.Cs.HelpLabel;

	public class HostApp : System.Windows.Forms.Form 
	{
		/// <summary> 
		///    Required designer variable. 
		/// </summary> 
		private System.ComponentModel.Container components;
		private System.Windows.Forms.Label label1;
		private System.Windows.Forms.TextBox textBox1;
		private System.Windows.Forms.Button button1;
		private Microsoft.Samples.WinForms.Cs.HelpLabel.HelpLabel helpLabel1;

		public HostApp() 
		{
			// 
			// Required for Windows Form Designer support 
			//
			InitializeComponent();

		}

		/// <summary> 
		///    Clean up any resources being used. 
		/// </summary> 
		protected override void Dispose(bool disposing) 
		{
			if (disposing) 
			{
				components.Dispose();
			}
			base.Dispose(disposing);
		}

		/// <summary> 
		///    Required method for Designer support - do not modify 
		///    the contents of this method with the code editor. 
		/// </summary> 
		private void InitializeComponent() 
		{
			this.components = new System.ComponentModel.Container();
			this.label1 = new System.Windows.Forms.Label();
			this.button1 = new System.Windows.Forms.Button();
			this.textBox1 = new System.Windows.Forms.TextBox();
			this.helpLabel1 = new Microsoft.Samples.WinForms.Cs.HelpLabel.HelpLabel();

			label1.Location = new System.Drawing.Point(16, 16);
			label1.Text = "Name:";
			label1.Size = new System.Drawing.Size(56, 24);
			label1.TabIndex = 3;

			helpLabel1.Dock = System.Windows.Forms.DockStyle.Bottom;
			helpLabel1.Size = new System.Drawing.Size(448, 40);
			helpLabel1.TabIndex = 0;
			helpLabel1.Location = new System.Drawing.Point(0, 117);

			button1.Anchor = AnchorStyles.Right | AnchorStyles.Bottom;
			button1.Size = new System.Drawing.Size(104, 40);
			button1.TabIndex = 1;
			helpLabel1.SetHelpText(button1, "This is the Save Button. Press the Save Button to save your work.");
			button1.Text = "&Save";
			button1.Location = new System.Drawing.Point(336, 56);

			this.Text = "Control Example";
			this.ClientSize = new System.Drawing.Size(448, 157);

			textBox1.Anchor = AnchorStyles.Left| AnchorStyles.Right | AnchorStyles.Top;
			textBox1.Location = new System.Drawing.Point(80, 16);
			textBox1.Text = "<Name>";
			helpLabel1.SetHelpText(textBox1, "This is the name field. Please enter your name here.");
			textBox1.TabIndex = 2;
			textBox1.Size = new System.Drawing.Size(360, 20);

			this.Controls.Add(label1);
			this.Controls.Add(textBox1);
			this.Controls.Add(button1);
			this.Controls.Add(helpLabel1);
		}

		/// <summary> 
		/// The main entry point for the application. 
		/// </summary>
		[STAThread]
		public static void Main(string[] args) 
		{
			Application.Run(new HostApp());
		}

	}
}
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft