Xojo Documentation Xojo Documentation

Control Sets serve two purposes. One is to allow you to have a collection of controls that share a single set of event handlers. The other is to create controls dynamically while your app is running. In both cases, you create a control set by selecting a control and then changing the value for the Member Of property in the Inspector (located in the Control Set group on the Advanced tab of the Inspector).

Creating a New Control Set

To create a new Control Set for the selected control, choose New Control Set from the popup menu. This creates a Control Set with the name of the selected control.

You add other controls to the Control Set by clicking on them and selecting the Control Set name to add them to. When you do this you'll see the Index property get a value to indicate its position in the Control Set. This is how you can tell them apart.

Control Sets were previously known as Control Arrays (in 2012 and earlier). They were renamed because they are not arrays and really don’t have anything to do with arrays.

You can also use UserGuide:Desktop Container Controls as an alternative to Control Sets. Container Controls cannot be configured as a Control Set, although you can use Control Sets within a Container Control.

Once you have a Control Set you can refer to the individual controls by their index value. You will need to manually keep track of the total number of controls in your set for looping purposes. For example, if you have created a control set that consists of four TextFields, you can create a loop to update the text in each of the fields:

Var lastSetIndex As Integer = 3
For i As Integer = 0 To lastSetIndex
MyTextFieldSet(i).Value = "Field " + i.ToString
Next

Adding a Control to a Control Set

Sharing Event Handlers

If you have multiple controls on the window that are part of a Control Set, the controls share their events. However, each event now has a new index parameter that you use to identify a specific control.

Controls Sets are a handy way to manage multiple controls that share similar functionality.

You can use the index parameter to iterate through the controls. For example, if you have a Control Set called MyCheckBox that consists of 4 Check Boxes, you could loop through them like this in the Action event to see which ones where checked:

For i As Integer = 0 To 3
If MyCheckBox(i).Value Then
MessageBox(MyCheckBox(i).Caption + " is selected")
End If
Next

Dynamic Controls / Adding Controls at Run-Time

There may be situations where you can’t build the entire interface ahead of time and need to create some or all of the interface elements programmatically. This can be done provided that the window already contains a control of the type you wish to create and that control belongs to a Control Set. In this case, the existing control is used as a template. For example, if you wish to create a Button via code, there must already be a Button on the window that you can “clone.” Remember that controls can be made invisible, so there is no need for your template control to be visible to the user. Once you have created a new instance of the control, you can then change any of its properties.

Dynamic Controls

Suppose you need to clone a Button that is already in the window, named PushButton1.

To create a new Button control via code, do this:

1. In the Inspector for the Button, select New Control Set from the Member Of popup menu in the Control Set group. When the new controls are created while the app is running, they become additional elements of this Control Set. In this example, you will create a new Button when the user clicks on the original Button.
2. In the Action event of PushButton1, Dim a variable of type PushButton, which is the base class for a Button. Assign the variable a reference to a new control using the New operator and use the name of the Control Set. This example shows a new Button being created using the PushButton1 Control Set. When the new control is created, it is moved to the right of the template control:
   Dim pb As PushButton // this is the control class
   pb = New PushButton1 // create clone of the control on the layout
   pb.Caption = "Clone"
   pb.Left = Me.Left + Me.Width + 10 // reposition it
   
3. Click the Run button. When the app launches, click the "Original" button. This creates a new Button to the right of the original. If you click “Clone,” you will create another clone to the right of the first two, and so on.

Since any new control you create in this manner shares the same event handler code as the template control, you may need to differentiate between them in your code. You use the index parameter of the control that is (passed in to the event handler to identify the control being used.

If your code needs to create different kinds of controls and store the reference to the new control in one variable, you can declare the variable as being of the type of object that all the possible controls you might be creating have in common (e.g, the super class or an interface). For example, if a variable can contain a reference to a new Radio Button or a new Check Box, the variable can be declared as a RectControl because both Radio Buttons and Check Boxes inherit from the RectControl class. Keep in mind, however, since the variable is a RectControl, the properties specific to a RadioButton or CheckBox will not be accessible without casting.

Here is the preceding example using RectControl and casting:

Var rc As RectControl
rc = New PushButton1 // create clone
PushButton(rc).Caption = "Clone"
PushButton(rc).Left = Me.Left + Me.Width + 10

Removing Controls at Run-Time

To remove a control that you added at run-time, you call the Close method for the control. This code can be used to add a new Button to a control set:

// NewPB is a Property on the Window: NewPB As PushButton
NewPB = New PushButton1 // create clone
NewPB.Caption = "Clone"
NewPB.Left = Me.Left + Me.Width + 10

Elsewhere, you can use this code to remove the added PushButton:

NewPB.Close

Remember, because Control Sets are not arrays if you remove a control in the middle of the Control Set you will get a "hole" in the index values. For example if you have four items in a Control Set they will initially have index values of 0, 1, 2, 3. If you remove index 2 then you will have three items in the Control Set with index values of 0, 1, 3. Index value 2 will be Nil.

Control Sets with Menus

You can add or remove items to menus at run-time using the Append, Insert and Remove methods of the MenuItem class. Using this technique is preferred over a Menu Control Set, which remains available as an option.

See Also

• RectControl class; UserGuide:Desktop Control Hierarchy, UserGuide:Desktop Container Controls topics
• Examples/Desktop/Controls/ControlSets project