In Chapter 34, when you looked at an AutoLISP routine (see Figure 34.3), you saw an example of the COMMAND function. You use the COMMAND function in AutoLISP to execute AutoCAD commands. This function treats all subsequent arguments as if they were typed at the command line interactively. When programming with the COMMAND function in AutoLISP, exactly duplicate what you would do at the command line. For example, to draw a line, you follow the steps shown in the following table. The second column shows how you would perform the same action in an AutoLISP routine.

For example, if you're using the variables startpt and endpt for the start point and endpoint of a line, here's how you would access the LINE command in an AutoLISP expression:

(command "_line" startpt endpt "")

Functions always begin with the DEFUN function. You can define three principal types of functions:

When you create an S::STARTUP function, you need to decide where to put it. Chapter 34 briefly explained the difference between acad.lsp and acaddoc.lsp. The need for two files arose because AutoCAD includes MDI (Multiple Document Interface), which enables you to open more than one drawing at a time. For more information, see the "Automatically loading LSP files" sidebar. S::STARTUP is a great function for enhancing productivity. In this way, you can automate whatever general setup operations you normally do at the beginning of a drawing session, or for every drawing that you open.

Here's an AutoLISP routine that uses both the DEFUN and COMMAND functions:

(defun c:redline (/ startpt endpt)
  (terpri)
  (setq startpt (getpoint "Select the redline start point:"))
  (terpri)
  (setq endpt (getpoint startpt "Select the redline end point:"))
  (command "_line" startpt endpt "")
  (command "_chprop" "_last" "" "_color" "red" "")
)

Here's an explanation of this routine:

To use this routine, you would follow these steps:

Here is another example of an AutoLISP routine that defines an S::STARTUP function. It uses several of the features that I've been discussing in this chapter.

(defun s::startup ()
  (setq old_osmode (getvar "osmode"))
  (setvar "osmode" 0)
  (command "_rectang" "_width" "0.1" "0,0" "10,10")
  (command "_text" "8,1" "0.2" "0" "name")
  (command "_text" "8,0.7" "0.2" "0" "date")
  (command "_text" "8,0.4" "0.2" "0" "revision")
  (command "_zoom" "_extents")
  (setvar "osmode" old_osmode)
)

This routine creates a simple title block and border each time you open a new drawing. It turns object snaps off (the OSMODE system variable) so that all the text doesn't snap to the same location. But first it saves the current OSMODE value. At the end, the routine returns OSMODE to its original setting.

In order to use this routine — or one of your own — you can add it to the end of acaddoc.lsp. AutoCAD 2010 does not come with this file, so the first time that you want to use it, you must create it.

Warning

Before using the S::STARTUP function, be sure that an S::STARTUP function does not already exist. Other applications that you may have purchased or downloaded may include an S::STARTUP file. Adding a second S::STARTUP could possibly interfere with the operation of these other applications. On the command line, type (s::startup)

You can create functions that accept arguments, sometimes called parameters. An argument is a value that must be supplied with the function. The function then uses the value of that argument in its operation.

Earlier in this chapter, I explained that local variables are placed in parentheses after a slash. Arguments go in the same set of parentheses, but before the slash. If there are no local variables, you don't need the slash. Here is an example of a function with one argument:

(defun chg2red (selected_object)
...
)

To actually use this routine in AutoCAD or within another AutoLISP routine, use the format (chg2red selected_object). The argument is sent to the chg2red routine by adding the argument after the function name, all enclosed in parentheses.

Whenever you use the chg2red function within a routine, you must follow it by its argument. You can obtain the argument by using a variable whose value you've set in the routine, by obtaining a value through user input, or by typing in a specific value when you use the function.

The following exercise uses a function that is called from within the routine.

STEPS: Using AutoLISP Functions and Commands

Don't save the routine or your drawing.

Here's how the routine works:

AutoCAD has a wide variety of system variables to control the drawing environment. Thankfully, the creators of AutoLISP enabled the AutoLISP programmer to automate setting and retrieving AutoCAD system variables.

Don't confuse the terms variable and system variable. A variable is a value that is stored for use in a routine. A system variable is an AutoCAD setting that changes how AutoCAD works.

