Description

Use the ChildControlByName property to obtain the form’s child control specified by its name.

In general, a control is a component that occupies a place on a form. For example, a button is a control, and a dialog is not. The ChildControlByName property lets you only access form controls, that is, it does not let you access components that do not occupy a place on a form, such as dialogs. To obtain a dialog component by its name, use the ComponentByName property.

Declaration

UserForm.ChildControlByName(Name)

Read-Only Property

A user form component object

Name

[in]

Required

String

Applies To

The property is applied to the following object:

UserForm

Parameters

The property has the following parameter:

Name

A string specifying the name of the desired form control.

Property Value

A form’s child component that has the specified name.

Remarks

If you use Python or DelphiScript, you should enclose the parameter of the ChildControlByName property in square brackets: ChildControlByName[Name].

The ChildControlByName property is similar to the ComponentByName property. The difference in these properties is that ChildControlByName is used to access components that are situated directly on the form, whereas ComponentByName lets you access all form components -- those that are situated on the form as well as those that are situated on the form’s container components, such as panels and group boxes. Also, the ChildControlByName property lets you access all kind of components except those that do not occupy a place on a form, such as dialogs, whereas the ComponentByName property can be used to enumerate all components, including dialogs.

Note that you can also obtain the form component via the UserForm object by directly specifying the component name.

Example

The following code obtains the form’s control by its name, sets the control’s properties and shows the form:

JavaScript, JScript

function Test()
{
  var Control, TestForm;

  // Obtains the form
  TestForm = UserForms.FormByName("TestForm");

  // Obtains the form’s child control by its name
  Control = TestForm.ChildControlByName("btn_OK");
  // Modifies the control’s properties
  Control.Enabled = false;
  Control.Caption = "OK";
  // Displays the form
  TestForm.ShowModal();

  …
}

Python

def Test():
  # Obtains the form
  TestForm = UserForms.FormByName["TestForm"]
  # Obtains the form's child control by its name
  Control = TestForm.ChildControlByName["btn_OK"]
  # Modifies the control's properties
  Control.Enabled = False
  Control.Caption = "OK"
  # Displays the form
  TestForm.ShowModal()
  # ...

VBScript

Sub Test

  Dim Control, TestForm

  ' Obtains the form
  Set TestForm = UserForms.FormByName("TestForm")

  ' Obtains the form’s child control by its name
  Set Control = TestForm.ChildControlByName("btn_OK")
  ' Modifies the control’s properties
  Control.Enabled = False
  Control.Caption = "OK"
  ' Displays the form
  TestForm.ShowModal

  …
End Sub

DelphiScript

procedure Test();
var Control, TestForm;

begin
  // Obtains the form
  TestForm := UserForms.FormByName('TestForm');

  // Obtains the form’s child control by its name
  Control := TestForm.ChildControlByName('btn_OK');
  // Modifies the control’s properties
  Control.Enabled := false;
  Control.Caption := 'OK';
  // Displays the form
  TestForm.ShowModal;

  …
end;