As previously mentioned, a constructor describes what to do when an application creates an object based on the elements described in the class. The class is a blueprint of sorts that an application uses to create an instance of the class, or an object. The act of creating an instance of the class is called instantiation. All these fancy terms simply mean that you’re building an object based on a particular class definition—nothing more.

Every class requires a constructor, which has precisely the same name as the class and no return type. If you don’t specifically create a constructor, the compiler uses a default constructor—a constructor that doesn’t require any input arguments or perform any useful work. The default constructor is empty. The example class will use the constructor to assign values to the variables that the class requires to work and perform other essential startup tasks. Example 8-1 shows the constructor for this example. The global variables appear alongside their matching properties in the Creating the Private Variables and Public Properties section of the chapter. You won’t understand everything in the constructor just yet, but you will by the time you reach the end of this part of the example.

// Define the class constructor to initialize variables
// and perform other useful tasks.
public TestClass()
{
    // Allow additions and deletions.
    _AllowAdditions = true;
    _AllowDeletions = true;

    // Create an empty ball list.
    _BallList = new List<BallData>();
}

The _AllowAdditions and _AllowDeletions variables determine whether the caller can add or remove balls from the list. The constructor sets these variables to true because most developers will want to add and remove balls at the outset.

The actual ball list is a List of type BallData. You’ll learn more about the BallData type in the Defining a Structure section of the chapter. The example could have used a simple array to hold the list of balls, but using a List provides access to additional methods that make managing the list easier. All that the constructor does is initialize _BallList—it doesn’t add any balls to the list because the developer wouldn’t expect that.

Two of the ball properties will work fine with an enumeration—size and color. Someone could probably argue that balls come in a large number of sizes, but the fact is that the number of sizes is finite and therefore adaptable to an enumeration. You use the enum keyword to define an enumeration. Then, you create a list of comma-separated entries to go into the enumeration, as shown in Example 8-2.

// Create an enumeration that contains a list of acceptable ball colors.
public enum BallColor
{
    Red,
    Yellow,
    Green,
    Blue,
    Purple
}

// Create an enumeration that defines the possible ball sizes.
public enum BallSize
{
    Small,
    Medium,
    Large
}

If you plan to use the enumeration outside the class, you must define it as public. It’s rare that you’d define an enumeration as private (which means that no one else can see it). Each enumeration must also have a unique name, which is BallColor and BallSize in this case.

Enumerations also usually reside outside the class structure, but within the namespace. This makes the enumeration easier for the developer using your class to access. Consequently, your code should look something like the window in Figure 8-1 after you add the enumerations to it.

Figure 8-1. Create the required enumerations for this example.

Your class will use global variables to hold data, but you don’t want just anyone looking at this information in an uncontrolled manner. Instead, you want to control access to the data through properties. Using properties makes it possible check incoming data in a number of ways to ensure that it’s safe for your class. In addition, you can filter and format outgoing data if desired. As a consequence, variables should always be private in a class, but properties will normally be public so that everyone can access them. Example 8-3 shows the private variables and their associated public properties for this example.

// Make it possible to control additions and deletions.
private Boolean _AllowAdditions;
public Boolean AllowAdditions
{
    get { return _AllowAdditions; }
    set { _AllowAdditions = value; }
}
private Boolean _AllowDeletions;
public Boolean AllowDeletions
{
    get { return _AllowDeletions; }
    set { _AllowDeletions = value; }
}

// Define the list of balls for this application.
private List<BallData> _BallList;
public List<BallData> BallList
{
    get { return _BallList; }
}

// The person using the class may want to know how
// many balls are in the list.
public Int32 BallCount
{
    get { return _BallList.Count; }
}

Properties can take a number of forms. The most common form is shown with _AllowAdditions and AllowAdditions. The AllowAdditions property shows how you declare a standard property—one that doesn’t do anything special and allows both get (read) and set (write) access. You can use this sort of setup as long as you’re certain that the class user won’t do anything with the property that will cause damage to the object. In this case, Boolean values are safe. The _AllowDeletions and AllowDeletions pair works the same way.

The _BallList variable is a List of type BallData. Each element contains the information for one ball in the list. The BallList property only allows get access as a security feature. You don’t want anyone to supply their own list of balls; instead, you want to manage the list with your class. It’s essential to control the data in such a way as to make your class reliable and secure. This way, the developer using your class can access the list of balls, but can’t force the object holding the list to do anything other than supply the data as output.

Sometimes a property won’t have a variable associated with it. In fact, you’ll find many such properties in real-world classes. The BallCount property doesn’t directly manipulate _BallList. Instead, it returns the number of elements in _BallList so that the caller knows whether there are any balls to process. Theoretically, the caller could obtain the same information quite easily, but there’s a chance that the callers list of balls is outdated. Providing this property ensures that the count the caller gets is the right one.

