int cvxCmdAction ( evxCmdAction type, /* I: action type */ svxCmdActionParam* param /* I: callback function (NULL to remove the callback) */ ) /* DESCRIPTION: Set a callback function. When processing the target command option, the callback function will be called. If this function called many times with the same 'type', only the last will take effect. If param or param->pfn is NULL, the original callback function, if there exists, will be removed. If type is VX_CMD_START, param->pfn should return 0 if the specified command can be started, else return 1. RETURN: 1 if error, else 0. WARNING: If one call this function to register a callback in a dll module, he must call this function again, with argument param set as NULL, to unregister the callback for each action before the dll module exit. Usually we can do this in the exit function of the dll module. */ ________________________________________________________________________________ void cvxCmdBuffer ( const char *String, /* I: command string */ int Priority /* I: priority of execution (0 or 1) */ ) /* DESCRIPTION: Buffers the input command string for execution after the current command and any previously-buffered command events are finished executing. If "Priority" is input as 1, the input command string is given higher priority for execution than command strings buffered with "Priority = 0". For example, if you register a pointer to a "void MyFunction(void)" callback function using cvxCmdFunc(), you can cause the function to be invoked after pending commands have executed using cvxCmdBuffer("~MyFunction"). */ ________________________________________________________________________________ void cvxCmdCallback ( const vxName Name, /* I: function name */ void *Function /* I: function pointer */ ) /* DESCRIPTION: Registers a pointer to an auxiliary callback function used by a command template. The function does not require a licensing code. The "init=", "exit=", "echo_obj=" and "callback=" fields reference auxiliary callback functions. Function pointers should be registered in the "Init" function called when your library is dynamically loaded by ZW3D at runtime. The callback function should be of the following type: int Callback(char *TemplateName, int idField, int idData) The echo_obj function should be of the following type: void Echo(int idData, void *ptr) If developer wants to unload the DLL plug in file dynamically. It is a MUST to run cvxCmdFuncUnload() in the exit function. */ ________________________________________________________________________________ int cvxCmdChkLic ( const vxName Name /* I: Command name */ ) /* DESCRIPTION: Returns 0 if the specified command has a valid license, 1 if it does not. */ ________________________________________________________________________________ int cvxCmdEval ( vxName Name, /* I: name of evaluation function */ int idData /* I: id of command data container */ ) /* DESCRIPTION: Passes "idData" to the evaluation function identified by "Name". It is assumed the function has been registered with ZW3D (see cvxCmdFunc()). The function should be of type "int function(int idData, int *idOutput)". Undo-redo transaction logging is managed by this command. Use cvxDataInit() and cvxDataSet() to set up "idData". Unlike cvxCmdExec(), "idData" is not deleted by this function. The calling procedure is responsible for cleaning up "idData" using cvxDataFree(). When an echo has been initiated with cvxEchoStart, this function will call the echo_obj function associated with idData and add the objects to the echo instead of adding them to the database. When in echo mode (cvxEchoStart called) Return 0 : Success 1 : Internal error 2 : There is no active command 3 : The active command does not have an echo_obj function 4 : There is no echo object associated with the active command 5 : The template associated with "idData" could not be found in Forms.Z3 6 : The template associated with "idData" does not have an echo_obj function 7 : The echo_obj function associated with "idData" was not registered When in regular mode: Returns 1 if function fails; 0 if it succeeds. */ ________________________________________________________________________________ int cvxCmdExec ( int idData /* I: id of command data container */ ) /* DESCRIPTION: Executes the command defined by "idData". Use cvxDataInit() and cvxDataSet() to set up "idData". "idData" is always deleted by this function, even if it fails. When an echo has been initiated with cvxEchoStart, this function will call the echo_obj function associated with the command and add the objects to the echo instead of adding them to the database. Automatic creation of feature-sets is disabled while this function is executing. When in echo mode (cvxEchoStart called) Return 0 : Success 1 : Internal error 2 : There is no active command 3 : The active command does not have an echo_obj function 4 : There is no echo object associated with the active command 5 : The template associated with "idData" could not be found in Forms.Z3 6 : The template associated with "idData" does not have an echo_obj function 7 : The echo_obj function associated with "idData" was not registered When in regular mode: Returns 1 if function fails; 0 if it succeeds. */ ________________________________________________________________________________ int cvxCmdExec2 ( int idData /* I: id of command data container */ ) /* DESCRIPTION: Same as cvxCmdExec, except that the VDATA object was not deleted when the command outputs its input. When in regular mode: Returns 1 if function fails; 0 if it succeeds. */ ________________________________________________________________________________ int cvxCmdExecWithOut ( int idData, /* I: id of command data container */ int *idOut /* O: id of output data object (NULL to ignore) */ ) /* DESCRIPTION: Same as cvxCmdExec2, except that the function output the index of output data object. When in regular mode: Return 1 if function fails; 0 if it succeeds. */ ________________________________________________________________________________ int cvxCmdFunc ( const vxName Name, /* I: function name */ void *Function, /* I: function pointer */ double Code /* I: ZW3D licensing code (e.g. VX_ADV_MODELING) or 0.0 */ ) /* DESCRIPTION: Registers a function referenced by the "function=" or "custom=" fields in a command template definition. The function is registered with a ZW3D licensing code. ZW3D ensures the user has the appropriate license before allowing access to the function. Callback functions should be registered in the "Init" function called when your library is dynamically loaded by ZW3D at runtime. For a standard command operation, the function should be the following type: int StandardCommand(int idInputData, int *idOutputData) For a custom command operation, the function should be the following type: int CustomOperation(int idInputData) For a callback function invoked by a command string that is the function name preceded by a "tilda" (e.g. ~MyFunction), the function should be one of the following types: void MyFunction(void) or... void MyFunction(char *string) invoked by sending the string "~MyFunction("text string")" using cvxCmdSend() or cvxCmdBuffer(). The API functions beginning with cvxData...() are used to compose and to query the data containers referenced by "idInputData" or "idOutputData". For documentation on the the callback function registered in the header of a GUI template, see cvxFormFunc(). If developer wants to unload the DLL plug in file dynamically. It is a MUST to run cvxCmdFuncUnload() in the exit function. Returns 0 if the input function was successfully registered. Returns 1 if a symbol with the same name as the input function already exists. In this case, the pre-existing symbol is kept and the input function is ignored. */ ________________________________________________________________________________ int cvxCmdFuncUnload ( const vxName Name /* I: function name */ ) /* DESCRIPTION: Unload specified function registered via cvxCmdFunc()/cvxCmdCallback()/ cvxFormFunc()/cvxFormCallback() if developer wants to unload the DLL plug in file dynamically. The input name must be the same as the one used in cvxCmdFunc()/cvxCmdCallback()/cvxFormFunc()/cvxFormCallback(). */ ________________________________________________________________________________ int cvxCmdInput ( const vxName Name, /* I: command template name */ int idDataIn, /* I: optional data container id (0 if undefined) */ int *idDataOut /* O: output data container id (0 if undefined) */ ) /* DESCRIPTION: Uses the specified template to gather input data. Waits in this function until the data has been collected. Then outputs the id of the collected data via "idxDataOut". Assigns the input data to a new data object if "idDataIn < 1". Otherwise, uses new input data to modify the data object defined by "idDataIn". It is assumed that "idDataIn" was created by cvxDataInit(). If "idDataOut" is output as 0, "idDataIn" is automatically deleted. This means the user tried to execute another command while this function was waiting for input. Returns 1 if function fails to collect input data; 0 if it succeeds. */ ________________________________________________________________________________ void cvxCmdInqActive ( vxName Name /* O: name of active command input form */ ) /* DESCRIPTION: Outputs the name of the active command input form. */ ________________________________________________________________________________ int cvxCmdInteract ( vxName Name /* I: command template name */ ) /* DESCRIPTION: Executes the specified command in interactive input mode (i.e. those commands that would preceded by an exclamation mark when executed from the command line). The user is prompted for the command's inputs, then the command is executed. Returns 1 if user pressed Escape or Cancel or if some other error occurred. Otherwise, returns 0. */ ________________________________________________________________________________ int cvxCmdMacro ( char *Input, /* i: null-terminated ascii string of macro commands */ char **Output /* o: pointer to of output data string (NULL to ignore) */ ) /* DESCRIPTION: "Input" is interpreted as a string of one or more newline-delimted macro command strings -- without the macro/endmacro keywords. A new macro is started, the encoded macro commands are executed and the macro is terminated. The contents of variables created by the macro commands are output via "Output" as a single comma-delimited, null-terminated ascii string. The first item in the string is the total number of variables encoded in the string. This is followed by an encoding of each variable. Each variable is encoded with its name first, followed by the number of array elements in the variable, followed by the array values. Values are either ascii-encoded floating point numbers, or strings enclosed in double quotemarks. The following is an example: # variables Num = 25 Strings = {"hello dolly", "hello world"} Array = {100,125,150} # ascii-encoded variable data 3,Num,1,25,Strings,2,"hello dolly","hello world",Array,3,100,125,150 Memory for "Output" is allocated by this function. The memory must be deallocated by the calling procedure. If there is no output data, a NULL pointer is output. If this function errors out anywhere along the way, the string "ERROR" will be output via "Output" and this function will return 1. Otherwise, it will return 0. */ ________________________________________________________________________________ int cvxCmdMacro2 ( char *path /* i: macro file path */ ) /* DESCRIPTION: Runs a macro of specified path. Returns 1 if function fails; 0 if it succeeds. */ ________________________________________________________________________________ void cvxCmdMarker ( vxName Okay, /* I: undo to this marker on "Okay" (or input NULL) */ vxName Cancel /* I: undo to this marker on "Cancel" (or input NULL) */ ) /* DESCRIPTION: Log undo-redo markers for the active template-driven command. If "Okay" defines a valid marker, ZW3D will automatically undo to the marker when input for the active command is accepted by the user. This undo will happen BEFORE the evaluation function associated with the command is executed. If the user cancels the active command while input is being gathered, ZW3D will automatically undo to the "Cancel" marker, if it is defined. Input a blank string or NULL if a marker is not defined for either the "Okay" or "Cancel" case. Undo-redo markers (see cvxUndoRedoMarker()) may be used with this function to manage automatic deletion of entities created during the user input gathering phase of a template-based command. */ ________________________________________________________________________________ int cvxCmdRegisterRcc ( vxName File /* I: file name */ ) /* DESCRIPTION: Register a Qt resource file(rcc file).The rcc file contains the resources used in dll.If developer wants to unregister the rcc file in file dynamically. It is a MUST to run cvxCmdUnRegisterRcc() in the exit function. */ ________________________________________________________________________________ void cvxCmdSend ( char *CommandString /* I: null-terminated ascii command string */ ) /* DESCRIPTION: Executes the input command string. If "String = NULL", the event queue is polled for buffered command strings, which are allowed to execute in the order they were buffered. When this function is called, any current thread of execution is suspended until pending command strings are processed, after which this function returns control to the calling procedure. */ ________________________________________________________________________________ int cvxCmdStateGet ( vxName CmdName, /*I: command name*/ evxCmdState *State /*O: state of the command*/ ) /* DESCRIPTION: Get the state of the command. */ ________________________________________________________________________________ int cvxCmdStateSet ( vxName CmdName, /*I: command name*/ evxCmdState State /*I: state of the command*/ ) /* DESCRIPTION: Set the state of the command. */ ________________________________________________________________________________ int cvxCmdTemplate ( vxPath File /* I: file that contains command template(s) */ ) /* DESCRIPTION: Loads, compiles and registers the command template(s) defined in the specified file. If "File" does not define a full path to the template file, ZW3D searches for the file in the runtime directory, the directories defined in "vxpaths", and the installation directories. When ZW3D session management is enabled, dynamically-loaded templates are deleted when a session is cleared. So that ZW3D can automatically reload the templates on-demand, register the directory that contains your template files using cvxPathAdd(). Each template file should have the same name (minus the .t extension) as the command defined inside of it. For example, if "TEMPLATE=MyCommand", the container file should be named "MyCommand.t". A command template defines the input data required by a command and the name of the function the data is passed to for command execution. The template also has information that tells the ZW3D Input Manager how to interactively prompt the user for the inputs required by the command. These input fields may have callback functions associated with them. All functions and variables referenced by a command template must be registered with cvxCmdFunc(), cvxCmdCallback() or cvxCmdVariable(). See the "Virtual Forms" online help topic for more information about the definition of command templates. When a command template is used to define an "Options" form (i.e. opt_form), fields of the "opt_form" may be managed using some cvxFieldXXX() and cvxItemXXX() functions. This is done by inputting "OptForm" for the "Form" argument of the form management functions. Another way to dynamically define a template is to write it to a file in the ZW3D "temp" directory (see cvxPathTemp()) and then use this function to load/compile it. When a session is cleared, ZW3D reloads command templates from the "temp" directory on-demand -- as long as the template file name is the command name defined inside the file by "TEMPLATE=...". Template files in the "temp" directory are automatically deleted when ZW3D exits. If developer wants to unload the DLL plug in file dynamically. It is a MUST to run cvxCmdTemplateUnload() in the exit function. Returns 1 if function fails; 0 if it succeeds. */ ________________________________________________________________________________ int cvxCmdTemplateUnload ( vxPath File /* I: file that contains command template(s) */ ) /* DESCRIPTION: Unload the command template(s) defined in the specified file and registered via cvxCmdTemplate() or cvxFormTemplate() if developer wants to unload the DLL plug in file dynamically. The input file path must be the same as the one used in cvxCmdTemplate(). */ ________________________________________________________________________________ int cvxCmdUnRegisterRcc ( vxName File /* I: file name */ ) /* Unregister the Qt resource file(rcc file) registered via cvxCmdRegisterRcc(). If developer wants to unload the DLL plug in file dynamically. The input name must be the same as the one used in cvxCmdRegisterRcc(). */ ________________________________________________________________________________ void cvxCmdVariable ( vxName Name, /* I: global variable name */ void *Variable /* I: pointer to global variable */ ) /* DESCRIPTION: Registers a pointer to a global variable (i.e. the variable's address) referenced in a command template "options" string. Global variables should be registered in the "Init" function called when your library is dynamically loaded by ZW3D at runtime. If developer wants to unload the DLL plug in file dynamically. It is a MUST to run cvxCmdVariableUnload() in the exit function. */ ________________________________________________________________________________ int cvxCmdVariableUnload ( const vxName Name /* I: Variable name */ ) /* Unload the variable registered via cvxCmdVariable() if developer wants to unload the DLL plug in file dynamically. The input name must be the same as the one used in cvxCmdVariable(). */ ________________________________________________________________________________ void cvxEchoColorAtGet ( svxWireAt *at /* O: display attributes*/ ) /* DESCRIPTION Return display attributes stored at echo. */ ________________________________________________________________________________ void cvxEchoColorAtSet ( svxWireAt *at /* I: display attributes */ ) /* DESCRIPTION Set display attributes echo. */ ________________________________________________________________________________ void cvxEchoColorGet ( evxColor *Color /* O: active wireframe color for dynamic echo */ ) /* DESCRIPTION: Gets the active wireframe color of the dynamic echo. */ ________________________________________________________________________________ void cvxEchoColorSet ( evxColor Color /* I: active color for dynamic echo */ ) /* DESCRIPTION: Sets the active color (wireframe and shaded) for dynamic echo. */ ________________________________________________________________________________ void cvxEchoCustomEnd() /* DESCRIPTION: cvxEchoEnd MUST be called at the end of the function that called cvxEchoCustomStart. Failure to do so could leave aspects of the GUI disabled (including error display) and could also mess up undo-redo. */ ________________________________________________________________________________ void cvxEchoCustomStart() /* DESCRIPTION: cvxEchoCustomStart should only be called at the beginning of the "echo_obj" function associated with the currently executing command template. It should ALWAYS be paired with a call to cvxEchoCustomEnd() at the end of the "echo_obj" function. Calling this function at the beginning of an "echo_obj" function sets up the environment so that you can use other API functions to edit the target object inside the "echo_obj" function. Those edits will persist until the next time the "echo_obj" function is called, at which time the edits will automatically be undone prior to the next round of edits to the target object. The function prototype for a custom echo function looks like the following: void MyCustomEcho(int idData, void *echo) The "idData" passed to MyCustomEcho() is the id of the same container of command input data that is passed to the evaluation function associated with the currently executing command template. The "void *echo" argument is currently not used but should be included in the echo function's argument list as shown. Register a pointer to the custom echo function as follows: cvxCmdFunc("MyCustomEcho",(void*)MyCustomEcho,0.0); The custom echo function is registered in the custom command template as follows:MyCustomEcho This function should not be used in conjunction with cvxEchoStart(). */ ________________________________________________________________________________ void cvxEchoDraw() /* DESCRIPTION: Draw the echo data of the active form. */ ________________________________________________________________________________ void cvxEchoEnd() /* DESCRIPTION: Instructs the API to stop sending entities to the echo and start sending them to the database again. cvxEchoEnd MUST be called at the end of the echo that called cvxEchoStart. Failure to do so will cause most API functions to quit working. */ ________________________________________________________________________________ void cvxEchoEscDisable() /* DESCRIPTION: Disable checking for certain escapes that ZW3D may issue while an echo function is executing. This function does not disable checking for escapes issued by the user. Each call to this function must be paired with a call to cvxEchoEscRestore(). Use of this function is discouraged. It is intended for special situations in which a long-running echo function would otherwise trigger an automatic escape. Usually such escapes should be allowed to occur to keep the user interface responsive during echo. An appropriate use of this function, for example, would be to disable escape checking to make an expensive calculation once in an echo function, after which the echo function might cache the results and restore escape checking so future calls to the echo function can execute quickly and respond normally to ZW3D's built-in automatic escapes. */ ________________________________________________________________________________ void cvxEchoEscRestore() /* DESCRIPTION: Restore escape checking previously disabled by a call to cvxEchoEscDisable(). */ ________________________________________________________________________________ void cvxEchoStart() /* DESCRIPTION: Instructs the API to start sending entities to the echo rather than to the database. The function should always be paired with a call to cvxEchoEnd. cvxEchoStart should only be called from within the "echo_obj" function associated with the currently executing command template. */ ________________________________________________________________________________ int cvxMacroInqPath ( vxPath path, /* O: path of macro (NULL to ignore) */ vxLongName file /* O: file name of macro (NULL to ignore) */ ) /* DESCRIPTION: Gets the path and file name of the currently running macro. If no running macro, path[0] = 0 and file[0] = 0. The path and file cannot both be NULL. Return 1 if error, else 0. */ ________________________________________________________________________________