Objects.Save Method

Applies to TestComplete 15.62, last modified on March 19, 2024

Description

The Save method saves OLE-compatible properties of the tested object Object to the Objects collection item Name. If an error occurs during the save (for example, the specified object is not found), Save returns False and generates an error description, which you can retrieve from the LastError property of the Objects object (and post the description to the test log).

Declaration

Objects.Save(Object, Name, PropNames, ExceptedPropName, Recursive, OutputDirectory)

Object [in]    Required    The needed tested object    
Name [in]    Required    String    
PropNames [in]    Optional    String Default value: Empty string   
ExceptedPropName [in]    Optional    String Default value: Empty string   
Recursive [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:

Parameters

The method has the following parameters:

Object

The tested object whose properties you want to save.

Name

Unique name of the Objects collection’s item to which you want to store the needed properties. All the contents of the existing item with the specified name will be rewritten. If the specified item doesn’t exist, it will be created in the Objects collection.

PropNames

A string that contains the names of Object’s properties that should be saved. The property names specified in this string must be separated by spaces. If PropNames is not specified or is an empty string (this is the default value), all the properties will be saved.

If the string contains a property which does not belong to the object, the property is ignored.

ExceptedPropName

A string that contains the names of Object’s properties that should not be saved. The property names specified in this string must be separated by spaces. This parameter is useful when you want to save most of the object's properties because in this instance, you only need to set a short “exception list” of undesired properties, which saves you from listing all of the properties to be saved. If ExceptedPropNames is not specified or is an empty string (this is the default value), no specific properties will be missed when saving properties of Object.

The ExceptedPropNames and PropNames parameters are mutually exclusive. So, the ExceptedPropNames and PropNames parameters cannot have a value at the same time. If these parameters have a non-empty value at the same time, the method returns False and generates an error description, which you can retrieve from the LastError property of the Objects object.

Recursive

If it is False (the default value), only the Object object's properties will be saved. If the parameter is True, the method iterates through child objects of the selected test object and saves those of their properties that match the pattern set by the PropNames or ExceptedPropNames parameter.

OutputDirectory

The name of the directory where the object’s properties will be saved. The default value is an empty string and means that the object’s properties will be saved to the <ProjectFolder>\Stores\Objects folder.

Result Value

True, if the properties’ values were stored successfully, and False otherwise.

Remarks

Objects.Load retrieves the property values stored by Objects.Save, and Objects.Compare compares them to those of the current object. Object.Save does save read-only properties, but of course they cannot be restored through Objects.Load. They can, however, be compared through Objects.Compare.

Example

The following code demonstrates how you can save properties of the desired object to an item of the Objects collection and compare the values of the stored properties with the actual values of the properties.

JavaScript, JScript

function Test()
{
  var w, PropertyNames, CollectionName;
  w = Sys.Desktop.ActiveWindow();

  // Prepares the property list
  PropertyNames = "Top Left Height Width";
  // Sets the name of the property collection
  CollectionName = "ActiveWindowProps";
  // Saves the values of the properties specified in PropertyNames.
  // Note that the Save method also has the fourth parameter
  // that lets you not to save certain properties.
  Objects.Save(w, CollectionName, PropertyNames);
  ...
  // Compares property values
  if (! Objects.Compare(w, CollectionName))
    Log.Message("Properties have been changed.");
}

Python

def Test():
   w = Sys.Desktop.ActiveWindow()
   # Prepares the property list
   PropertyNames = "Top Left Height Width"
   # Sets the name of the property collection
   CollectionName = "ActiveWindowProps"
   # Saves the values of the properties specified in PropertyNames.
   #Note that the Save method also has the fourth parameter
   # that lets you not to save certain properties.
   Objects.Save(w, CollectionName, PropertyNames)
   # ...
   # Compares property values
   if not Objects.Compare(w, CollectionName):
     Log.Message("Properties have been changed.")

VBScript

Sub Test
  Set w = Sys.Desktop.ActiveWindow

  ' Prepares the property list
  PropertyNames = "Top Left Height Width"
  ' Sets the name of a property collection
  CollectionName = "ActiveWindowProps"
  ' Saves the values of the properties specified in PropertyNames.
  ' Note that the Save method also has the fourth parameter
  ' that lets you not to save certain properties.
  Objects.Save w, CollectionName, PropertyNames
  ...
  ' Compares property values
  If Not Objects.Compare(w, CollectionName) Then
    Log.Message "Properties have been changed."
  End If
End Sub

DelphiScript

var
  w, PropertyNames, CollectionName : OleVariant;
begin
  w := Sys.Desktop.ActiveWindow();
  // Prepares the property list
  PropertyNames := 'Top Left Height Width';
  // Sets the name of the property collection
CollectionName := 'ActiveWindowProps';
  
  // Saves the values of the properties specified in PropertyNames.
  // Note that the Save method also has the fourth parameter
  // that lets you not to save certain properties.
Objects.Save(w, CollectionName, PropertyNames);
  ...
  // Compares property values
  if not Objects.Compare(w, CollectionName) then
    Log.Message('Properties have been changed.');
end;

C++Script, C#Script

function Test()
{
  var w, PropertyNames, CollectionName;
  
  w = Sys["Desktop"]["ActiveWindow"]();

  // Prepares the property list
  PropertyNames = "Top Left Height Width";
  // Sets the name of the property collection
  CollectionName = "ActiveWindowProps";
  // Saves the values of the properties specified in PropertyNames.
  // Note that the Save method also has the fourth parameter
  // that lets you not to save certain properties.
  Objects["Save"](w, CollectionName, PropertyNames);
  ...
  // Compares property values
  if (! Objects["Compare"](w, CollectionName) )
    Log["Message"]("Properties have been changed.");
}

See Also

Adding Property Collections to Stores
Compare Method
Load Method

Highlight search results