## PickElement

### Introduced

v1.0

### Description

Prompts the user to pick an element.
Note: This command uses output arguments. C# and some scripting languages (such as JScript, PerlScript and Python) don't support arguments passed by reference so you need to use the best workaround for your situation:
For scripting languages this command returns an ISIVTCollection which you can use to get the output arguments.
For C# you can use the XSIApplication.ExecuteCommand method to call this command. ExecuteCommand packs the output arguments into a C# System.Object containing an Array of the output arguments (see Calling Commands from C#).

### Scripting Syntax

    PickElement( SelFilter, LeftMessage, MiddleMessage, [PickedElement], [ButtonPressed], SelRegionMode, [ModifierPressed] );

### Parameters

Parameter | Type | Description
--- | --- | ---
SelFilter | FilterConstant | Selection filter that specifies what type of element to pick. Default Value: siGenericObjectFilter
LeftMessage | String | Status bar message for the left mouse button.
MiddleMessage | String | Status bar message for the middle mouse button.
PickedElement | CollectionItem | Returns the element picked by the user.
ButtonPressed | Long | Returns the mouse button clicked by the user.
Possible Values: | Description:
0 | Right mouse button (or the Esc key), which means the user aborted the picking session
1 | Left mouse button
2 | Middle mouse button
SelRegionMode | Long | Type of selection to perform. Default Value: 0
Possible Values: | Description:
0 | None (use current mode)
1 | Rectangle
2 | Raycast
3 | Lasso
4 | Freeform
5 | Paint
ModifierPressed | Long | Returns the modifier key pressed by the user.
Possible Values: | Description:
0 | None
1 | Shift modifier key
2 | Ctrl modifier key
3 | Shift-Ctrl modifier key

### Examples

#### 1. JScript Example

    /*

    	This example illustrates how to set up a pick session to pick only polygons.

    */

    NewScene( null, false );

    CreatePrim( "Cube", "MeshSurface" );

    var rtn = PickElement( "polygon", "Select polygons", "Select polygons", polygons, button, 0 )

    logmessage( "Picked Element:" + rtn.Value("PickedElement") +

    		" Button:" + rtn.Value("ButtonPressed") +

    		" Modifier:" + rtn.Value("ModifierPressed") );

    var element = rtn.Value( "PickedElement" );

    var button = rtn.Value( "ButtonPressed" );

    var modifier = rtn.Value( "ModifierPressed" );

    if ( button != 0 )

    {

    var polygons = element.SubComponent.Parent3DObject.ActivePrimitive.Geometry.Facets;

    var polygonIndices = element.SubComponent.ElementArray.toArray();

    	for ( var i=0; i<polygonIndices.length; i++ )

    {

    		var currpolygon = polygons( polygonIndices[i] );

    		logmessage( currpolygon + " is at index " + currpolygon.Index );

    }

    }

    // Result is something like this (varies as to what gets picked):

    // INFO : Picked Element:cube.poly[0,4] Button:1 Modifier:0

    // INFO : PolygonFace is at index 0

    // INFO : PolygonFace is at index 4

    //

#### 2. VBScript Example

    ' The following example uses PickElement to pick an object of a given type

    ' (eg: mesh) then another of another given type (eg: nurbs) to finally

    ' parent one to the other

    dim parent, child, button, modifier

    CreatePrim "Sphere", "NurbsSurface"

    Translate , -4.80504207251944, 6.3879907927616, -0.63879907927616, _

    siRelative, siView, siObj, siXYZ

    CreatePrim "Cone", "MeshSurface"

    PickElement "surface_mesh", "Select parent nurbs object", _

    "Select parent nurbs object", parent, button,, modifier

    if button <> 0 then

    	PickElement "polygon_mesh", "Select child mesh object", _

    		"Select child mesh object", child, button

    	if button <> 0 then

    		if modifier = 0 then

    			ParentObj parent, child

    		else

    			ParentObj child, parent

    		end if

    	end if

    end if

    'The nurbs should now be parent of the mesh (or vice-versa for MMB)

#### 3. JScript Example

    /*

    	The following example uses PickElement to pick subcomponents on a geometry

    */

    CreatePrim( "Sphere", "MeshSurface" );

    SetSelFilter("Vertex");

    var rtn = PickElement( "point", "Select points", "Select points" );

    var button = rtn.Value( "ButtonPressed" );

    var points = rtn.Value("PickedElement");

    if ( button != 0 ) {

    	CreateCluster( points );

    }

    // A cluster of points should now exist in the sphere.

#### 4. VBScript Example

    '

    ' The following example uses PickElement to select a property of a 3D object

    '

    dim parent, child, button

    CreatePrim "Sphere", "MeshSurface"

    set AProperty = PickElement( "property", "Select a property", _

    	"Select a property", property, button )

    if button <> 0 then

    	SelectObj property

    end if

    ' A property of the sphere should now be selected.

#### 5. Python Example

    #

    #	This example demonstrates how to get values from the

    #	output arguments of PickElement.

    #

    from win32com.client import constants as c

    xsi = Application

    xsi.NewScene( Application.ActiveProject, 0 )

    root = xsi.ActiveSceneRoot

    # Set up some models to pick

    oMdl = root.AddModel()

    oMdl.Name = "Parent1"

    oMdl = root.AddModel()

    oMdl.Name = "Parent2"

    oMdl1 = oMdl.AddModel()

    oMdl1.Name = "Child"

    oPicked = xsi.PickElement( c.siModelFilter, 'Pick model', 'Pick model' )

    xsi.LogMessage( "# of values returned: " + str(oPicked.Count) )

    # You can access the output arguments by index (returned sorted

    # alphabetically according to parameter name)...

    xsi.LogMessage( "Button pressed: " + str(oPicked(0)) )

    xsi.LogMessage( "Picked element: " + str(oPicked(2)) )

    # ... or access them by name

    xsi.LogMessage( "Modifier pressed: " + str(oPicked.Value("ModifierPressed")) )

    # Expected result for picking Parent2 with the MMB while

    # holding down alt+shift (# of values will always be 3):

    #INFO : # of values returned: 3

    #INFO : Button pressed: 2

    #INFO : Picked element: Parent2

    #INFO : Modifier pressed: 3