KXL Getting Started
KeyCreator \ Advanced-Customization \ KXL-Getting-Started

Getting Started

A KXL program file may be generated using a text editor or word processing program under the rules defined in this guide. Names for these files follow the same specifications as the system's naming convention, along with the addition of an extension. Specific extensions are discussed in their respective sections of the KXL documentation.
 

To execute a KXL file, use the Add-Ins > KXL Execute option.
 

If an error is detected, KXL file processing halts and an error message is displayed.
 

A typical KXL file consists of variable length records delimited by newlines. Each of these statements directs the flow of the program. A typical statement represents either a primitive, command or expression, along with any required parameters. Please refer to the Functions section of this guide for detailed information on primitives, program control statements and commands.
 

KXL Expressions

The purpose of an expression is to evaluate a mathematical statement and optionally store the results in a variable. Refer to Register Variables, found in this section, for an explanation of the different types of variables offered by the system.
 

For example:
 

POINT (2.0+a), 3.0, (a*b)
 

describes a POINT primitive with an x value assigned the results of 2 plus the numeric value of a, a y value of 3, and a z value assigned the results of a times b.
 

Note that in a KXL program, an expression terminates at the end of a line unless a backslash(\) is found. When this is the case, the command is continued on the following line. For example:
 

n = sqrt(a*b)+\
sin(angle)*2*\
(x+y+z)
 

This equation is evaluated as n = sqrt(a*b)+sin(angle)*2*(x+y+z). The backslash (\) must be the last character in the line, immediately preceding the newline.
 

The following rules apply to KXL expressions. There are three types of constants, as listed below.
 

Integer Constants

A decimal integer is a sequence of digits 0 - 9. If the first digit is a 0, the integer is taken as an octal (base 8) value.  In this case only digits 0 - 7 are valid.  If the sequence is preceded by the prefix 0x or 0X, the integer is taken as a hexadecimal (base 16) value. In addition to 0 - 9, hexadecimal digits also include the characters a-f (upper or lower case) corresponding to the values 10 - 15 respectively.
 

Float Constants

A float constant consists of a signed integer part, a decimal point, a fractional part, an E (or e), and a signed integer exponent. Either the integer part or the fractional part may be omitted, but not both. Either the decimal point or the E (or e) with exponent may be omitted, but not both.
 

String Constants

A string constant is a sequence of characters enclosed in quotes, such as "this is a string".  All strings are treated as an array of characters and are automatically terminated by the null character (ASCII value 0). Thus, the string "hello" actually contains six characters.  A special character sequence is provided to denote control characters and characters outside of the ASCII range. The sequence is signaled by a backslash (\) character. When detected, the next character is interpreted as shown below. For characters not listed, the character itself is used.  This provides a way of entering characters which normally have a special meaning (e.g., use \\ (two backslashes in a row) for the \ (backslash, as used in filenames) character, \" for ", etc.)
       \n        newline
       \r        carriage return
       \t        tab
 

In addition to the above characters, an octal value may be entered by following the \ character with a three digit octal number (e.g., \263).
 

Also, a hexadecimal value may be entered by following the \ character with the character x and two hexadecimal digits (e.g., \x85). For an octal value the permissible range is \000 - \377; for a hexadecimal the range is \x00 - \xff.
 

Most of the operators recognized by the expression evaluator are equivalent to their counterparts in the 'C' programming language. The list is as follows:
 

Math Operators

       a + b                  addition
       a - b                          subtraction
       a * b                          multiplication
       a / b                          division
       a ^ n                          nth power of a
       (a)                            precedence
       a[n]                           array index
       -a                             negative a
       +a                             positive a
       a % b                  a (integer) modulus b
       xxx = b                numeric
 

Variable Assignment

       $msg="hello"                   string variable assignment
       $$msg[x] = "world"             slist element assignment
       a=1.5                                  double floating point assignment
       b=1                                    integer (stored as double) assignment
 

Logical Operators

       a == b                 equal comparison
       a != b                 not equal comparison
       a > b                       greater than comparison
       a < b                       less than comparison
       a >= b                      greater than or equal to comparison
       a <= b                      less than or equal to comparison
       a && b                 AND operation
       a || b                       OR operation
       (a) ? x : y            conditional
 

Bitwise Operators

       a | b                     a ORed with b
       a & b                  a ANDed with b
       a # b                  a XORed with b
       a >> b                       a shifted right by count of b
       a << b                       a shifted left by count of b
       ~a                             complement
 

Algebraic operations are prioritized, as with most programming languages. The precedence of operators, listed below, is grouped by operator type. The group header indicates whether the operators are processed from left to right or vice versa.  The list is arranged from higher to lower precedence with operators on the same line having equal precedence. Note that ' (feet) and " (inches) are actually special unary operators.
 

       Primary-expression operators (left->right) 
       ()            []                                
       functions (cos, sqrt, sizeof, etc.)           
       Unary operators  (right->left)             
       +             -             ~                     
       Binary operators (left->right)             
       ^                                             
       *             /             %                     
       +             -                                 
       >>          <<                              
       <          >          <=         >=     
       ==            !=                                
       &                                             
       #                                             
       |                                        
       &&                                            
       ||                                          
       ?:                                            
       Assignment operator (right -> left)           
       =                                             
 

Example

Simple Equation

Statement:

      x = 4 / 10 * @PI + cos(45)

Result:

      variable x is assigned the value 1.963744

 

Embedded Assignments

Statement:

      x = (y = 23 / 5) + (z = @depth)

      (where @depth = 0)

Results:

      variable x is assigned the value 4.6

      variable y is assigned the value 4.6

      variable z is assigned the value of system variable

      <at>depth which, in this case, equals zero.

 

String Assignment

Statement:

     $msg = "Hello"

Results:

     The string variable $msg is created with an array size of 6

     and contains the characters "Hello" followed by a null

     terminating character.  This is equivalent to the statement:

 

     array $msg[6] = {72, 101, 108, 108, 111, 0}

 

Register Variables

Variables may substitute a constant numeric value anywhere in a KXL program file (e.g., primitives, commands or expressions), including when specifying an array size.
 

There are two types of variables offered, a variable set by the user, and a system variable maintained and updated by the system.
 

Rules for Register Variables

1)      Variables may be assigned a name consisting of any number of characters. The first character of a variable name must begin with a letter. The remaining characters may be any combination of alphanumeric and underscore (_) characters.  Upper and lower case differences are observed.
 

2)      Arrays may be used if they have been previously initialized with the ARRAY statement.
 

3)      A number of reserved variables are maintained and updated by the system. They are accessible through KXL as read-only.  These variables must always begin with the @ character. System variables are case insensitive.
 

KXL and the Undo/Redo System

KXL programs are responsible for managing their own interactions with the Undo/Redo system.  The NoteState command notes a state in the database.  This should be used after an action that causes the database to be altered.  Geometric entities that are created in may not display until a NoteState command has been issued.  This should be used after a complete set of actions that should be considered a single action from the user's perspective.  For example, a KXL program that created a rectangle would use NoteState once after creating all four lines, not after each line.
 

Mixing geometry creation and user interaction commands in a single state can lead to problems.  If a KXL program creates geometry, then without using NoteState, stops to ask the user to indicate a position, for example, and the user uses an immediate mode command that creates a state, such as deleting an entity, that geometry creation will become part of the state for the immediate command.
 

The view manipulation commands and most of the SET commands are not part of the undo system, and so do not require a NoteState.  Changing the units of the part does require a NoteState, because of where the data is stored and because all dimensions in the part have to be updated to the new units.