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.
© 2024 Parametric
Technology GmbH
(a subsidiary of PTC Inc.), All Rights Reserved |