Interactive Selection
Function Introduced:
ProSelect() is the Creo TOOLKIT function that forces the user to make an interactive graphics selection in . 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 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.
 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.*/
)
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.
|
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
|
|
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 section Fundamentals. This is used in situations like Feature, Define in 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.
|
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.
• PRO_SELECT_CANCEL_ON_CLOSE_DLG—Specifies that the X(cancel) behaves the same as Close.
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.
|
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().
|
• 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 .
• The function ProSelect() returns PRO_TK_NO_ERROR when you end the command without making any selection in . The function returns the output argument p_n_sels as zero and the array p_sel_array as NULL.
|