User Interface: Selection

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:

ProSelectionAsmcomppathGet()

ProSelectionModelitemGet()

ProSelectionUvParamGet()

ProSelectionViewGet()

ProSelectionPoint3dGet()

ProSelectionDepthGet()

ProSelectionVerify()

ProSelectionWindowIdGet()

ProSelectionUvParamSet()

ProSelectionViewSet()

ProSelectionPoint3dSet()

ProSelectionDrawingGet()

ProSelectionDwgtblcellGet()

Unpacking a ProSelection Object

For each item of information that ProSelection can contain, there is a Creo Parametric TOOLKIT function that extracts that information. The following table lists these items.

Creo Parametric TOOLKIT Function	Creo Parametric 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 Parametric 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 Parametric 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 Parametric TOOLKIT function.

Interactive Selection

Function Introduced:

ProSelect()

ProSelect() is the Creo Parametric 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
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

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:

ProSelectionHighlight()

ProSelectionDisplay()

ProSelectionUnhighlight()

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 Parametric 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:

ProSelbufferSelectionsGet()

ProSelectionCollectionGet()

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 Parametric 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.

Removing the Items from the Selection Buffer

Functions Introduced:

ProSelbufferClear()

ProSelbufferSelectionRemove()

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:

ProSelbufferSelectionAdd()

ProSelbufferCollectionAdd()

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.