4D Doc Center : OBJECT DUPLICATE

4D v13.4

OBJECT DUPLICATE


OBJECT DUPLICATE ( {* ;} object {; newName {; newVar {; boundTo {; moveH {; moveV {; resizeH {; resizeV}}}}}}} {; *} )

Parameter	Type	Description
*	Operator	If specified, object is an object name (string) If omitted, object is a variable or a field
object	Form object	Object name (if * is specified) or Variable or field (if * is omitted)
newName	Text	Name of new object
newVar	Pointer	Pointer to variable of new object
boundTo	Text	Name of previous enterable object (or radio button)
moveH	Longint	Horizontal shift of new object (>0 = to the right, <0 = to the left)
moveV	Longint	Vertical shift of new object (>0 = downwards, <0 = upwards)
resizeH	Longint	Value of the horizontal resize of the object
resizeV	Longint	Value of the vertical resize of the object
*	Operator	If specified= absolute coordinates If omitted= relative coordinates

Description

The OBJECT DUPLICATE command is used to create a copy of the object designated by the object parameter in the context of the form being executed (Application mode). The source form, generated in Design mode, is not modified.

By default, all the options specified in the Property list for the source object are applied to the copy (size, resizing options, color, etc.), including any associated object method.
However, the following exceptions should be noted:

Default button: there can only be one default button in a form. When you duplicate a button having the "Default button" property, this property is assigned to the copy and is removed from the source object.
Keyboard equivalents: the keyboard shortcut associated with a source object is not duplicated. This property is left blank in the copy.
Object names: there cannot be several objects with the same name in a form. If you do not pass the newName parameter, the name of the source object is automatically incremented in the new object (see below).

If you pass the optional * parameter, you indicate that the object parameter is an object name (string). If you do not pass this parameter, you indicate that the object parameter is a field or a variable. In this case, you pass a field or variable reference (object field or variable only) instead of a string.
If you pass a field or variable reference and if the form contains several objects that use the same reference, the first occurrence found will be used. In this case, in order to avoid any ambiguity, it is recommended to work with object names, that are unique.

Pass the name assigned to the copy of the object in the newName parameter. This name must be in keeping with the rules for naming objects and be unique in the form. If it is not valid or already used by another object, the command does nothing and the OK variable returns 0.
If you omit this parameter or pass an empty string, the new name is automatically generated by incrementing the source object name (if this name is not already used). For example:

Source name	Name of copy
Button	Button1
Button20	Button21
Button21	Button23 if Button22 already exists

Pass a pointer to the variable to be associated with the new object in newVar. As a rule, you must point to a variable of the same type as the that of the source object but certain kinds of "retyping" are possible. The command provides automatic functions to facilitate writing generic code:

Usually, all "enterable" variables can be retyped; for example, an object displaying a Date or Longint can be duplicated and used with a variable of the Text type. Any compatible properties will be kept. The command also permits changing types between Text objects and Picture objects. Note that a text object that is duplicated and associated with a Boolean variable or field will automatically appear as a check box.
It is usually possible to dynamically transform a variable into a field and vice versa.
On the other hand, graphic objects (buttons, check boxes, and so on) cannot be transformed into other types of controls.

If the variable type is not compatible with the object, the command does nothing and the OK variable is set to 0. If you omit this parameter, the variable is created dynamically by 4D (see the paragraph Dynamic Variables). If you duplicate a static object (lines, rectangle, static picture, etc.), this parameter is ignored. Pass a Nil (->[]) pointer if you want to be able to use the other parameters.

You use the boundTo parameter in two cases:

update of entry order: in this case, in boundTo, pass the name of the enterable object located just before the duplicated object. If you want for the new object to become the first object in the entry order of the page, pass the new Object First in entry order constant (see the OBJECT Get pointer command).
association with a group of radio buttons: radio buttons function in a coordinated fashion when they are grouped. If the duplicated object is a radio button, in boundTo pass the name of a radio button of the group to which you want to attach the new object.

If you omit this parameter or pass an empty string, the new object becomes the last enterable object of the form page. In the case of a radio button, the object is attached to the group of the source button.

The new object can be moved and resized via the moveH, moveV, resizeH and resizeV parameters. As with the OBJECT MOVE command, the direction of the move or the resizing is specified by the sign of the values passed in the moveH and moveV parameters:

If the value is positive, the move or resizing is carried out, respectively, to the right or downwards.
If the value is negative, the move or resizing is carried out, respectively, to the left or upwards.

By default, the values of moveH, moveV, resizeH and resizeV modify the coordinates of the object in relation to its previous position. If you want for these parameters to specify absolute coordinates, pass the optional final * parameter.
If you omit these parameters, the new object is superimposed on top of the source object.

This command must be used in the context of the display of a form. It will generally be called in the On Load form event or following a user action (On Clicked event).

Note: If the On Load form event is associated with the source object, it is generated for the duplicated object when the command is executed. This allows, for example, the value of the object to be initialized.

For technical and logical reasons, OBJECT DUPLICATE cannot be called within the certain form events, in particular:

On Load event generated in an object method
On Unload event
Event related to printing context (On Header, On Printing Detail, etc.). To print an object several times, you must use the Print object command.

When the command is called in a context that is not supported,the object is not duplicated and the OK variable is set to 0. If it is called in a printing context, the error -10601 is generated as well.

If the command was executed correctly, the OK variable is set to 1. Otherwise, it is set to 0.

Example 1

Creation of a new button named "CancelButton" on top of the existing "OKButton" object and association with the vCancel variable:

OBJECT DUPLICATE(*;"OKButton";"CancelButton";vCancel)

Example 2

Creation of a new radio button "bRadio6" based on the existing radio button "bRadio5". This button will be associated with the variable <>r6, integrated with the group of the "bRadio5" button and placed 20 pixels above it:

OBJECT DUPLICATE(*;"bRadio5";"bRadio6";<>r6;"bRadio5";0;20)