Symbol Customization

The following functions are usable in the context of Annotation. If you want to create symbols in the context of 3D Documentation and in the context of Annotation, please refer to the documentation for functions useable for both applications in parallel. It is recommended to use those functions for new implementations.

Symbol Creation and Registration:: sd-am-create-symbol-dialog
sd-am-register-symbol
sd-am-unregister-annotation-template
sd-am-unregister-symbol
sd-am-unregister-symbol-all
Predicates:: sd-am-symbol-p
Inquiries:: sd-am-inq-symbol-param-names
sd-am-inq-symbol-param
sd-am-inq-symbol-text-area
Geometry Creation:: sd-am-create-symbol-line
sd-am-create-symbol-polygon
sd-am-create-symbol-arc
sd-am-create-symbol-circle
sd-am-create-symbol-selectable-point
Hatch Creation:: sd-am-create-symbol-hatch
Text and Parameter Creation:: sd-am-create-symbol-text
sd-am-create-symbol-parameter
sd-am-set-symbol-param-value

The reference point for symbol placement and scaling is always 0,0.

For the geometry element creation in symbols the current geometry attributes are applied.
For the text and parameter element creation in symbols the current text attributes are applied.
For the hatch element creation in symbols the current manual hatch attributes are applied.

SD-AM-CREATE-SYMBOL-DIALOG [function]

(sd-am-create-symbol-dialog :name                dialog-name
                            :title               title
                            :variables           variables
                            :save-variables      save-variables
                            :auto-angle          auto-angle
                            :position-prompt     position-prompt
                            :before-position     before-position
                            :after-position      after-position
                            :local-functions     local-functions
                            :draw-symbol-command draw-symbol-command
                            :mutual-exclusion    mutual-exclusion
                            :help-action         help-action)

Description:

Creates a dialog that allows the user to interactively create a symbol, enter the parameter values and place the new symbol on the drawing. This function creates a dialog template to which all the individual symbol's specific dialog parts - as defined by the function parameter list - are added automatically. For general information on dialogs see the Dialog Generator Manual.

Parameters:

:name {STRING} - The Lisp symbol of the created dialog.

:title {STRING}

A title that will appear in the top border of the dialog window. If not specified, the title is derived from name.

:variables {PROPERTY-LIST}

Specifies the dialog variables. Each property of a variable is specified by a keyword and its value. The variables list is described in the Dialog Generator Manual. The default value is nil.

:save-variables {LIST OF SYMBOLS}

This attribute specifies which of the :variables will be saved as symbol variables. These variables will be used for editing the symbol. The default value is nil.

:auto-angle {BOOLEAN [nil]}

Indicates whether the default setting for the symbol angle should be set to Auto or not.

:position-prompt {STRING}

A text that appears in the prompt area while the user places the symbol on the drawing. If no position-prompt is specified, the default string is "Identify position for symbol".

:before-position {LISP-form}

Contains all commands that are executed just before the symbol is positioned. The default value is nil.

:after-position {LISP-form}

Contains all commands that are executed just after the symbol has been positioned. The default value is nil.

:local-functions {LISP-form}

The definition of all local functions of the dialog. The definition of a local function follows the same rules as the definition of a LISP function by means of defun. See the Dialog Generator Manual for more information. The default value is nil.

:draw-symbol-command {LISP-form}

Contains all function calls which are necessary to draw the symbol, i.e. to create the symbol parameters, geometry, texts and hatches. Can be any of the following functions:

sd-am-create-symbol-line

sd-am-create-symbol-polygon

sd-am-create-symbol-arc

sd-am-create-symbol-circle

sd-am-create-symbol-selectable-point

sd-am-create-symbol-hatch

sd-am-create-symbol-text

sd-am-create-symbol-parameter

The default value is nil.

:mutual-exclusion {LISP-form}

The mutual-exclusion list ensures that a value is assigned to only one of its variables at one time. In the symbol dialog menu a diamond shaped indicator shows which variable holds a value. Selecting another variable from this list will cause the indicator highlight the new variable and at the same time will remove the value from the old variable. See the Dialog Generator Manual for further information. The default value is nil.

:help-action {LISP-form}

