3D Documentation - User defined Symbols

Creation Dialog

sd-doc3d-create-symbol-dialog

Creation of symbol elements (3D Documentation & Annotation)

sd-create-symbol-text
sd-create-symbol-parameter
sd-create-symbol-line
sd-create-symbol-polygon
sd-create-symbol-arc
sd-create-symbol-circle

Functions to be used within the symbol definition code (3D Documentation & Annotation)

sd-current-symbol-3d-documentation-p
sd-current-symbol-annotation-p
sd-set-symbol-reference-point
sd-set-symbol-settings

Template Browser (3D Documentation & Annotation)

sd-register-template
sd-unregister-template

SD-DOC3D-CREATE-SYMBOL-DIALOG  [macro]

(sd-doc3d-create-symbol-dialog :name dialog-name
                               :title dialog-title 
                               :variables dialog-variables-code
                               :position-prompt position-prompt
                               :local-functions local-functions-code
                               :draw-symbol-command draw-symbol-command-code
                               :save-variables save-variables-list
                               :mutual-exclusion mutual-exclusion-list
                               :help-action help-action
                               :reference-selection-3d reference-selection-3d-list
                               :symbol-type symbol-type
                               :install-function install-function-code)

Description:

Creates a dialog that allows the user to interactively create a symbol, enter the parameter values and place the new symbol on the model. For general information on dialogs see the Dialog Generator Manual.

The parameters listed in the following section define the symbol specific part of the dialog.

Other parameters necessary to create a symbol (like reference element, docuplane, orientation ...) are added automatically.

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.

:position-prompt {STRING}

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

: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 and texts. :draw-symbol-command may contain any number of the functions described within this page. 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.

:reference-selection-3d {LIST of focus-type}

reference-selection-3d specifies what kinds of items are allowed to be selected as reference element. The default corresponds to the focus-types allowed for the creation of a generic text. These are edges (2D and 3D), faces, parts, assemblies and workplanes).

:symbol-type {One of :surface, :welding or :general}

symbol-type defines the set of settings (like color, ...) used for the newly created symbol

:install-function {LISP-form}

If you want to use the symbol in 3D Documentation AND in Annotation you can specify all the parameters above in a separate install-function. This install-function can then be accessed via sd-doc3d-create-symbol-dialog and sd-am-create-symbol-dialog. See examples.

Return value:

nil

Example:

(in-package :my-package)
(use-package :oli)

(defun get-simple-symbol-smiley(key)
  (case key
    (:name "SMILEY")
    (:title "Smiley")
    (:mutual-exclusion '(MOOD_SMILE MOOD_WEEP))
    (:reference-selection-3d '(*sd-face-seltype* *sd-edge-3d-seltype*))
    (:position-prompt "Specify position for smiley")
    (:symbol-type :general)
    (:variables
     '(
        (SIZE :value-type :positive-number
              :initial-value (get-default-size)
              :title "Size"
        )
        (EYES_OPEN :value-type :boolean
                   :initial-value t
                   :title "Eyes open"
        )
        (NAME :value-type :string
              :title "Name"
              :initial-optional t
        )
        (MOOD_SMILE :value-type :boolean
                    :toggle-type :grouped-toggle
                    :title "Smile"
                    :initial-value t
        )
        (MOOD_WEEP :value-type :boolean
                    :toggle-type :grouped-toggle
                    :title "Weep"
                    :initial-value nil
        )
      ) ;; end variables
    )
    (:local-functions '( 
                         (get-default-size () 
                           40
                         )
                       )
    )
    (:draw-symbol-command
     '(progn

        (sd-create-symbol-circle 0,0 (/ size 2))
        ;; Nose
        (sd-create-symbol-line (make-gpnt2d :x (* size (/ 1 8)) :y (/ size -8))
                               (make-gpnt2d :x 0 :y (* size (/ 1 6))) )
        (sd-create-symbol-line (make-gpnt2d :x 0 :y (* size (/ 1 6)) )
                               (make-gpnt2d :x (* size (/ -1 8)) :y (/ size -8)))
        (sd-create-symbol-line (make-gpnt2d :x (* size (/ -1 8)) :y (/ size -8))
                               (make-gpnt2d :x (* size (/ 1 8)) :y (/ size -8)) )

 
        (if MOOD_WEEP
          (sd-set-symbol-settings :geo-color 16711680 :geo-linetype :phantom)
          (sd-set-symbol-settings :geo-color 65535 :geo-linetype :solid)
        )
        (if EYES_OPEN
          (progn
            (sd-create-symbol-circle (make-gpnt2d :x (* size (/ 1 4)) :y (* size (/ 1 6)))
                                          (if MOOD_SMILE
                                            (/ size 6)
                                            (/ size 10)))
            (sd-create-symbol-circle (make-gpnt2d :x (* size (/ -1 4)) :y (* size (/ 1 6)))
                                          (if MOOD_SMILE
                                            (/ size 6)
                                            (/ size 10)))
          )
          (progn
            (sd-create-symbol-line (make-gpnt2d :x (* size (/ 1 8)) :y (* size (/ 1 6)))
                                   (make-gpnt2d :x (* size (/ 1 4)) :y (* size (/ 1 6))) )
            (sd-create-symbol-line (make-gpnt2d :x (* size (/ -1 8)) :y (* size (/ 1 6)))
                                   (make-gpnt2d :x (* size (/ -1 4)) :y (* size (/ 1 6))) )
          )
        )


        (if MOOD_SMILE
          (sd-create-symbol-arc 0,0 (make-gpnt2d :x (/ (* size -3) 8) :y (/ (* size -1) 8))
                                    (make-gpnt2d :x (/ (* size 3) 8) :y (/ (* size -1) 8)))
          ;; else
          (sd-create-symbol-arc (make-gpnt2d :x 0 :y (/ size -1.5))
                                (make-gpnt2d :x (/ size 4) :y (/ size -3))
                                (make-gpnt2d :x (/ size -4) :y (/ size -3)))
        )

        (when NAME
          (sd-set-symbol-settings :text-adjust 8 :text-color 1234567 :text-size 2.5)
          (sd-create-symbol-parameter "Name" NAME :position (make-gpnt2d :x 0 
                                                                                   :y (- (/ size -2) (/ size 10))))
        )
        (sd-set-symbol-reference-point 0,0)
      ) ;; end draw-command
    )
    (:save-variables '(SIZE NAME EYES_OPEN MOOD_SMILE MOOD_WEEP))
    (t
      NIL
    )
  )
)

