Working with TextBoxes in Micro Focus Visual COBOL

For information on the remaining properties for a Textbox or to review the properties above please see the Visual COBOL documentation or Microsoft Developer Network (MSDN).

Name Property

The Name property is used to provide a unique name to the control so it can be accessed programmatically. For TextBoxes I like to use the abbreviation 'tbx' in the first three positions and then follow that with something specific to what the Textbox is for. For Masked Textboxes I use the abbreviation 'mtb' in the first three positions. I like to use camel-case (capital letter for the first letter of each word) for readability purposes. I would highly recommend establishing a naming convention to be used in your shop.



Character Casing Property

When you entered some information for the multi-line textbox you may have noticed that no matter what you entered the characters were converted to upper case. This was due to the CharacterCasing property being set to 'Upper'. In some instances a program may only accept upper or lower case information. Rather than accept the information from the screen, create a parser to interpret the information for case, and adjust accordingly a simple setting in the control enables the proper case.



MaxLength Property

MaxLength is the maximum number of characters a textbox will accept. For the Basic textbox we've set the maximum number of characters to accept to '50'.



Password Character Property

One property that is very useful is the Password Character property. When a user enters data into a field with this property set the characters are automatically changed to the character in the property. For our example we've used the ampersand "@" character.



Experiment with this property and see what character works well for your environment.

Text Property

Text is the information entered into the textbox by the user. In most instances the text property will be set to null or spaces in the property dialog.

You may have an occasion where you will want to set an initial value and this is where you can do that. In our example we are actually reading the information the user entered into the different text boxes. We do this programmatically with the following code:



The 'text' property for each control was accessed and the contents were moved to a temporary working-storage field using the 'set' verb. The temporary holding fields were defined in the method using standard COBOL PIC clauses:



By using standard COBOL data definitions I can now call a standard COBOL program to process the data just entered.

Visible Property

The Visible property is used to either show or hide a control on a form. You can use hidden fields to store information that the user entered on a screen, as a counter or just about anything you don't want the user to see. In our example we use the Visible property to both show and hide different controls on the screen.

There are actually two buttons on the Form with only one being visible. We use the 'Visible' property with a value of 'True' to show a control or a value of 'False' to hide a control. The Process button has it's Visible property set to true via the Property Panel:

For the Reset Button the Visible property is set to 'False' in the Property Panel:

The Visible property can be manipulated through code to either show or hide an existing control.

When the Process button is clicked we want to hide it and then show the Reset button. The code to perform this little trick is:




The first line of code shows the hidden Reset button. (btnReset::Visible to true).

The next line of code hides the Process button. (btnProcess::Visible to false).

Masked Text Boxes

Our example uses two masked text boxes, one for numeric data and one for the entry of a typical United States Social Security Number.

Masked text boxes, as the name implies, enable the user to define a mask so that any data entered into the field will be checked to determine if it meets the criteria specified. For the numeric textbox we have set the Mask property to allow only numeric characters. This is accomplished by the following in the properties area:

We've entered 12 zeros, thus implying this textbox can only accept numeric data and only up to 12 numbers. Try entering a non-numeric character. Can you? There's more you can do with masks. Notice the selection button to the right of the zeros? When you click the button the following dialogue box appears:

The Input Mask screen allows the developer to use a preconfigured Mask or to define a custom mask (which is what we did with the 12 numeric characters). If you'll notice, the Social Security Number is a pre-defined mask and we simply used it with the other masked text box.

When working with masked textboxes though, no matter how you define the mask the data being accepted is still considered text (that is 'System.String' in .NET data types). So even though we defined the input to be numeric when we read it into our temporary fields programmatically it is text data and has to be converted to numeric. In our example we defined two fields, numericTemp and numericEntered and defined them as:

In order to read our data from the screen we first read the data from the screen field into the temporary character based field (numericTemp) and then move it into the numeric field (numericEntered). The following code accomplishes this:

Masked Textboxes can save a COBOL developer a significant amount of coding and testing. The edits a developer would normally have to define, create and test are already defined within the .NET environment. The coding time required to create a new form to place in front of an existing legacy application should be significantly reduced, not to mention the amount of code created. Masked Textboxes are a control anyone creating user interfaces should experiment with and become familiar with. This is a significant time saver.

Reset Button

The Reset button is used to return the application to the state it was in when we the application first started. Study the code and the technique. There is nothing different in the method than what has already been discussed above, without all the comments in-line in the code. In our example we called another method to reset the Visible property of all the controls rather than have them in the same method.

One technique I would like to point out is how the text fields are reset. Notice the construct "String::Empty"? We're taking advantage of the .NET Framework and the capabilities it provides. The String class has a read-only field and the value of this field is the zero-length string, "".

In application code, this field is most commonly used in assignments to initialize a string variable to an empty string. You can also test whether the value of a string is either null or String.Empty by using the IsNullOrEmpty method.

Wrap-Up

The ZIP file has all the necessary source code for you to follow along and see how to update the properties we've described in the article. Read through the code; learn from it and use it in your projects. Even though we used a WinForm to present the information, the same concepts apply to WPF or WebForms. Yes there may be differences but this should at least serve as a starting point to help you figure out how to manipulate similar properties in the other presentation environments. Also, if you have a TextBox property you're not sure how to work with send it to us. Chances are if you're having questions someone else is also and we'd like to help you figure it out and expand our examples!

Happy Coding!