Clicking the help button executes the help-action for the customized symbol. See the Dialog Generator Manual for more information. The default value is nil.

Return Value:

Undefined

Example:

(sd-am-create-symbol-dialog
  :name "SYMBOL_DATUM"
  :title "Datum"
  :position-prompt "Place the datum symbol in drawing"
  :draw-symbol-command
         (let ((pnt1   (make-gpnt2d :x   0.0 :y  0.0))
               )
           ; change the symbol text and geo settings 
           ; (else the current ones are taken)
           (sd-call-cmds (AM_TEXT_SETTINGS  :size     3.5 :abs_angle 0.0
                                            :slant    0.0 :ratio    1.0
                                            :adjust   5   :frame    "OFF"
                                            :font1b   "hp_i3098_v"))
           ; define the symbol parameters
           (sd-am-create-symbol-parameter "datum" DATUM :position pnt1)
           (sd-am-create-symbol-line (list (make-gpnt2d :x   -3 :y  -3)
                                           (make-gpnt2d :x   +3 :y  -3)
                                           (make-gpnt2d :x   +3 :y  +3)
                                           (make-gpnt2d :x   -3 :y  +3)
                                           (make-gpnt2d :x   -3 :y  -3)))
           ) ;; end let 

  :before-position (setf last-text-length (* 3.5 (+ 4 (length datum))))
  :after-position  (progn (setf max-datum (+ max-datum 1))
                      (when (< max-datum 26)
                        (setf DATUM (format nil "~A" (code-char (+ 65 max-datum))))
                        )
                      ) ;; end after-input
  :local-functions ( (make-beautiful (a-string)
                       (sd-string-upcase a-string)
                     ) )
  :save-variables (datum)
  :variables
  (
   (DATUM
     :value-type     :string
     :title          "Datum"
     :prompt-text    "Specify the Datum"
     :initial-value  "A"
     :after-input (setf DATUM (make-beautiful DATUM))
     ) ;; end datum
   (max-datum
     :initial-value 0
    ) ;; end max-datum
  ) ;; end variables
) ;; end macro call

SD-AM-REGISTER-SYMBOL [function]

(sd-am-register-symbol :meta-name   meta-name
                       :create-dia  create-dia
                       :edit-dia    edit-dia
                       :pixmap-file pixmap-file
                       :file-name   file-name
                       :category    category)

Description:

Adds a symbol to the symbol browser. If the symbol with the specified meta-name already exists in the browser, it will replace the existing one. If create-dia is specified, the registered symbol will be created by this dialog ("dialog-based symbol"), and edit-dia may optionally specify a dialog to be used for editing the parameter values of an existing symbol. As an alternative to create-dia and edit-dia, an MI file-name can be specified from which the symbol is loaded ("file-based symbol"), in which case create-dia and edit-dia are ignored and generic dialogs are used for creating and editing the symbol.

Parameters:

:meta-name {STRING}: Unique symbol name to be added or replaced. If meta-name is omitted create-dia name is used instead. Meta-name is used to identify the symbol in the symbol browser.
:create-dia {STRING}: The Lisp symbol of the dialog that allows to create the symbol. The specified dialog has to be loaded before.
:edit-dia {STRING}: The Lisp symbol of the dialog that allows to edit the parameters of an existing symbol. The specified dialog has to be loaded before.
:pixmap-file {STRING}: The name of a pixmap-file which contents is shown left of the meta-name in the symbol browser. The pixmap can be created with sd-create-image. It is recommended to use the same size for all registered symbol pixmaps (60x30) and to use background and foreground colors, which are set to Creo Elements/Direct Modeling colors during the registration. No pixmap is shown for the symbol if pixmap-file is omitted.
:file-name {STRING}: An MI file name. To create the symbol, the file which defines the geometry, texts, parameters and hatches is loaded and a generic dialog allows to enter values for the symbol parameters.
:category {STRING}: The name of a symbol browser category to which the symbol is inserted or where it replaces an existing symbol with the same meta-name. Categories allow the user to classify numerous symbols in several groups, which leads to a tree structure in the symbol browser. If category is omitted the symbol is registered on the root level.

Return Value:

Undefined

Example:

