BeginGroupN.md

BeginGroupN

Description

May be used to create objects in an existing group by passing a group handle; if a handle initialized to NIL is passed a new group is created.

PROCEDURE BeginGroupN(VAR groupHandle : HANDLE);

def vs.BeginGroupN(groupHandle):
    return groupHandle

Parameters

Name	Type	Description
groupHandle	HANDLE	The group handle to be used; if handle is initialized to NIL a new group is created.

Remarks

_c_ 2021.02.24:

Be very careful with BeginGroupN, this won't automatically return NIL if empty. Used in Plug-in object it will crash VW upon attempting to use the common Group operation routines and the Group handle is not valid (Tested up to VW 2021 SP3).

gr1 := NIL;
BeginGroupN(gr1);
EndGroup;
{ gr1 now unexpectedly is not NIL }
		
BeginGroup;
EndGroup;
gr2 := LNewObj;
{ this is NIL }

{ 
 IF gr1 <> NIL THEN
 	killer := CreateDuplicateObject(gr1, NIL); this hangs VW in pios }
		
{ 
IF gr1 <> NIL THEN
	killer := FInGroup(gr1); this causes VW to instantly quit in pios }

{ solution: make sure that the handle is valid adding some basic geometry that you might delete later }
BeginGroupN(gr1);
Locus(0, 0);
EndGroup;

Examples

BeginGroupN(groupHandle);
  Rect(-1,1,0.5,0);
EndGroup;
{ adds created rect to existing group }

groupHandle := nil;
BeginGroupN(groupHandle);
  Rect(-1,1,0.5,0);
EndGroup;
{ creates new group and adds created rect to created group }

BEGIN
	gPluginObjH := CreateCustomObjectN ('Seating Section', 0, 0, 0, FALSE);
	tempObjH := HDuplicate (h, 0, 0);
	BeginGroupN(profileGroupH);
	Locus(0,0);
	EndGroup;
	result := SetCustomObjectPath (gPluginObjH, tempObjH);
	result := SetCustomObjectProfileGroup( gPluginObjH, profileGroupH );

BEGIN
	BeginGroupN( HighlightGroupHand );
		HighlightMaskHand := CreateDuplicateObject( pioPathObjHand, HighlightGroupHand );
		{
		IF pioLineMode
		THEN SetPolyClosed( HighlightMaskHand, FALSE )

Begin
	BeginGroupN( TriangleGroupHand );

import vs

# May be used to create objects in an existing group by passing a group
# handle; if a handle initialized to NIL is passed a new group is created.
groupHandle = vs.FSActLayer()  # handle to the first selected object on the active layer

objHandle = vs.BeginGroupN(groupHandle)
if objHandle is not None:
    vs.Message('Created object handle: ' + str(objHandle))

See Also

VS Functions: BeginGroup | EndGroup

Version

Availability: from Vectorworks 2011

Category

• Objects - Groups