These aren’t the only ways to work with properties. You’ll see another property example in the Defining a Structure section of the chapter.

Structures serve a number of essential purposes. However, the most important reason to use them is to create structured data elements in your application. Unlike a class, structures only contain data elements for the most part. You define a structure using the struct keyword. Like enumerations, structures usually reside outside the class (within the namespace) to make them easier to access. Example 8-4 shows an example of a structure.

// Define a structure to hold the ball information.
public struct BallData
{
    // It's possible to define Color and Size as fields
    // because their content is strictly controlled by the
    // enumeration.
    public BallColor Color;
    public BallSize Size;

    // Use a private field and a public property for the Name.
    private String _Name;
    public String Name
    {
        get
        {
            return _Name;
        }
        set
        {
            // Check the name length for potential problems.
            if (value.Length <= 10)

                // When the name is the right length, use it.
                _Name = value;
            else

                // Otherwise, tell the developer using the class
                // that there is an exception.
                throw new
                    ArgumentOutOfRangeException(
                        "Provide a string that is ten characters long.");
        }
    }
}

This structure contains three data entries: Color, Size, and Name. Color and Size are relatively safe entries because the information they contain is strictly controlled by the associated enumerations. Someone using the class won’t be able to provide unwanted information in either of these two entries.

However, Name is simply a String. Someone could provide the wrong kind of information when working with it. The name could be too long, filled with spaces, or damaging in some other way. A developer with nefarious intent could even send a script instead of a name, just to see what would happen. In this case, the code simply verifies that Name isn’t too long. However, in a production application you’d include additional checks to ensure that the data is correct.

Many classes provide events to alert the caller to specific conditions. When you think about events, think about actions because that’s what events are all about. Events typically have five elements:

This section discusses how to create the delegate and the event declaration for three events: OnBallAdded, OnBallDeleted, and OnEndOfBalls. These events signal changes in _BallList that a developer may need to know about. Example 8-5 shows the code required to perform this task.

// Tell the user when balls are added.
public delegate void BallAdded(BallData Ball);
public event BallAdded OnBallAdded;

// Tell the user when balls are deleted.
public delegate void BallDeleted(BallData Ball);
public event BallDeleted OnBallDeleted;

// Indicate there are no more balls in the list.
public delegate void EndOfBalls();
public event EndOfBalls OnEndOfBalls;

This doesn’t look like much code, but a lot is going on behind the scenes. As you can see, the first line declares a delegate in each case. The delegate could return a value, but normally it doesn’t. Many delegates do require input arguments, such as the BallData type uses for two of the delegates.

The second line contains the event declaration. Each declaration is public so developers working with the class can access the events. The event keyword comes next. The third element is the name of a delegate to associate with the event that controls the event signature. Finally, the code provides an event name. Most event names start with the word On, followed by the name of their associated delegate. However, nothing says that you absolutely must follow this policy.

When creating a class, most developers create the groundwork, as this example has done. All of the elements are in place now for creating methods that finalize the class interaction with the application. Example 8-6 shows the classes provided with this example.

// Create methods for adding and removing balls.
public List<BallData> AddBall(BallData NewBall)
{
    // Verify that we can add the ball.
    if (_AllowAdditions)
    {

        // Add the new ball.
        _BallList.Add(NewBall);

        // Raise an event to indicate the addition.
        if (OnBallAdded != null)
            OnBallAdded(NewBall);

        // Return the updated list.
        return _BallList;
    }
    else
    {
        // Tell the developer there is a problem.
        throw new InvalidOperationException("Additions not allowed.");
    }
}

public List<BallData> DeleteBall(BallData OldBall)
{
    // Verify that there is a ball to delete.
    if (_BallList.Count == 0)
        throw new InvalidOperationException("There are no balls to delete!");

    // Verify that deletions are allowed.
    if (_AllowDeletions)
    {
        // Remove the existing ball.
        _BallList.Remove(OldBall);

        // Raise an event to indicate the deletion.
        if (OnBallDeleted != null)
            OnBallDeleted(OldBall);

        // Raise an event if this is the last ball.
        if (_BallList.Count == 0)
            if (OnEndOfBalls != null)
                OnEndOfBalls();

        // Return the updated list.
        return _BallList;
    }
    else
    {
        // Tell the developer there is a problem.
        throw new InvalidOperationException("Deletions not allowed.");
    }
}

