Visual Basic Reference

  • Article

Add Method (Controls Collection)

See Also    Example    Applies To

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.

Adding Unreferenced Controls at Run Time

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.

Removing Controls

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.