Control Arrays

What Is a Control Array?


In Visual Basic, you can create arrays of any data type you want. You can also create an array of controls. Control arrays are a distinctive feature of Visual Basic that brings efficiency and power to the language. You can use them to create a common event procedure that's shared among all the controls in the control array. You also can use them to add and remove controls and forms to your program dynamically at runtime. This chapter shows you all you need to know to be able to work effectively with them.

Can I create a control array?

The name Index is used for other purposes, so check the online help before assuming that a control can be added to a control array.


All the intrinsic controls can be used in control arrays. These controls all have an Index property that's used to identify a particular control in a control array.


Creating a Control Array at Design Time


Many control arrays that you create will be built at design time. As you add controls to your form, you will need to group some of them into control arrays. This example shows you how to do that.

Create a control array of CommandButtons
1. Add a CommandButton to the center of the form frmMain and name it cmdMyButton. Set the value of cmdMyButton's Caption property to Action.

2. Make sure that cmdMyButton is selected. Choose Copy from the Edit menu to copy the CommandButton to the Clipboard.

3. Choose Paste from the Edit menu . You're presented with a dialog box asking whether you want to create a control array. Click Yes to create the control array.


Now that the control array is created, if you go to the Properties window and display the Object drop-down list, notice that there are now two CommandButtons with the name cmdMyButton, each with its own subscript.



Double-click either CommandButton to look at the Click event procedure. Notice that it now has an Index argument. This argument is an Integer that indicates the subscript of the control to which the event procedure applies. Because all controls of a control array share the same event procedure, you differentiate between controls by the value of Index--0 is the first control, 1 is the second control, 2 is the third, and so on.

The code in Listing 3.18 displays a string in the titlebar of the form frmMain that reports which CommandButton of the control array cmdMyButton() the user clicked. Copying this code to the cmdMyButton_Click(Index as Integer) event procedure can give you a sense of how to work with the Index argument.

LISTING 3.18 The CommandButton's Click Event Handler

01 Private Sub cmdMyButton_Click(Index As Integer)
02 ` Change the form's caption to indicate which
03 ` button in the control array generated an event.
04 Me.Caption = "You clicked button #" & Index & "."
05 End Sub




Extending Control Arrays at Runtime


Making a control array at design time will suffice if you know how many controls you will need in the array. But what do you do if you don't know how many controls you will need in your control array until the program is running? You solve this problem by adding controls to your control array at runtime by using the Load statement.

Add a control to a control array at runtime

1. Add a CommandButton to the upper-left corner of the form frmDArry and name it cmdCtrlArray.



Creating a control array

This action creates a control array with one element. The Index must be set to zero initially, so that controls loaded later will be added to the control array correctly.

2. In the Properties window, set the value of the CommandButton's Index property to 0.

3. So you can tell the controls apart at runtime, set the CommandButton's caption to Button #0.

4. Add the code in Listing 3.19 to the form's Form_Load() event.

5. Save and run the code.

LISTING 3.19 Adding a New CommandButton

01 Private Sub Form_Load()
02 `Create a new command button
03 Load cmdCtrlArray(1)
04
05 `Move it directly underneath the old one
06 cmdCtrlArray(1).Left = cmdCtrlArray(0).Left
07 cmdCtrlArray(1).Top = cmdCtrlArray(0).Top _
+ cmdCtrlArray(0).Height
08 cmdCtrlArray(1).Caption = "Button #1"
09
10 `Make the new button visible
11 cmdCtrlArray(1).Visible = True
12
13 End Sub

When you run the code, notice that the program makes a new CommandButton on the form and places it just below the first

Where did the control go?

All newly created elements of a control array have a Visible value of False. When you make your new controls at runtime, don't forget to put a line of code in that sets the value of the Visible property to True. Otherwise, you can't see the control.

You must do a certain amount of tweaking to get a newly created control to be operational in your program. New controls are exact duplicates of the first control element of the control array. The values of all properties except Index and Visible are identical--including the values of Left and Top. Thus, when you create a new control, it will be placed right over the first control in the array. For the new control
to be able to coexist with other controls in the control array, you must move the control to a new position.