View source for Control arrays

== What is a control array? ==

A control is just like a regular array but instead of an array of integers or strings, you have an array of textboxes or labels or whatever other control you wish to make an array of. You then access each control the same way you would access a normal array: with an index.

== Why is a control array useful? ==

Imagine you wish to create a game like minesweeper. You want a 10x10 grid of buttons. If you didn't know about control arrays, you might create 100 buttons, named square1 to square100. You would have 100 click events, one for each button. Not only is this very tedious, but the other reasons why this is bad are obvious. With a control array, you would just have an array of buttons called squares which you would index with the numbers 0 to 99. You would only have one click event to deal with. This is obviously much better!

== How do you create a control array? ==

Creating a control array is simple. You can do it in one of several ways:

* Create the initial control the way you would any other control and give it a name. Following on from the above example, you might call it "squares". Now select the control and copy it (hint: use the control-c shortcut). Now simply click the destination, be that the form or a container such as a frame or picturebox, and paste it (hint: use the control-v shortcut). The first time you do this, you will be asked if you wish to create a control array. Click on yes. Now when you continue to paste them, you won't be asked. Also, if you name another control the same name as the control array (squares, for example), it will become part of the array.

* Create the initial control but this time set its index property to "0". Now when you paste further instances of this control or create controls with the same name, the array will be created. You won't be prompted whether or not to make one.

* Change the name of some already added controls so that they are all the same. Once you make 2 the same, you will be prompted to make a control array. Click yes and continue as normal.

== Using a control array ==

Once you have created a control array, using it is simple. When you type the name of the control array and press the period (.) key, you'll see that the intellisense gives you a list of methods shown below:

* Count - This is the number of controls in the array
* Item - When suffixed with the index in brackets, this will refer to a single control in the array corresponding to the index. This is similar to the Item method of a collection. This is the default method so if you just add the brackets without typing "Item", it'll still work.
* LBound - The lower boundary of the array. This should be, and usually will be 0.
* UBound - The upper boundary of the array.

To access an individual control you can do something like:

Squares(0).Caption = "x"

or

Squares.Item(0).Caption = "x"

It doesn't matter which you use because, as mentioned, Item is the default method and so both mean the same thing.

== Events in a control array ==

There is only ever one procedure which handles a particular event for each control in the control array. For example, if you have a control array of buttons then the click event will be the same procedure for each and every button. So how do you tell which button was pressed? The answer is simple. Each event will now have an Index parameter as it's first parameter, telling you the index of the particular control which the event applies to.

A common mistake is to create a control, write the events for it, and THEN turn it in to a control array. Now none of the events have the Index parameter as they should, because they were created before the control was part of an array. This will lead to a compile time error message. The reverse is certainly possible, although much rarer.

Here is an example:

 Private Sub Squares_Click(Index As Integer)
    MsgBox "You clicked on button " & Index & _
           " with caption " & Squares(Index).Caption
 End Sub

== Creating controls at runtime ==

Let's recall the squares example again. Obviously creating 100 buttons, even using the control-c and control-v shortcuts for copy and paste, is still a tedious task. Well the good news is that you can create them using code.

How do we do this? Simply create an initial control as you normally would and make sure to set the Index property to 0. Now you can use the Load procedure to load new controls. Each new control inherits the main properties of the initial one all except the visible property which will be set to false always. So remember to show them when you're done.

Here's how we would create a grid of 100 squares, assuming we already created a control called "Squares" at position 0,0 and with an Index property set to 0:

 Dim x As Integer, y As Integer, index As Integer
 For x = 1 to 10
    For y = 1 to 10
        index = index + 1
        
        Load Squares(index)
        
        Squares(index).Left = (x - 1) * squares(0).Width
        Squares(index).Top = (y - 1) * squares(0).height
        Squares(index).Visible = True
    Next y
 Next x


And that's it for control arrays!