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. 
application = cf.Application.GetInstance()
project = application:NewProject()
-- Create a cuboid with its base corner at the specified ' Point '
corner = cf.Point(-0.25, -0.25, 0)
cube = project.Contents.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. A GetProperties method is available that allows you to get access to the settings of an object, make the required changes and then set the properties using SetProperties.
application = cf.Application.GetInstance()
project = application:NewProject()
-- Create a cuboid with its base corner at the specified ' Point '
corner = cf.Point(-0.25, -0.25, 0)
cube = project.Contents.Geometry:AddCuboid(corner, 0.5, 0.5, 1.25)
-- Modify the cuboid
newSettings = cube:GetProperties()
newSettings.Depth = "2"
newSettings.Height = "2"
newSettings.LocalWorkplane.LocalDefinedWorkplane.Origin.X = "2.5"
newSettings.LocalWorkplane.LocalDefinedWorkplane.Origin.Y = "-0.5"
newSettings.LocalWorkplane.LocalDefinedWorkplane.Origin.Z = "1"
cube:SetProperties(newSettings)

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). The default properties for an object can be accessed using the GetDefaultProperties method.