// Define a method for obtaining a list of ball names.
public List<String> GetNames()
{
    // Create an empty list to hold the name.
    List<String> Names = new List<String>();

    // Obtain a list of names from the internal list.
    foreach (BallData Item in _BallList)
        Names.Add(Item.Name);

    // Return the resulting list.
    return Names;
}

// Define a method for returning a specific ball.
public BallData GetBall(String Name)
{
    // Check each item in the list for the name.
    foreach (BallData Item in _BallList)

        // If the name matches, return the item to the
        // caller and exit the loop.
        if (Item.Name == Name)
        {
            return Item;
        }

    // Otherwise, throw an exception to indicate that the
    // ball wasn't found.
    throw new KeyNotFoundException("The ball name doesn't exist.");
}

Because of the way the class is constructed, it must have the following two methods: AddBall() and DeleteBall(). Otherwise, the class user could never interact sufficiently with _BallList to make the class usable. Many classes have methods such as these that must be in place to make the class useful. You should make a list of them as part of defining the class. In both cases, the method determines whether an addition or deletion is allowed. If it’s allowed, the code adds or deletes a ball as required, and then raises an appropriate event—either OnBallAdded() or OnBallDeleted(). The method then returns the current _BallList to the caller for further processing if necessary. When additions or deletions aren’t allowed, the method throws an exception.

Deleting a ball is a special operation. You can keep adding balls to the list until the system runs out of memory (a very long time for modern systems). However, you can’t delete balls that don’t exist. The DeleteBall() method looks for this problem and throws an exception if that condition occurs. To help prevent someone from trying to delete a ball when the list is empty, the method also raises the OnEndOfBalls() event when the list is exhausted after a previous deletion. The caller can handle this event and disable deletions in the application by using it.

The GetNames() method has a number of uses. The most obvious use is to populate a list box in the calling application with the names of balls currently in the list. A second use is to obtain a list of possible names to delete. An application may decide to delete all balls that begin with the letter S, which would require obtaining a list of the ball names first. The GetNames() method returns a List of type String to the caller that’s obtained by accessing each ball in _BallList using the foreach loop and adding its name to the list. If there are no names in the list because there are no balls in the list, the method returns an empty list, which is what the caller will expect.

The GetBall() has just one use for the most part. When you want to delete a ball from the list, you must supply a BallData object to the DeleteBall() method. It’s possible to obtain this information directly using a local _BallList object, but it’s better to call the class for the information so that you can ensure that the data is both current and correct. In this case, the code uses a foreach loop to locate a ball with the required name. It then returns the BallData object to the caller when found. If the object isn’t found, the method raises an exception that the application should handle.

As in most cases, you need to add a using statement to your code to make certain classes available. In this case, the only class you need to make available is TestClass. Consequently, you add the following using statement:

using TestLibrary;

The application needs to perform a few tasks when it starts. For example, it must instantiate a copy of the TestClass for use with the application. Of course, you’ll create a number of global variables used with the application methods. Example 8-7 shows the code needed for this purpose.

// Create an instance of TestClass.
TestClass TheClass;

// The current ball.
List<BallData> CurrentBalls;

// The selected ball within the list.
Int32 SelectedBall;

public Form1()
{
    InitializeComponent();

    // Initialize the TestClass.
    TheClass = new TestClass();

    // Set the source of information for the comboboxes.
    cbColor.Items.AddRange(Enum.GetNames(typeof(BallColor)));
    cbSize.Items.AddRange(Enum.GetNames(typeof(BallSize)));

    // Create an empty ball list.
    CurrentBalls = new List<BallData>();

    // Set the selected ball number.
    SelectedBall = 0;
}

The first global variable is TheClass, which is the instance of TestClass used for this application. The constructor instantiates TheClass without any balls added to it.

You’ll use CurrentBalls to store a list of the balls currently in TheClass. This information is especially useful when debugging the application, but it also comes in handy for display purposes. Because there aren’t any balls in TheClass at the outset, CurrentBalls is initialized to a blank list in the constructor.

Because it’s important to keep track of the current ball in the list, the application creates SelectedBall. This value is updated every time the user adds or deletes balls, and also when the user moves from one ball to another using the Next and Previous buttons. In short, SelectedBall always points to the ball displayed on screen.

The constructor also has some odd-looking code that initializes the list of items in cbColor and cbSize. The Enum.GetNames() method obtains a list of names based on the strings inside of BallColor and BallSize. These names are presented to cbColor and cbSize as an array of strings, which you add using the AddRange() method. The result is a list of strings like the one shown in Figure 8-5 for cbColor.

Figure 8-5. In some cases, it’s best to dynamically fill a combobox with entries, rather than use a static list.

