## 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