PickElement

Introduced

v1.0

Categories

selection userinterface

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