Custom Feature Reference Manual
This section describes the functions available to create and interact
with custom features. It is recommended that new users first review the
concepts guide and be familiar with the dialog
generator.
SD-DEFFEATURE [macro]
(sd-deffeature feature-name
Feature identification attributes
:library library-name
:revision revision
:description feature-description
:feature-type feature-type
:name-str LISP-form
Feature behavior attributes
:on-split split-behavior
:on-body-split body-split-behavior
:on-merge merge-behavior
:on-body-merge body-split-behavior
:on-xform xform-behavior
:on-copy copy-behavior
:on-invalidate invalidate-behavior
:on-attach-cnt attach-count-behavior
:on-lost-ref lost-reference-behavior
:allow-actions keyword-list
:attachment attach-behavior
:filing filing-behavior
:warning warning-behavior
:constructor LISP-form
:verifier Symbol to function
:auto-verifier Value
:destructor Symbol to function
:inq-coord-sys-fnc LISP-form
:select-variable variable-name
:owner-variable variable-name
:save-variables variable-list
:report-variables variable-list
Feature appearance attributes
:category category
:src-location URL-to-source-file or URL-to-library-file
:pixmap URL-to-pixmap-file
:label-str LISP-form
SD-DEFDIALOG attributes
:module module
:dialog-title title
:dialog-type dialog-type
:dialog-control dialog-control
:toolbox-button toolbox-button
:variables variable-definitions
:after-initialization LISP-form
:local-functions function-definitions
:mutual-exclusion mutual-exclusion
:start-variable start-variable
:prompt-variable prompt-variable
:top-prompt-text top-prompt-text
:precondition precondition-form
:exception LISP-form
:ok-action-precondition LISP-form
:ok-action LISP-form
:cancel-action LISP-form
:cleanup-action LISP-form
:help-action LISP-form)
- Description:
- Defines a feature and the associated feature dialog. The feature is
referenced by the combination :library "_"
feature-name.
-
- Parameters:
-
- feature-name
{symbol}
- A symbol representing the name of the feature. Symbols that denote
existing LISP functions and SD dialogs within the specified library
will be rejected.
- :library {symbol}
- A :library attribute is a symbol that is used to uniquely
distinguish this feature from other similarly named features. This
creates a distinction between the "paint" feature from two different
manufacturers. The library name should be an identifier to uniquely
identify your organization.
- :revision {number [1.0]}
- A numeric value (major.minor) which specifies the revision number
of the feature definition (e.g. 1.0). The revision number will be used
to ensure that older feature definitions will not be used to modify
features. If a newer revision feature definition is used in a modify
operation, the feature will be converted to the newer revision.
- :description {string [""]}
- A string which gives a brief description of the feature and its
attributes. This string is for reference only and is not functionally
used for any purpose. It is intended to be a documentation tool for
the feature developer.
- :feature-type {KEYWORD [:non-geometric]}
-
Specifies the type of feature.
- :geometric - The feature will affect the geometry of
the model.
- :non-geometric - The feature does not produce any
geometry.
- :name-str {LISP-form [<:dialog-title>]}
-
This attribute contains a LISP form, that is evaluated to generate
the name prefix for the feature. If the resulting prefix is unique,
it is used to name the feature; if it is not unique, integer digits
will be appended until a unique name is found. Any characters that
are not alphanumeric or in the set [.-_] are relaced with the
underscore character. The following values may be specified for
:name-str:
- NIL - the default value, :dialog-title, will
be used if it exists; otherwise the feature-name will be
used.
- :none - the feature will not be named and will not show
up in the browser.
- LISP-form - the string returned from evaluating the
LISP-form will be used as the name. If the result is an empty
string, then the feature will not be named and will not show up in
the browser.
- :on-copy {KEYWORD [:copy]}
-
Specifies the feature behavior when the feature or the item to which
it is attached is copied. The copy may be the result of an explicit
request by the user, or it may be an implicit copy performed by one
of the machining operations. For example, the Unite operation
makes an implicit copy of the toolbody. If a feature on the
toolbody has its :on-copy behavior set to
:maintain, then the feature will not be copied and thus
will not be merged onto the blank body, even if the
:on-merge behavior is set to :maintain.
- :copy - make a copy of the feature on the new item
- :maintain - maintain the feature only on the old item
(do not copy the feature to the new item)
- :on-merge {KEYWORD [:maintain]}
-
Specifies the behavior of a feature on a Part body when an element
of the feature (such as a face, edge or vertex) is merged with
another element.
- :maintain - on an implicit merge, if both elements are
part of the feature, they are allowed to merge and the resulting
element becomes part of the feature; if only one of the elements
is part of the feature, the feature is maintained on that element
and the elements are not merged. For an explicit merge (Modify
3D - Merge) the elements are merged and the resulting element
becomes part of the feature
- :detach - the feature is detached (destroyed)
- :on-body-merge {KEYWORD [:maintain]}
-
Specifies the behavior of a feature on a Part body when the body is
merged with another body.
- :maintain - for body merges: the feature is maintained
on the resulting body
- :detach - the feature is detached (destroyed)
- :on-split {KEYWORD [:copy]}
-
Specifies the behavior of a feature on a Part body when an element
of the feature (such as a face or edge) is split.
- :copy - the new element is added to the feature
- :detach - the feature is detached (destroyed)
- :on-body-split {KEYWORD [:copy]}
-
Specifies the behavior of a feature on a Part body when the body is
split.
- :copy - if any of the elements of the feature are part
of the new body, a copy of the feature containing those elements
is created on the new body. The moved elements are removed from
the feature on the old body.
- :detach - the feature is detached (destroyed)
- :on-xform {KEYWORD [:maintain]}
-
Specifies the behavior when the feature receives a transform event.
This only occurs for the isotropic scaling of the body the feature
is attached to.
- :maintain - the feature is maintained on the body
- :detach - the feature is detached (destroyed)
- :on-invalidate {KEYWORD [:maintain]}
-
Specifies the behavior when a feature is invalidated. A feature is
invalidated when a reference variable (a variable which is not the
:select-variable, but contains a reference to an entity
such as a face, edge, vertex, feature, etc) loses its reference
(that is, the referenced entity is destroyed). :geometric
features will also be invalidated when the geometry of any of its
elements changes. This will occur when a Modify 3D operation affects
an element of the feature (for example, move, offset, taper, change
radius, etc.)
- :maintain - the feature is kept, but is invalidated
(the feature label will change color to red to indicate
this).
- :detach - the feature is detached (destroyed)
- :on-attach-cnt {KEYWORD [:maintain]}
-
Specifies the behavior when the number of elements which a feature
points to changes, (i.e. the feature loses any of its elements or
any aditional elements are added to the feature during modeling
operations).
- :maintain - the feature is kept
- :invalidate - the feature is invalidated (the feature
label will change color to red to indicate this)
- :detach - the feature is detached (destroyed)
- :on-lost-ref {KEYWORD [:maintain]}
-
Specifies the behavior when a feature loses any of its variable
references. A feature can lose a variable reference when Creo
Elements/Direct Modeling commands destroy a face to which the
feature references.
- :maintain - the feature ist kept
- :detach - the feature is detached (destroyed)
- :allow-actions {KEYWORD-LIST ['(:create :modify
:copy)]}
-
Limits the actions that can be performed by this sd-deffeature. It
may be any combination of the above list. At a minimum
:create must be specified. If an action is attempted
by the user that is not in the :allow-actions, an error
message will be displayed to the user.
- :create - allow feature to be created.
- :modify - allow feature to be modified.
- :copy - allow feature to be copied.
- :attachment {KEYWORD [:contents]}
-
When the feature is attached to an object (assembly, part,
worklane-set, or workplane) this behavior determines if the feature
is attached to the shared part (contents) or non-shared part
(instance) of the object.
- :instance - attach to the instance (non-shared
part)
- :contents - attach to the contents (shared part)
NOTE: this property is ignored for :geometric
features because they must always be attached to the contents
(shared part).
- :filing {filing specification [:sd-file]}
-
Specifies the types of output files that will include the feature.
The following filing specifications are valid:
- :sd-file - include the feature in standard Creo
Elements/Direct Modeling output files
- :annotator - labels associated with this feature are
transferred to annotator
- :mi-file - the feature is included in MI files created
for layouts
- :vrml-file - the feature will be stored in VRML
files
- :none - the feature is not included in any output
files
- LIST OF {:sd-file :mi-file :vrml-file} - the feature
will be stored for all of the specified file types
Examples:
:filing :none ; never store the feature
:filing :vrml-file ; store only in VRML file
:filing '(:sd-file :mi-file) ; store in SD and MI files
- :warning {warning specification ['(:invalidate
:conflict)]}
-
Specifies the feature conditions upon which a warning will be
displayed to the user. The following warning specifications are
valid:
- :invalidate - warn when the feature is invalidated
- :delete - warn when the feature is deleted
- :conflict - warn when a feature conflict occurs. A
conflict condition arises when two features of the same type are
attached to the same element (for example, two paint features on
the same face)
- :none - do not generate warning messages
- LIST OF {:invalidate :delete :conflict} - the user will
be warned for all of the specified conditions
Examples:
:warning :none ; never warn
:warning :invalidate ; warn only on invalidation
:warning '(:delete :conflict) ; warn on conflict and deletion
- :constructor {LISP-form}
-
A constructor is executed when performing a CREATE or COPY
operation. It is also executed after the :destructor
function in a MODIFY operation. All new faces created within the
constructor will automatically become part of the feature. A
constructor can be used for geometric or non-geometric features. The
return value of the cosntructor determines whether the operation was
succesful. The constructors return values and their meanings are as
follows:
- :error - an error occured; no message is displayed
- (values :error msg) - an error occured; the specified
message will be displayed
- any other value - constructor was successful
If an error condition for the constructor is returned, control
will be passed back to the user with the dialog still active and the
undo state set to the state before the ok-action was invoked.
Examples:
:constructor
' (sd-call-cmds (subtract_3d
:blanks (sd-inq-parent-obj (first CENTER_PT))
:tools NAME
:keep_tool :no))
NOTE: All new faces created by the subtract command above will become
part of the feature provided that the specified :owner-variable is a
parent of all the newly created faces. Otherwise an error message is
displayed.
- :verifier {Symbol [always :ok]}
-
A verifier is a symbol to a function which must accept a
single parameter that is the custom feature to be verified. The
function represented by the supplied symbol is executed as the last
action when performing a CREATE, COPY or MODIFY operation. It is
also executed when a Revalidate command is executed. In this
case the invalid feature will be revalidated if the
:verifier returns :ok. The return values and their
meanings are:
- :ok - verification was successful
- :warning - The feature did not pass validation tests,
mark the feature as invalid and continue the process. No message
is displayed.
- (values :warning msg) - same as :warning but the
specified message will be displayed
- :error - The feature did not pass validation tests and
the user is required to fix the problem before continuing. A
default error message is displayed.
- (values :error msg) - same as :error but the specified
message will be displayed
Examples:
:verifier 'verify-tapped-hole
(defun verify-tapped-hole(feat)
;;example verifier for tapped hole. Check if tapped hole has one or
;;two faces on it. Otherwise, it must be invalid
(let ((num-faces (sd-inq-feature-components :feat-sel-item feat)))
(if (or (eql (length num-faces) 1) (eql (length num-faces) 2))
:ok
(values :error "tapped hole is not valid where placed"))))
- :auto-verify {Lisp form [nil]}
- Specifies if the supplied :verifier should be executed
during model modification which may impact this feature. If the value
of :auto-verify is nil, the supplied :verifier is
only executed while the feature is being created, modified or copied.
If the value of :auto-verify is t, the supplied
:verifier will be executed automatically when modeling
operations occur that could cause the feature to become invalid.
- If set to t, the programmer needs to program the
:verifier so that it can be executed in a timely fashion as
this function may be called often. Also, be aware that since it can be
called at any time, no use of sd-call-cmds can occur within the
supplied :verifier.
- :destructor
{Symbol [nil]}
- The destructor is a symbol to a function which must accept
a single parameter that is the custom feature to be destroyed. This
function is executed before the :constructor for a MODIFY
operation. It is used to destroy the old feature before the
construction of the new, modified feature. The return value of the
destructor is used to determine success. If the supplied destructor
can not delete the supplied feature for whatever reason, it should
return a nil value.
-
Default Behaviours when no destructor is supplied:
- :non-geometric feature - delete feature attributes only
- :geometric feature - use the Modify 3D - Cut command to
remove the feature geometry and the attached feature attributes
from the model
NOTE: the supplied destructor form is only used during
the modification of a custom feature. It is not used at this time
within the Remove_Feature command.
NOTE: if a destructor is supplied, it is the
responsibility of the destructor to delete the feature (and perform
whatever side effects that are desired). Destroying a feature can be
accomplished either by deleting all components which belong to the
feature or by using the Remove_feature command.
Examples:
:destructor 'tapped-hole-destructor
(defun tapped-hole-destructor(feat)
;;example destructor for geometrical feature - cut all faces that belong
;;to this feature. This will in turn delete the feature itself
(sd-call-cmds (remove_faces :check :faces :by_feature feat)
:success t :failure nil))
:destructor 'paint-destructor
(defun paint-destructor(feat)
;;example destructor for non-geometrical feature - remove color from faces
;;on feature, then delete the feature (leave faces of the feature alone).
(sd-call-cmds (progn (clear_face_color :by_feature feat)
(remove_feature feat))
:success t :failure nil))
- :inq-coord-sys-fnc
{Symbol [nil]}
-
This function is used to query the feature for its
coordinate-system.
The coord-sys-fnc is a symbol to a function which must accept
a single parameter, that is the custom feature to be inquired.
It returns a list of 3 values, which define the position and 2
directions of the feature's local coordinate-system.
In the context of pattern operations, the
:inq-coord-sys-fnc gets called.
NOTE: for a custom feature (geometric) to be used in a
pattern, this function must be specified.
-
Example:
:inq-coord-sys-fnc 'hole-axis-placement
(defun hole-axis-placement(feat)
(let (vars)
;; inquire and extract the variables of the given feat, to form a valid coordinate-system
;; in this example the feature holds the 3 variabels :center, :axis and :u_direction
(setq vars (oli::sd-cust-feat-inq-vars feat :variables '(:center :axis :u_direction) :dest-space :global :units :internal))
;; ==> (:center 10,0,10 :axis (0,0,-1 10,0,10 nil) :u_direction (0,1,0 10,0,10 nil))
(list (getf vars :center) (first (getf vars :axis)) (first (getf vars :u_direction)))
)
)
- :select-variable {SYMBOL [nil]}
- The :select-variable specifies which :variable
will contain the selected elements for the custom feature. In the case
that the :owner-variable is not specified, the select
variable must specify a :modifies clause to indicate whether
the instance or contents will be modified to allow for access
verification (writable vs. read-only).
- :owner-variable {SYMBOL [<:select-variable>]}
- The :owner-variable is used to set the owner of the
feature (where it is stored). The :owner-variable must be a
symbol to a variable that accepts a single sel-item. If not specified,
non-geometric features will use the first item in the select-variable
as the :owner-variable's value. Geometric features require
the :owner-variable to be specified. The specified owner
variable has the requirement that it must specify a :modifies clause
to indicate whether the instance or contents will be modified to allow
for access verification (writable vs. read-only).
-
A NOTE ON FEATURES CROSSING OBJECT BOUNDARIES:
- All elements added to the feature must be children of the
owner specified by the :owner-variable. This is enforced
at run time by the sd-deffeature code. To create a feature that
cross object boundaries (I.E. parts, assemblies, workplanes,
workplane sets, containers, etc...), the :owner-variable
must be explicitly set to a common owner of the feature
components.
- The feature is only stored when the contents of the
:owner-variable are stored.
- Previously it was required that the :constructor's
return value be a sel-item to the owner of the feature. This is
no longer necessary with the introduction of this
:owner-variable.
- :save-variables {specification [:all-visible]}
-
This attribute specifies which of the :variables will be
saved as feature variables. The :select-variable which is
used to specify the selection variable for :non-geometric
features is automatically saved and should not be included in the
:save-variables specification. The specification options
are:
- :all - all variables will be saved
- :all-visible - all visible variables will be saved
- :none - no variables will be saved
- SYMBOL - the variable specified by the symbol will be
saved
-
LIST OF SYMBOLS - all the specified variables will be
saved
NOTE: there exists several types of variables that don't
make sense to save their values and will be excluded in all
cases. Those types include the following:
- :push-action
- :expand-shrink
- variables that don't exist, have an unknown value type, or
have no value
- :report-variables {specification
[<:save-variables>]}
-
This attribute specifies which of the :variables will be
reported when requested through the UI. The specification options
are:
- :all - all variables will be saved
- :all-visible - all visible variables will be saved
- :none - no variables will be saved
- SYMBOL - the variable specified by the symbol will be
saved
- LIST OF SYMBOLS - all the specified variables will be
saved
NOTE: when no value is set for :report-variables, the
specifictation for :save-varialbes is used.
- :category {string or LIST OF STRINGS
["/Custom-Features"]}
- A string or list of strings specifying the category path(s) to
which the feature belongs. The category path(s) are used for report
generation and grouping methods for selection/creation of custom
features. Any path is valid for a category as long as it begins with a
"/".
- :src-location {URL [nil]}
- This is a URL to the feature definition file (that is, the file
where the sd-deffeature can be found). If a :src-location is
not specified, then an existing instance of the feature cannot be
modified or a new feature created until the feature definition has
been loaded, or an alternate location is specified in the local
appearance data for the feature. A URL can either be a local file
specification or a fully specified URL address.
- :pixmap {URL [nil]}
- This is a URL to a pixmap file for the feature. This pixmap is
displayed in the structure browser and the custom feature browser. If
none is supplied, a default pixmap is used.
- :label-str {LISP-form [<:name-str>]}
-
This attribute contains a LISP form, which is evaluated to generate
the label string for the feature. The returned string may contain
embedded newline characters which break the label into multiple
lines. The following values may be specified for
:label-str:
- NIL - the :name-str form will be evaluated if
specified; otherwise the :dialog-title is used if
specified; otherwise the feature-name is used.
- :none - no label will be generated for the feature
- LISP-form - the string returned from evaluating the
LISP-form will be used for the label. If the string is empty, then
the feature will not have a label.
NOTE: The :label-str form may access the values
of the features variables to generate the feature label. Multiple
fonts (such as the hp_symbols and hp_symbols2 fonts) are also
supported via the shift-in/shift-out mechanisms.
SD-DEFDIALOG properties:
All supported SD-DEFDIALOG properties are
valid for use within a SD-DEFFEATURE definition. Included below as
examples are some of the key properties.
-
-
:dialog-title {string [feature-name]}
- Specifies a title that will appear in the top border of
the dialog window. If not specified, the title is derived
from feature-name.
-
:variables {PROPERTY-LIST [nil]}
-
Specifies the variables of the dialog. See SD-DEFDIALOG in the
Creo
Elements/Direct Modeling Integration Kit Reference
Manual.
-
NOTE: the following variable names are reserved
and cannot be used within sd-deffeature.
- description
- dialog
- feature_id
- action
- gbrowser
- last_state
- cust_feat_initializing
Two new values types have been introduced along
with custom features:
value
type |
comments |
:URL |
This value type is a string representing a file
specification. The specification may be in the
form of a local file path or any valid URL
address.
- Examples:
- "../file"
- "/dir1/dir2/file2"
- "http://www.ptc.com"
- "ftp://www.ptc.com"
- "file://localhost/tmp/file3"
- "file:///tmp/data.pkg"
NOTE: The performance of retrieving a URL
is dependent on network security and
performance. If a server is not responding, it
may take as much as one minute for the retrieval
method to time out and return control back to
SD.
|
:custom-feature |
This value type allows for the selection of
custom features. It is basically the same value
type as :feature, but restricts it
further to only those features created by
sd-deffeature. |
- :after-initialization {LISP-form [nil]}
- This form will be executed as soon as all the dialog
variables have been initialized (possibly employing the
:initial-value specifications). The
:after-initialization form is a good place to
finalize the state of the dialog before it becomes
interactive.
- :local-functions {LIST [nil]}
-
The keyword :local-functions can be used to define any
number of local functions. The definition of a local
function follows the same rules as the definition of a
LISP function by means of defun.
A local function is recommended whenever a function,
that requires access to local variables, can be used in
several places throughout the dialog.
- :mutual-exclusion {LIST, or LIST of LISTs
[nil]}
-
Specifies sets of variables in which only one variable can
possess a value at one particular time. The variables can
be specified either in the form of one or several lists:
- '(variable_1 ... variable_n) or
- '((variable_1 ... variable_n) ... (var_1 ...
var_m))
- :start-variable {SYMBOL [nil]}
- Specifies a variable that will be activated initially
active when creating a feature of this type. The value of
the :start-variable can be entered immediately by a
user. This behaviour is slightly different from SD-DEFDIALOG
where this property only applies to dialogs placed in the
toolbox.
- :prompt-variable {SYMBOL [nil]}
- Specifies a variable for which a value will be requested
from the user after each input interaction.
- :top-prompt-text {STRING ["Click an
Option"]}
- Specifies a text that appears in the prompt area when no
dialog variable is accepting user input data. The default
text is "Click an Option".
- :precondition {LISP-form [nil]}
- This form will be executed before the dialog appears on
the screen. If the form is supplied and does not return :OK,
the dialog will be canceled.
- :exception {LISP-form [nil]}
- This form will be executed in the event of an
exception.
- :ok-action-precondition {LISP-form [nil]}
-
This form will be executed when the OK Button of the
dialog is pressed. The function must return a either a
keyword {:ok :default} or the keyword
:error and an error message.
- :ok - The OK actions will be executed.
- :default - The built-in variable check will
be activated and used to determine whether the OK
actions will be executed.
- :error - The error message will be displayed.
The OK actions will not be executed.
- :ok-action
{LISP-form [nil]}
-
This form is executed after the construction/modification
of a feature is complete. It is used to perform any
additional operations on the completed feature. Such
operations may include generating side-effects such as
changing the color of a face to match that of a feature
variable. The supplied :ok-action is used to derive the
actual :ok-action for the feature. Therefore, for looping
dialogs it is not possible to simply use the action
associated with the supplied :ok-action.
-
For those features that require looping dialogs, the
complete :ok-action for the feature dialog can be
accessed via the function (sd-cust-feat-ok-action).
Even if you have no :ok-action defined,
sd-cust-feat-ok-action will be available and will
perform the steps necessary to create/modify/copy this
feature. If sd-cust-feat-ok-action is succesful, it
will return the sel-item to the constructed feature.
Otherwise, this function will return nil.
example:
-
:variables
'((FACE :value-type :face)
(NEXT :push-action (progn
(your-setup-loop)
(sd-cust-feat-ok-action)
(your-end-loop)))
- :cancel-action {LISP-form [nil]}
- Form to be executed when the CANCEL Button of the dialog
is pressed.
- :cleanup-action{LISP-form [nil]}
- This form will be executed immediately after the
execution of the OK actions or cancel action.
- :help-action {LISP-form [nil]}
- This form will be executed when the HELP button is
pressed. The form has access to all dialog variables that
are visible on the screen.
|
- Return Value:
-
- t - the feature definition was successful
- nil - an error occurred
Example:
-
(in-package :EXAMPLES)
(use-package :OLI )
(sd-deffeature 'PAINT
; Feature Identification attributes
:library 'CoCreate
:revision 1.0
:description "Paint Feature demonstration"
:feature-type :non-geometric
:name-str `(format nil "~A_~A" F_TYPE "Paint")
; Feature Behavior attributes
:filing '(:sd-file :mi-file :vrml-file) ;default is :sd-file
; Feature Appearance attributes
:category "/Mfg/Finishing"
:src-location "http://fc.cocreate.com/features/examples/paint.lsp"
:pixmap "http://fc.cocreate.com/features/examples/paint.pm"
:report-format "http://fc.cocreate.com/features/examples/paint.rpt"
; Feature Control attributes
:select-variable 'F_ITEMS
:start-variable 'F_ITEMS
:save-variables :all-visible ;(:none, :all, :all-visible, list)
; sd-defdialog attributes
:dialog-title "Paint"
:ok-action '(let (faces)
(setq faces
(sd-call-cmds(get_selection :select :by_feature (sd-active-cust-feat))))
(sd-call-cmds(set_face_color faces F_COLOR))
)
:variables
'((F_ITEMS :selection (*sd-face-seltype*)
:multiple-items t
:title "Selection"
:modifies :contents
:prompt-text
"Select Faces for paint feature")
(F_COLOR :value-type :rgb-color
:title "Color"
:prompt-text "Specify a color")
(F_TYPE :value-type :string
:title "Type"
:prompt-text "Specify the paint type."
:initial-value "Latex"))
)
Defaults of the above example:
- :on-split = :copy
- :on-copy = :copy
- :on-merge = :maintain
- :on-body-merge = maintain
- :on-xform = :maintain
- :on-invalidate = :maintain (non-geometric features in general are
never invalidated)
- :attachmentent = :contents
- :warning = '(:invalidate :conflict)
- :verifier = t
- :label-string = :name-str value
- :dialog-title = feature ("PAINT")
- generated dialog name = EXAMPLES_PAINT
SD-CUST-FEAT-LOCAL-APPEARANCE [function]
(sd-cust-feat-local-appearance feature-name
:library library
:category category
:alternate-location URL-to-source-file
:alt-location-first yes_no
:pixmap URL-to-pixmap-file
- Description:
- This function sets the local appearance data for a feature. All the
attributes default to a null value, which means that the attributes
specified in the feature definition should be used. When a value is
specified for a field, that value will override the value in the feature
definition.
-
- Parameters:
-
- feature-name {symbol}
- A symbol representing the name of the feature.
- :library{symbol}
- A symbol representing the library containing the feature. The
specified library needs to match the same library defined in the
feature definition (sd-deffeature).
- :category {string or LIST OF STRINGS ["
/Custom-Features"]}
- A string or list of strings specifying the category path(s) to
which the feature belongs.
- :alternate-location {URL [nil]}
- The URL to an alternate feature definition file. The feature's
:src-location is used as the primary URL to the definition
file, and if that URL does not exist or cannot be accessed, then the
alternate location is used (see :alt-location-first). A
feature cannot be created or modified unless a feature definition
(either the primary or alternate) can be accessed.
- :alt-location-first {Boolean [nil]}
- Determines if the :alternate-location should be attempted
to be accessed before the original :src-location is
attempted. This is useful if you know that the original source
location is unavailable to your location. Otherwise, the system will
attempt to first contact the :src-location.
- :pixmap {URL [nil]}
- The URL to the pixmap file to override the pixmap defined in the
feature.
- Return Value:
-
- the value of the local appearance attributes
- nil - an error occurred
- Example:
-
(sd-cust-feat-local-appearance 'PAINT
:library 'CoCreate
:pixmap "/opt/CoCreate/my_pixmaps/paint_it.pm"
:category '("/BodyAttributes" "/PostProcessing/InHouse")
:alternate-location "http://my-host/features/backup/paint.lsp")
:atlernate-location-first nil)
==> (:library 'CoCreate :pixmap ...)
SD-CUST-FEAT-INQ-PROPS [function]
(sd-cust-feat-inq-props feature
:properties items)
- Description:
- This function gets the value of one or more properties of a
feature.
-
- Parameters:
-
- feature {sel-item}
- A sel-item representing the feature instance.
- :properties {specification [:all]}
-
A specification of the CUST_FEAT properties to inquire. The
specification options are:
- :all - all properties of the feature are returned
- KEYWORD - the value of the property specified is
returned
- LIST OF KEYWORDS - the values of the properties are
returned
-
The supported property keywords are:
- :dialog - symbol name of the feature and its
corresponding dialog
- :revision - the revision number of the feature
- :on-copy - the copy behavior
- :on-split - the entity split behavior
- :on-merge - the entity merge behavior
- :on-xfrom - the behavior on transformation
- :on-invalidate - the behavior when invalidated
- :attachment - the parcel attachment mode
- :filing - which file types the feature will be included
in
- :warning - the conditions that will generate a
warning
- :category - the list of categories
- :src-location - URL to the feature definition
- :pixmap - URL to the feature pixmap
- :category - the list of categories
- Return Value:
-
- value - the value of the properties of the feature as a
PLIST
- nil - either a single item was requested which had a
NIL value, or an error occured.
- Examples:
-
(sd-cust-feat-inq-props feat :properties '(:revision :on-copy :filing))
==> (:revision 1.5 :on-copy :maintain :filing (:sd-file :mi-file))
(sd-cust-feat-inq-props feat)
==> (:revision 1.5 :on-copy ... :category '("/BodyAttribute" "/PostProcessing"))
SD-CUST-FEAT-INQ-VARS [function]
(sd-cust-feat-inq-vars feature
:variables items
:dest-space space
:units unit-type)
- Description:
- This function gets the value of one or more variables of a feature.
The value is returned transformed to a specified coordinate space and in
the specified unit system.
-
- Parameters:
-
- feature {sel-item}
- A sel-item representing the feature instance.
- :variables {specification [:all]}
-
A specification of the CUST_FEAT variables to inquire. The
specification options are:
- :all - all properties of the feature are returned
- KEYWORD - the value of the property specified is
returned
- LIST OF KEYWORDS - the values of the properties are
returned
- :dest-space {KEYWORD or sel-item [:local]}
-
A specification of the destination space to transform variable
values to. The options are:
- :local - leave values in local coordinate space
- :global - transform values to global coordinate
space
- sel-item - transform to the coordinate space of the
specified parcel
- :units {KEYWORD [:external]}
-
Specifies the units in which variable values are returned. The
options are:
- :internal - leave values in internal (system)
units
- :external - convert values to external (user)
units
- Return Value:
-
- value - the value of the variables of the feature as a
PLIST.
- nil - either a single item was requested which had a
NIL value, or an error occured.
- Example:
-
- (sd-cust-feat-inq-vars feat :variables '(:one :two)
:dest-space :global :units :external)
- ==> (:one 1.0 :two "two")
- Note:
- If you wish to inquire which entities are attached to the given
feature, use the function sd-inq-feature-components.
SD-CUST-FEAT-SELECT [function]
(sd-cust-feat-select owners
:recursive t-or-nil
:attachment attachment
:test test-fnc)
- Description:
- This function is used to select custom features starting at
owners which pass the specified test-fnc and
attachment. The function can be controlled to select custom
features only attached to the given owners or it can also scan
through all the children of owners to find all custom features
within the given owners list. All custom features that match the given
criteria are returned.
-
- Parameters:
-
- owners {sel-item or LIST of sel-items}
- A sel-item representing the start point of the selection function.
If a list of sel_items is provided, each owner in the list will be
scanned for custom features.
- recursive {t or nil [nil]}
- Determines if the selection function should scan through all the
children of the specified owners. If t, then all custom
features attached to owners and their children will be scanned for.
Otherwise, only those custom features attached to the owners will be
searched.
- attachment{KEYWORD or SEL_ITEM [:all]}
-
Determines at what level on the owner to scan for custom features.
Options include:
- :all - all levels of the owner are scanned
- :instance - only features attached at the instance
level of the owner is searched.
- :contents - only features attached at the contents
level of the owner is searched.
- SEL_ITEM - only features which have components attached
to the supplied SEL_ITEM are searched for.
- test{SYMBOL to a function [t]}
- Only those custom features which pass the given test-fnc will be
returned. The default is to match all custom features. The supplied
test-function, must return nil if the test fails (i.e. you don't want
to match this custom feature).
- Return Value:
-
- features - a list of the matched features found on the
specified items.
- nil - none of the specified items has a feature of the
specified properties which is attached to given owners.
- Examples:
-
(sd-cust-feat-select (sd-pathname-to-obj "/my_assy"))
==> returns all custom features in "/my_assy"
(sd-cust-feat-select (sd-pathname-to-obj "/my_assy") :recursive t)
==> returns all custom features in "/my_assy and its children.
(defun find-paints(feat)
(sd-string= "EXAMPLES_PAINT"
(second (sd-cust-feat-inq-props feat :properties :dialog))))
(sd-cust-feat-select (sd-pathname-to-obj "/my_assy")
:recursive t :test 'find-paints)
==> returns all "PAINT" features within the assembly "/my_assy" and
its children.
(sd-cust-feat-select (sd-pathname-to-obj "/my_assy") :test 'find-paints
:attachment my-face)
==> returns all "PAINT" features which use the face "my-face"
SD-CUST-FEAT-INQ-LABEL [function]
(sd-cust-feat-inq-label feature)
- Description:
- This function retrieves the label associated with a custom
feature.
-
- Parameters:
-
- feature {sel_item}
- This parameter specifies the custom feature from which to retrieve
the label.
- Return Value:
-
- label - sel_item to the label attached to the given
feature.
- nil - there is no label associated with this custom
feature.
SD-ACTIVE-CUST-FEAT [function]
(sd-active-cust-feat)
- Description:
- This function will return a handle (sel-item) to the custom feature
currently being manipulated.
-
- Return Value:
-
- sel-item - a sel-item to the current active custom
feature
- nil - no custom feature is currently active
SD-CUST-FEAT-ACTION [function]
(sd-cust-feat-action)
- Description:
- This function can be used to query the action being performed on the
current feature. The feature attribute :allowed-actions limits
which actions a feature is allowed to participate.
-
- Return Value:
-
- KEYWORD
- :create - returned during the creation of a custom
feature.
- :modify - returned when custom feature is being
modified.
- :copy - returned when custom feature is being copied.
SD-MODIFY-CUST-FEAT [function]
(sd-modify-cust-feat feat :action action
:values value-list
:query-only flag)
- Description:
- This function can be used to both modify and query a custom feature
programmatically. As a query utility, this function will return back as a
list the entire command sequence of the custom feature. If the
query-only flag is nil, then this function will perform the
specified action on the custom feature updating the values of the
custom feature with the specified values.
- NOTE: This function must be called within the scope of a user
defined command unless the query-only flag is set to t.
-
- Parameters:
-
- Feat - sel-item of custom feature to be modified
- :action {keyword [:modify | :copy]}
- determines if the function will modify or copy an existing custom
feature.
- :values {property-list [nil]}
- property list containing the new values of the custom
feature.
- :query-only {boolean [nil]}
- boolean flag to control if the command should be executed [nil] or
if this function should return the command list as its return value,
but not actually perform the modification [t].
- Return Value:
-
- with the query-flag set, a list containing the command syntax of
the custom feature.
- without the query-flag set, the return value of the executed
custom feature or t.
nil - an error occured
- Examples:
-
-
Let feature be a sel-item pointing to a 3D note with the
string "A 3D note" attached to a face.
Example 1: Modify the note string of a 3D note.
(sd-modify-cust-feat feature :action :modify :values '(:note "A modified 3D note"))
Example 2: Copy a 3D note to face2 (where face2 is a sel-item to
a face) with the string "A copied 3D note".
(sd-modify-cust-feat feature :action :copy :values '(:items face2 :note "A copied 3D note"))
Example 3: Query the command syntax of a custom feature (a
3D_note for this example).
(sd-modify-cust-feat feature :action :modify :query-only t"))
==> (CUST_FEAT::COCREATE_3D_NOTE :ACTION :MODIFY :FEATURE_ID
#S(ELAN::SEL_ITEM ELAN::PATH
(#S(ELAN::NPARCEL DSM::SIMPLE-ENTITY-PTR 313681616)
#S(ELAN::NPARCEL DSM::SIMPLE-ENTITY-PTR 317704896))
LISP::TYPE 313541376 ELAN::ITEM
#S(K2::FEATURE DSM::SIMPLE-ENTITY-PTR 318384448))
:NOTE "A 3D note" :URL "" :CATEGORY :GENERIC :ACTION
:INITIALIZED))
Example 4: Query a custom feature, add additional values, and
manually execute sd-call-cmds (normally, this is not necessary since
the same results can be accomplished by simply not using the
query-only flag)
(setq cmd (sd-modify-cust-feat feature :action :modify :values '(:note "An edited 3D note")))
==> cmd = (CUST_FEAT::COCREATE_3D_NOTE :ACTION :MODIFY :FEATURE_ID
#S(ELAN::SEL_ITEM ELAN::PATH
(#S(ELAN::NPARCEL DSM::SIMPLE-ENTITY-PTR 313681616)
#S(ELAN::NPARCEL DSM::SIMPLE-ENTITY-PTR 317704896))
LISP::TYPE 313541376 ELAN::ITEM
#S(K2::FEATURE DSM::SIMPLE-ENTITY-PTR 318384448))
:NOTE "A 3D note" :URL "" :CATEGORY :GENERIC :ACTION
:INITIALIZED :NOTE "An edited 3D note"))
;;now,manually execute the command, which will modify the 3d_note.
(eval (sd-call-cmds ,cmd))
SD-SHOW-CUST-FEAT-BROWSER [function]
(sd-show-cust-feat-browser :root root
:categories-only flag
:position position)
- Description:
- This function will display the custom feature browser starting from a
specified node of the category tree.
-
- Parameters:
-
- :root {string ["/"]}
- This parameter specifies the starting point or root of the
category tree to be displayed.
- :categories-only {BOOLEAN [nil]}
- A boolean specifying whether only categories should be displayed
(nil), or if features should be displayed as well
(t).
- :position {LIST}
- When specified, the browser is attached as defined. Otherwise, it
is placed at the top right corner of the SD window. (See sd-show-display-table
documentation for supported position options).
- Return Value:
-
- t - the operation was successful
- nil - an error occured
SD-HIDE-CUST-FEAT-BROWSER [function]
(sd-hide-cust-feat-browser :ignore-pin flag)
- Description:
- This function will hide the custom feature browser.
-
- Parameters:
-
- :ignore-pin {BOOLEAN [nil]}
- A boolean specifying whether to hide the browser, even if pinned
(t).
- Return Value:
-
- t - the operation was successful
- nil - an error occured
SD-RETRIEVE-URL [function]
(sd-retrieve-url URL)
- Description:
-
This function retrieves a local file or URL and copies it to a local
file. The function returns the name of the local file. This function
can be used anywhere Creo Elements/Direct Modeling wants a filename.
If a local file definition is supplied, Creo Elements/Direct Modeling
search-directories will be used to locate the local file name.
NOTE: there is currently a restriction that password protected URLs
cannot be handled.
WARNING: the local file into which the URL is copied is a temporary
file. It will only be available until the next URL is retrieved. If the
file is needed for a longer time period, the feature developer must
include the code to copy it to a more permanent location. The feature
developer is then responsible for clean-up of such copied files.
- Parameters:
-
- URL {URL}
- This parameter specifies the URL to retrieve.
- Return Value:
-
- filename - the filename of the local copy of the URL.
- nil - an error occured
- Examples:
-
(sd-retrieve-url "c:/temp/rec.out")
==> "c:/temp/rec.out"
(load (sd-retrieve-url "ftp://my-machine.edu/feature_lib.lsp"))
==> "c:/temp/sdAcbd00e"
(sd-retrieve-url "//localhost/temp/file3")
==> "c:/temp/sdAcbd00c"
- NOTE:
- For local file: URLs, the local host must be specified as
either "//localhost" or "//" before the absolute path to the file. (See
also URL value type).
SD-SET-PROXY [function]
(sd-set-proxy :proxy proxy
:domain domain
:port port
:protocol protocol)
- Description:
- This function defines a proxy and domain specification for accessing
URLs.
-
- Parameters:
-
- :proxy {string}
- This parameter specifies the proxy host to use for the specified
:protocol. If the protocal is :no-proxy, then this
parameter is ignored.
- :domain {string or LIST of strings}
- This parameter specifies the domains for the :no-proxy
condition. This parameter is ignored unless the protocal is set to
:no-proxy.
- :port {number [80]}
- A specification of the port number for the domain. The default is
80 which is the standard http port number.
- :protocol {KEYWORD or LIST of KEYWORDS [:HTTP]}
- This parameter specifies the protocol to be set. Any valid
protocol may be given in the form of a KEYWORD; or the KEYWORD
:no-proxy to specify no proxy for the given domain.
- Return Value:
-
- value - the proxy value(s) that were established
successfully
- nil - an error occured
- Examples:
-
(sd-set-proxy :proxy "my-proxy.com" :protocol :http :port 80)
==>(:http "http://my-proxy.com:80")
(sd-set-proxy :proxy "my-proxy.com" :protocol '(:http :ftp))
==>(:http "http://my-proxy.com" :ftp "http://my-proxy.com")
(sd-set-proxy :domain '("foo.com" "fc.cocreate.com") :protocol :no-proxy)
==> ("foo.com" "fc.cocreate.com")
Modifying Custom Features Programmatically
To modify custom features programmatically, a way to find out the correct
syntax for a certain type of the custom features is to use the command
modify_custom_feature (see Command Index in the SD help message). It will
return a list back, which contains exactly the command for the feature
modification. This list also shows how to input all the parameters in a
correct order for invoking this function.
As an example for modifying custom features programmatically, the
following code shows how to modify the upper and lower limits of a GDT
plus/minus tolerance through a user dialog (the limit values are changed to
+/- 0.6).
Example:
(in-package :sample)
(use-package :oli)
(sd-defdialog 'modify-plus-minus-tol
:variables
'(
(sel-tol :selection (oli::*sd-feature-seltype*))
)
:ok-action
'(let (cmd-list pos)
;;query feature for proper command syntax (statt :any you can specify
;;the feature type if you know its keyword)
(setq cmd-list (sd-call-cmds (modify_custom_feature :any sel-tol)))
(when cmd-list
;;modify the desired variables in this list
(setq pos (position :tol_high cmd-list))
(when pos
(setf (nth (1+ pos) cmd-list) 0.6))
(setq pos (position :tol_low cmd-list))
(when pos
(setf (nth (1+ pos) cmd-list) -0.6))
;;now modify the feature (as shown in integration kit)
(eval `(sd-call-cmds ,cmd-list))
)
)
)
© 2024 Parametric
Technology GmbH
(a subsidiary of PTC Inc.), All Rights Reserved |