The TRectObjectPicker component is the Rectangle Selector tool that lets users select an object on the screen by dragging the selection rectangle around the object. You can use it in your forms to let users visually specify an object to work with.

After a user has drawn the selection rectangle, the TRectObjectPicker component returns the name of the object within the selection. If the selected area contains several objects, TRectObjectPicker returns the name of their common parent object.

The TRectObjectPicker component has the OnObjectPicked event that is fired after the user selects an object. You can write an event handler for this event and perform the desired actions upon selecting the object. For instance, you can display the name of the selected window or control in a text box.

A full list of available properties, methods and events of the TRectObjectPicker object is provided below:

TRectObjectPicker Properties

TRectObjectPicker Properties

Name	Description
`ChildControl`	Returns the child component by index.
`ChildControlByName`	Returns the child component by name.
`ChildControlCount`	Returns the total number of child components for the given component.
`ClientHeight`	Returns the height of the component’s client area.
`ClientWidth`	Returns the width of the component’s client area.
`Cursor`	Specifies the cursor’s image when it is over the component.
`Height`	Specifies the component’s height.
`Hint`	Specifies the text displayed when the cursor stays over the component.
`Left`	Specifies the horizontal coordinate of the component’s left edge.
`Name`	Specifies the component’s name.
`ParentShowHint`	Specifies whether the component uses the parent’s `ShowHint` property value instead of its own.
`PickedObjectName`	Specifies the full name of the selected window or control object (the name is specified in TestComplete terms).
`PickedRectBottom`	Returns the vertical (Y) coordinate of the bottom edge of the selected rectangular area.
`PickedRectHeight`	Returns the height of the selected rectangular area.
`PickedRectLeft`	Returns the horizontal (X) coordinate of the left edge of the selected rectangular area.
`PickedRectRight`	Returns the horizontal (X) coordinate of the right edge of the selected rectangular area.
`PickedRectTop`	Returns the vertical (Y) coordinate of the top edge of the selected rectangular area.
`PickedRectWidth`	Returns the width of the selected rectangular area.
`Property`	Obtains or sets the value of the property specified by its index.
`PropertyByName`	Obtains or sets the value of the property with the specified name.
`PropertyCount`	Returns the number of component properties.
`PropertyName`	Returns the property name by index.
`ShowHint`	Specifies whether to display the component’s hint.
`Top`	Specifies the vertical coordinate of the component’s top edge.
`Visible`	Specifies whether the component is visible on screen.
`Width`	Specifies the component’s width.

TRectObjectPicker Methods

TRectObjectPicker Events

To obtain the name of the selected object, use the component’s PickedObjectName property. The following code demonstrates how you can obtain the name of the selected object and display it in a text box:

JavaScript, JScript

// This routine is called when the OnObjectPicked event occurs
function UserForm1_RectObjectPicker1_OnObjectPicked(Sender)
{
  var objName;

  // Obtain the name of the selected object
  objName = UserForms.UserForm1.RectObjectPicker1.PickedObjectName;

  // Displays the name in a text box
  UserForms.UserForm1.cxTextEdit1.Text = objName;
}

Python

# This routine is called when the OnObjectPicked event occurs
def UserForm1_RectObjectPicker1_OnObjectPicked(Sender):
  # Obtain the name of the selected object
  objName = UserForms.UserForm1.RectObjectPicker1.PickedObjectName

  # Displays the name in a text box
  UserForms.UserForm1.cxTextEdit1.Text = objName

VBScript

' This routine is called when the OnObjectPicked event occurs
Sub UserForm1_RectObjectPicker1_OnObjectPicked(Sender)
  Dim objName

  ' Obtain the name of the selected object
  objName = UserForms.UserForm1.RectObjectPicker1.PickedObjectName

  ' Displays the name in a text box
  UserForms.UserForm1.cxTextEdit1.Text = objName
End Sub

DelphiScript

// This routine is called when the OnObjectPicked event occurs
procedure UserForm1_RectObjectPicker1_OnObjectPicked(Sender);
var objName;
begin
  // Obtain the name of the selected object
  objName := UserForms.UserForm1.RectObjectPicker1.PickedObjectName;

  // Displays the name in a text box
  UserForms.UserForm1.cxTextEdit1.Text := objName;
