addControl

addControl(c: Control);

The addControl method of the Form class dynamically adds the control referenced in the c parameter to a form at run time.

If the c parameter references a persistent object, the call is rejected.

If you use this method to add a control to a form in the JADE Painter, see also the flagControlForSave method.

The following example shows the use of the addControl method.

vars
    btn : Button;
begin
    create btn transient;          // create the control
    btn.name    := "testButton";   // set the name
    btn.parent  := testFrame;      // parent of button is a frame called
                                   // test frame
    btn.caption := "Test Button";  // set the caption
    self.addControl(btn);          // add the button to the form
end;

When you create the control, the constructor for the control class sets properties for the control to their default values. In particular:

The tabIndex property is set to zero (0).
The control name is set to the control class name; for example, button.
The control text or caption property is set to the control name; for example, button.
The top and left properties are always set to zero (0), but default values are assigned to width and height.
The parent defaults to the form at run time.

In JADE Painter at design time, if you make the parent of the control the form, the control appears not to have been drawn. The Painter overlays a frame on the form, which is the parent object for any controls that are painted directly onto the form. The constructor of the control should therefore set its parent to a specific object other than the form. (This applies only to transient controls that are created from within another custom control.)

If you do not set the parent of the control in the JADE Painter, the control is added to the Painter form rather than to the form that you are editing.

If you want to set the parent property to a control rather than the form, do this before calling the addControl method. This value defaults to the form (during processing of the addControl method).

The font of the control is not set. The default application font (see the Application class fontName property) is used when the addControl method is called. Any properties of the control that can be set in Painter can be set before calling the addControl method.

When a form is created with scaleForm set to true, dynamically added controls are also scaled when the current dpi is different from the dpi used to paint the form. Your logic should create the controls in the size relative to the dpi setting under which the form was created.

Properties that can be set only at run time (for example, the listIndex property of the ListBox control class) cannot be set before the addControl method is called. Methods for the control cannot be invoked until after the addControl method.

The added control generates event method calls using the name of the control; for example, name_click. Any required methods must be predefined in the form where the control is added (for details, see the setEventMapping method).

Use the delete instruction to remove a control from a form and destroy it. If delete is not called, the control is destroyed when the form is unloaded.

The addControl method differs from the loadControl method, in that the loadControl method creates a copy of an existing control and adds it to a form at run time.