(sd-am-register-symbol           ; dialog based symbol
  :meta-name   "Long Datum"
  :pixmap-file "symbol-long-datum.xbm"
  :create-dia  "symbol_datum"
  :category    "Datum")

(sd-am-register-symbol           ; dialog based symbol
  :meta-name   "Tolerance"
  :pixmap-file "pixmaps/sym_tol0.xbm"
  :create-dia  "am_create_symbol_tolerance"
  :edit-dia    "am_edit_symbol_tolerance")

(sd-am-register-symbol           ; file based symbol
  :meta-name   "My_symbol"
  :pixmap-file "pixmaps/my_symbol.xbm"
  :file-name   "symbols/my_symbol.mi")

SD-AM-UNREGISTER-ANNOTATION-TEMPLATE [function]

(sd-am-unregister-annotation-template meta-name :type type)

Description:

Removes Annotation-template of specified type from the template browser. If no template of specified type and meta-name exist, nothing happens. If template is the last one in an existing category. the category is removed as well.

Parameters:

meta-name {STRING} - The name of the Annotation-template to be removed.

:type {KEYWORD [:all]}

Can be one of the following keywords:

:sketch - used for removing template of sketches type
:symbol - used for removing template of symbols type
:text - used for removing template of texts type
:drawing - used for removing template of drawing type
:all - used for removing template of all type which includes above 3 types.

Return Value:

Undefined

Example:

     (sd-am-unregister-annotation-template "Long Datum" :type :symbol)

SD-AM-UNREGISTER-SYMBOL [function]

(sd-am-unregister-symbol meta-name)

Description:

Removes a symbol from the symbol browser. If no symbol with the specified meta-name does exist, nothing happens. If the symbol is the last one if an existing category. the category is removed as well.

Parameters:

meta-name {STRING} - The name of the symbol to be removed.

Return Value:

Undefined

Example:

     (sd-am-unregister-symbol "Long Datum")

SD-AM-UNREGISTER-SYMBOL-ALL [function]

(sd-am-unregister-symbol-all)

Description:

Removes all registered symbols from the symbol browser. Afterwards the symbol browser is empty.

Parameters:

Return Value:

Undefined

Example:

     (sd-am-unregister-symbol-all)

SD-AM-SYMBOL-P [function]

(sd-am-symbol-p element)

Description:: Predicate to determine whether or not an element is a symbol.
Parameters:: element {SEL_ITEM} - The element to inquire.
Return Value:: t - The element is a symbol.; nil - The element is not a symbol.

SD-AM-INQ-SYMBOL-PARAM-NAMES [function]

(sd-am-inq-symbol-param-names symbol)

Description:: Inquire the parameter names of a symbol.
Parameters:: symbol {SEL_ITEM} - Symbol to be inquired.
Return Value:: {LIST of STRINGs} - List containing all parameter names.

SD-AM-INQ-SYMBOL-PARAM [function]

(sd-am-inq-symbol-param symbol 
                        name)

Description:

Inquire a symbol parameter defined by its name.

Parameters:

symbol {SEL_ITEM} - Symbol containing parameter.

name {STRING} - Parameter name.

Return Value:

Property list with the following keys:

:name {STRING} - Parameter name.

:position {GPNT2D} - Parameter text position.

:value {LIST of STRINGs} - Parameter value.

SD-AM-INQ-SYMBOL-TEXT-AREA [function]

(sd-am-inq-symbol-text-area position)

Description:

Inquires the area of the text or parameter at the given position within the currently created symbol. This function enables the subsequent creation of symbol geometry which is dependent on the size of certain texts in a symbol.

Parameters:

position {GPNT2D} - The text or parameter position.

Return Value:

{key/value LIST} - A list of key/value pairs containing the requested text area data, with the keywords:

:width {LONG-FLOAT} - Text width.

:height {LONG-FLOAT} - Text height.

SD-AM-CREATE-SYMBOL-LINE [function]

(sd-am-create-symbol-line pnt-list)

Description:: Create a line or a polyline within a symbol. If pnt-list contains exactly 2 points, then a line is created, for more than 2 points a polyline is created. The line or polyline is created with the current geometry attributes.
Parameters:: pnt-list {list of GPNT2Ds} - The coordinates list. Must contain at least 2 points.
Return Value:: t - The line was created.; nil - An error occured.

