Batch Modification of API Objects

Some API objects allow batch modification of properties. Objects that support batch modification will have a SetProperties method that accepts a dictionary (Lua table) of properties.

Batch modifications are performed as a single operation and may be required in situations where there are multiple properties that need to change and they have a dependency on each other.

Batch modification is best explained using examples. The examples below are equivalent and the result is the same. The cuboid object is used as an example.

Example 1

The code extract creates a cuboid and then modifies it by modifying each property individually. 
app = cf.GetApplication()
project = app:NewProject()
-- Create a cuboid with its base corner at the specified ' Point '
corner = cf.Point(-0.25, -0.25, 0)
cube = project.Geometry:AddCuboid(corner, 0.5, 0.5, 1.25)
-- Modify the cuboid
cube.Depth = 2
cube.Height = 2
cube.Depth = 2
cube.Origin.U = 2.5
cube.Origin.V = -0.5
cube.Origin.N = 1

Example 2

The code extract performs the same operations as for Example 1, but the modification is done as a single operation. The changes to the cuboid are collected in a dictionary that corresponds to the properties available for the “Cuboid ”object. The new properties are then applied to the cuboid using the SetProperties method.
app = cf.GetApplication()
project = app:NewProject()
-- Create a cuboid with its base corner at the specified ' Point '
corner = cf.Point(-0.25, -0.25, 0)
cube = project.Geometry:AddCuboid(corner, 0.5, 0.5, 1.25)
-- Modify the cuboid
newSettings = {}
newSettings["Depth"] = 2
newSettings["Height"] = 2
newSettings["Origin.U"] = 2.5
newSettings["Origin.V"] = -0.5
newSettings["Origin.N"] = 1
cube:SetProperties(newSettings)

Example 3

The code extract below again performs the same operation, but instead of defining the dictionary and then applying the settings, the dictionary is constructed directly. There is no difference between this example and the previous one, but the syntax is slightly different and thus warrants mention.
app = cf.GetApplication()
project = app:NewProject()
-- Create a cuboid with its base corner at the specified ' Point '
corner = cf.Point(-0.25, -0.25, 0)
cube = project.Geometry:AddCuboid(corner, 0.5, 0.5, 1.25)
-- Modify the cuboid
cube:SetProperties({["Depth"] = 2,
["Height"] = 2,
["Origin.U"] = 2.5,
["Origin.V"] = -0.5,
["Origin.N"] = 1})

Since the batch modification using the SetProperties method performs the validation and updates the object in a single step, there is a performance gain (not visible for such a small example). A GetProperties method is also available allowing users to get access to the settings that have been applied to an object, make the required changes and then set the properties using SetProperties again. The default properties for an object can be accessed using the GetDefaultProperties method