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.

• Defining a custom feature
  • sd-deffeature
  • URL value type
  • custom-feature value type
  • sd-cust-feat-action
  • sd-cust-feat-local-appearance
• Inquiring custom features
  • sd-cust-feat-inq-props
  • sd-cust-feat-inq-vars
  • sd-cust-feat-select
  • sd-cust-feat-inq-label
  • sd-active-cust-feat
• Modifying custom features
  • sd-modify-cust-feat
• Display functions
  • sd-show-cust-feat-browser
  • sd-hide-cust-feat-browser
• URL and Proxies
  • sd-retrieve-url
  • sd-set-proxy
• Modifying custom features programmatically

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))
       )
     )
  )