Working With CheckBoxes in Micro Focus Visual COBOL

The CheckBox control is used to enable selection of different options available in a given process or application. CheckBoxes are normally used to enable multiple selections rather than single items.

This article will review the common properties of the CheckBox control. These are the name, text, checked and checkstate properties. We'll also review the use of events associated with a CheckBox. An event when it occurs invokes or calls a method to handle the situation that has just occurred. For those unfamiliar with the term "method", a method is a piece of code that is executed when called, kind of like a small program. We'll go into methods more in a little bit.

WinForm

We've already created the WinForm we'll be using. Remember, the intent is to learn how to manipulate CheckBoxes, not create WinForms. Our WinForm was specifically designed to be simple and to only present the basic information. It appears as:

Pretty simple, right? At the top we have a Label that provides some information about Check Boxes. We also have a button on the screen that says "Reset" and we have the Check Boxes contained within a group item titled "Color Selection". There are actually more controls but they are "hidden" from the user right now. We explained about the "Visible" property in previous articles, please consult the previous articles for how to manipulate this fun property or check the Microsoft documentation.

Check Box Properties

Check Boxes, like all controls, have properties associated with them. Although there are many properties that can be manipulated there really are only a few that have any real implication when working with Check Boxes.

When working with properties the general format used to update a property is:

SET controlName::property TO {something}
Where: controlName is the name of the control
Property is the name of the property to be manipulated
{something} is specific to each property and can be text, Boolean, enums, etc.

We're going to concentrate our discussion on the following properties:

Property	Description
Name	How the control is referenced programmatically
Text	The actual text that is displayed to the user
Visible	Can you see the control. Accepts a Boolean value of "true" or "false"
CheckAlign	The location of the check box inside another control
Checked	Is the check boxed "checked"? Boolean value of "true" or "false"
CheckState	The current state of the check box. Possible values are "Unchecked", "Checked" or "Indeterminate". Works with the Behaviour property "ThreeState". More on these later.
AutoCheck	Causes the CheckBox to automatically change state when clicked
ThreeState	Enables three states of the check box, "Unchecked", "Checked" or "Indeterminate"

For information on the remaining properties for a Check Box 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 Check Boxes I like to use the abbreviation "cbx" in the first three positions and then follow that with something specific to what the Check Box is for. In our example we have three check boxes. Each will be the same so let's look at the first check box, the red one. I named this check box "cbxRed". 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.

Text Property

The Text property is the text the users sees next to each check box. Because our application works with colors I have the color selection for each check box. Our Text property contains the value "Red" as shown in the Property Panel:

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.

All of our Check Boxes are visible and thus the Visible property of each is set to true.

CheckAlign Property

The CheckAlign property determines the location of the check box inside the control.

The alignment uses a grid style display. Our example stayed with the default value of MiddleLeft. If you look carefully at the grid you can see that position appears a darker gray than the rest of the grid. While our example is using a font size that is hard to see a difference, adjust the font size in your example and see how the different selections affect how the text is positioned.

Checked Property

The Checked Property is a Boolean value of either "true" if the check box is checked or "false" if it is not.

The default state of the property is "false", which we have used.

CheckState Property

Similar to the Check Property, the CheckedState property provides additional information about the current status of the check box.

There are three possible selections:

CheckState	Appearance.Normal	Appearance.Button
Checked	The CheckBox displays a check mark.	The control appears sunken.
Unchecked	The CheckBox is empty.	The control appears raised.
Indeterminate	The CheckBox displays a check mark and is shaded.	The control appears flat.

The use of the Indeterminate state is enabled with the additional property "ThreeState". Indeterminate controls normally have a shaded appearance and are generally inaccessible to the user. The default value for the CheckedState property is "Unchecked" which is the value we have our check boxes set to.

ThreeState Property

The ThreeState property indicates whether the checkbox will allow three states or two.

The default value is "False" which is what our example uses.

AutoCheck Property

The AutoCheck property causes the check box to automatically change state when it is clicked. Now I experimented with this property to see how the affect it would have on the code. I like to take advantage of the options within the Framework and environment that make my coding life easier and this is one of them that I personally like as it makes my coding life easier.

By having this property set to "true" the values of the "Checked" and "CheckState" properties are automatically updated when the user clicks on the checkbox. This saves coding time by not having to verify if the value has changed or not and I can now use an event to monitor the checkbox, which I'll explain in bit. Experiment with this property on your own and see how it can affects your coding.

Events

We reviewed Events in a previous article but I'll go through them once more because they are important to coding in a distributed environment. If you're new to object-oriented programming you may not be familiar with the term "event". So before we talk about the events associated with the checkbox object I thought I'd try and define just what an event is and why it's important in Visual COBOL and distributed programming in general.
From MSDN we have the following definition of an event:

"An event is a message sent by an object to signal the occurrence of an action. The action could be caused by user interaction, such as a mouse click, or it could be triggered by some other program logic. The object that raises the event is called the event sender. The object that captures the event and responds to it is called the event receiver."

Simple, right? Let me add some more explanation to this definition. Let's look at the first sentence: An event is a message sent by an object to signal the occurrence of an action. This is essentially the core explanation, something happens and a notice is sent out to do something. In our case the button is clicked (the something happens); a notice is sent out (a "button click" event is raised); and something is done (the method btnReset_Click is executed). The rest of the definition is for information purposes, this first line is really what an event is: a notification that something has happened and someone has to address what has happened.

To access the events for the btnReset, in the properties Window select the button with the little lightning bolt on it. If you hover over it a tool-tip will appear informing you this is the button for events.

Click the lightning bolt and the following screen will be displayed (once all the sections are minimized):

If you'll notice I've left one section expanded, the Action area. The action "Click" has an entry next to it (btnReset_Click). This is the method that will be executed when the button is clicked. The Reset_Click method will reset the check boxes back to the original values so you can run the example again without having to restart the application. The code to accomplish this is:

There are also events associated with the checkbox control. When you clicked on a checkbox a message appeared saying you just clicked a specific color. The message was displayed when the "Checked_Changed" event was raised for a checkbox. The Check_Changed event is raised whenever the "Check" property is changed. See how all this is tying together? The code to display the message for each checkbox color is similar to the code used for the red checkbox so we'll show you that code:

Using the properties for the checkbox we can expand the code to eliminate the need for the reset button. If you look at the CheckedChanged event for the blue checkbox you'll see the following code:

When the CheckedChanged event is raised, the code now checks the state of the blue checkbox. If it is checked it displays the label at the bottom of the screen by setting the Visible property of the label to true. If it is not it hides the label at the bottom of the screen by setting the Visible property to false. This simple check of the properties can thus eliminate the need for a reset button in our example.

Try experimenting with the different properties and events. We've only covered the properties and events most commonly associated with the CheckBox control. There are many others and they may have an effect on how you create applications.

For further information about events and event handlers refer to the Micro Focus Visual COBOL documentation or MSDN.

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 CheckBox 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!