Description

The Regions.AddPicture method lets you add the specified image to the Regions collection and save it there as an item with the given name.

The image format is specified by the Images property of your test project. It can also be set at test run time by using the Options.Images.SetDefaultPictureConfiguration method.

Declaration

Regions.AddPicture(Picture, Name, Mouse, OutputDirectory)

Picture	[in]	Required	Variant
Name	[in]	Optional	String	Default value: Empty string
Mouse	[in]	Optional	Boolean	Default value: False
OutputDirectory	[in]	Optional	String	Default value: Empty string
Result	Boolean

Applies To

The method is applied to the following object:

Regions

Parameters

The method has the following parameters:

Picture

The Picture object (or an object that has the Picture method which returns a Picture object) that represents the image you want to add to the Regions collection.

Name

Unique name of the collection item under which the image will be saved in the Regions collection. If this parameter is omitted or set to an empty string, TestComplete will generate the item name itself.

A few notes:

If the Picture parameter holds an image that is not saved to a file, the Name parameter must be a valid file name (see the Remarks section for details).
If the Regions collection already contains an element with the specified name, this element will be changed without any warning (that is, the element’s file will be overwritten automatically).
The assigned name will be used to address the image from scripts, so it must be a valid script identifier. Scripting languages supported by TestComplete have different rules for names. To specify the name that matches any language, start the name with a letter and enter only letters, digits and underscore characters.

Mouse

This parameter is only effective when the Picture parameter specifies an object (for example, window) that contains the Picture method that returns the Picture object. The Mouse parameter specifies whether the captured image will include the mouse pointer. The default value is False and means that the mouse pointer is not included in the image.

OutputDirectory

The name of the directory where the image will be saved. The default value is an empty string and means that the image will be saved to the <ProjectFolder>\Stores\Regions folder.

Result Value

If the image was added successfully, the AddPicture method returns True. Otherwise, it returns False and generates an error string, which you can retrieve from the LastError property of the Regions object (and post to the test log).

Remarks

If the Picture parameter represents an image that is not saved to a file, the AddPicture method saves this image to a .bmp file to the Regions subfolder of the folder holding the Stores project item file. In this case, the Name parameter is used as the file name as well, so it must match Windows file naming rules. That is, it can contain only characters from the extended character set (128–255), except for reserved characters:

< > : " / \ | ? *

Later you can use the Regions editor to modify the image item’s name used to refer it is scripts so that it contains special characters, if needed.

Example

The following code saves a region of an active window to a .bmp file in the project’s folder and adds the file to the project’s Regions collection (note that if the Regions collection already has an element with the specified name, the element’s file will be overwritten).

JavaScript, JScript

var w;
w = Sys.Desktop.ActiveWindow().Picture(20, 20, 50, 50);
// To save the entire window, use
// w = Sys.Desktop.ActiveWindow();
Regions.AddPicture(w, "MyFile.bmp");

Python

w = Sys.Desktop.ActiveWindow().Picture(20, 20, 50, 50)
# To save the entire window, use
# w = Sys.Desktop.ActiveWindow()
Regions.AddPicture(w, "MyFile.bmp")

VBScript

Set w = Sys.Desktop.ActiveWindow.Picture(20, 20, 50, 50)
' To save the entire window, use
' Set w = Sys.Desktop.ActiveWindow
Regions.AddPicture w, "MyFile.bmp"

DelphiScript

var w : OleVariant;
…
w := Sys.Desktop.ActiveWindow.Picture(20, 20, 50, 50);
// To save the entire window, use
// w := Sys.Desktop.ActiveWindow;
Regions.AddPicture(w, 'MyFile.bmp');