Creo Elements/Direct Modeling / Creo Elements/Direct Drafting Communication: Functions

This document is about what functions are to be used to execute commands in Annotator (special version of Creo Elements/Direct Drafting) as well as to receive data from Annotator in Creo Elements/Direct Modeling.

• Executing a Creo Elements/Direct Drafting command
  • What Creo Elements/Direct Drafting commands can be executed ?
• Executing a Creo Elements/Direct Drafting command and receiving it's result
  • What are valid Creo Elements/Direct Drafting commands returning data ?
• Inquiring the position of an object selected
• Inquiring the id of an object selected
• Handling of errors reported from Creo Elements/Direct Drafting

SD-EXECUTE-ANNOTATOR-COMMAND  [function]

(sd-execute-annotator-command :cmd "Command")

Description:

This function executes a command inside the Creo Elements/Direct Drafting. The function terminates as soon as the Creo Elements/Direct Drafting finished the execution of the command.

Parameters:

cmd {STRING} - String containing the statement to be executed by the Creo Elements/Direct Drafting It must be a valid Creo Elements/Direct Drafting command

Return Value:

no return value - always

SD-EXECUTE-ANNOTATOR-FUNCTION  [function]

(sd-execute-annotator-function :fnc "Function")

Description:

sd-execute-annotator-function executes a function inside the Creo Elements/Direct Drafting. It terminates as soon as the Creo Elements/Direct Drafting finished the execution of the command and returns a LISP form. This LISP form has been sent from the Creo Elements/Direct Drafting to Creo Elements/Direct Modeling.

It is important to know that the command called must return a LISP form to Creo Elements/Direct Modeling. This can be done using the Creo Elements/Direct Drafting macros described below.

Parameters:

fnc {STRING} - String containing the statement to be executed by the Creo Elements/Direct Drafting It must be a valid Creo Elements/Direct Drafting function

Return Value:

any LISP form - always

SD-GET-ANNOTATOR-POSITION  [function]

(sd-get-annotator-position :object object-selected)

Description:

sd-get-annotator-position returns a string containing the x and y coordinates of the Creo Elements/Direct Drafting object selected. x and y are separated by a ','.

Parameters:

object {SEL_ITEM} - Creo Elements/Direct Drafting object selected It must have been inquired as described here

Return Value:

a string containing x and y coordinate of the object selected
e.g. "23.322444342,12.32435245" or
nil in case the object is not an Creo Elements/Direct Drafting object.

SD-GET-ANNOTATOR-REFERENCE  [function]

(sd-get-annotator-reference :object object-selected)

Description:

sd-get-annotator-reference returns a number representing the id of the Creo Elements/Direct Drafting object selected. This id can be used by the Creo Elements/Direct Drafting command SELECT with keyword POINTER

Parameters:

object {SEL_ITEM} - Creo Elements/Direct Drafting object selected It must have been inquired as described here

Return Value:

a number being the id of the object selected
e.g. 23421232 or
nil in case the object is not an Creo Elements/Direct Drafting object.

Note

When executing a valid Annotator command / function it is important to keep the concept of drawing / sheet structure and the current part the Annotator (Creo Elements/Direct Drafting) is using. To avoid subsequent problems follow the recommendation below.

Definition: Valid Creo Elements/Direct Drafting command

A valid Creo Elements/Direct Drafting command is any Creo Elements/Direct Drafting command or macro fulfilling the requirements listed below:

• It must not be longer then (sd-get-max-cmd-length)
• If the command contains the Creo Elements/Direct Drafting token "DEFINE" it must contain the "END_DEFINE" token as well.
  Otherwise Creo Elements/Direct Modeling will go to an endless loop.
  The overall recommendation is to avoid defining macros at run-time but - whenever possible - to write a Creo Elements/Direct Drafting macro file to be read by Creo Elements/Direct Drafting at startup time.

It is important to know that Creo Elements/Direct Drafting commands awaiting input from the user have to get this input from Creo Elements/Direct Modeling. This is true for all kinds of input.
Example: if you send a command awaiting a mouse pick it is not sufficient to pick into the viewport. Creo Elements/Direct Modeling has to send the pick to Creo Elements/Direct Drafting using sd-execute-annotator-command():

   (sd-execute-annotator-command :cmd "12.345678,98.765432")

How to receive a coordinate in Creo Elements/Direct Modeling Dialogs can be found here.

Definition: Valid Creo Elements/Direct Drafting function

A valid Creo Elements/Direct Drafting function is any Creo Elements/Direct Drafting Command or Macro fulfilling the requirements listed below:

• It must not be longer then (sd-get-max-fnc-length)
• It must fulfill all requirements for a valid Creo Elements/Direct Drafting command
• It must return a valid LISP form to Creo Elements/Direct Modeling. Otherwise you might experience strange behavior of Creo Elements/Direct Modeling later
  How to return a LISP form to Creo Elements/Direct Modeling...

Recommendations when executing annotator commands / functions

Avoid leaving the wrong active part by restoring the last state after the customized action is finished.

• Integration Kit, e.g. using sd-defialog
  use the following commands to inquire the current sheet
  (sd-am-inq-curr-sheet)
  or
  (sd-am-inq-curr-sheet-name)
  and when finished make sure you switch back to the original status, by adding
  :cleanup-action (sd-call-cmds (AM_CURRENT_SHEET xxx))
• Creo Elements/Direct Drafting Macro Level
  Avoid using "EDIT_PART TOP" or "EDIT_PART '/' " AND staying at "TOP" or "/" when ending the macro / add-on. At start, always inquire the current part inside your macro AND at the end set the current part back to the former current part.

SD-AM-ERRORS  [function]

(sd-am-errors option)

Description:

Handling of errors reported from Creo Elements/Direct Drafting

Parameters:

option {KEYWORD} - specifies the return value or action

:get_all (default) - returns a list of first and last errors
:get_first - ask for first reported error
:get_last - ask for last reported error
:clear - resets the errors to "NOERROR"

Return Value:

depending on the option KEYWORD

:get returns errors {PROPERTY LIST} (:first .... :last ...) or nil
:get_first returns error {STRING} or nil
:get_last returns error {STRING} or nil
:clear returns T

Example:

(sd-am-errors :get_last)