TdhEditBox - A dynamically assignable and configurable pop-up text-entry box

• Download demo - 50 KB
• Download source - 72.6 KB

Introduction and Features

The TdhEditBox component originated as a minor "bell and whistle" for a custom TabControl/TabPage project. I'd wanted a visually intuitive way to allow users to change the TabPage.Text value, and I came up with a simpler version of this component. The demo screenshot shows the component being used for this purpose.

In making this an independent component, my goals were flexibility and ease of use (both for the programmer and the end-user). To that end:

1. The component may be added to the Visual Studio Toolbox and added to one's project as any other component.
2. The component code determines from the user's mouse or keyboard behavior when the edit-action is complete and/or rejected.
3. The component optionally uses Regular Expression validation, both during input and upon completion of the edit-action.
4. The component supplies several pre-defined (and tested) Regular Expressions, which may be easily employed by merely setting a property.
5. When "attached" to a control, the component contains code to figure out where the pop-up editbox ought to be positioned and its width.

Or, the programmer may set these values via his own code.

6. When "attached" to a control, the component itself optionally modifies the control's Text property upon successful completion of the edit-action.

Or, the programmer's code can use either a DialogResult value or an event handler to capture and make use of the text string entered into the pop-up edit box.

The TdhEditBox class supplies the public programming interface to a pop-up or on-demand System.Windows.Forms.TextBox control contained within a borderless System.Windows.Forms.Form, and this design is the basis of the component's flexibility of use.

Using the TdhEditBox Component With Your Application

The TdhEditBox component was written (and compiled) using VS2002 (.NET 1.0) with the intention that the source code be readily available to other developers regardless of the .NET version they are using.

To use the TdhEditBox component as is, add a reference in your project to the class library 'TDHEditBox.dll'.

// The namespace used in the 'TDHEditBox.dll' library is:

using TDHControls.TDHEditBox;

// Sample code using the TdhEditBox component:

// Instruct the [TdhEditBox] component code to automatically modify [this.Text]:
private void button1_Click(object sender, System.EventArgs e)
{
    // Let the TdhEditBox code determine its own position and dimensions
    // As [this] is a Form, the TdhEditBox code will occupy/hide
    // the entire area of [this.ClientRectangle]

    // This [tdhEditBox1.MaxLength] value will be retained until it is reset
    this.tdhEditBox1.MaxLength = 50;
    this.tdhEditBox1.Show(this, "", true);
}


// Capturing the [TdhEditBox] component .DialogResult value
// and programatically modifying [this.Text]:
private void button4_Click(object sender, System.EventArgs e)
{
    // Manually position the TdhEditBox over the Form's Title-bar
    System.Drawing.Point argPoint = new System.Drawing.Point(this.Left + 4, this.Top + 4);
    int argHeight = 22;
    int argWidth = this.ClientRectangle.Width;

    // This [tdhEditBox1.MaxLength] value will be retained until it is reset
    this.tdhEditBox1.MaxLength = 75;

    if( (this.tdhEditBox1.ShowDialog(argPoint, argHeight, argWidth, this.Text) 
        == System.Windows.Forms.DialogResult.OK)
    //&& this.tdhEditBox1.EditAccepted
    // if DialogResult.OK this will be true
    && this.tdhEditBox1.EditTextChanged 
    )
    {
        this.Text = this.tdhEditBox1.EditText;
    }
}


