Using Mask Triples from the SelectObject Routine

As we saw in Beginning Selections, the SelectObject(...) method provides a fairly quick and easy way to allow the user to select one or more objects. However, if you need interactive selection, but the ‘type array’ method could not provide enough control; allow me to introduce you to the selection method using mask triples.

Using SelectObject(...)

You may notice that this SelectObject(...) method has the exact same name as the one that filters by type array. Those of keen eye will also notice that the parameter signature shown below of the method is slightly different than the type array version.

Here’s the signature of the SelectObject:

Public Function SelectObject( _
message As String, _
title As String, _
scope As Selection.SelectionScope, _
action As Selection.SelectionAction, _
includeFeatures As Boolean, _
keepHighlighted As Boolean, _
maskArray As Selection.MaskTriple(), _
ByRef object As NXObject, _
ByRef cursor As Point3d _
) As Selection.Response

Overloading is a language feature that lets the programmer reuse the same function name with different parameters. This allows for more flexibility and convenience for the users of the function (such as journal programmers). A good example of this is the VB.NET MessageBox class that has 21 versions of the Show method! http://msdn.microsoft.com/en-us/library/system.windows.forms.messagebox_methods.aspx Suffice it to say there should be a version that does what you need.

The message parameter will show up in the cue line, use this to prompt the user what to pick.

The title parameter will show up in the title of the dialog box. There is not much room here, so keep it short. A simple “Select {main object type}” usually does the job.

The scope parameter limits where the selection is allowed to take place. The following options are available:

• Selection.SelectionScope.UseDefault
• Selection.SelectionScope.WorkPart - limit selection to only entities within the work part
• Selection.SelectionScope.AnyInAssembly - select from pretty much anywhere
• Selection.SelectionScope.WorkPartAndOccurrence - limit selection to the work part and its components

The action parameter determines what happens with your selected object(s). The available options here are (taken from the net_ref help file):

• EnableAll - Include objects in the selection
• EnableSpecific - Include selected objects in selection
• DisableSpecific - Remove selected objects from selection
• ClearAndEnableSpecific - Clear selection and include selected objects
• AllAndDisableSpecific - Select all objects except for selected objects
• Count - Include count of selected objects

To be honest, I’ve only used the ClearAndEnableSpecific option, it has always met the need. You will probably find good uses for the other options if you have access to the dialog styler (I do not). If you have a short code example using one of the other options, please submit it along with a short explanation.

If you need to allow the selection of features, pass a True value in the includeFeatures parameter, otherwise pass in False.

A False value passed into the keepHighlighted parameter will give control of the object’s highlighting to the selection method. If you want full control over when the highlighting turns off, such as when you are using the dialog styler, pass in a True value.

This brings us to the real meat of this method, the maskArray. The maskArray parameter is an array of maskTriple objects. The maskTriple, in turn, is a three element array of integers representing the objects available through the NXOpen API. The maskTriples act as filters, limiting what is allowed for selection. Each maskTriple added to the maskArray allows a single type of object to be selected; the subtype may allow for all subtypes to be selected (UF_all_subtype), or it may further narrow the selection to a single subtype. A simple selection may only require one maskTriple, more complicated selections may require several.
 

Assinging Values to the maskTriple:
To make your programming life a little bit easier, you can use the maskTriple constructor to assign values. The constructor takes the arguments as below:

Selection.MaskTriple ( _
Type As Integer, _
Subtype As Integer, _
SolidBodySubtype As Integer _
)

All of the objects available through the NXOpen API are divided into types and subtypes.

If you wanted to mask for arcs, the maskTriple would be:

Selection.MaskTriple(5, 0, 0).
 

The maskTriple for circular edges of a solid body would be:

Selection.MaskTriple(70, 0, 3)

So how do you know what numbers to pass in to the maskTriple? All of the available object types and subtypes can be found in the uf_object_types.h file which is in the UGOPEN subdirectory in your NX install path. The available SolidBodySubtypes can be found in the uf_ui_types.h file, which can also be found in the UGOPEN directory. This is a large file, so search for Constants for selection solid_type to find your available options quickly.

The SolidBodySubtype only has an affect when the type is set to UF_solid_type (70); if the type is something other than UF_solid_type, pass in a zero. When UF_solid_type is used, the subtype is ignored (pass in a zero), and the SolidBodySubtype takes over.

Not only do these files list the available types, they also define an enumeration (named constants) so the previous masks would look like this:

Selection.MaskTriple(UFConstants.UF_circle_type, _
            0, _
            0)
Selection.MaskTriple(UFConstants.UF_solid_type, _
            0, _
            UFConstants.UF_UI_SEL_FEATURE_CIRCULAR_EDGE)

Using these named constants helps to make your code self-documenting. When you revisit your code a week, a month, a year later, you will know exactly what the filter was set up to do without searching through the uf_object_types.h and uf_ui_types.h files.

Putting it all together: Working journal that selects a single object using SelectObject(...) with SelectionMask.Triple

Here is an example journal that allows for the selection of arcs or circular edges and simply reports the object’s tag and type to the listing window.