SD-AM-CREATE-SYMBOL-POLYGON [function]

(sd-am-create-symbol-polygon point-list)

Description:: Creates a closed polygon within a symbol
Remark: To create a filled polygon use sd-am-create-symbol-hatch in addition.
Parameters:: point-list {list of GPNT2D's} - start and intermediate points of the polygon. Must contain at least 3 points.
Return value:: t - The polygon was created.; nil

SD-AM-CREATE-SYMBOL-ARC [function]

(sd-am-create-symbol-arc cen-pnt
                         start-pnt
                         end-pnt)

Description:: Create an arc within a symbol. The arc is defined counter-clockwise from start-pnt to end-pnt with cen-pnt is center point. The radius is implicitely defined by the distance from cen-pnt to start-pnt. The arc start angle and end angle are defined by start-pnt and end-pnt with respect to cen-pnt. The arc is created with the current geometry attributes.
Parameters:: cen-pnt {GPNT2D} - Coordinates of center point.; start-pnt {GPNT2D} - Coordinates of start point.; end-pnt {GPNT2D} - Coordinates of end point.
Return Value:: t - The arc was created.; nil - An error occured.

SD-AM-CREATE-SYMBOL-CIRCLE [function]

(sd-am-create-symbol-circle cen-pnt 
                            radius)

Description:: Create a circle within a symbol. The circle is defined by radius and center point. The circle is created with the current geometry attributes.
Parameters:: cen-pnt {GPNT2D} - Coordinates of center point.; radius {LONG-FLOAT} - Radius.
Return Value:: t - The circle was created.; nil - An error occured.

SD-AM-CREATE-SYMBOL-SELECTABLE-POINT [function]

(sd-am-create-symbol-selectable-point cen-pnt

Description:: Create a point within a symbol. This point can be used for attaching dimensions to it. The point is created with the current geometry attributes.
Parameters:: cen-pnt {GPNT2D} - Coordinates of point.
Return Value:: t - The point was created.; nil - An error occured.

SD-AM-CREATE-SYMBOL-HATCH [function]

(sd-am-create-symbol-hatch face-pnt)

Description:: Create a hatch within a symbol. The face to be hatched is defined by face-pnt, a point internal to the face, and must be bounded by a contiguous sequence of geometry elements. The hatch is created with the current symbol hatch attributes.
Parameters:: face-pnt {GPNT2D} - Coordinates of a point in the face to be hatched.
Return Value:: t - The hatch was created.; nil - An error occured.

SD-AM-CREATE-SYMBOL-TEXT [function]

(sd-am-create-symbol-text text
                          position)

Description:

Defines a symbol text at the given position. The text must be a one line.

Parameters:

text {STRING or LIST of STRINGs} - The text string.

position {GPNT2D} - The text position.

Return Value:

plist - Property list of the following format:: (:width width :height height) width and height of the text created
nil - An error occured.

SD-AM-CREATE-SYMBOL-PARAMETER [function]

(sd-am-create-symbol-parameter name
                               value
                               :position position)

Description:

Defines a symbol parameter which is displayed as a one line text at the given position. The parameter name must be unique within a symbol.

Parameters:

name {STRING} - Parameter name.

value {STRING or LIST of STRINGs} - The value; An empty string means that no value is assigned.

:position {GPNT2D} - Parameter position

Return Value:

plist - Property list of the following format:: (:width width :height height) width and height of the text created
nil - An error occured.

SD-AM-SET-SYMBOL-PARAM-VALUE [function]

(sd-am-set-symbol-param-value symbol
                              param
                              value)

Description:: Set a symbol parameter value. An existing parameter value is overwritten. The value must be a one line string.
This function can only be used for generic symbols. These symbols can not be edited with a programmatically symbol dialog.
Parameters:: symbol {SEL_ITEM} - Symbol containing the parameter.; param {STRING} - The name of the parameter to be edited.; value {STRING or LIST of STRINGs} - The new value. An empty string means that the old parameter is deleted without assigning a new value.
Return Value:: t - The parameter value has been set.; nil - An error occured.