// Using the [TdhEditBox.OnEditComplete] Event
// and programatically modifying [this.Text]:
private void button5_Click(object sender, System.EventArgs e)
{
    // The [TdhEditBox.OnEditComplete] event-delegate may be attached
    //   using either of two methods. It's generally better to use 
    //   the [.OnEditComplete_AttachDelegate()] method, as this ensures
    //   that there is only one event-delegate attached to the component:
    //this.tdhEditBox1.OnEditComplete += 
    //    new TDHControls.TDHEditBox.EditComplete(this.button5_OnEditComplete);
    this.tdhEditBox1.OnEditComplete_AttachDelegate(
        new TDHControls.TDHEditBox.EditComplete(this.button5_OnEditComplete)
    );

    // Manually position the TdhEditBox over the Form's Title-bar
    System.Drawing.Point argPoint = new System.Drawing.Point(this.Left + 4, this.Top + 4);
    int argHeight = 22;
    int argWidth = this.ClientRectangle.Width;

    // This [tdhEditBox1.MaxLength] value will be retained until it is reset
    this.tdhEditBox1.MaxLength = 50;

    this.tdhEditBox1.Show(argPoint, argHeight, argWidth, this.Text);
}

private void button5_OnEditComplete(object sender, 
    TDHControls.TDHEditBox.EditEventArgs editArgs)
{
    if (editArgs.EditAccepted 
    && editArgs.EditTextChanged)
    {
        // One can capture the text entered in the [TdhEditBox] component
        //   in either of two ways:
        //this.Text = this.tdhEditBox1.EditText;
        this.Text = editArgs.EditText;
    }

    // Depending upon just how the [TdhEditBox] component is being used,
    //   it may be quite important to detach the event-delegate upon 
    //   completion of the edit-action.
    // The [TdhEditBox.OnEditComplete] event-delegate may be deattached
    //   using either of two methods. It's generally better to use 
    //   the [.OnEditComplete_RemoveDelegate()] method, as this ensures
    //   removal of all event-delegate(s) attached to the component:
    //this.tdhEditBox1.OnEditComplete -= 
    //    new TDHControls.TDHEditBox.EditComplete(this.button5_OnEditComplete);
    this.tdhEditBox1.OnEditComplete_RemoveDelegate();
}


// Using Regular Expression input validation with the [TdhEditBox] component:
private void button7_Click(object sender, System.EventArgs e)
{
    // This Regular Expression validation will be in effect until it is removed
    this.tdhEditBox1.FilterType = TDHControls.TDHEditBox.FilterTypes.PhoneNbr;

    // Setting [.MaxLength] generally isn't necessary; 
    //   The edit filter will see to it that the text entered is valid 
    //   according to the Regular Expression (including length).
    //   Though, in this example, if [.MaxLength] had previously  
    //   been set to a value < 14, we would want to reset/correct it here.
    this.tdhEditBox1.MaxLength = 14;

    this.tdhEditBox1.Show(this.txtPhone, "", true);

    // Since we don't want to use Regular Expression validation with any 
    //   other controls, let's remove the Regular Expression filters now 
    //   (i.e. now that [.Show()] has been called).
    // The [.Show()] method won't lose the Regular Expression filter values 
    //   at this point because they have already been passed to 
    //   the pop-up EditBox.
    this.tdhEditBox1.FilterType = TDHControls.TDHEditBox.FilterTypes.Clear;
}

Caveats to Using the TdhEditBox Component

One could, of course, make use of multiple instances of the TdhEditBox component in an application. However, the design intention is that a single instance should suffice. But, this does have a drawback -- specifically, that one needs to remember to unset or reset the various properties if the values set previously will interfere with the current usage.

For instance, if one had previously assigned/attached an OnEditComplete event delegate, and had not removed/detached it, the event will fire, and the associated event-code will execute on a subsequent use of the TdhEditBox instance. In the demo program, I intentionally coded an example of this behavior (which may be seen by clicking the "Change Form's Title (EventHandler - Forgetful)" button).

The TdhEditBox End-User Experience

The intention of the TdhEditBox component is that user interaction with it be intuitive and easy. Thus, no special user actions nor secondary controls are necessary to dismiss the component, whether to accept or reject the edit-action. Rather, the component is dismissed by keyboard or mouse behavior.

Specifically:

