User Interface: Selection
This section contains functions that enable you to select objects in Creo Parametric from within the Graphics Window or the Model Tree using the mouse or the keyboard.
The Selection Object
Like ProModelitem, the object ProSelection identifies a model item in the Creo Parametric database. ProSelection, however, contains more information than ProModelitem, and is therefore sometimes used instead of ProModelitem in situations where the extra information is needed. The most important use of ProSelection is as the output of the function for interactive selection, ProSelect() (thus the name ProSelection).
ProSelection is declared as an opaque pointer, and is, strictly speaking, a WHandle because, although the model item is a reference to a Creo Parametric database item, the other information is not.
Functions Introduced:
Unpacking a ProSelection Object
For each item of information that ProSelection can contain, there is a Creo TOOLKIT function that extracts that information. The following table lists these items.
Creo TOOLKIT Function
Creo TOOLKIT Object
Meaning
ProSelectionAsmcomp
pathGet()
ProAsmcomppath
Assembly component path
ProSelectionModelitem
Get()
ProModelitem
Model item
ProSelectionPoint3dGet()
ProPoint3d
3-D point on the model item
ProSelectionUvParamSet()
ProUvParam
u and v, ort, of that point
ProSelectionDepthGet()
double
Selection depth
ProSelectionDistance
Eval()
double
Distance between two selected objects. The selection objects can be surfaces, entities, surface-curves, surface-nodes, or points.
ProSelectionViewGet()
ProView
Drawing view in which the selection was made
ProSelectionWindow
IdGet()
int
Window where a selection is done
ProSelectionDrawingGet()
ProDrawing
Drawing in which the selection was made.
ProSelectionDwgtblcell
Get()
several integers
Table segment, row, and column of a selected drawing table cell
The assembly component path is the path down from the root assembly to the model that owns the database item being referenced. It is represented by the object ProAsmcomppath and is described fully in the Assembly: Basic Assembly Access section.
The model item describes the database item in the context of its owning model, but does not refer to any parent assembly.
The 3-D point is the location, in solid coordinates, of a selected point on the model item, if it is a geometry object. The solid coordinates are those of the solid directly owning the model item.
If the model item is a surface, ProUvParam contains the u and v values that correspond to the 3-D selection point described above. If the item is an edge or curve, ProUvParam contains the t value.
The selection depth is the distance between the selected point and the point from which the selection search started. This is important only when you are using ProSolidRayIntersectionCompute(), described in the section Ray Tracing.
The view is used to distinguish different views of a solid in a drawing.
Building a ProSelection Object
Some Creo TOOLKIT function require a ProSelection object as an input. In many cases the assembly path—ProAsmcomppath—and the modelitem will be all that is needed, so ProSelectionAlloc() or ProSelectionSet() can be used. In other cases, for example when a ProSelection needs to identify a specific drawing view, or a specific location on a geometry item, you may also need to call functions ProSelectionViewSet(), ProSelectionUvParamSet(), and ProSelectionPoint3dSet().
ProSelection Function Examples
Examples of Creo TOOLKIT functions that use ProSelection are as follows:
•  ProSelect() uses ProSelection as its output to describe everything about the selected item.
•  ProGeomitemDistanceEval() uses ProSelection as its input, instead of ProGeomitem, so it can measure the distance between model items in different subassemblies.
•  ProSelectionHighlight() and ProSelectionUnhighlight() use ProSelection as inputs to distinguish different instances of the same model item in different subassemblies, and also different drawing views of the same model.
•  ProFeatureCreate() usually uses ProSelection objects to identify the geometry items the feature needs to reference.
•  ProDrawingDimensionCreate() uses ProSelection objects to identify the entities the dimension will attach to and the drawing view in which the dimension is to be displayed.
In a case such as ProGeomitemDistanceEval(), which uses ProSelection as an input, you might need to build a ProSelection object out of its component data items. The function ProSelectionAlloc() allocates a new ProSelection structure, and sets the ProAsmcomppath and ProModelitem data in it. The function ProSelectionSet() sets that information in a ProSelection object that already exists. The function ProSelectionVerify() checks to make sure the contents of a ProSelection are consistent.
The functionProSelectionCopy() copies one ProSelection object to another. ProSelectionFree() frees the memory of a ProSelection created by ProSelectionAlloc() or as output by a Creo TOOLKIT function.
Interactive Selection
Function Introduced:
ProSelect() is the Creo TOOLKIT function that forces the user to make an interactive graphics selection in Creo Parametric. Using this function the user can specify filters which control the items that can be selected.
Typically, the user has control over the filter options available from the filter menu located in the status bar at the bottom of the Creo Parametric graphics window. A call to ProSelect() sets application desired filters for the next expected selection.
The user interface shown when prompting for an interactive selection will be the selection dialog, with OK or Cancel buttons. Depending on the selection types permitted the user will be able to select items via:
•  The graphics window
•  The model tree
•  The search tool
•  External object
•  Items external to the activated component
None of these selections or possible selections will provide guidance to the user about what to select and why. Therefore, it is important to provide detailed instructions to the user through the message window or dialog box that the application expects the user to make a selection. Use the function ProMessageDisplay() to explain to the user the type or purpose of the selection you want them to make.
Note
When using this function in a UI command, make sure that the command priority for the UI command is appropriate for using ProSelect(). Improper priority settings can cause unpredictable results. See also Normal priority actions in the User Interface: Menu section.
The synopsis of ProSelect() is as follows:
ProError ProSelect (
  char              option[],        /* (In)  The selection filter. */
  int               max_count,       /* (In)  The maximum number of
                                              selections allowed. */
  ProSelection     *p_in_sel,        /* (In)  An array of pointers to
                                              selection structures used
                                              to initialize the array
                                              of selections. This can
                                              be NULL. */
  ProSelFunctions  *sel_func,        /* (In)  A pointer to a structure
                                              of filter functions. This
                                              can be NULL. */
  ProSelectionEnv   sel_env,         /* (In)  Use attribute PRO_SELECT_ACTIVE_
COMPONENT_IGNORE to also select items
external to the activate component. */ ProSelAppAction appl_act_data, /* (In) Use NULL. */ ProSelection **p_sel_array, /* (Out) A pointer to an array of pointers to selected items. This argument points to static memory allocated by the function. It is reallocated on subsequent calls to this function.*/ int *p_n_sels /* (Out) The actual number of selections made. The function allocates the memory for this function and reuses it on subsequent calls.*/ )
The first input argument to ProSelect(), option, is the set of item types that can be selected. This is in the form of a C string which contains the names of the types separated by commas (but no spaces). The following table lists the item types that can be selected by ProSelect(), the name of the type that must appear in the option argument, and the value of ProType contained in the ProModelitem for the selected item.
Creo Parametric Database Item
ProSelect() Option
ProType
Geometry Items
Datum point
point
PRO_POINT
Datum axis
axis
PRO_AXIS
Datum plane
datum
PRO_SURFACE
Datum Feature Symbol
set_datum_tag
PRO_SET_DATUM_TAG
Coordinate system datum
csys
PRO_CSYS
Coordinate System Axis
csys_axis
PRO_CSYS_AXIS_X PRO_CSYS_AXIS_Y PRO_CSYS_AXIS_Z
Edge (solid or datum surface)
edge
PRO_EDGE
Vertex
edge_end
PRO_EDGE_START, or PRO_EDGE_END
Datum curve
curve
PRO_CURVE
Datum curve end
curve_end
PRO_CRV_START, or PRO_CRV_END
Composite Curve
comp_crv
PRO_CURVE
Edge (solid only)
sldedge
PRO_EDGE
Edge (datum surface only)
qltedge
PRO_EDGE
Pipe segment end
pipeseg_end
PRO_PSEG_START or PRO_PSEG_END
Surface (solid or quilt)
surface
PRO_SURFACE
Surface (solid)
sldface
PRO_SURFACE
Surface (datum surface)
qltface
PRO_SURFACE
Surface (point)
pntsrf
PRO_SURFACE_PNT
Quilt
dtmqlt
PRO_QUILT
Annotations
Dimension
dimension
PRO_DIMENSION
Reference dimension
ref_dim
PRO_REF_DIMENSION
Geometric tolerance
gtol
PRO_GTOL
3D symbol
symbol_3d
PRO_SYMBOL_INSTANCE
Note
any_note
PRO_NOTE
3D Note
note_3d
PRO_NOTE
3D surface finish
surffin_3d
PRO_SURF_FIN
Annotation element
annot_elem
PRO_ANNOTATION_ELEM
Drawing Items
Drawing view
dwg_view
PRO_VIEW
Drawing table
dwg_table
PRO_DRAW_TABLE
Draft entity
draft_ent
PRO_DRAFT_ENTITY
Detail symbol
dtl_symbol
PRO_SYMBOL_INSTANCE
Detail note
any_note
PRO_NOTE
Table cell
table_cell
PRO_DRAW_TABLE
Solids and Features
Feature
feature
PRO_FEATURE
Part
part
PRO_PART
Component Feature
membfeat
PRO_FEATURE
Assembly component model
component
PRO_PART, PRO_ASSEMBLY
Part or subassembly
prt_or_asm
PRO_PART, or PRO_ASSEMBLY
Miscellaneous Items
Creo Simulate Items
Refer to the table in the section Selection of Creo Simulate Items
External object
ext_obj
PRO_EXTOBJ
Diagram fixed connector, fixed component, or parametric connector
dgm_obj
PRO_DIAGRAM_OBJECT
Diagram wire (not a cable)
dgm_non_cable_wire
PRO_DIAGRAM_OBJECT
Solid Body
3d_body
PRO_BODY
ECAD conductor
ecad_cu
PRO_ECAD_CONDUCTOR
MBD table
table_3d
PRO_TABLE
The second argument specifies the maximum number of items the user can select. If there is no maximum, set this argument to -1.
The third argument to ProSelect() is an expandable array of ProSelection structures (created using ProArrayAlloc() and ProSelectionAlloc()) used to initialize the selection list. For more information refer to section Expandable Arrays in the chapter Fundamentals. This is used in situations like Feature, Define in Creo Parametric where the user has the option of removing a default selection for a feature reference.
The fourth argument is an optional structure that specifies three, user-defined filter functions. These enable you to filter the items that are selectable in a customized way. For example, you could arrange that only straight edges are selectable by writing a filter that would check the type of the edge, and return an appropriate status. This function would then be called within ProSelect() to prevent the user from selecting a curved edge.
The fifth argument allows the user to pass a set of attributes to ProSelect() using the function ProSelectionEnvAlloc(). The function ProSelectionEnvAlloc() returns the ProSelectionEnv handle which is given as input to ProSelect(). The attributes of ProSelectionEnvAlloc() are:
•  PRO_SELECT_DONE_REQUIRED—Specifies that user has to click OK in the Select dialog box to get the selected items.
•  PRO_SELECT_BY_MENU_ALLOWED—Specifies that search tool is available in the function ProSelect() when the attribute value is set to True, which is the default value.
•  PRO_SELECT_BY_BOX_ALLOWED—Specifies that user must draw a bounding box to get the items selected within the box.
Note
The attribute PRO_SELECT_BY_BOX_ALLOWED can be used only for the types specified under “Geometry Items” in the above table.
•  PRO_SELECT_ACTIVE_COMPONENT_IGNORE—Specifies that user can select items external to the activate component.
•  PRO_SELECT_HIDE_SEL_DLG—Specifies that the Select dialog box must be hidden.
The sixth argument is not used in this release and should be set to NULL.
The final two arguments are the outputs, that is, an expandable array of ProSelection structures, and the number of items in the array. The previous section explains how to analyze the contents of a ProSelection object.
Note
The array of ProSelections is allocated and reused on subsequent calls to ProSelect().
Therefore, you must not free the output array. Also, if you wish to preserve any of the selections made, you should copy that selection using ProSelectionCopy().
Note
•  When using the function ProSelect() from within a loop, if you encounter the error PRO_TK_PICK_ABOVE (-14), then you must handle this error by returning control back to Creo Parametric.
•  The function ProSelect() returns PRO_TK_NO_ERROR when you end the command without making any selection in Creo Parametric. The function returns the output argument p_n_sels as zero and the array p_sel_array as NULL.
Highlighting
Functions Introduced:
The function ProSelectionHighlight() highlights an item specified by a ProSelection object in a color chosen from the enumerated type ProColortype. This highlight is the same as the one used by Creo Parametric (and ProSelect()) when selecting an item—it just repaints the wire-frame display in the new color. The highlight is removed if you use the View Repaint command or ProWindowRepaint(); it is not removed if you use ProWindowRefresh().
The function ProSelectionUnhighlight() removes the highlight.
ProSelectionHighlight() will not change the highlight color of an item already highlighted. If you need to do this, call ProSelectionUnhighlight() on the first item.
The function ProSelectionDisplay() does the same highlight as ProSelectionHighlight() but uses the standard highlight color used by Creo Parametric.
Note
For performance reasons, calls to ProSelectionHighlight() are cached and executed after a short delay or after a window repaint.
Selection Buffer
Introduction to Selection Buffers
Selection is the process of choosing items on which you want to perform an operation. In Creo Parametric, before a feature tool is invoked, the user can select items to be used in a given tool's collectors. Collectors are like storage bins of the references of selected items. The location where preselected items are stored is called the selection buffer.
Depending on the situation, different selection buffers may be active at any one time. In Part and Assembly mode, Creo Parametric offers the default selection buffer, the Edit selection buffer, and other more specialized buffers. Other Creo Parametric modes offer different selection buffers.
In the default Part and Assembly buffer there are two levels at which selection is done:
•  First Level Selection
Provides access to higher-level objects such as features or components. You can make a second level selection only after you select the higher-level object.
•  Second Level Selection
Provides access to geometric objects such as edges and faces.
Note
First-level and second-level objects are usually incompatible in the selection buffer.
Creo TOOLKIT allows access to the contents of the currently active selection buffer. The available functions allow your application to:
•  Get the contents of the active selection buffer.
•  Remove the contents of the active selection buffer.
•  Add to the contents of the active selection buffer.
Reading the Contents of the Selection Buffer
Functions Introduced:
Use the function ProSelbufferSelectionsGet() to access the contents of the current selection buffer. The function returns independent copies of the selections in the selection buffer (if the buffer is cleared, this array is still valid).
If there is no active selection buffer this function returns an error.
Use the standard Creo TOOLKIT functions to parse the contents of the ProSelection array.
However, the selection buffer stores chain and surface collections using a special mechanism. The function ProSelectionCollectionGet() can be used to extract the ProCollection object from a ProSelection.
Note
As per the manner of storage of the collection in the selection buffer, once the collection has been cleared from the buffer the ProSelection referring to the collection is no longer valid. Therefore, it is recommended to extract the ProCollection object from the ProSelection before there is a possibility that it may be cleared from the selection buffer.
Creo Parametric will execute the callback function ProSelbufferChangePostAction() defined by the application, when there is a change in the selection buffer. This function is available by calling the function ProNotificationSet() with the value of the notify type as PRO_SELBUFFER_CHANGE_POST.
The function ProSelbufferChangePostAction() is applicable for selection buffer change in drawing mode and solid mode.
Removing the Items from the Selection Buffer
Functions Introduced:
Use the function ProSelbufferClear() to clear the currently active selection buffer of all contents. After the buffer is cleared, all contents are lost.
Use the function ProSelbufferSelectionRemove() to remove a specific selection from the selection buffer. The input argument is the index of the item (the index where the item was found in the call to ProSelbufferSelectionsGet()).
Note
Because of the specialized nature of the Edit buffer in Creo Parametric, modification of the contents of the Edit buffer is not supported.
Adding Items to the Selection Buffer
Functions Introduced:
Use the function ProSelbufferSelectionAdd() to add an item to the active selection buffer.
Note
The selected item must refer to an item that is in the current model such as its owner, component path or drawing view.
This function may fail due to any of the following reasons:
•  There is no current selection buffer active.
•  The selection does not refer to the current model.
•  The item is not currently displayed and so cannot be added to the buffer.
•  The selection cannot be added to the buffer in combination with one or more objects that are already in the buffer. For example: geometry and features cannot be selected in the default buffer at the same time.
Use the function ProSelbufferCollectionAdd() to add a chain or surface collection to the active selection buffer. It has similar restrictions as ProSelbufferSelectionAdd().
Note
because of the specialized nature of the Edit buffer in Creo Parametric, modification of the contents of the Edit buffer is not supported.
Refer to the sample code Example 3: Assigning Creo Parametric command to popup menus. This example demonstrates the use of the selection buffer to determine the context for a popup menu button.