The Annotation module of Creo Elements/Direct Modeling is a two process solution.
While activation the module a special version of Creo Elements/Direct Drafting is used as a client to execute commands given by Creo Elements/Direct Modeling.
All the interactive input capabilities of this Creo Elements/Direct Drafting are cut off. It does not output error messages or warnings to it's screen, either.
This Creo Elements/Direct Drafting will be totally controlled from Creo Elements/Direct Modeling. Inside this document this Creo Elements/Direct Drafting process is called Annotator.
The following document describes an interface enabling it's users to execute commands inside the Annotator described above. They also describe how to receive data in Creo Elements/Direct Modeling from Annotator .
The interface is delivered "as is" and will be subject to change in the
future.
What the commands do is in your responsibility. Because it's easily
possible to modify a drawing in a way it cannot be updated any more by the
standard Annotation module functionality we recommend to read the documentation about what operations you should
avoid.
First of all the Annotation module must have been activated in order to
execute commands in Annotator .
Having done so a procedural interface to Annotator is established in order
to
The synergy of Creo Elements/Direct Modeling and Annotator requires extended knowledge and advanced programming skills in
So, the interface described in these documents should be used carefully
with a good understanding of what is going on in Annotator and Creo
Elements/Direct Modeling when executing commands.
Target customers of the interface are VARs, Application Engineers and
experienced Creo Elements/Direct Modeling and Annotator customers.
Since the Annotator used in this solution is "blind" it is of no use
trying to create Annotator User Interface (menus, tables, filebrowser,
etc).
The commands to do so are not cut off but will not behave as expected. Any
kind of textual output like the command line, prompt line, status line,
Annotator viewport number and much more are not visible.
All this does not make it easier to develop Annotator macro code.
Avoid these commands
We recommend to write Annotator macros inside a pure and complete Annotator enviroment. You should avoid commands related to these areas:
In fact it does not make much sense to use the areas described above at
all since there is an equivalend Creo Elements/Direct Modeling functioanlity
for each single one.
Take good care on Annotator settings
There is one group of functionality that should be taken care of especially
Changing Annotator settings does work in any way you do it but you need
to know that many settings are required to be known by Creo Elements/Direct
Modeling.
A good example are the CATCH and SHOW settings. To keep
MODELING_NAMEs as well as Annotator s settings in sync it is required to
make Creo Elements/Direct Modeling to inform Annotator about settings
changed since he always is the master in this master/slave situation.
... using tables
You can use commands related to these areas but you do need to totally control them from Creo Elements/Direct Modeling:
This exception is intended to be applicable when programming Drawing
Frames containing text fields to be filled up by a PDM system like
WorkManager.
In addition certain hardware and software exceptions are transferred to
Creo Elements/Direct Modeling.
The most important ones are
You don't have control over these kinds of events.
They can occur at any time whenever Annotator raised the exception. Since
this indicates a severe programming error Annotator will be in an undefined
state.
The error box describing the type of exception will pop up inside Creo
Elements/Direct Modeling's graphical user interface immediately.
We provide a LISP
function to send a command to Annotator .
We provide a LISP
function to send a command to Annotator and receive it's result. This
result must be a valid LISP form.
The command to be executed by Annotator must return LISP data to Creo
Elements/Direct Modeling using the macros described below.
NOTE: these Annotator functions return a value that should be
checked.
let isopen (DOCU_OPEN_CONNECTION_TO_SD)
This function establishes the connection to Creo Elements/Direct Modeling.
It has to be called before calling any of the functions below. It must not
be called twice!
let done (DOCU_ADD_LINE_TO_SD)
This function adds one line to the output stream connected to Creo
Elements/Direct Modeling.
This line must be a Annotator string token.
This function may be called after having called (DOCU_OPEN_CONNECTION_TO_SD)
only.
It may be called multiple times if required.
This function will just add the line given to the output stream buffer but
not send the line. This must be done by calling:
let isclosed (DOCU_CLOSE_CONNECTION_TO_SD)
This function closes the connection to Creo Elements/Direct Modeling and
notifies Creo Elements/Direct Modeling about it.
It must be called once after having called (DOCU_OPEN_CONNECTION_TO_SD)
only.
It must not be called twice.
Actually, this command will flush all lines sent to SD.
let lispstring (DOCU_CSTRING_TO_LSTRING 'c_string')
This function must be used to transfer string data to Creo Elements/Direct
Modeling.
It may be called as many times as required.
The programmer must take special care on sending strings to Creo
Elements/Direct Modeling. A Annotator function to transform a Annotator
string into a LISP string has been provided:
In case the programmer wants to transfer a string inside a LISP form or
another string to Creo Elements/Direct Modeling it is required to "escape"
the double quote characters.
For example:
let isopen (DOCU_OPEN_CONNECTION_TO_SD) let done (DOCU_ADD_LINE_TO_SD '42') let isclosed (DOCU_CLOSE_CONNECTION_TO_SD)
let lispstring (DOCU_CSTRING_TO_LSTRING '~42') let isopen (DOCU_OPEN_CONNECTION_TO_SD) let done (DOCU_ADD_LINE_TO_SD lispstring) let isclosed (DOCU_CLOSE_CONNECTION_TO_SD)
let formstring '(format nil' let formatstring (DOCU_CSTRING_TO_LSTRING 'The current part in Annotator is ~A') let partstring (DOCU_CSTRING_TO_LSTRING '~42') let endstring ')' let output ((formstring+(formatstring+partstring))+endstring) let isopen (DOCU_OPEN_CONNECTION_TO_SD) let done (DOCU_ADD_LINE_TO_SD output) let isclosed (DOCU_CLOSE_CONNECTION_TO_SD)
These four functions can be used to solve e.g. the following task:
Task: "Inquire the unique part id of the current Annotator part from
MODELING_NAME"
Solution 1: The straight forward approach
;; This is Creo Elements/Direct Modeling LISP code (setq Annotator -function (format nil "~A ~A ~A ~A ~A ~A" "inq_part '.'" "let pid (inq 302)" "let pid_s (DOCU_CSTRING_TO_LSTRING pid)" "let isopen (DOCU_OPEN_CONNECTION_TO_SD)" "let done (DOCU_ADD_LINE_TO_SD pid_s)" "let isclosed (DOCU_CLOSE_CONNECTION_TO_SD)" ) ;; end format ) ;; end setq (setq current-part (sd-execute-annotator-function :fnc Annotator -function))
will do the job.
Solution 2: As described here it is recommended to
write a Annotator macro file and to call it:
{ This is Annotator macro code } DEFINE Am_send_unique_part_id inq_part '.' let pid (inq 302) let pid_s (DOCU_CSTRING_TO_LSTRING pid) (DOCU_OPEN_CONNECTION_TO_SD) (DOCU_ADD_LINE_TO_SD pid_s) (DOCU_CLOSE_CONNECTION_TO_SD) END_DEFINE
After having loaded this macro into Annotator it can be called this way:
;; This is Creo Elements/Direct Modeling LISP code (setq current-part (sd-execute-annotator-function :fnc "Am_send_unique_part_id")
Developing Annotator macros becomes more difficult then in Annotator
because there is no way to view the macro inside Annotator .
So, it's probably a good idea to use a real Annotator if available to
develop the macro itself.
In this case the macros introduced to send LISP-data to Creo Elements/Direct
Modeling cannot be used.
The macro must be loaded into the Annotator running as Annotation
module.
You load the macro by adding an "INPUT" statement to Annotator 's startup
file.
For prototyping it's probably more convenient to simply execute the "INPUT"
command from within Creo Elements/Direct Modeling:
;; this is Creo Elements/Direct Modeling LISP code (sd-execute-annotator-command :cmd "INPUT 'yourfile.mac'")
Having loaded the macro you can call it by it's name:
;; this is Creo Elements/Direct Modeling LISP code (sd-execute-annotator-command :cmd "Am_your_macro")
In case your macro is supposed to return data to Creo Elements/Direct Modeling you need to call it using (sd-execute-annotator-function)
;; this is Creo Elements/Direct Modeling LISP code (sd-execute-annotator-function :fnc "Am_your_macro")
If your macro did not return what you expected it to return you can have
a look on the data send by Annotator most recently:
;; this is Creo Elements/Direct Modeling LISP code (symbol-function 'docu::eval-result)
It's important to know that this statement must be executed right after
having called your macro. Otherwise this information has potentially been
overwritten by an other call to Annotator .
This is an example for what you could get.
(LISP::LAMBDA-BLOCK DOCU::EVAL-RESULT () (LISP::LIST :DOCU-DRAWING "SD_drawing" "~1" "" (LISP::LIST (LISP::LIST :DOCU-SHEET "1" "~2" "" (LISP::LIST (LISP::LIST :DOCU-FRAME ".tb_frame_A1" "~3" "" (LISP::LIST)))))))
This is identical to this LISP list:
'(:DOCU-DRAWING "SD_drawing" "~1" "" ((:DOCU-SHEET "1" "~2" "" ((:DOCU-FRAME ".tb_frame_A1" "~3" "" LISP::NIL)))))
There are a couple of limitations applicable.
(sd-get-max-cmd-length)
(sd-get-max-fnc-length)
(sd-get-max-return-data-size)
It cannot be changed.
In case you need to transfer more data write a file to the filesystem
and return the command to load the file to Creo Elements/Direct
Modeling.
This might change in the future.
Limitations 1. and 2. are not really new limitations since Annotator itself cannot handle input lines longer then 1024 Byte. In addition it is always possible to simply send two shorter commands to Annotator instead of one long command.
Almost no user will ever find limitation 3. applicable.
Limitation 4. is an important one and must not be violated.
Please note that none of these limitations will be checked.
It is your responsibility to follow the rules.
© 2024 Parametric
Technology GmbH (a subsidiary of PTC Inc.), All Rights Reserved |