• Clicking anywhere outside the component's editbox dismisses the component and rejects the action. The exception to this is when any signature of the component instance's .ShowDialog() method is used to invoke the pop-up editbox.
• Use of the [Escape] key dismisses the component and rejects the action.
• Use of the [Return] key dismisses the component and accepts the action.
• Use of the [Tab] key dismisses the component and accepts the action.

The TdhEditBox Programming Interface

The members of the TdhEditBox's interface are:

• DialogResult - This (readonly) System.Windows.Forms.DialogResult property returns a value indicating the final status of the most recent usage of the TdhEditBox component: OK, Cancel, None, Ignore.
• EditAccepted - This (readonly) boolean property indicates whether the user accepted or rejected/canceled the edit-action.
• EditText - This (readonly) string property supplies the result of the user's usage of the TdhEditBox component.
• EditTextChanged - This (readonly) boolean property indicates whether the user actually modified the value of the EditText property.
• AttachedControl - This System.Windows.Forms.Control property allows a default control to be "attached" to the TdhEditBox component.
• MaxLength - This int property specifies the maximum length of the text which may be entered in the TdhEditBox component's editbox. The default value is 256.
• FilterInput - This string property defines an optional Regular Expression string to be used to validate the input to the TdhEditBox component's editbox as it is typed.
• FilterFinal - This string property defines an optional Regular Expression string to be used for final validation of the input to the TdhEditBox component's editbox.
• FilterType - This TDHControls.TDHEditBox.FilterTypes property may be used to set the FilterInput and FilterFinal properties to pre-defined and tested Regular Expression strings.

• public void Show() - Using this method requires that the AttachedControl property be set. This method is equivalent to: Show(AttachedControl, AttachedControl.Text, true);.
• public void Show(System.Windows.Forms.Control control, string initText, bool autoApplyEditedText) - Using this method, the component instance code will determine the positioning and dimensions of the pop-up editbox, relevant to the 'control' argument. The 'initText' argument supplies an initial string value to be displayed in the pop-up editbox; if an empty string is given, the instance code will use the 'control.Text' value. The 'autoApplyEditedText' argument determines whether the component instance code will automatically modify the 'control.Text' value upon user acceptance.
• public void Show(System.Drawing.Point ptShow, int height, int width, string initText) - When using this method, the programmer must supply the component instance with the position and dimensions of the pop-up editbox. The 'initText' argument supplies an initial string value to be displayed in the pop-up editbox.
• public System.Windows.Forms.DialogResult ShowDialog() - Using this method requires that the AttachedControl property be set. This method is equivalent to: ShowDialog(AttachedControl, AttachedControl.Text, true);.
• public System.Windows.Forms.DialogResult ShowDialog(System.Windows.Forms.Control control, string initText, bool autoApplyEditedText) - Using this method, the component instance code will determine the positioning and dimensions of the pop-up editbox, relevant to the 'control' argument. The 'initText' argument supplies an initial string value to be displayed in the pop-up editbox; if an empty string is given, the instance code will use the 'control.Text' value. The 'autoApplyEditedText' argument determines whether the component instance code will automatically modify the 'control.Text' value upon user acceptance.
• public System.Windows.Forms.DialogResult ShowDialog(System.Drawing.Point ptShow, int height, int width, string initText) - When using this method, the programmer must supply the component instance with the position and dimensions of the pop-up editbox. The 'initText' argument supplies an initial string value to be displayed in the pop-up editbox.

• public event TDHControls.TDHEditBox.EditComplete OnEditComplete - The OnEditComplete event fires when the user's mouse or keyboard action causes dismissal of the TdhEditBox instance, whether acceptance or rejection of the edit-action.
• public delegate void EditComplete(object sender, TDHControls.TDHEditBox.EditEventArgs editArgs) - The EditComplete event delegate defines the signature of the OnEditComplete event.

History

• 2008 July 17: Submission of TdhEditBox - ver. 1.0.005 to The Code Project.