(when (sd-license-free-module-active-p "3DDOCU")
  (sd-doc3d-create-symbol-dialog
   :install-function  get-simple-symbol-smiley)
  (sd-register-template :name "Smiley" 
                        :action "DOC3D_CREATE_SYMBOL_SMILEY"
                        :application "3D Documentation"
                        :type :symbol
                        :path "User Defined"
                        :image-file NIL)
)

(when (sd-module-active-p "ANNOTATION")
  (sd-am-create-symbol-dialog
   :install-function  get-simple-symbol-smiley)
  (sd-register-template :name "Smiley" 
                        :action "AM_CREATE_SYMBOL_SMILEY"
                        :application "Annotation"
                        :type :symbol
                        :path "User Defined"
                        :image-file NIL)
)

SD-CREATE-SYMBOL-TEXT  [function]

(sd-create-symbol-text text position)

Description:

Creates a text within the current symbol. When the symbol gets modified later, this text cannot be modified.

Parameters:

text {STRING} - The text to be displayed within the symbol.

position {GPNT2D} - The position within the symbol

Return value:

nil

Example:

(sd-create-symbol-text "text" 10,20)

SD-CREATE-SYMBOL-PARAMETER  [function]

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

Description:

Creates a text within the current symbol. When the symbol gets modified later, this text can be modified.

Parameters:

name {STRING} - The name of the option within the dialog

value {STRING} - The value that corresponds to the name. This value is displayed within the symbol.

position {GPNT2D} - The position within the symbol

Return value:

nil

Example:

(sd-create-symbol-parameter "Name" "Tom" :position 0,20)

SD-CREATE-SYMBOL-LINE  [function]

(sd-create-symbol-line start-point end-point)

Description:

Creates a line within the current symbol

Parameters:

start-point {GPNT2D} - start point of the line

end-point {GPNT2D} - end point of the line

Return value:

nil

Example:

(sd-create-symbol-line 0,0 30,10)

SD-CREATE-SYMBOL-POLYGON  [function]

(sd-create-symbol-polygon point-list :filled filled)

Description:

Creates a closed polygon within the current symbol

Parameters:

point-list {LIST OF GPNT2D's} - start and intermediate points of the polygon
Please note, that the function automatically adds the first point of the list to the end of the list again. That means that the created polygon is always closed.

filled {BOOLEAN} (3D Documentation only) - Specifies whether the polygon is filled.
Remark: For Annotation use sd-current-symbol-annotation-p and sd-am-create-symbol-hatch in addition.

Return value:

nil - An error occurred.

Example:

(sd-create-symbol-polygon (list 0,0 0,10 10,10))
(sd-create-symbol-polygon (list 0,0 0,10 10,10 10,0))
(sd-create-symbol-polygon (list 0,0 0,10 10,10 10,0) :filled t)

SD-CREATE-SYMBOL-ARC  [function]

(sd-create-symbol-arc center-point start-point end-point)

Description:

Creates an arc within the current symbol

Parameters:

center-point {GPNT2D} - Center point of the arc

start-point {GPNT2D} - Start point of the arc

end-point {GPNT2D} - End point of the arc

Return value:

nil

Example:

(sd-create-symbol-arc 30,0 90,0 -30,0)

SD-CREATE-SYMBOL-CIRCLE  [function]

(sd-create-symbol-circle center-point radius)

Description:

Creates a circle within the current symbol.

Parameters:

center-point {GPNT2D} - Center point of the circle

radius {NUMBER} - Radius of the circle

Return value:

nil - An error occurred.

Example:

(sd-create-symbol-circle 25,25 25)

SD-CURRENT-SYMBOL-3D-DOCUMENTATION-P  [function]

(sd-current-symbol-3d-documentation-p)

Description:

This function inquires if the current symbol is created for 3D documentation

It is important when you define a symbol that should be usable in 3D Documentation and Annotation, whereby some code is specific to those applications.

No Parameters

Return value:

T - If the current symbol is created for 3D Documentation

nil - If the current symbol is created for Annotation

Example:

(sd-current-symbol-3d-documentation-p)
         ==> T

SD-CURRENT-SYMBOL-ANNOTATION-P  [function]

(sd-current-symbol-annotation-p)

Description:

This function inquires if the current symbol is created for Annotation.

It is important when you define a symbol that should be usable in 3D Documentation and Annotation, whereby some code is specific to those applications.

No Parameters

Return value:

T - If the current symbol is created for Annotation

nil - If the current symbol is created for 3D Documentation

Example:

(sd-current-symbol-annotation-p)
        ==> T

SD-SET-SYMBOL-REFERENCE-POINT  [function]

(sd-set-symbol-reference-point ref-point)

Description:

Sets the reference point of the current symbol to the fixed position specified in the ref-point parameter.

If this function is used the resulting symbol dialog does NOT have the options to switch between spider and stub.

Parameters:

ref-point {GPNT2D} - A point that will be used as symbol reference point

Return value:

nil

Example:

(sd-set-symbol-reference-point -2,4)

SD-SET-SYMBOL-SETTINGS  [function]

(sd-set-symbol-settings :text-size text-size
                        :text-adjust text-adjust
                        :text-font1b text-font
                        :text-color text-color
                        :text-line-spacing text-line-spacing
                        :text-abs-angle text-abs-angle
                        :text-slant text-slant
                        :text-ratio text-ratio
                        :text-frame text-frame
                        :geo-color geo-color
                        :geo-linetype geo-linetype)

Description:

Defines the settings used for subsequent calls of functions creating text or geometry within the current symbol.

Parameters:

:text-size {NUMBER [mm]} - Used as default text size for texts created in the current symbol

:text-adjust {NUMBER} - The text adjust number (between 1 (lower left) and nine (upper right)) specifying the adjust point.

:text-font1b {STRING} - The name of the font used for texts created in the current symbol

:text-color {NUMBER} - The color used for texts created in the current symbol

:text-line-spacing {NUMBER} - The line spacing used for multi-line texts created in the current symbol

:text-abs-angle {ANGLE [rad]} - The indidivual text angle (Annotation only)

:text-slant {ANGLE [rad]} - The slant of a text, used for 'italic' characters (Annotation only)

:text-ratio {NUMBER} - Width to height ratio of text (Annotation only)

:text-frame {STRING} The indidivual text frame type. One of "OFF" "BALLOON" "BOX" "FLAG" (Annotation only)

:geo-color {NUMBER} - The color used for geometry created in the current symbol

:geo-linetype {KEYWORD} - One of :solid, :dashed, :long_dashed, :dot_center, :dash_center, :center_dash_dash, :phantom, :dotted

Return value:

nil

Example:

(sd-set-symbol-settings :text-size 5.0
                        :text-adjust 7
                        :text-font1b "hp_block_v"
                        :text-color 65535
                        :text-line-spacing 3.2
                        :geo-color 16711680
                        :geo-linetype :phantom)

SD-REGISTER-TEMPLATE  [function]

(sd-register-template :name name
                      :action action
                      :application application
                      :type type
                      :path path
                      :image-file image-file)

Description:

Registers a new entry to the template browser.

This function can be used to fill the template browser of 3D Documentation or the template browser of Annotation.

Parameters:

:name name {STRING} - defines the title of the entry in the template browser

:action action {STRING} - The command (and its parameter) to be executed

:application application {STRING} - Either "3D Documentation" or "Annotation"

:type type {KEYWORD} - For 3D Documentation: Only :symbol is allowed;

For Annotation: One of :symbol, :text, :sketch

:path path {STRING} - Parent entry in the template browser (string may contain '/')

:image-file image-file {STRING} - Picture shown in the template browser

Return value:

• In case of success:
  1. Property list with :name, :action, :application, :path-name :lsp-file, :image-file, :source
  2. Number of registered templates
• In case of an error
  1. NIL
  2. One of :missing-name, :missing-action, :invalid-application-given, :wrong-template-type

Note

Use this function with a multiple-value-setq construct to inquire all return values

Example:

(sd-register-template :name "Smiley"
                      :action "DOC3D_CREATE_SYMBOL_SMILEY"
                      :application "3D Documentation"
                      :type :symbol
                      :path "User Defined"
                      :image-file NIL)

SD-UNREGISTER-TEMPLATE  [function]

(sd-unregister-template :name name
                        :application application
                        :path path)

Description:

Removes an entry from the template browser.

This function can be used to fill the template browser of 3D Documentation or the template browser of Annotation.

Parameters:

:name name {STRING} - defines the title of the entry in the template browser

:application application {STRING} - Either "3D Documentation" or "Annotation"

:path path {STRING} - Parent entry in the template browser (string may contain '/')

Return value:

T - In case of success.

nil - In case of an error.

Example:

(sd-unregister-template :name "Smiley"
                        :application "3D Documentation"
                        :path "User Defined")