Extending user control and IDE/VS.NET Toolbox

• Download demo project - 1000 Kb

Introduction

What is it?

• ctxtbx inherits from TextBox (System.Windows.Forms). Control extension: If the length of the character string in the textbox (ctxtbx.Text.Length) exceeds a specified number of characters (ctxt.FlashLength), the textbox starts flashing, to indicate to the user that the entered character string is invalid (too long).

• The purpose of this project is to demonstrate the following:

  • To extend user control via delegates and events.

  • To add custom control to Toolbox. Access control property via Property Browser.

  • The control is packaged in one single dll. It can be consumed by any .NET/WIN32 client.

  • The Application Note provides the necessary information to deploy this module to C#/VB.NET client. Please be aware that RAD tools are only available to C#/VB.NET. If you intend to consume this package in a managed C++/COM/WIN32 client, the procedures provided in the APPLICATION NOTES do not readily apply.

  • Prerequisite to this tutorial: C#/VB.NET, Windows Forms, UEM (unified events modeling). A good understanding of the following subjects would help, but not entirely necessary: assemblies, strong names, PPK, GAC.

Application Note

To install the module into the GAC (Global Assembly Cache):

• Key file: txtbxlib.snk (This step is already done. The key file is in your solution folder.) The key file is generated with sn.exe, and it�s referenced by AssemblyInfo.cs. For those of you who�re not entirely familiar with the procedure, read up on the following topics: GAC, sn.exe, assembly, strong name.

  For your information, here�s the command prompt entry:

  sn -k txtbxlib.snk
  

• Visual Studio.NET command prompt: gacutil -i txtbxlib.dll (You need to do this yourself.) (Fig 5)

• To add the control to the Toolbox:

  • right click anywhere on the Toolbox. (Fig 1)

    

    • Select "Customize Toolbox" (Fig 1,2)

    • Select ".NET Framework components" (Fig 2)

    

  • Browse, and select txtbxlib.dll (Fig 3)

    

  To use the control in your Windows Form, just drag it from the Toolbox and drop it onto your form. (Fig 1)

Three control properties

• ctxtbx.FlashLength (Length of character string in textbox to trigger flashing. Default: 10)

• ctxtbx.flashColor (Flash color. Default: System.Drawing.Color.Red)

• ctxtbx.flashfreq (Flash frequency. Default: 1)

You can access these properties from Properties Browser (Fig 4), or in class ctxtbx constructor. Now, select the editbox and pay attention to browser and Fig 6 (class hierarchy). Please note that ONLY properties can be found under "Properties Browser" - other class attributes are not displayed here.

That�s all for client implementation, just drag the control from the Toolbox and drop it on your Windows form. A sample application is included in the package for demonstration purpose (SomeClient). Before you run the executable, make sure:

• The control assembly (txtbxlib.dll) has been installed into the GAC.

• Toolbox references to txtbxlib.dll

Now that�s the easy way, which implies that there�s an alternative: Just cut and paste the control class ctxtbx from library source file txtbxlib.cs, and instantiate ctxtbx in your Windows Form�s constructor. Be sure to include the following namespaces: System.Threading, System.Drawing, System.Windows, System.Windows.Forms and System

Architecture and implementation:

Everything in ctxtbx is packaged in one single dll (Managed C# class library): txtbxlib.dll

Please note that references to System.Drawing and System.Windows.Forms were added to the solution.

At the top of the package is the txtbxlib namespace. The ctxtbx class is the one and only one class implemented in the dll.

Perhaps the easiest way to explain the code is to trace the sequence of events that occurs when the user clicks on the textbox. So, here it is:

• User enters into textbox.

• The OnKeyDown event is triggered.

  protected override void OnKeyDown(KeyEventArgs e)
  {
      CheckLength();
      base.OnKeyDown(e);
  }
  

  The method will invoke CheckLength

• The CheckLength is triggered. The method checks the length of the character string in ctxtbx every time the user enters text into the textbox. If length of character string ctxtbx.Length exceeds ctxtbx.FlashLength, event OutOfRangeEvent is fired. If not, nothing happens.

  public delegate int OutOfRangeDelegate(int num);
  
  publicevent OutOfRangeDelegate OutOfRangeEvent;
  

  Now, the association between the OutOfRangeEvent and its handlers can be found in the constructors:

  OutOfRangeDelegate d1 = new OutOfRangeDelegate(this.OnOutOfRange_1);
  OutOfRangeDelegate d2 = new OutOfRangeDelegate(this.OnOutOfRange_2);
  
  this.OutOfRangeEvent += d1;
  this.OutOfRangeEvent += d2;
  

  The above code snippets maps handler OnOutOfRange_1 and OnOutOfRange_2 to OutofRangeEvent through delegate OutOfRangeDelegate.

• Event handlers invoked.

  • OnOutOfRange_1<CODE>

    This method spins up a thread to execute <CODE>FlashIt(..) - which gives you the flashing.

  • OnOutOfRange_2

    This method changes the border style from fixed-single to fixed-3D.

• Let�s say the user realizes that she made a mistake and truncates the character strings to less than ctxtbx.FlashLength. Once again, OnKeyDown is triggered.

• CheckLength is triggered in turn. But, this time, since the number of characters in the textbox ctxtbx.Length is less than ctxtbx.FlashLength, OutOfRangeEvent is NOT fired and the thread that executes the flashing (m_FlashThread) is aborted.

That�s pretty much it.

• Project Package: ctxtbx.zip

• ctxtbx Control

  • Project Type: C# class library

  • Project Name: txtbxlib

  • Binary: txtbxlib.dll (Release folder)

  • Key file: txtbxlib.snk

• SomeClient

  • Project Type: C# Windows Application

  • Binary: SomeClient.exe (You need to install control assembly to GAC first!)