Option Strict Off
Imports System
Imports NXOpen
Imports NXOpen.UF

Module NXJournal
Sub Main

Dim theSession As Session = Session.GetSession()
Dim workPart As Part = theSession.Parts.Work
Dim displayPart As Part = theSession.Parts.Display
Dim lw As ListingWindow = theSession.ListingWindow
Dim mySelectedObject As NXObject

lw.Open
If SelectAnObject("Select arc or circular edge", mySelectedObject) = Selection.Response.Cancel Then
Exit Sub
End if
lw.WriteLine("Object Tag: " & mySelectedObject.Tag)
lw.WriteLine("Object is a: " & mySelectedObject.GetType.ToString)

lw.Close

End Sub

Function SelectAnObject(ByVal prompt As String, byRef selObj as NXObject) As Selection.Response

Dim theUI As UI = UI.GetUI
Dim title As String = "Selection"
Dim includeFeatures As Boolean = False
Dim keepHighlighted As Boolean = False
Dim selAction As Selection.SelectionAction = _
Selection.SelectionAction.ClearAndEnableSpecific
Dim cursor As Point3d
Dim scope As Selection.SelectionScope = Selection.SelectionScope.WorkPart
Dim selectionMask_array(1) As Selection.MaskTriple

With selectionMask_array(0)
.Type = UFConstants.UF_solid_type
.Subtype = 0
.SolidBodySubtype = UFConstants.UF_UI_SEL_FEATURE_CIRCULAR_EDGE
End With
With selectionMask_array(1)
.Type = UFConstants.UF_circle_type
.Subtype = 0
.SolidBodySubtype = 0
End With

Dim resp As Selection.Response = theUI.SelectionManager.SelectObject( _
prompt, title, scope, selAction, _
includeFeatures, keepHighlighted, selectionMask_array, selobj, cursor)

If resp = Selection.Response.ObjectSelected OrElse _
resp = Selection.Response.ObjectSelectedByName Then
Return Selection.Response.Ok
Else
Return Selection.Response.Cancel
End If

End Function

End Module

Using SelectObjects(...)

To select multiple objects, use the SelectObjects(...) method is very similar to the SelectObject(...) method described above. However the Select Objects(...) does require an array variable of NXObjects as a parameter and it does not require (or return) a Point3d object parameter (cursor position). The parameter signature of this method is shown below:

Public Function SelectObjects( _
message As String, _
title As String, _
scope As Selection.SelectionScope, _
action As Selection.SelectionAction, _
includeFeatures As Boolean, _
keepHighlighted As Boolean, _
maskArray As Selection.MaskTriple(), _
ByRef objectArray As NXObject() _
) As Selection.Response

Below is an example journal that allows for multiple selection of arcs and/or circular edges.

Option Strict Off
Imports System
Imports NXOpen
Imports NXOpen.UF

Module NXJournal
Sub Main

Dim theSession As Session = Session.GetSession()
Dim workPart As Part = theSession.Parts.Work
Dim displayPart As Part = theSession.Parts.Display
Dim lw As ListingWindow = theSession.ListingWindow
Dim mySelectedObjects() As NXObject

lw.Open
If SelectObjects("Select objects", mySelectedObjects) = Selection.Response.Cancel Then
Exit Sub
End if
For each obj as NXObject in mySelectedObjects
lw.WriteLine("Object Tag: " & obj.Tag)
lw.WriteLine("Object is a: " & obj.GetType.ToString)
lw.WriteLine("")
Next

lw.Close

End Sub

Function SelectObjects(ByVal prompt As String, byRef selObj() as NXObject) As Selection.Response

Dim theUI As UI = UI.GetUI
Dim title As String = "Selection"
Dim includeFeatures As Boolean = False
Dim keepHighlighted As Boolean = False
Dim selAction As Selection.SelectionAction = _
Selection.SelectionAction.ClearAndEnableSpecific

Dim scope As Selection.SelectionScope = Selection.SelectionScope.WorkPart
Dim selectionMask_array(1) As Selection.MaskTriple

With selectionMask_array(0)
.Type = UFConstants.UF_solid_type
.Subtype = 0
.SolidBodySubtype = UFConstants.UF_UI_SEL_FEATURE_CIRCULAR_EDGE
End With
With selectionMask_array(1)
.Type = UFConstants.UF_circle_type
.Subtype = 0
.SolidBodySubtype = 0
End With

Dim resp As Selection.Response = theUI.SelectionManager.SelectObjects( _
prompt, title, scope, selAction, _
includeFeatures, keepHighlighted, selectionMask_array, selObj)

If resp = Selection.Response.Ok
Return Selection.Response.Ok
Else
Return Selection.Response.Cancel
End If

End Function

End Module

Recap:

Althought the SelectObjectMaskTriple() is more difficult to set up you can see how it will allow the user more options in the selection process. By setting up the MaskTriple() then understanding and defining what parameters you need, you can create a selection process that will be as selective as you need.

Objectives:

In this tutorial, we have learned how to use maskTriples in both the SelectObject and SelectObjects methods to create a finely tuned selection process.