It helps to have a centralized means of displaying the ball data. You have to think about two situations. In the first situation there aren’t any balls in the list. When the application starts, there aren’t any balls in the list, so all of the fields should be blank. There won’t be any balls in the list when the user deletes the last ball either, so the fields should again be empty. The second situation is when there are balls in this list. In this case, the code should display the data pointed at by SelectedBall. Example 8-8 shows the code used to display information in these two scenarios.

private void DisplayCurrentBall()
{
    if (TheClass.BallCount == 0)
    {
        // Clear the form.
        txtBallName.Text = "";
        cbColor.SelectedIndex = -1;
        cbSize.SelectedIndex = -1;

        // Disable the Next and Previous buttons.
        btnNext.Enabled = false;
        btnPrevious.Enabled = false;
    }
    else
    {

        // Enable or disable the Next and Previous buttons as needed.
        btnNext.Enabled = true;
        btnPrevious.Enabled = true;
        if (SelectedBall == TheClass.BallCount - 1)
            btnNext.Enabled = false;
        if (SelectedBall == 0)
            btnPrevious.Enabled = false;

        // Obtain the information for the selected element.
        BallData ThisBall = CurrentBalls.ElementAt(SelectedBall);

        // Place the information in the form.
        txtBallName.Text = ThisBall.Name;
        cbSize.SelectedItem = ThisBall.Size.ToString();
        cbColor.SelectedItem = ThisBall.Color.ToString();
    }
}

One of the questions that people ask relatively often online is how to clear the content of a combo box once you set it. The answer is to set the SelectedIndex property value to -1. For some reason, setting the Text or SelectedText property won’t work. Clearing a text box is much easier. You simply set its Text property to a blank string, as shown.

Part of the process for working with the balls is to ensure that the Next and Previous buttons are set properly. The code begins by enabling both of them. When specific conditions are true, such as SelectedBall pointing to the beginning of the list, the associated button is disabled. When there’s zero or one ball, neither of the buttons is enabled because there aren’t any other balls to see. Otherwise, you’ll see the correct buttons enabled.

When displaying ball information, you need specifics about a particular ball. The code uses the ElementAt() method to obtain this information from CurrentBalls using SelectedBall as the selector. When the code obtains this information, it can transfer the information directly to the user interface as shown.

A central part of the application is adding and removing balls from the list. Otherwise, the application can’t exercise any of its other functions. Example 8-9 shows the code used to add and remove balls.

private void btnAdd_Click(object sender, EventArgs e)
{
    // Don't allow blank values.
    if ((txtBallName.Text == "") | (cbColor.Text == "") | (cbSize.Text == ""))
    {
        MessageBox.Show("You must provide values for all three fields.");
        return;
    }

    // Crate a new BallData structure.
    BallData NewBall = new BallData();

    // Fill it with data.
    try
    {
        // The name may not meet the criterion.
        NewBall.Name = txtBallName.Text;
    }
    catch (ArgumentOutOfRangeException AOORE)
    {
        // If not, display an error message, display the
        // previous data, and exit.
        MessageBox.Show(AOORE.Message);
        DisplayCurrentBall();
        return;
    }
    NewBall.Color = (BallColor)cbColor.SelectedIndex;
    NewBall.Size = (BallSize)cbSize.SelectedIndex;

    // Create the new ball.
    CurrentBalls = TheClass.AddBall(NewBall);

    // Change the ball selection.
    SelectedBall = CurrentBalls.Count - 1;

    // Display the ball information.
    DisplayCurrentBall();
}

private void btnDelete_Click(object sender, EventArgs e)
{
    // Create a blank BallData object.
    BallData DeleteBall = new BallData();

    // Obtain the correct ball to delete based on the entry
    // in the text box.
    try
    {
        DeleteBall = TheClass.GetBall(txtBallName.Text);
    }
    catch (KeyNotFoundException KNFE)
    {
        // Display an error message if the ball isn't found and
        // exit the event handler.
        MessageBox.Show(KNFE.Message);
        return;
    }

    // Use the information to delete the ball.
    try
    {
        CurrentBalls = TheClass.DeleteBall(DeleteBall);
    }
    catch (InvalidOperationException IOE)
    {
        // Display an error message if necessary.
        MessageBox.Show(IOE.Message);
    }

    // Check the number of remaining balls.
    if (TheClass.BallCount > 0)
    {
        // Reset the selected ball and redisplay if possible.
        SelectedBall = 0;
        DisplayCurrentBall();
    }
    else
        DisplayCurrentBall();
}

