Adds a control to the Controls collection and returns a reference to the control.
Syntax
object.Add (ProgID, name, container)
The Add method syntax has these parts:
| Part | Description |
| object | Required. An object expression that evaluates to an object in the Applies To list. |
| ProgID | Required. A string that identifies the control. The ProgID of most controls can be determined by viewing the Object Browser. The ProgID is composed of the Library and Class of the control. For example, the CommandButton control's ProgID is VB.CommandButton. In cases where the ProgID differs from that shown in the Object Browser, Visual Basic displays an error message that contains the correct ProgId. |
| name | Required. A string that identifies the member of the collection. |
| container | Optional. An object reference that specifies a container of the control. If not specified or NULL, defaults to the container to which the Controls collection belongs. You can put a control in any existing container control (such as the Frame control) by specifying this argument. A user control or an ActiveX document can also be a container. |
Remarks
Note The Controls collection is a late-bound collection. This means the compiler cannot determine in advance which controls are contained by the collection, their objects or their interfaces. Without this information, the Auto Statement Builder will not function.
This method allows you to add controls to an application at run time. Dynamic control addition can be used to add the functionality of a control to an application, even after the application has been compiled and deployed. For example, you may have several complex user controls, each suited to a different task. Depending on an external factor, such as time or date or user input, a different user control could be added to an existing form in an application. You can also use the container argument of the method to specify a container control (such as the Frame control) to position the control. Or you can design an application that automatically reads a file, database, or registry entry for new controls to load. In this way, you can modify an application without having to redeploy it.
Important When you add an unreferenced control that requires a license to an existing (deployed) application, you must also add the license key for the control before using the Add method. For information on when and how to add licenses, see "Licenses Collection" in the See Also list.
You can also use the Add method to dynamically add a control that is not referenced in the project. (An "unreferenced" control is a control that is not present in the Toolbox.) To do so, you must also add the control's License key to the Licenses collection as well. The example below adds a control's license key before adding the control itself:
Option Explicit
Private WithEvents extCtl As VBControlExtender
Private Sub Form_Load()
Licenses.Add "prjWeeks.WeeksCtl", "xydsfasfjewfe"
Set extCtl = Form1.Controls.Add("prjWeeks.WeeksCtl", "ctl1")
extCtl.Visible = True ' The control is invisible by default.
End Sub
Note See Add Method (Licenses Collection) in the See Also list for more information about retrieving a control's license key.
In order to program the events of such an unreferenced control, however, you must declare an object variable using the WithEvents keyword as a VBControlExtender object (shown above), and set the object variable to the reference returned by the Add method. Then use the VBControlExtender object's ObjectEvent event to program the control's events. An abbreviated example is shown below.
Option Explicit
Dim WithEvents objExt As VBControlExtender ' Declare VBControlExtender variable
Private Sub LoadControl()
Licenses.Add "Project1.Control1", "xydsfasfjewfe"
Set objExt = Controls.Add("Project1.Control1", "myCtl")
objExt.Visible = True
End Sub
Private Sub extObj_ObjectEvent(Info As EventInfo)
' Program the events of the control using Select Case.
Select Case Info.Name
Case "Click"
' Handle Click event here.
' Other cases now shown
Case Else ' Unknown Event
' Handle unknown events here.
End Select
End Sub
Note You can't assign an intrinsic control to the VBControlExtender variable; any attempt will result in a type mismatch error.
You can also program the events of a dynamically added control by declaring an object variable using the WithEvents keyword, and setting the reference returned by the method to the variable, as shown below:
Option Explicit
' Declare object variable as CommandButton.
Private WithEvents cmdObject As CommandButton
Private Sub Form_Load()
Set cmdObject = Form1.Controls.Add("VB.CommandButton", "cmdOne")
cmdObject.Visible = True
cmdObject.Caption = "Dynamic CommandButton"
End Sub
Private Sub cmdObject_Click()
Print "This is a dynamically added control"
End Sub
If you intend to add a user control or any ActiveX control to your form, you must either add the control to the Toolbox, or add its License key to the Licenses collection. See the Add Method (Licenses Collection) for more information.
Note If you add an ActiveX or user control to your project but don't use it on a form, you must also uncheck the Remove Information About Unused ActiveX Controls option on the Make tab of the Project Properties dialog box. If your application attempts to add the control, the Add method will fail because the necessary information has been discarded.
To remove any controls added dynamically, use the Remove method. It should be noted that you can only remove controls added using the Add method (in contrast to controls added using the Load statement). The example below removes a dynamically added control:
Form1.Controls.Remove "ctl1" ' The control's name is ctl1.