VS:Mirror
.VectorScript|VectorScript ..VS:Function Reference|Function Reference ..VS:Function_Reference_Appendix|Appendix
Description
Calls a user defined procedure to operate on each object matching the specified search criteria.
The procedure subroutine specified by the callback parameter must have one parameter of type HANDLE, which is passed the handle to an object by the ForEachObject call.
PROCEDURE ForEachObject(
callback :PROCEDURE;
c :CRITERIA);
def vs.ForEachObject(callback, c): return None
Parameters
callback PROCEDURE Name of action procedure to be applied to matching objects c CRITERIA Search criteria for locating objects.
Return Value
The reflected object (this will be the same as the input object if dup is false).
Remarks
_c_ (2016.05.14): Pay attention how you place your brakets while using criteria strings through variables. Extra brakets might not work and never return errors:
.VectorScript|VectorScript
..VS:Function Reference|Function Reference
..VS:Function_Reference_Appendix|Appendix
<vwDoc>
<desc>
Reflect an object across an axis.
For a 2D reflection, the axis is a line containing arbitrary point p and extending along vector v.</desc>
<def>
FUNCTION Mirror(
h :HANDLE;
dup :BOOLEAN;
p1 :POINT;
p2 :POINT) : HANDLE;
def vs.Mirror(h, dup, p1, p2):
return HANDLE
</def>
<params>
h HANDLE The object to reflect
dup BOOLEAN If false, transform the original object to the new position. If true, create a new object
p1 POINT An arbitrary point on the mirror axis
p2 POINT A second arbitrary point on the mirror axis
</params>
<return></return>
<remark>
_c_ (2019.11.09) This doesn't support Groups and is unpredictable on 3D objects
Version
Availability: from Vectorworks 2017
recordName := 'Part Info'; { needs single quotes because of the space }
criteria = Concat('((R in [', ', recordName, ', ']))'); { wrap in single quotes }
ForEachObject(ProcThatTakesAHandle, criteria); { works fine }
ForEachObject(ProcThatTakesAHandle, (criteria)); { doesn't work }
(Others) Don't use DelObject inside a ForEachObject callback.
Essentially, ForEachObject is roughly equivalent to
h := FObject; WHILE h <> NIL DO BEGIN {do something} h := NextObj(h); END;
The only difference is that ForEachObject is handling the looping for you, and providing a convenient mechanism for filtering the objects by criteria.
Now, if you're deleting h inside that loop, the NextObj call is going to fail miserably. Doing anything that will alter the sequence of entities in the drawing list, inside a loop that walks the drawing list, will produce unexpected results. This includes creating objects, deleting objects, changing the layer of an object, or changing the stacking order (VS:HMoveForward, VS:HMoveBackward). This will be true if you are walking the drawing list explicitly (using NextObj), or implicitly (using VS:ForEachObject, VS:ForEachObjectInLayer, or VS:ForEachObjectInList).
So use ForEachObject just to build a handle array. Then go back and iterate through the handles, and delete the ones you don't like.
Rgm [2012.11.21]: Note that you can pass in a string for the c:CRITERIA parameter. This appears to be the best way to use variable criteria, e.g.:
recordName := 'Part Info'; { literal, or maybe the value of a function } criteria = Concat('((R in [', '''', recordName, '''', ']))'); { '''' gives a single quote when parsed } ForEachObject(ProcThatTakesAHandle, criteria);
</remark>
<sample>
PROCEDURE PickRect; PROCEDURE SelectThem(h :HANDLE); BEGIN SetSelect(h); END; BEGIN ForEachObject(SelectThem, "T=RECT"); END; RUN(PickRect);
Python:
import vs def SelectThem(h): vs.AlrtDialog( "we're in" + str(h)) vs.AlrtDialog( 'should show three consecutive dialogs' ) vs.ForEachObject( SelectThem, "T=WALL" )
</sample>
<version> Availability: from All Versions
</version>
</vwDoc>