end;

C++Script, C#Script

// This routine is called when the OnObjectPicked event occurs
function UserForm1_RectObjectPicker1_OnObjectPicked(Sender)
{
  var objName;

  // Obtain the name of the selected object
  objName = UserForms["UserForm1"]["RectObjectPicker1"]["PickedObjectName"];

  // Displays the name in a text box
  UserForms["UserForm1"]["cxTextEdit1"]["Text"] = objName;
}

To obtain the scripting interface to the selected object, use the eval (JavaScript, JScript, Python, C#Script, C++Script), Eval (VBScript) or Evaluate (DelphiScript) function (see the example below). After you obtain the object reference, you can call the object’s methods and set or get the values of the object’s properties. For instance, the following code demonstrates how you can obtain a reference to the selected object and obtain the object’s Left and Top properties:

JavaScript, JScript

// This routine is called when the OnObjectPicked event occurs
function UserForm1_RectObjectPicker2_OnObjectPicked(Sender)
{
  var obj, objName, leftProperty, topProperty;

  // Obtain the name of the selected object
  objName = UserForms.UserForm1.RectObjectPicker2.PickedObjectName;

  // Get the object reference
  obj = eval(objName);

  // Obtain the object properties
  leftProperty = obj.Left;
  topProperty = obj.Top;
  Log.Message("Left: " + leftProperty);
  Log.Message("Top: " + topProperty);
}

Python

# This routine is called when the OnObjectPicked event occurs
def UserForm1_RectObjectPicker2_OnObjectPicked(Sender):

  # Obtain the name of the selected object
  objName = UserForms.UserForm1.RectObjectPicker2.PickedObjectName

  # Get the object reference
  obj = eval(objName)

  # Obtain the object properties
  leftProperty = obj.Left
  topProperty = obj.Top
  Log.Message("Left: " + str(leftProperty))
  Log.Message("Top: " + str(topProperty))

VBScript

' This routine is called when the OnObjectPicked event occurs
Sub UserForm1_RectObjectPicker2_OnObjectPicked(Sender)
  Dim obj, objName, leftProperty, topProperty

  ' Obtain the name of the selected object
  objName = UserForms.UserForm1.RectObjectPicker2.PickedObjectName

  ' Get the object reference
  Set obj = Eval(objName)

  ' Obtain the object properties
  leftProperty = obj.Left
  topProperty = obj.Top
  Log.Message "Left: " & leftProperty
  Log.Message "Top: " & topProperty
End Sub

DelphiScript

// This routine is called when the OnObjectPicked event occurs
procedure UserForm1_RectObjectPicker2_OnObjectPicked(Sender);
var obj, objName, leftProperty, topProperty;
begin
  // Obtain the name of the selected object
  objName := UserForms.UserForm1.RectObjectPicker2.PickedObjectName;

  // Get the object reference
  obj := Evaluate(objName);

  // Obtain the object properties
  leftProperty := obj.Left;
  topProperty := obj.Top;
  Log.Message('Left: ' + aqConvert.VarToStr(leftProperty));
  Log.Message('Top: ' + aqConvert.VarToStr(topProperty));
end;

C++Script, C#Script

// This routine is called when the OnObjectPicked event occurs
function UserForm1_RectObjectPicker2_OnObjectPicked(Sender)
{
  var obj, objName, leftProperty, topProperty;

  // Obtain the name of the selected object
  objName = UserForms["UserForm1"]["RectObjectPicker2"]["PickedObjectName"];

  // Get the object reference
  obj = eval(objName);

  // Obtain the object properties
  leftProperty = obj["Left"];
  topProperty = obj["Top"];
  Log["Message"]("Left: " + leftProperty);
  Log["Message"]("Top: " + topProperty);
}

Name	Description
`PropertyExists`	Checks to see if the component has the property with the specified name.
`SetFocus`	Moves the input focus to the component.

TRectObjectPicker Object

See Also