To set or retrieve AutoCAD system variables, you use two functions, SETVAR and GETVAR, which can be used on AutoCAD system variables. (You can use SETVAR only on system variables that are not read-only.) Here's how they work:

Although you can use SETVAR and GETVAR on many system variables, here are two system variables that are often changed in an AutoLISP routine:

STEPS: Using AutoLISP to Work with System Variables

Don't save your drawing.

Here's how this routine works. This discussion assumes that you have already read the discussion of the previous routine, which was very similar.

As a result of these changes, the chgcolor program always sets the CMDECHO system variable back to the value it had before being run.

A list is always enclosed in parentheses with spaces between the elements of the list. One common use for lists is for coordinates, as shown in the following example:

(1.0 3.5 2.0)

This list represents the X,Y,Z coordinates 1.0,3.5,2.0. You often need to extract one or more of the elements in a list. Table 35.1 shows the common list-extraction functions, using the example list (1.0 3.5 2.0).

For more flexibility, you can use the NTH function. Use the NTH function to access any element in a list by passing two arguments that specify the number of the element (items are numbered starting from 0) and the list that you want.

The name of the list is usually a variable set with SETQ:

(setq corner (list 1.0 3.5 2.0))

In this example, (nth 0 corner) returns 1.0 because 1.0 is the first item in the list corner.

The LIST function creates a list. If all the items in a list are constant values (not variables), you can use the QUOTE function to create a list. You can use a single quote (the same as an apostrophe on the keyboard) as a shortcut for the QUOTE function. The following two functions are equivalent:

(setq corner (list 1.0 3.5 2.0))
(setq corner '(1.0 3.5 2.0))

Many more AutoLISP list-extraction functions are detailed in the AutoLISP Function Synopsis Appendix of the AutoLISP Developer's Guide. Look under Basic Functions; then List Manipulation Functions. However, you can go a long way by remembering the functions listed here.

A dotted pair is a special type of list that contains only two elements. Some AutoLISP functions do not accept dotted pairs as an argument, but they're used to represent AutoCAD database objects. To construct a dotted pair, use the CONS function:

(cons 40 4.5)

This example returns (40 . 4.5). This list type is known as a dotted pair because it contains exactly two elements, and the elements are separated by a period or dot.

STEPS: Working with AutoLISP Lists

Don't save your drawing.

Conditional statements enable program flow to be determined, based on the outcome of a given decision. These decisions result in the return of either T, meaning true, or nil, meaning false. To try out the following statements, type them in the Visual LISP Console window. For instance, for the statement

(< 3 5)
T

AutoLISP returns T for true, having determined that 3 is less than 5. For the statement

(> 3 5)
nil

AutoLISP returns nil for false, having determined that 3 is not greater than 5. For the statement

(= 3 5)
nil

AutoLISP returns nil, because 3 is not equal to 5. Because conditional statements return either T or nil, you can use the IF statement. The general syntax of the IF statement is (if conditional-test if-true if-false). You can also use the IF statement with other functions that return a value; nil is always evaluated as the if-false potion of the IF statement while T or any other value is evaluated as the if-true portion.

For example, you may want to find circles whose radius is less than 0.25. In this case, you could use the following IF statement. In this example, radius is a variable that has been previously set.

(if (< radius 0.25)
  (princ  "
The radius is less than .25")
  (princ  "
The radius is not less than .25")
 )

The conditional test is (< radius 0.25). The if-true statement is (princ " The radius is less than .25"). The if-false statement is (princ " The radius is not less than .25"). This IF statement is equivalent to saying, "If the radius is less than .25, print 'The radius is less than .25' but if not, print 'The radius is not less than .25.'"

You can leave out the if-false statement. In this case, AutoLISP executes the if-true statement if the conditional statement is true and does nothing if it's false, and continues on to the rest of the program. In the following exercise, you see both types of IF statements, one nested inside the other.

STEPS: Using the IF Statement

Don't save your drawing.

Looping provides the capability to execute a step or a number of steps a given number of times, based on an evaluation that you make in your application. One way to do this is with the WHILE function.

The format of the WHILE function is:

(while conditional-test-if-true
        then-perform-following-code-until-condition-is-false)

One method that can be useful with a WHILE conditional-test-if-true statement is to include a counter for the WHILE expression. A counter counts how many times an operation is executed. You can then end the operation when the counter reaches a certain number. To create a counter, set a variable (perhaps named "counter") to the number at which you want to start. Then write the code for one pass through the looping statement. Then set the counter to the next higher number, using an expression, such as the following:

(setq counter (+ 1 counter))

The routine then loops back over the statements until the counter reaches the value that you set.

Here's a simple example:

(defun c:process (/ counter)
  (setq counter 1)
  (while (< counter 6)
    (princ "
Processing number ")
    (princ counter)
    (terpri)
    (setq counter (+ 1 counter))
  )
)

In this example, the process function starts by setting the variable counter to 1. Then you start the WHILE statement and specify that the counter must be less than 6. Within the WHILE statement, you print the text string "Processing number" and then the value of the counter variable. You use (terpri) so that each text string starts on a new line. Then you set the counter to the next higher number. Each time through the WHILE loop, the value of the counter is incremented by 1. Without the increment statement, line 3 would always evaluate to true, and the WHILE loop would never exit because the counter would always be 1.

If you accidentally program an infinite loop like this, you can stop the execution of your AutoLISP routine by pressing Esc, pressing Ctrl+Break, or choosing Debug

In the preceding example, the WHILE loop continues as long as the counter is less than 6. When the counter reaches 6, the WHILE function stops. The WHILE statement returns the last value of the routine, so AutoCAD prints 6 on the last line. Figure 35.2 shows the result.

Figure 35.2. The result of the process function.

When using WHILE, you may want to combine several operations under the condition. The IF function normally evaluates one then expression if the test expression is true. Suppose you want an IF expression that processes various tasks if the test condition is true. An IF expression, as previously mentioned, processes a "do-if-true" and "do-if-false." Therefore, to process more than one "do-if-true" expression, you need to separate the "do-if-true" processes from the "do-if-false" processes. To accomplish this, use PROGN (short for program nest) to include (or nest) all items that you want executed when the test is true. In general, PROGN evaluates all the statements within its parentheses and returns the last evaluation as if it were one statement, as the following example demonstrates.

In the following example, you see the same IF statements used in an earlier example. However, after the second IF statement, you want your routine to print two lines if the entered number equals 3. You can do this by enclosing the two lines of code (plus a terpri) within a PROGN statement:

(defun c:compare2three (/ entered_num)
  (setq entered_num (getint "
Enter an integer: "))
  (if (< entered_num 3)
    (princ "
The entered number is less than 3.")
    (if (= entered_num 3)
      (progn
        (princ "
The entered number is equal to 3.")
        (terpri)
        (princ "
This is the one we are looking for.")
      )
      (princ "
The entered number is greater than 3.")
    )
  )
  (princ)
)

STEPS: Using WHILE, IF, PROGN, and a Counter

Figure 35.4. The result of the PRINT0TO10 function.

Don't save your drawing.

Every object in the AutoCAD database has an entity name. This name enables you to reference that object anywhere in your AutoLISP application. To see an example of an entity name, type the following after starting a new drawing:

(command "_line" "3,3" "5,5" "")
(entlast)

AutoLISP responds with an Entity name such as <Entity name: 2ed0520>.

The numbers will probably differ on your system, but using the information returned from ENTLAST enables you to programmatically get or set a variety of options on any given database object by referencing its entity name.

The ENTGET (entity get) function is the key to making modifications to the drawing database. The ENTGET function takes an entity name as an argument. After drawing the line in the preceding steps, type the following:

(setq myline (entget (entlast)))

AutoLISP responds with:

((-1 . <Entity name: 15ac558>) (0 . "LINE") (330 . <Entity name:
   15ac4f8>)(5 . "2B") (100 . "AcDbEntity") (67 . 0)
(410 . "Model") (8 . "0")(100 . "AcDbLine") (10 3.0 3.0 0.0) (11 5.0
   5.0 0.0) (210 0.0 0.0 1.0))

This is a representation of how the line is stored in the AutoCAD drawing database. AutoLISP returns a large list that contains multiple smaller lists. Each of the smaller lists is referred to as a group indexed by the first element. The entity name is in group −1. Each of the initial numbers in the small lists represents a different quality of the line. These numbers are called object group codes. The object group codes used most often are listed in Table 35.2.

You can also use Visual LISP to examine an AutoCAD object. Begin by choosing View

After you end object selection, you're returned to Visual LISP, where you see the Inspect dialog box. Select the name of the entity and right-click while the cursor is over the selected text. Choose Inspect to see information about the object. Figure 35.5 shows information about an arc.

Figure 35.5. Getting information about a drawing object from Visual LISP.

Not all these group codes are present in the line that you drew. For instance, group 62 (color) is absent in the list returned by AutoLISP. Every time you draw a line, you don't explicitly set its color. As a result, it defaults to the current color. In the same way, AutoLISP doesn't explicitly set every attribute of every group. In this case, the color is ByLayer and the current layer is 0. AutoLISP returned (8 . "0") in the preceding list to signify that the line is on layer 0.

There are many other group codes than the ones listed in Table 35.2, and they can be found in the Visual LISP Help system. From Visual LISP, choose Help

To manipulate a given attribute of an object, two important functions are ASSOC and SUBST:

To manipulate the start point of your line, first get the start point:

(setq startpt (assoc 10 myline))

AutoLISP responds:

(10 3.0 3.0 0.0)

To modify the start point of your line, use:

(setq new_startpt '(10 6.5 1.0 0.0))
(setq myline (subst new_startpt startpt myline))

AutoLISP responds:

((−1 . <Entity name: 15ac558>) (0 . "LINE") (330 . <Entity name:
   15ac4f8>)(5 . "2B") (100 . "AcDbEntity") (67 . 0)
(410 . "Model") (8 . "0")(100 . "AcDbLine") (10 6.5 1.0 0.0) (11 5.0
   5.0 0.0) (210 0.0 0.0 1.0))

In this case, new_startpt is substituted for the existing startpt in the object myline. No changes to the line are yet apparent. To commit the change, you need the ENTMOD function.

The key to modifying objects is the ENTMOD (entity modify) function. The list returned by AutoLISP can be modified and then passed to ENTMOD as an argument to update the AutoCAD database. Continuing with the previous example, if you enter:

(entmod myline)

AutoLISP responds:

((−1 . <Entity name: 15ac558>) (0 . "LINE") (330 . <Entity name:
   15ac4f8>) (5 ."2B") (100 . "AcDbEntity") (67 . 0)
(410 . "Model") (8 . "0") (100."AcDbLine") (10 6.5 1.0 0.0)
(11 5.0 5.0 0.0) (210 0.0 0.0 1.0))

The AutoCAD database is changed as well, and the start point of your line is now at X = 6.5, Y = 1.0, Z = 0.0.

A selection set is created with the SSGET (selection set get) function. This prompts the user with the familiar Select objects: prompt. Table 35.3 shows commonly used selection-set functions.

You can use a maximum of 128 selection sets at any given time. To release a selection set back to AutoLISP so that it can be used again, set the selection set to nil, as in (setq ss nil).

For example, you can enter the following in a new drawing:

(command "_circle" "3,3" "2")
nil
(command "_circle" "4,4" "3")
nil
(command "_line" "7,2" "6,6" "3,4" "5,5" "")
nil
(setq mysset (ssget))
Select objects: all 

5 found
Select objects: 

<Selection set 1>

Now mysset is set to the selection set specified by all, which includes the three line segments and the two circles. To see what you have in your selection set, type the following, either on the command line or in the Visual LISP Console window:

(sslength mysset)
5

You now know that you have five objects in your selection set. The first object is number 0, and the fifth object is number 4. To see what the first object is, enter the following:

(ssname mysset 0)
<Entity name: 3fe0550>

To get the database data on the object, enter:

(entget (ssname mysset 0))

Visual LISP responds:

((−1 . <Entity name: 3fe0550>) (0 . "LINE") (330 . <Entity name:
  16014f8>)(5 . "30") (100 . "AcDbEntity") (67 . 0) (410 . "Model") (8 . "0")(100 . "AcDbLine") (10 3.0 4.0 0.0) (11 5.0 5.0 0.0) (210 0.0 0.0 1.0))

By stepping through each of the entity names returned by SSNAME from 0 to 4, you can manipulate each of the objects in the selection set.

STEPS: Creating Selection Sets

Here's a breakdown of the routine in Step 1: