-------------------------------------------------------------------------- Command Templates -------------------------------------------------------------------------- ZW3D command templates are the most common way to gather and manage user input in ZW3D. They are defined by a ascii "templates" defined in external files with a ".t" extension. Similar templates are used to define GUI forms used to gather and display information through the Windows interface. A command template contains keywords and prompts that tell ZW3D what kinds of user inputs to gather for a particular command. It also defines the names of C function callbacks used to process the input data and to generate results in ZW3D. Command templates are also called "Virtual Forms" in ZW3D. The GUI form that is displayed based on a command template definition is usually called an "Options Form". The "Options Form" manages user input via both the GUI form and the graphics display area, with dynamic preview of user selections and their anticipated results. A typical command template has a short header section followed by a series of "FIELD"'s. Each field corresponds to a single piece of data being collected. Note that here, a single piece of data may in fact be a list of entities. ZW3D will process each field request until it hits a "trigger" statement. At this point a call is made to the function on the right hand side of the "function=" specifier along with an index to the collected data. Fields which appear after the "trigger" statement are taken to be optional inputs (max 4) and appear as option buttons below the text input window. Once a template is complete, it can be made available to ZW3D by compiling it into a local copy of Forms.Z3. To compile a single template file, type the following statement from the command line of a Windows console (without the quotemarks): "zw3d -t template_file.t Forms.Z3". If you have a folder which contains multiple templates then you may compile all of them with the following command: "zw3d -d folder_name Forms.Z3". The above commands must be executed from within your ZW3D user folder. The "About..." option on the ZW3D Help pulldown menu shows the path to your ZW3D user folder. --------------------------------------- Example Command Template: # A line that starts with pound sign is treated as a comment TEMPLATE=FtCutSph description=Create spherical cut feature. function=FtCutSph echo=FtEchoBaseSph FIELD=Center class=point id=1 prompt=Select sphere center point. options=/edge/curve/point/, FIELD=radius class=distance id=2 prompt=Select sphere radius. options=num=VgFtRadC,min=0, FIELD=name class=string id=3 prompt=Enter feature name or press "Accept". options=empty_ok, trigger FIELD=Quick class=entity id=4 prompt=Select face on base shape for attaching new feature. options=/face/,empty_ok,dbl_pick_ok, ------------------------------------- ---------------- Command Strings ---------------- A template which has been compiled into Forms.Z3 may be activated directly from the ZW3D command line by using an "!" followed by the template name. You will also see this used inside of menu templates to initiate operation templates. If a command is preceded by a tilda (~), it is assumed to be the name of a void function with void arguments (void function(void)). The specified function is called, including custom functions implemented with the API. Command strings assigned to buttons or icons in ZW3D menus are launched when the menu item is pressed. ------------------------ Command Template Format ------------------------ TEMPLATE = Template name (up to 15 characters long). description = Command description (less than 80 char). function = Optional name of function invoked when form is accepted. (function type is documented below) child = Execute form as child of active form. auto_repeat = Auto-repeat the virtual form each time it is accepted. no_repeat = Don't allow middle mouse button to cause form to repeat. repeatable_child = Allow child form to repeat when middle button is pressed. init = Name of C language function for initializing command(see below). icon_id = Icon number as defined by evxCmdType in VxApi.h. opt_form Include this keyword if you want all command options to be shown on the command form. If the keyword is not included, the user will be prompted for input options one by one, but will not have a view of all of them simultaneously. Generally speaking, you should always include this keyword in a command template. FIELD = field label (up to 31 characters) id = integer field id (numbered from 1-100) class = field data class prompt = field prompt options = Optional comma-delimited list of options callback = Optional function that is called when the field is modified int function(char *template name, int field_id, int idx_data) Maximum function name length is 15 characters. list - keyword that tells Input Manager to collect a list of items hints = Optional comma-delimited list of hints (up to 48 characters per hint) FIELD = field label (up to 31 characters) . . . trigger (keyword that "triggers" execution of "function"). or pseudo_trigger (keyword that "triggers" execution of "function", but does not specify start of options buttons) Fields that follow the "trigger" keyword are assigned to the "Options" buttons at the bottom of the GUI (over the text input field). Not so with the pseudo_trigger. When the field that contains the "trigger" or "pseudo_trigger" keyword is accepted during interactive input, the C language function defined by "function =" is automatically invoked by the Input Manager. Input data gathered by the Input Manager, according to the template specification, is passed to the function via an object called the "input data object" (i.e. VDATA). Following is a typical template format showing usage of the pseudo_trigger: FIELD=prompt1 class = string FIELD=prompt2 class = string pseudo_trigger FIELD=prompt3 class=number callback=JumpBackToRegularPrompts FIELD=place_holder class=string trigger FIELD=option1 class=option callback=OptionJumptoPrompt3 Under normal execution, the user will respond to prompts 1 and 2 and then the form will execute. When the user goes to option1, it may (based on input) jump to prompt3 to gather additional input. The callback on prompt3 will then jump to one of the first 2 prompts. Note that only option1 shows up on the "Options" buttons. The input data object (VDATA) is composed of various sub-objects (i.e. "data items") that correspond to the fields of the input template. Each data item contains an object whose class is specified by a field's "class" keyword (e.g. class = ). If a field is flagged as a list (e.g. list = yes), the data item consists of a list of objects of the specified class. If "list=yes" is not included in a FIELD definition, it is assumed the field is used to gather a single element of data. The C language function assigned to "function = " should have the following type and arguments: int YourFunction ( int idx_in, /* i: index of input data-object (class=VDATA) */ int *idx_out /* o: index of output data-object (class=VDATA) */ ) { return(0 or 1); } The function should return 1 if it fails or 0 if it succeeds. It is critical that the function return the proper value. A return value of 1 tells the Input Manager to automatically "undo" any modifications made by "YourFunction()" to the object database or the graphic display. "Idx_in" is a handle to an object that contains the input data (VDATA) gathered by the Input Manager according the the template associated with "YourFunction()". "YourFunction()" may use the "cvxDataGet***" functions to query "idx_in" for the various data items stored in the object referenced by "idx_in". Each data item is identified by a template field id. "YourFunction()" can ignore "*idx_out". The "child" Option ------------------ Templates are assumed to be of type "root" by default. When a "root" template is executed, execution of the previous form is either paused (IM.exec_option=1) or terminated (IM.exec_option=0). The results of the form are piped back to the input manager. When a "child" template is executed, it becomes the child of the previous form and pipes its results back to its parent form. The "init" Option --------------------- The "init" keyword is used to define a function that is automatically called each time a form is initialized. You can use this function to initialize globals before the virtual form is executed. The init function has the following arguments: int callback_function ( int idx_data, /* I: index of input data-object */ int *idx_out, /* I: index of output data-object */ ) The "callback" Option --------------------- The "callback" keyword is used to define a function that is automatically called each time input is added to a field. You can use this function to check the field's input and take appropriate action if necessary. The callback function has the following arguments: int callback_function ( char *template name, /* I: name of active form */ int field_id, /* I: id of active field */ int idx_data /* I: index of form's VDATA object */ ) Return 1 from the callback function if you want the Input Manager to stay at the active field. Otherwise, return 0 and the Input Manager will process the field as usual. For example, if the input associated with the field isn't what you're looking for, you could force the Input Manager to re-execute the field. -------------------------------------------------------------------------- Template Field Classes and Options -------------------------------------------------------------------------- ------------------ 1. class = "null" ------------------ This class is used to add a single NULL field to a form that doesn't require any input -- it simply fires off the evaluation function associated with the form. When the NULL field is activated, it logs an event that forces the field to trigger so that the form is executed. There are no "options" associated with this class. -------------------- 2. class = "string" -------------------- This class is used to interactively get a null-terminated ascii string. Use cvxDataGet() to retrieve data items of this class from a VDATA object. a. option = "show=GuiFormName" Display the specified GUI form. The form will be taken down automatically when a new command is executed (it stays up while a command is repeated). b. option = "$CommandString" Passes the specified command string to the application logged event handlers. c. option = "~FunctionName" Calls the specified C function, which is assumed to be of type "void function(void)". d. option = "string=VariableName" If the active field does not have data, the string stored in "char *VariableName" is added to the field, the field is accepted and control moves to the next field. ------------------------------------------- 3. class = "number", "distance" or "angle" ------------------------------------------- These classes are used to interactively get a dimensionless number, distance or angle. They support the same set of options. Distances whose units are not explicitly specified are assumed to be given in the active system of linear units. Angles whose units are not explicitly specified are assumed to be in degrees. Units should be explicitly specified for all numbers contained in expressions, unless a number is dimensionless. Use cvxDataGet() or cvxDataGetNum() to retrieve data items of the numeric classes from a VDATA object. a. option = "is_int" Specify that the numeric input should be integer-valued. b. option = "dyn" Enable dynamic locator tracking. c. option = "num=VariableName" Initialize the numeric input to the floating point value stored in the double precision global variable specified by "VariableName". d. option = "int=VariableName" Initialize the numeric input to the integer value stored in the double precision global variable specified by "VariableName". e. option = "max=NumericValue" Set the upper bound for numeric input to "NumericValue". f. option = "min=NumericValue" Set the lower bound for numeric input to NumericValue. g. option = "ref=TemplateFieldId" Use the start point and normal direction of the object associated with the template field specified by "TemplateFieldId" to initialize the global reference point and direction used to map locator location to a number. This is the feature used to get extrusion distances dynamically using the mouse. h. option = "init=TemplateFieldId" Use the numeric class (distance, angle, dimensionless) of the object associated with the specified template field to initialize the class (distance, angle, dimensionless) of the numeric input. i. pop_ext Display pop-up menu used for extrusion command. The menu has "To Point", "Boundary Face" and "Through All" options. j. pop_ang Display pop-up menu with options to get an angle by selecting a dimension and by selecting several pre-defined constants. k. empty_ok Accept field when the middle mouse button or "Enter" is pressed, even if the field is empty (i.e. doesn't have input data). l. option = "~FunctionName" Calls the specified C function, which is assumed to be of type "void function(void)". -------------------- 4. class = "point" -------------------- This class is used to interactively get a point or list of points. If the active target object is 2D, the points are projected onto the plane of the object (Z = 0.0). If the active target object is 3D, the points are mapped into 3D space via the active view plane, unless they are derived from other 3D geometry, in which case their location in 3D space is determined by the method used to derive them from existing geometry, or if their location is specified via absolute coordinate input. Use cvxDataGet(), cvxDataGetPnt() and cvxDataGetPnts() to retrieve data items of the "point" class from a VDATA object. a. option = "two_ent" When selecting a point on an entity(s), this option allows a single pick to select two intersecting entities simultaneously. b. option = "hi_ent" When selecting a point on an entity, this option enables highlighting of the entity. c. option = "crit_pnt" Enable the "critical point" point input method if the active target object requires "critical points" for certain applications (i.e. profiles require that dimension points be "critical" points). The "Input Options" popup will not display any other point input options. d. option = "on_ent" Enable the point input method that dynamically maps the locator position to the closest point on the entity within the locator's aperature. All other pick input methods are disabled. e. option = "marker_off" Disable display of point markers. f. option = "qpick_off" Disable dynamic mapping of locator position to "critical" points or "on-entity" points (quick-pick). g. option = "qpick_on" Enable dynamic locator mapping (quick-pick). h. option = "/FilterItemName/FilterItemName/..../ Set up a temporary entity filter based on a list of filter items delimited by backslashes. Only the specified items will be active for entity picks when selecting "critical" points or "on-entity" points. The following items are currently supported: item = "part" item = "shell" item = "face" item = "edge" item = "curve" item = "profile" item = "dimen" item = "plane" item = "asm" item = "crv_list" item = "layer" item = "datum" item = "fcurv" (curve-on-face) item = "point" (2D or 3D point entity) i. option = "limit=MaxCount" If "list=yes", limit the number of point selections to "MaxCount". j. option = "pick_par" Start pick traversal with target object's parent, excluding the target object from traversal. By default, the scope of entity pick traversal is limited to the target object. k. option = "proj_off" Disable point projection for 2D target objects. For example, by default, if you picked the endpoint of an edge that lay out of the plane of a 2D object, the point logged as input would be the projection of the endpoint onto the plane of the 2D object. If "proj_off" were active, the endpoint would be logged as a 3D point relative to the plane of the 2D object. l. option = "pop_tan" Add a "Tangent" button to the "Point Input" pop-up menu. When this point input mode is enabled, point-on-curve picks are flagged with type "V_PNT3_TO", instead of V_PNT3_ON. Use this option when you want to differentiate between a point-on-curve pick used to define 1) an exact position on the curve and a point-on-curve pick used to define 2) the general location of a point of tangency with the curve. m. option = "pop_gen" Add "Entity" and "Length" buttons to the "Point Input" pop-up menu. These options allow the user to combine point, entity and length input in a single field. Use "cvxDataGet()" to query the field. n. option = "pop_face" Display only the "On Face" button on the "Point Input" pop-up menu. When pressed, this button allows the user to select a point on a face. o. option = "chk_line" Only accept linear entity picks. p. option = "empty_ok" Accept field when the middle mouse button or "Enter" is pressed, even if the field is empty (i.e. doesn't have input data). q. option = "absolute" Force point input method to "absolute" coordinate input and disable the pop-up menu. r. option = "dim_pnt" This option enables prompting for an optional dimension text location point and dimension text string each time a point is selected. Prompting for the text location and text string is conditional based on the status of flags set using CdWiPnt_TxtPnt() and CdWiPnt_DimTxt(). These functions accept 0 (OFF) or 1 (ON) integer input to disable/enable prompting for a dimension text location point and dimension text string, respectively. s. option = "dist" If this option is set and a string without commas is entered by the user, the string is interpreted as a distance and is assigned to the "x" coordinate of the point input object. If "cvxDataGet" is used to query the object, it will return a number instead of a point. t. option = "ang" If this option is set and a string without commas is entered by the user, the string is interpreted as an angle and is assigned to the "x" coordinate of the point input object. If "cvxDataGet" is used to query the object, it will return a number instead of a point. u. option = "get_dir" Force pick mode so that it will only pick points on lines. Show an arrow pointing along the line from the line endpoint closest to the pickpoint. The direction of the arrow is stored with the VPNT3 data object. Use cvxDataGet() to get the point and direction associated with the VPNT3 data object. See the "is_direction" option in the "VsGenInp" data structure (VxCad.h). v. option = "get_dir_rot" Force pick mode so that it will only pick points on lines. Show an arrow pointing along the line from the line endpoint closest to the pickpoint. The direction of the arrow is stored with the VPNT3 data object. Use cvxDataGet() to get the point and direction associated with the VPNT3 data object. See the "is_direction" option in the "VsGenInp" data structure (VxCad.h). Also, show the direction of right-hand-rule rotation about the direction vector. w. option = "root_path" Force pick-path to record beginning with the "root-most" object. x. option = "pick_all" Start pick traversal with target object's root object. By default, the scope of entity pick traversal is limited to the target object. y. option = "pick_last" Pick the last "target" entity in a pick-path, instead of the first. Picking the first "target" entity is the default action. A "target" entity is one whose class is entered as a negative number in a filter item definition. At the moment, this option only works for component (VCOMP) picks. z. option = "pick_comp" or option = "ignore_comp" Make the active component (int VgCompIndex) the only component in the target object that can be picked (pick_comp) or the only component that cannot be picked (ignore_comp). aa. option = "~FunctionName" Calls the specified C function, which is assumed to be of type "void function(void)". bb. option = "ignore_targ" Exclude target object from pick traversal. cc. option = "end_pnt" Enable the "critical point" point input method. The "Input Options" popup will not display any other point input options. dd. option = "no_crit" Use default point input method but do not allow "critical point" point input method. The "Input Options" popup will not display "critical point" point input options. This have to be used only for 2D target. ee. option = "ray_cast" When nothing else is picked, automatically kick into ray_cast face picking. This makes it possible to pick a point on an edge or a face without switching modes. ff. option = "ray_focus=FLD" Focus ray_cast picking on the faces selected in FLD. gg. option = "no_fcurv" Exclude parting line curves. e.g. CdCvCrnrTrim, make a corner, doesn't support parting lines. hh. option = "force_face" Force point input method to "On Face". -------------------- 5. class = "entity" -------------------- This class is used to interactively get an entity pick or a list of entity picks. Use cvxDataGet(), cvxDataGetEnt() or cvxDataGenEnts() to retrieve data items of the "entity" class from a VDATA object. a. option = "dbl_pick_ok" Allow an entity to be picked twice during execution of a single template. b. option = "qpick_on" Enable dynamic highlighting of entities as the locator passes over them. c. option = "qpick_off" Disable dynamic highlighting of entities. d. option = "/FilterItemName/FilterItemName/..../ (see documention for "point" class) e. option = "limit=MaxCount" If "list=yes", limit the number of entity picks to "MaxCount". f. option = "string=TextString" Initialize the text input field with "TextString. g. option = "pick_par" Start pick traversal with target object's parent, excluding the target object from traversal. By default, the scope of entity pick traversal is limited to the target object. h. option = "chk_line" Only accept linear entity picks. i. option = "chk_plane" Only accept planar entity picks. j. option = "empty_ok" Accept field when the middle mouse button or "Enter" is pressed, even if the field is empty (i.e. doesn't have input data). k. option = "form=GuiFormname" Display the specified GUI form while the entity input widget is active. Un-display the form when the widget is de-activated. l. option = "pop_up=MenuName" Display the specified pop-up menu while the entity input widget is active (if the right mouse button is pressed). m. option = "show=GuiFormName" Display the specified GUI form. The form will be taken down automatically when a new command is executed (it stays up while a command is repeated). n. option = "~FunctionName" Calls the specified C function, which is assumed to be of type "void function(void)". o. option = "browse = ObjectClassId" Activates the pop-up menu with the "Browse" option. When the user selects the "Browse" option, a list of objects of the specified class will be displayed. Set "object class id" to -1 to display objects of all classes. For now, this option may only be used to display root objects when a file is active, but no target object is active. p. option = "hi_depth = DepthCount" Sets the depth of assembly traversal for highlighting. "hi_depth = 1" will only traverse through the top-level part. "hi_depth greeater than 1" will traverse into sub-parts. q. option = "root_path" Force pick-path to record beginning with the "root-most" object. r. option = "frozen_ok" Allow "frozen" entities to be picked. s. option = "pick_comp" or option = "ignore_comp" Make the active component (int VgCompIndex) the only component in the target object that can be picked (pick_comp) or the only component that cannot be picked (ignore_comp). t. option = "ignore_targ" Exclude target object from pick traversal. u. option = "tpl_name = string" Limits picks to entites that were created with a template of the given name. v. option = "chain_pick" Make chain picking the initial pick state. w. option = "assem_mode" Enable extended entity picking if assembly modeling mode is active. x. option = "extend" Allow extended entity picking when F8 is held down. y. option = "chk_dwgtbl" Only accept drawing table entity picks. z. option = "force_extend" Force extended entity picking for some pop-up filters (UiFiEC). aa. option = "chk_cnln" Apply connection line filter to picks. ab. option = "chk_adj_fc"" Apply circle filter to picks. ac. option = "center_line" Enable picking of lines or face centerlines. ad. option = "ignore_locator" Disable locator event processing. ae. option = "auto_extern" Automatically create external reference when the F7 key is held down. af. option = "save_layers" Flag VDATA as dependent on layer visibility so that layer visibility status is saved with the feature driven by the VDATA. --------------------- 6. class = "option" --------------------- This class is used to interactively get an exclusive choice from a list of options. The choices, or "options", are encoded in the field's "options" string using the following format: options = IntegerVariableName, OptionLabel1:IconName1:JumpToThisFieldId1, OptionLabel2:IconName2:JumpToThisFieldId2, . . . The "options" string should end with a comma. It may contain up to 8 options. The icon name and/or "jump to" field id can be skipped as shown below: options = IntegerVariableName, OptionLabel1::JumpToThisFieldId1, OptionLabel2::, . . . The global variable name may be followed by an equal-sign and a "hard-coded" initial value as shown below: options = IntegerVariableName=2,OptionLabel1,OptionLabel2, Use cvxDataGet() or cvxDataGetNum to retrieve data items of the "option" class from a VDATA object. This field automatically allows "no input" without declaring "empty_ok". The "options" string may optionally contain the following keywords: a. option = "|checkbox Display an option field as a checkbox. In this case, the field prompt is displayed on the Option Form instead of the field name. b. option = "|radio" Display an option field as two radio buttons --------------------------- The following is an example of an option field that activates collection of optional inputs from field 12 or field 13: FIELD=Spine id=3 class=option prompt=Select spine method. options=VgFtSpineMeth,None=0,Guide plane=1::12,Spine curve=2::13, Optional input fields 12 and 13 should be listed in the command template below field 3 and between the "pseudo_trigger" and "trigger" keywords. Fields 12 and 13 are disabled and enabled automatically as the user changes the option associated with Field 3. --------------------------- The following is another example with multiple inputs: . . . trigger FIELD=Spine id=3 class=option prompt=Select offset method options=VgFtOffset,None=0,Shrink=1,Thicken=2, FIELD=1st offset id=4 class=distance prompt=Enter first offset callback=CdSkip2ndOffset options=|enable=FtOffsetEnable,|indent, FIELD=2nd offset id=5 class=distance prompt=Enter second offset options=|enable=FtOffsetEnable2,|indent, --------------------------- The |enable callback function FtOffsetEnable2() should return 1 if the field should be enabled. int FtOffsetEnable(void) { return (VgFtOffset != 0 ); } An |enable function can be used on any field in the template. The |enable function is called very often, so it should not do any major computations. Also notice the |indent keyword used for fields 4 and 5. This makes them look like they are grouped with option field 3. ----------------------- 7. class = "continue" ----------------------- This widget waits for the user to press "Enter" or "Accept", then continues to the next field of the active form. No input data is logged with the form. Typically, the prompt associated with a field with "class=continue" would say "Press [Accept] to continue.". This field automatically allows "no input" without declaring "empty_ok". For cases where there is no way to eliminate a placeholder field, the field should be class=continue. This will keep the field from showing up on the option form. There is not much need for these, but when one is needed, it should be class=continue with no field name. All "SkipTo" fields should be "class=continue" with no field name. ----------------------- 8. class = "command" ----------------------- Use a field of this type to execute a child command template (such as adding a variable radius to fillet). Using class=command with options=!MyTemplate, will cause "MyTemplate" to be executed when the button is pushed. This makes the widget show up as a push button on the Options Form.