The first task to perform when adding a ball is to ensure that the entry is at least complete. The initial if statement checks for values in each of the fields. When any of the fields are blank, the application tells the user to provide additional information. More advanced applications would actually highlight the field missing the data. The point is that you must perform checks like this when adding information to any sort of data source. Even the most conscientious user will occasionally forget to provide required information.

The next step is to create a new BallData object, NewBall, to fill with data. Remember that the Name entry is actually a property that checks for invalid input, so you must place this part of the code within a try ... catch block, as shown. Make sure you catch the correct exception, which is ArgumentOutOfRangeException in this case. Because you don’t want the incorrect information displayed on-screen, the code calls DisplayCurrentBall() to reset the display to show correct information. If the Name property check succeeds, the code finishes adding the information to NewBall. It then calls AddBall() to create the ball, updates SelectedBall, and calls DisplayCurrentBall() to show the ball information on-screen.

Deleting a ball follows a different process than adding one. The application doesn’t force the user to try to remember the specifics about a ball—just the ball name. It then uses the GetBall() method to obtain a BallData object from the class that contains the full ball information. If two balls in the list have precisely the same name, the application deletes the first one. In a production application you can add code that displays a list of all of the balls that have the correct name and tell the user to choose one. The example takes this route in the interest of simplicity and because many real-world applications work precisely this way. When the name the user has requested doesn’t exist, the class throws a KeyNotFoundException and the application must be ready to handle it.

After the application obtains a BallData object, it uses it to call DeleteBall(). Again, a potential exception is associated with this call, so you must provide code to handle it. Handling each potential exception separately makes it possible to create a more reliable application and one that provides better information to the user about the source of problems.

It’s possible that deleting the requested ball will empty the list. Consequently, the code relies on the BallCount property to check for additional balls. If there’s an additional ball, the code sets SelectedBall to 0 and displays the first ball in the list by calling DisplayCurrentBall(). When there aren’t any balls to display, the code simply calls DisplayCurrentBall() to clear the fields and disable the Next and Previous buttons.

Most of the hard work has been done for this application. All you really need now is a way to move between the ball entries. Example 8-10 shows how to perform this task.

private void btnNext_Click(object sender, EventArgs e)
{
    // If we're not at the end of the list, increment the
    // selected ball count and display the new information.
    if (SelectedBall != TheClass.BallCount - 1)
    {
        SelectedBall++;
        DisplayCurrentBall();
    }
}

private void btnPrevious_Click(object sender, EventArgs e)
{
    // If we're not at the beginning of the list, decrement the
    // selected ball count and display the new information.
    if (SelectedBall != 0)
    {
        SelectedBall--;
        DisplayCurrentBall();
    }
}

In both cases, the code determines whether there’s actually a next or previous ball in the list. If there is, the code changes the value of SelectedBall and calls DisplayCurrentBall() to display it.

Users may want to see a list of all of the balls. The form that the application uses is a detail form, but many users will want some form of grid. Because the example is so simple, you can get by using a message box for the task. However, in a real-world application with complex data requirements, you’d use multiple forms to perform the task. Example 8-11 shows how to display a list of ball names for this example.

private void btnShow_Click(object sender, EventArgs e)
{
    // Obtain a list of the ball names.
    List<String> BallNames = TheClass.GetNames();

    // Create a string from the array.
    String Result = "";
    foreach (String Item in BallNames)
        Result += Item + "
";

    // Display them in a message box.
    MessageBox.Show(Result);
}

The call to GetNames() provides a List of type String. The code uses a foreach loop to change this List into a single String, Result, with suitable formatting. When the String is complete, the code displays a message box like the one shown in Figure 8-6 with three ball entries.

Figure 8-6. The application output shows the list of balls stored in TheClass.

TestClass has three events that the application should handle. This is not because the application is incomplete as it is right now, but simply because this is your test harness application and must test every aspect of the application. Plus, you’ll want to know how to work with events found within classes at some point. To perform this task, you must add some code to the constructor. The IDE helps add this code, but you’ll need to get it started. The following procedure shows how to add the event handlers.

Creating Class-Based Event Handlers

At this point, you have three event handlers that won’t do very much except to say they aren’t implemented. You need to add some code to them. The application doesn’t require the events for the tasks that it’s performing, so a simple message box will work just fine. Example 8-12 shows the code you need for this part of the application.

void TheClass_OnEndOfBalls()
{
    MessageBox.Show("End of the list!");
}

void TheClass_OnBallDeleted(BallData Ball)
{
    MessageBox.Show("The ball was deleted.");
}

void TheClass_OnBallAdded(BallData Ball)
{
    MessageBox.Show("The ball was added.");
}

As you can see, each event handler reports on a status change. The user will get feedback now saying that the task completed successfully.