The AFXPickStep class allows the user to pick entities in the current viewport. You must create the keywords associated with pick steps in the same order as the pick steps in which the keywords are used. For example, if you have two pick steps, you must create the keyword passed into the first pick step before you create the second keyword, which is passed into the second pick step. Creating the keywords associated with pick steps in the same order as the pick steps in which the keywords are used ensures that the necessary setup commands are issued in the proper order for the command to work correctly.

You can specify many parameters when picking items from the viewport. You specify some of these parameters in the AFXPickStep constructor, and you specify other parameters by calling various methods of the pick step.

To construct a pick step, you must at least supply the following:

class MyProcedure(AFXProcedure):

    def __init__(self, owner):
    
        AFXProcedure.__init__(self, owner)
        
        self.cmd = AFXGuiCommand(self, 'myMethod', 'myObject')
        self.nodeKw = AFXObjectKeyword(self.cmd, 'node', TRUE)

    def getFirstStep(self):

        return AFXPickStep(self, self.nodeKw, 
            'Select a node', NODES)

Optional parameters in the constructor allow you to specify the following:

If the user is allowed to pick only one entity, the procedure will automatically advance to the next step after the user picks an entity; however, the user can back up to the previous step to change the selection. If the user is allowed to pick one or more entities, the user must commit the selections by clicking mouse button 2 or by clicking the Done button on the prompt line.

The highlight level controls the color of the selected entities. In some procedures, different colors are used between steps to distinguish the selections.

The sequence style controls how a sequence of picked objects is represented in the command string. If the sequence style is ARRAY, the picked objects will be represented as the concatenation of slices of arrays; for example, v[3:4] + v[5:8], where v is a vertex array. You cannot use the ARRAY sequence style to pick a combination of entities with multiple types because only objects of the same type can be concatenated. In addition, you cannot use the ARRAY sequence style to pick interesting points because interesting points are constructed on-the-fly and are not accessible from slices of an array.

If the sequence style is TUPLE, the picked objects will be represented as a tuple of individual objects; for example, ( v[3], v[5], v[6], v[7]). The style you choose depends on the format accepted by the command that you intend to issue. Some commands in ABAQUS/CAE accept both styles, but some accept only one or the other. For further details on the arguments to the AFXPickStep constructor, see the ABAQUS GUI Toolkit Reference Manual.

A refinement qualifies the types of pickable entities specified in the AFXPickStep constructor. The following example shows how to select only straight edges:

step = AFXPickStep(
    self, self.edgeKw, 'Select a straight edge', EDGES)
step.setEdgeRefinements(STRAIGHT)

By default, the procedure mode prevents previously selected geometric entities from being selected twice in the same procedure. If you do not want this behavior, you can call the allowRepeatedSelections method. The following example shows how to allow repeated selections:

step = AFXPickStep(
    self, self.edgeKw, 'Select a straight edge', EDGES)
step.allowRepeatedSelections(TRUE)

The procedure mode clears all highlighting when the user cancels a procedure. In addition, the procedure mode clears highlighting in the current step before backing up. The color of highlighted entities is controlled by the highlight level set in the AFXPickStep constructor.

The Selection Options dialog box is automatically available in any pick step. The available options in the Selection Options dialog box are automatically configured, based on the types of entities that the user is picking. For example, if the user is picking only faces, only Faces appears in the combo box in the dialog box. Similarly, if the user is picking a single entity, the drag shape and drag scope buttons are not available. As a result, procedures generally do not need to set the available selection options explicitly. If you need to set these options, you can use the procedure's setSelectionOptions method. You must set the procedure selection options prior to creating the first pick step. For more information, see the ABAQUS GUI Toolkit Reference Manual.

Normally a procedure will set these options only at the start of the procedure. However, during the procedure the user may change the settings, and the modified settings will be retained from step to step during the rest of the procedure.

If you want to allow the user to type in the coordinates of a point as an alternative to picking in the viewport, you can call the addPointKeyIn method and pass it a tuple keyword. The addPointKeyIn method posts a text field on the prompt line. The type of the keyword passed into the addPointKeyIn method determines what values are collected from the user; for example, two or three values and whether those values are float or integer types. For example, in the constructor of your procedure you could define an additional keyword as shown in the following code:

    self.pointKw1 = AFXObjectKeyword(self.cmd, 'point', TRUE)
    self.pointKw2 = AFXTupleKeyword(self.cmd, 'point', TRUE, 3, 3,
        AFXTUPLE_TYPE_FLOAT)

In one of the steps of your procedure you could add a key-in option, as shown below:

    step = AFXPickStep(
        self, self.pointKw1, 'Select a point', POINTS)
    step.addPointKeyIn(self.pointKw2)

If a step has a key-in text field, the user enters some values in the text field, and the user commits the values by pressing Enter, those values will be used in the command. Alternatively, if a step has a key-in text field and the user selects an entity in the viewport, that entity will be used in the command, regardless of whether anything was typed in the text field. The mode automatically takes care of deactivating whichever keyword needs to be deactivated based on these rules. In the previous example, if the user types in a point, self.pointKw1 will be deactivated and self.pointKw2 will be activated. In addition, self.pointKw2 will contain the value entered by the user.

Picking by face angle or by edge angle is always enabled when appropriate. For example, picking by face angle is enabled when the user is picking faces. You cannot disable picking by angle.

The AFXOrderedPickStep is a special pick step that preserves the order in which the user picks entities. For example, when picking four nodes to create a quad element, the order in which the user picks the nodes is important and must be preserved during picking. The user must pick the entities one at a time and cannot drag select them. In addition, because this is a single step that treats the picked entities as a single pick, the user cannot backup any of the individual picks. The step continues to loop until the user clicks the mouse button two.

The following limitations apply to picking procedures: