HyperPics: Beyond the UI

Debugging AutoLISP Programs - Part 1

Debugging AutoLISP programs is "A Zen like Experience," said no one ever... Although, I have tried to convince a number of people that it is very a calming and soothing activity over the years.  There are a number of different debugging techniques and tools that can be used to find and handle errors much easier, whether you are developing in AutoCAD on Windows or Mac OS.

Note: There are more debugging tools available on Windows than Mac OS at this time, which could change in the future.  If you do plan on developing a number of AutoLISP programs, you might want to consider getting access to the Windows version of AutoCAD if you are a user of Mac OS.  Just a simple suggestion, not something you must do.

The thought of debugging and error handling doesn't come naturally to new and even seasoned developers, as most are simply focused on solving the problem at hand and not all the extra baggage that often goes with well written code.  Of course, well written code is in the eye of the developer that is look at it in the current moment.  Also if it isn't broken, then why change or fix a process\approach to a solution?  After many years of writing custom programs, I have learned that debugging and error handling need to be some of the very first things to consider when writing any custom program.

While I am just as guilty for jumping in (feet, hands, and compiler first) and writing code, this approach can get you to the solution faster but can lead to some bad habits and headaches down the road.  One of the things that I have found useful in getting me to slowdown and think things through more clearly is the creation of a flowchart.  If you are not already creating one today, I recommend creating a flowchart to help you visualize all the logical paths through your programs.  Flowcharts make it easier to identify choices as well as potential failure points that need to be handled.  A flowchart can also be a great way to communicate the design of a program with other that are less technical.  Products like Microsoft Visio or Lucidchart are designed to create flowcharts, but the same can be accomplished with Microsoft Word, PowerPoint, and other word processor and presentation products.

Potential failure points can be introduced when a:

• User has an opportunity to provide input
• Global variable is used
• Program relies on a specific folder structure or an external data/support file, such as a drawing or text file or Windows registry entries
• Program utilizes an ActiveX/COM or external library

AutoLISP/Visual LISP offers a variety of built-in functions and features to help you track down problems and handle errors. You can utilize the following debugging and error handling functions and features when developing your custom programs:

• Basic debug messaging - AutoLISP functions alert, prompt, print1, prin1, and princ
• Basic function tracing facilities - AutoLISP functions trace and untrace
• Visual LISP IDE (Windows only) - Breakpoints, watch window, inspect window, and trace stack
• Data validating functions - AutoLISP functions numberp, zerop, boundp, minusp, listp, vl-consp, type, vl-symbolp, and vl-file-directory-p
• Error catching - AutoLISP functions vl-catch-all-apply, vl-catch-all-error-message, and vl-catch-all-error-p
• Custom error handling - AutoLISP functions *error*, vl-exit-with-error, vl-exit-with-value, *pop-error-mode*, *push-error-using-command*, and *push-error-using-stack*
• Undo grouping - AutoCAD UNDO command allows you to begin and end an undo group so that all changes made by your program can be reverted using the AutoCAD U command

Hope you find this overview topic helpful, I plan on following up with future articles that dive more into specifics about each debugging technique and tool that I mentioned.

Sincerely,
  Lee

(Updated) Splitting A String Into A List of Elements Based on Delimiter

Update - Sample code was revised to include some additional error handling and return some basic error messages in the case of nil being passed to the function.

When working with file paths in AutoCAD, it is common that you might need to work with a string that contains multiple paths that are separated by a delimiter.  Commonly, the delimiter used to separate one path from another is a semi-colon (;).

The ACADPREFIX system variable returns a string that contains a listing of all the AutoCAD support paths.

(getvar "acadprefix")

"C:\Users\ambrosl\appdata\roaming\autodesk\autocad 2017\r21.0\enu\support;C:\program files\autodesk\autocad 2017\support;C:\program files\autodesk\autocad 2017\support\en-us;C:\program files\autodesk\autocad 2017\fonts;C:\program files\autodesk\autocad 2017\help;C:\program files\autodesk\autocad 2017\express;C:\program files\autodesk\autocad 2017\support\color;C:\Program Files\Autodesk\AutoCAD 2017\drv;"

The following code defines a function named SPLIT which breaks up a string into elements with in a list based on the delimiter specified:

;; Usage: (split (getvar "acadprefix") ";")

(defun split (sExpression sDelimiter / len val sList)
  (if (and (= (type sExpression) 'STR) (= (type sDelimiter) 'STR))
    (progn
      ; Get the length of the first item from the expression based
      ; on delimiter position
      (setq len (vl-string-position (ascii sDelimiter) sExpression))

      ; Loop until there are no more instances of the delimiter
      ; in the expression
      (while (numberp len)
        ; Get the item from the expression
        (setq val (substr sExpression 1 len))

        ; Append the item to the list
        (setq sList (cons val sList))

        ; Get the remaining part of the expression
        (setq sExpression (substr sExpression (+ 2 len)))

        ; Get the length of the next item from the string based
        ; on delimiter position
        (setq len (vl-string-position (ascii sDelimiter) sExpression))
      )

      ; Add the last value to the list
      (if (/= sExpression nil)
        (setq sList (cons sExpression sList))
      )

      ; Reverses the elements in the list and return the list
      (reverse sList)
    )
    (progn
      (if (not (= (type sExpression) 'STR))
        (prompt "\nSplit Error: First argument must be the string to split.")
      )
      (if (not (= (type sDelimiter) 'STR))
        (prompt "\nSplit Error: Second argument must be the character that represents the delimiter to use.")
      )
      (princ)
    )
  )
)

The results of using the SPLIT function on the ACADPREFIX system variable is as follows:

(split (getvar "acadprefix") ";") 

("C:\\Users\\ambrosl\\appdata\\roaming\\autodesk\\autocad 2017\\r21.0\\enu\\support" "C:\\program files\\autodesk\\autocad 2017\\support" "C:\\program files\\autodesk\\autocad 2017\\support\\en-us" "C:\\program files\\autodesk\\autocad 2017\\fonts" "C:\\program files\\autodesk\\autocad 2017\\help" "C:\\program files\\autodesk\\autocad 2017\\express" "C:\\program files\\autodesk\\autocad 2017\\support\\color" "C:\\Program Files\\Autodesk\\AutoCAD 2017\\drv" "")

The SPLIT function can also be used to separate the name of an Xref from a named style or layer name.

For example, Grid Plan|Architectural_Plan_Dim is the layer name created in a host drawing after the drawing file named Grid Plan is attached and that drawing that contains a layer named Architectural_Plan_Dim. The pipe (|) character is used to separate the Xref name from the layer name.

(split "Grid Plan|Architectural_Plan_Dim" "|")
("Grid Plan" "Architectural_Plan_Dim")

Sincerely,
  Lee

AutoCAD Platform Customization: AutoLISP

Writing a book is never an easy task and nor is trying to coordinate multiple books that will eventually be released as a single book. Like any great project, you go in with one vision and often that changes over time as the project evolves.

Last year, I started working on a project at that time which was loosley named and had a vision to cover AutoCAD customization, AutoLISP, and VBA.  All of the subjects are near and dear to me of course as well.  It is such a great feeling when you can get AutoCAD to do something for you, instead of AutoCAD making you do something for it.

There are several main differences with these books that sets them apart from others that have been published before:

• Windows and Mac OS are covered.
• AutoCAD 2006 and later releases are covered, and in most cases the books cover releases all the way back to AutoCAD 2000. When there isn't something available in a specific release, it is called out in the book.
• Latest releases of the AutoCAD program; AutoCAD 2015 on Windows and AutoCAD 2014 on Mac OS.

I wanted the books to be as complete as possible for an AutoCAD veteran, but yet reader friendly for those new to the world of AutoCAD customization and programming.

Earlier this year, the first book of the series was published under the name "AutoCAD Platform Customization: User Interface and Beyond" and it can be purchased as an eBook through the following vendors:

• Amazon
• Wiley
• iBooks (for iOS)

The second book in the series is also now available, "AutoCAD Platform Customization: AutoLISP" and it can be purchased as an eBook through the following vendors:

• Amazon
• Wiley
• Barnes & Noble
• iBooks (for iOS)

If you wanted to learn how to leverage the AutoLISP programming language to create custom programs for AutoCAD-based programs (except AutoCAD LT) this book will get you started and then some.

Here is the published description of the "AutoCAD Platform Customization: AutoLISP" book:

Streamline and customize the AutoCAD platform using AutoLISP

AutoCAD Platform Customization: AutoLISP teaches you how to customize and personalize AutoCAD, Civil 3D, Plant 3D, and other programs built on Autodesk’s industry-leading AutoCAD platform. Written by the foremost authority on AutoCAD customization, this comprehensive learning resource features detailed discussions backed by real-world examples and tutorials designed to help you harness the full potential of AutoLISP. Downloadable datasets and examples are included to ensure a functional understanding of the presented concepts.

• Learn the basics of AutoLISP, and how to author and load LSP files
• Calculate and work with values
• Create and modify graphical and nongraphical objects
• Make choices and repeat expressions
• Work with the drawing environment
• Access directories and external files
• Use the Visual LISP® editor
• Work with ActiveX/COM libraries
• Create dialog boxes

Let me know what you think if you have purchased one of these books as I would like to get your feedback.

Sincerely,
  Lee

AutoCAD Platform Customization: User Interface and Beyond (eBook)

I have spent just over 16 years now extending AutoCAD from general customization of the user interface to custom applications written with ObjectARX.  Back in 1998 and 1999, I had an opportunity to develop and deliver several AutoCAD customization classes at a local technical college which I created from the ground up; still have the binders of content to show for it.

It was a great opportunity to learn how to write and deliver content, and in many ways this eventually led me to blogging and technical writing. While that content never saw the light of day again, it did create the foundation of my customization focused articles for AUGI HotNews back in 2004 and 2005, and a number of articles I put together for AUGIWorld over the years.

Over the past 3 years, I have been in talks with a publisher to write a new AutoCAD book focused on customization and even several programming interfaces. Those talks always seemed to stale out based on projected sales which is understandable and a bummer at the same time. That all changed mid-2013 when the book was given the green light and the first of several books has been published.

This is my first book of several in a series and is titled AutoCAD Platform Customization:User Interface and Beyond. Unlike many prior customization books, this book covers both Windows and Mac OS and for the most part covers AutoCAD 2006 and later.

Here is the published description of the book:

Options for AutoCAD customization are typically the domain of administrators, but savvy users can perform their own customizations to personalize AutoCAD. Until recently, most users never thought to customize the AutoCAD platform to meet their specific needs, instead leaving it to administrators. If you are an AutoCAD user who wants to ramp up personalization options in your favorite software, AutoCAD Platform Customization: User Interface and Beyond is the perfect resource for you. Author Lee Ambrosius is recognized as a leader in AutoCAD platform customization and can help you get the most out of AutoCAD.

• Establish and manage CAD standards for the drawings you create
• Control the startup process and settings that define the drawing environment
• Modify the user interface to display the commands you use most frequently and create new commands
• Create macros to speed up frequently repeated tasks
• Define custom shapes, linetypes, and hatch patters to control the linework in a drawing
• Use real-world tips and tutorials to reinforce the author's topical discussions

The book is currently available for purchase from the Google Play store and viewed using the Google Play Books app on Android and iOS. If there is another format you are interested in, please let me know and I can pass the information along to the publisher. There is no printed version at this time, we want to hear from you if you are interested in a printed copy.

If you are looking for a general AutoCAD book, check out the AutoCAD and AutoCAD LT Bible which I have been technical editor and a contributing author since the AutoCAD 2006 edition.

Many thanks to John Wiley & Sons, Inc for the opportunity to get what I know out there in printed form.

If you have any comments, please let me know.

Sincerely,
  Lee

AutoLISP Documentation Updates - Windows and Mac

Must be Fall... and someone left the door open. So that means one of two things, I either escaped or a product was recently released.  Now time to see if the long Summer days paid off.

Some of you might have heard that AutoCAD 2014 for Mac has recently been released, but that does not mean that those on AutoCAD Windows do not have something to celebrate as well.  Of course the latest version of Microsoft's Surface has hit the streets today as well, but that is not what I am talking about.

As part of the AutoCAD documentation team, and more precisely the developer documentation, I am always looking at ways to improve the way our documentation works and the type of content that is offered.  Several of these changes can now be seen and accessed by AutoLISP developers, whether you develop for the Mac or Windows.

Below is a summary of the changes that have been recently released as part of the AutoCAD for Mac release that AutoLISP developers should enjoy. (These changes are only part of the AutoCAD for Mac Help):

• New AutoLISP navigation links. The AutoLISP documentation is much easier to locate now and navigate from the main AutoCAD Help landing page.
  
• Function Listing (by Name and Feature) - Provides you with access to AutoLISP functions not only by alphabetic names but also by feature classification.
  
  
• AutoLISP Developer's Topic Map - It is in all in the name right. Listing of all essential topics in a flat scan able page, now this page is not everything that you might need but this should help guide you in the proper direction as to what is available.
  
  
• AutoLISP is now a platform documentation set. Gone is the separate Windows and Mac AutoLISP documentation, the function reference topics now call out what platform they are supported on. This will aid in those that plan to support their programs on both platforms, and give you an understanding of what function is not supported or what the differences might be.
  
  
• Reference topics updated. As part of the updates, the function reference topics have a new look to them.  Some content on the pages have been restructured and placed under specific section titles, thereby making it easier to find information on the page. Argument listings and return values now not only provide you with a brief description like they have before, but they now include information as to the type of data is expected or will return.
  
  
• Tutorials. Ready, Set, CODE!!! While not a huge offering, there are three new tutorials that are very basic for those that are looking to get started with AutoLISP for the first time.  These are much easier to understand than the previous Garden Path tutorial for those that are new to the language, but the existing Garden Path tutorial is just a click away as well once you are ready.
• It is all in the title. Topic titles have been updated to include AutoLISP, DCL, ActiveX, Visual LISP IDE, or a combination of several to give you an idea of what the information on that topic covers.
• Help Search Filters. Switch from All Content to Developer and use the Filter button to indicate what topics you want to filter on. All of the AutoLISP topics have been updated to work with this filter now, and should help you narrow down what you are looking for if you cannot find it as part of the new function listings or the topic map.

I am sure there are some other updates that I have missed as part of this posting, but will update this posting if I remember any of the other changes that have been made.

If you like or dislike the changes made, feel free to let me know.  Feedback is important either way so we can deliver the documentation you need to be successful at what you do.  If you want to see some additional changes made in the future, please let me know as well.

Sincerely,
  Lee

Listing Defined AutoLISP Variables and Functions

AutoLISP is one of the oldest and easiest ways of extending AutoCAD, but did you ever wonder what functions are currently defined or which global variables are already set?

The ATOMS-FAMILY (not the Adams Family) function returns a list of all the symbols, global variables, and functions currently defined for use by AutoLISP.  You can also use the function to check to see if a specific symbol, global variable, and/or function is currently defined or set.  This ability to check for the existence of previous definitions is helpful if you want to see which functions are exposed before loading an AutoLISP file.

Syntax:

(atoms-family format [symbol_list])

format - Determines how the values in the returned list are formated. Valid values are 0 for Symbols or 1 for Strings.

symbol_list - Optional; List of symbols, variables, or functions to search for.

For example:

Entering (atoms-family 1) at the Command prompt returns a long list that might look like the following.

("ACTOOLBARDOCKBOTTOM" "ACET-VAR-SETVAR" "ACVIEWPORT4" "AC3IN_1FT" "VLA-ADDBOX"
...
"VLA-GET-SHOWPLOTSTYLES" "VLA-GET-NUMCELLSTYLES" "AI_RETURN" "C:SAVEALL")

The list returned is useful, but can take a while to sort through as it is not in alphabetical order or an order that will make much sense.

As mentioned previously, you can use the ATOMS-FAMILY function to test for the existence of a symbol, function, or variable by passing in a list of the items you want to see exist.  This check can be helpful if your routines depend on the definition of a function from a previously loaded file.  If the check fails, you can then load the necessary file.

For example:

Entering (atoms-family 1 '("getpoint" "getpoints" "PI")) at the Command prompt returns a long list that might look like the following.

("GETPOINT" nil "PI")

The following is some sample code that exports the symbols, functions, global variables, and commands that are defined via AutoLISP or exposted to AutoLISP from .NET/ObjectARX.  The command that is defined creates four lists, and then sorts each before exporting the definitions out.  To determine the type of definition in the list returned by ATOMS-FAMILY, I used the TYPE function and to see if a definition is prefixed with "C:" to determine which functions at like a command at the Command prompt.

After the command is ran, the number of symbols, functions, global variables, and commands is output to the Command Line window, and a file named LspDumpFile.log is created under the root of the C drive.  You can do a comparison AutoLISP definitions by exporting out what is currently defined, renamed the file created, load an AutoLISP file, and then before a second export.  To do the comparison between the files, you can use a utility like WinDiff or UltraEdit or even MS Word.

(defun c:LISPDumpFile ( / afList nSyms nFuncs nCmds nVars
                                        lstSyms lstFuncs lstCmds lstVars
                                        item fp)
    (setq afList (atoms-family 1))
    (setq nSyms 0 nFuncs 0 nCmds 0 nVars 0
             lstSyms nil lstFuncs nil lstCmds nil lstVars nil)
    (foreach item aflist
        (progn
           (cond
               ((= (type (eval (read item))) 'SYM)
                    (progn
                        (setq nSyms (1+ nSyms))
                        (if (/= lstSyms nil)
                            (setq lstSyms (append lstSyms (list item)))
                            (setq lstSyms (list item))
                        )
                    )
               )
               ((and (= (type (eval (read item))) 'SUBR) (/= (substr (strcase item) 1 2) "C:"))
                     (progn
                          (setq nFuncs (1+ nFuncs))
                          (if (/= lstFuncs nil)
                              (setq lstFuncs (append lstFuncs (list item)))
                              (setq lstFuncs (list item))
                          )                
                     )
               )
               ((and (= (type (eval (read item))) 'SUBR) (= (substr (strcase item) 1 2) "C:"))
                     (progn
                          (if (/= (strcase item) (strcase "c:LISPDumpFile"))
                              (progn
                                  (setq nCmds (1+ nCmds))
                                  (if (/= lstCmds nil)
                                      (setq lstCmds (append lstCmds (list item)))
                                      (setq lstCmds (list item))
                                  )
                              )
                          )
                     )
               )
               ((or (= (type (eval (read item))) 'REAL)
                    (= (type (eval (read item))) 'INT)
                    (= (type (eval (read item))) 'LIST)
                    (= (type (eval (read item))) 'PICKSET)
                    (= (type (eval (read item))) 'ENAME)
                    (= (type (eval (read item))) 'VLA-OBJECT)
                    (= (type (eval (read item))) 'FILE)
                    (= (type (eval (read item))) 'VARIANT)
                    (= (type (eval (read item))) 'STR))
                        (progn
                            (setq nVars (1+ nVars))
                            (if (/= lstVars nil)
                                (setq lstVars (append lstVars (list item)))
                                (setq lstVars (list item))
                            )
                        )
               )
           )
        )
    )
    ;; Output details about defined Symbols and Functions
    (prompt (strcat "\nAutoLISP Symbols and Functions count: "
                    "\nSymbols - " (itoa nSyms)
                    "\nFunctions - " (itoa nFuncs)
                    "\nGlobal Variables - " (itoa nVars)
                    "\nCommands - " (itoa nCmds))
    )
    (setq fp (open "c:\\LspDumpFile.log" "w"))
    (write-line "Symbols" fp)
    (setq lstSyms (acad_strlsort lstSyms))
    (foreach item lstSyms
        (write-line item fp)
    )
    (write-line "" fp)
    (write-line "Functions" fp)
    (setq lstFuncs (acad_strlsort lstFuncs))
    (foreach item lstFuncs
        (write-line item fp)
    )
    (write-line "" fp)
    (write-line "Global Variables" fp)
    (setq lstVars (acad_strlsort lstVars))
    (foreach item lstVars
        (write-line item fp)
    )
    (write-line "" fp)
    (write-line "Commands" fp)
    (setq lstCmds (acad_strlsort lstCmds))
    (foreach item lstCmds
        (write-line item fp)
    )
    (close fp)
  (princ)
)

The following is a sampling of the LOG file that is generated.

Symbols
*LAST-VALUE*
:AUTOLISP
...

Functions
-
*
*ERROR*
*MERR*
...

Global Variables
AC0DEGREES
AC1_1
AC1_10
...

Commands
C:-BLOCKREPLACE
C:-BLOCKTOXREF
C:-CDORDER
...

Sincerely,
  Lee

External Link of Interest:
Commands that “work” in the AutoCAD 2013 Core Console - Through the Interface (by Kean Walmsley)

 

Getting User Input with AutoLISP and Handling ESC

AutoLISP is a great language for combining a few basic AutoCAD commands together or creating complex logic. To get the most out of AutoLISP, you will need to request input from the user and the type of input you need will depend on which AutoCAD commands or functions you are using.

This article is not about the individual input functions themselves, but how to handle the dreaded ESC key when the user is being prompted for input.

NOTE: This topic does apply to AutoCAD on Windows and Mac.

The following sample code shows the use of the INITGET and GETPOINT AutoLISP functions.  If you load and run the code in AutoCAD it will allow you to pick a point or Line or Circle as a keyword.  When being prompted, press ESC and the message "Completed successfully." is never displayed because the AutoLISP function was terminated.

(defun c:GetInputNoErrHandling( / returnPnt)
    ;; Define the valid keywords
    (initget 128 "Line Circle")
   
    ;; Get the user input
    (setq returnPnt (getpoint "Enter a point [Line/Circle]: "))

    (if (/= returnPnt nil)
        (cond
            ((= (type returnPnt) 'LIST)
                (alert (strcat "User provided the point: "
                               (rtos (nth 0 returnPnt) 2) ", "
                               (rtos (nth 1 returnPnt) 2) ", "
                               (rtos (nth 2 returnPnt) 2)))
            )
            ((= (type returnPnt) 'STR)
                (alert (strcat "User selected the keyword: " returnPnt))
            )          
        )
        (alert "No point was picked.")
    )
  (alert "Completed sucessfully!")
)

For many, this is a deal breaker in their code as they often leave system variables changed or tasks uncompleted.  To help clean this up, you can introduce an error handler block that helps to catch the error so you can make any changes as needed to end as graceful as possible.  The error handler block is a new function that AutoCAD calls and is named *error*.The downside to this approach is that you have stepped out of the main execution of your code so there really is no easy way to pick up the pieces and continue on.

The following shows a very basic example of the error handler block. Now when the user presses ESC when being prompted for input, the GetPoint function ends but you get a message about the error that is generated indicating a point you could clean things up in as needed.

(defun c:GetInputErrHandlingBlock( / returnPnt)
    (setq old_err *error*)

    (defun *error* (err_msg)
       (alert (strcat "Error: " err_msg))
       (setq *error* old_err)
    )
 
    ;; Define the valid keywords
    (initget 128 "Line Circle")
   
    ;; Get the user input
    (setq returnPnt (getpoint "Enter a point [Line/Circle]: "))

    (if (/= returnPnt nil)
        (cond
            ((= (type returnPnt) 'LIST)
                (alert (strcat "User provided the point: "
                               (rtos (nth 0 returnPnt) 2) ", "
                               (rtos (nth 1 returnPnt) 2) ", "
                               (rtos (nth 2 returnPnt) 2)))
            )
            ((= (type returnPnt) 'STR)
                (alert (strcat "User selected the keyword: " returnPnt))
            )          
        )
        (alert "No point was picked.")
    )
  (alert "Completed sucessfully!")
  (setq *error* old_err)
)

The final example is the best approach, but is the least commonly used approach from what I have seen among AutoLISp developers.  This approach uses the VL-CATCH-ALL-APPLY and VL-CATCH-ALL-ERROR-MESSAGE functions.  Instead of being forced out of your main function when the user presses ESC, you have the ability to trap the error and handle right there.  You could still use the error handler block for truly unexpected errors, but you should always code for things you know a user might encounter or do.  Pressing ESC is a common thing users do in AutoCAD, so you should handle it.

When the following code is loaded and executed, pressing ESC is caught and handled properly so the code can finish as expected.

(defun c:GetInputWithErrCatching( / returnPntOrErr)
    ;; Define the valid keywords
    (initget 128 "Line Circle")
   
    ;; Get the user input
    (setq returnPntOrErr (vl-catch-all-apply 'getpoint (list "Enter a point [Line/Circle]: ")))
 
    (if (= (type returnPntOrErr) 'VL-CATCH-ALL-APPLY-ERROR)
        (alert (strcat "Error: " (vl-catch-all-error-message returnPntOrErr)))
        (cond
            ((= returnPntOrErr nil)
               (alert "No point was picked.")
            )         
            ((= (type returnPntOrErr) 'LIST)
               (alert (strcat "User provided the point: "
                              (rtos (nth 0 returnPntOrErr) 2) ", "
                              (rtos (nth 1 returnPntOrErr) 2) ", "
                              (rtos (nth 2 returnPntOrErr) 2)))
            )
            ((= (type returnPntOrErr) 'STR)
               (alert (strcat "User selected the keyword: " returnPntOrErr))
            )          
        )
    )
  (alert "Completed sucessfully!")
)

Sincerely,
  Lee

Creating Objects without the COMMAND Function in AutoCAD

The ENTMAKE and ENTMAKEX functions are often forgotten elements of the AutoLISP programming environment because the use of the COMMAND function to call a command line LINE and CIRCLE are so tempting and easy.  Why reinvent the wheel if you do not need to, or in this case the functionality.

Both ENTMAKE and ENTMAKEX allow you to create new graphical and non-graphical objects without using the COMMAND function. This allows you to create a line and assign it a specific layer without first changing the layer with the Layer command and then calling the Line command to create the line and then restore the previous layer.  Not bad, but if you think about it further you need to turn off command echoing (CMDECHO) to keep the command line clean, drawing off screen or outside the drawing limits at times, and worry about the current running object snaps.

So after writing a few articles on the SETPROPERTYVALUE and GETPROPERTYVALUE functions the last few days I decided to go one step further and show how to create some new objects without the COMMAND function and then update their properties.  The following sample shows how to create a line, circle, and layer prior to updating their properties.

NOTE: The helper function (AddObj) does all the object creation work.

;; Begin Code
;; Create a new layer and change its plowable state, then
;; create a new line and circle without using the command function
;; 8/20/11 - Lee Ambrosius
(defun c:newObjects ( / layEnt newObj)
  ;; Create a new Layer named Const if it does not exist
  (if (= (setq layEnt (tblobjname "layer" "Const")) nil)
    (progn
      (setq layEnt (addobj "Layer"))
      
      ;; Update the new layers name
      (setpropertyvalue layEnt "Name" "Const")

      ;; Set the color of the new layer
      ;; Color can be ACI (6), true color (125,125,125),
      ;; or color book (PANTONE+ CMYK Coated,PANTONE P 1-3 C)
      (setpropertyvalue layEnt "Color" "231,18,18")

      ;; Set the layer so it cannot be plotted
      (setpropertyvalue layEnt "IsPlottable" 0)
    )
  )

  ;; Create a new line
  (setq newObj (addObj "Line"))

  ;; Set the start and end point
  (setpropertyvalue newObj "StartPoint" '(0.0 0.0 0.0))
  (setpropertyvalue newObj "EndPoint" '(5.0 5.0 0.0))

  ;; Change the layer of the new line
  (setpropertyvalue newObj "LayerID" layEnt)

  ;; Create a new circle
  (setq newObj (addObj "Circle"))

  ;; Set the start and end point
  (setpropertyvalue newObj "Center" '(5.0 5.0 0.0))

  ;; Change the layer of the new line
  (setpropertyvalue newObj "LayerID" layEnt)

 (princ)
)

;; Helper function to create the initial object without using the commands
(defun addObj (objType / newObj)
  (setq newObj nil)

  (cond
    ((= (strcase objType) "LINE")
        (setq newObj (entmakex '((0 . "LINE")
                                               (10 0.0 0.0 0.0) ; Start point
                                               (11 1.0 1.0 1.0) ; End point
                             ))
        )
    )
    ((= (strcase objType) "CIRCLE")
        (setq newObj (entmakex '((0 . "CIRCLE")
                                               (10 0.0 0.0 0.0) ; Center point
                                               (40 . 1.0) ; Radius
                             ))
        )
    )
    ((= (strcase objType) "LAYER")
        (setq newObj (entmakex (list (cons 0 "LAYER")
                                                    (cons 100 "AcDbSymbolTableRecord")
                                                    (cons 100 "AcDbLayerTableRecord")
                                                    (cons 2 (strcat "TEMP-" (rtos (getvar "CDATE") 2 8))) ; Name
                                                    (cons 70 0) ; State
                                                    (cons 62 7) ; Color
                                                    (cons 6 "Continuous") ; Linetype
                             ))
         )
    )
  )

 ;; Return the new object
 newObj
)

(prompt "\nType NEWOBJECTS to create a new line, circle, and layer without the COMMAND function.") 
;; End Code

Sincerely,
  Lee 

Accessing Information About Layers in a Drawing with GETPROPERTYVALUE

AutoCAD 2012 and AutoCAD 2012 for Mac has four new functions that essentially allow you to access object properties without the use of the COM API (Windows only) or dig around for a DXF code.  I covered the basics of these functions in the article New AutoLISP Functions in AutoCAD 2012 for Mac, but a few questions have come up about accessing non-graphical information such as Layers and Blocks.

The following example shows how to access the Layers table and then step through each layer in a drawing and return some information about the layer.

;; Begin Code
;; Outputs some general information about all the layers in a drawing
;; 8/19/11 - Lee Ambrosius
(defun c:LayInfo ( / )
  ;; Get the first layer in the LAYER symbol table
  (setq layTblEntry (tblnext "LAYER" T))

  ;; Loop while there are still layers
  (while layTblEntry
    ;; Get the layer and entity name of the layer
    (setq layName (cdr (assoc 2 layTblEntry)))
    (setq layTblEnt (tblobjname "layer" layName))

    ;; Use (dumpallproperties layTblEnt) to see what layer properties are available

    ;; Output some general layer info
    (prompt "\n_")
    (outputProp "Name" "Name" layTblEnt)
    (outputProp "Color" "Color" layTblEnt)
    (outputProp "Frozen" "IsFrozen" layTblEnt)
    (outputProp "Locked" "IsLocked" layTblEnt)
    (outputProp "Plottable" "IsPlottable" layTblEnt)
    (outputProp "LineWeight" "LineWeight" layTblEnt)

    ;; Get the linetype name
    (setq linetypeTblEnt (getpropertyvalue layTblEnt "LinetypeObjectID"))
    (outputProp "Linetype" "Name" linetypeTblEnt)

    ;; Get the next layer in the symbol table
    (setq layTblEntry (tblnext "LAYER"))
  )
 (princ)
)

;; Function used to output property information to the Command Line
(defun outputProp (infoTag propName ent / )
  (prompt (strcat "\n" infoTag ": "))
  (princ (getpropertyvalue ent propName))
 (princ)
)

(prompt "\nType LAYINFO to output information about the layers in the drawing.")
;; End Code 

Sincerely,
  Lee 

New AutoLISP Functions in AutoCAD 2012 for Mac

If you are planning to upgrade to AutoCAD 2012 for Mac (or AutoCAD 2012 on Windows) and use AutoLISP, there is some exciting news. One of the best features of the new release is the ability to access and modify object properties with a set of 4 new functions. The functions can be used to access both graphical and non-graphical objects in a drawing. The functions are not available in earlier releases and are a nice alternative to using the VLAX functions that are only available in AutoCAD 2012 on Windows.

The 4 new functions are:

• dumpallproperties - Outputs all the properties and their current value for the specified entity.
• getpropertyvalue - Returns the current value of the specified property for an entity.
• ispropertyreadonly - Returns T or nil of the specified property for an entity is read-only or not.
• setpropertyvalue - Sets the specified property to a new value for an entity. 

Now that you have 4 new functions just burning a hole in your code, the following helps you to using these new functions to change the background mask color of a dimension or multiline text object. The code also outputs the current background mask color before asking you to turn the background mask on or off.

*NOTE: Much of the desired error handling is not present in the sample code.*

To get started, you use the DUMPALLPROPERTIES function with the type of object you want to work with. Properties like Layer, Color, and Linetype are consistent across all graphical objects.  Add the objects you want to work with your drawing, for this example I added a linear dimension and multiline text object. After the objects are in the drawing, enter the following at the Command prompt to see a list of all available properties for an object:

(setq ent (car (entsel "\nSelect a dimension or multiline text object: ")))
(dumpallproperties ent)

You should see a listing of properties, data types, and values. For a multiline text object, the background mask behavior is controlled by 5 properties:

• BackgroundFill - A background fill is used or not
• BackgroundFillColor - The color of the background fill
• BackgroundScaleFactor - The factor used to control how far out from the text the fill should go
• BackgroundTransparency - The transparency level of the background fill
• UseBackgroundColor - Background fill color uses the drawing background to get the color for the fill

If no background fill was applied to the multiline text object, you will see the values of 'Failed to get value' and that is normal because the property is not set yet. Turning on Background Mask for the text object and running DUMPALLPROPERTIES again will reflect the current values assigned to the multiline text object.

For dimensions, you use the following properties to control the use of background masking:

• Dimtfill - A background fill is used or not
• Dimtfillclr - The color of the background fill

The ISPROPERTYREADONLY is used to test if a property is read-only or not before trying to update its value using the SETPROPERTYVALUE function.

The following sample shows the use of the GETPROPERTYVALUE and SETPROPERTYVALUE functions.

;; Update the fill color for a dimension or multiline text object
(defun c:bfill ( / ent objType bFill bFillClr bFillScale bFillTrans bUseBackClr kWord)
  ;; Get the object
  (setq ent (car (entsel "\nSelect a dimension or multiline text object: ")))

  ;; Check to see if an object was selected
  (if (/= ent nil)
    (progn

      ;; Get the type of object
      (setq objType (cdr (assoc 0 (entget ent))))

      ;; Output current background property values
      (if (= objType "MTEXT")
        (progn
          (setq bFill (getpropertyvalue ent "BackgroundFill"))
          (outputPropValue "BackgroundFill" bFill)

          (setq bFillClr (getpropertyvalue ent "BackgroundFillColor"))
          (outputPropValue "BackgroundFill" bFillClr)

          (setq bFillScale (getpropertyvalue ent "BackgroundScaleFactor"))
          (outputPropValue "BackgroundFill" bFillScale)

          (setq bFillTrans (getpropertyvalue ent "BackgroundTransparency"))
          (outputPropValue "BackgroundFill" bFillTrans)

          (setq bUseBackClr (getpropertyvalue ent "UseBackgroundColor"))
          (outputPropValue "UseBackgroundColor" bUseBackClr)
        )
        (progn
          (setq bFill (getpropertyvalue ent "Dimtfill"))
          (outputPropValue "Dimtfill" bFill)

          (setq bFillClr (getpropertyvalue ent "Dimtfillclr"))
          (outputPropValue "Dimtfillclr" bFillClr)
        )
      )

      ;; Prompt the user to turn background masking on or off
      (initget 0 "ON OFF")
      (setq kWord (getkword "\nEnable Background masking [ON/OFF]: "))

      ;; Toggles background mask on or off, when turning it on set it to cyan 
      (if (= objType "MTEXT")
        (progn
          (if (= kWord "ON")
            (progn
              (setpropertyvalue ent "BackgroundFill" 1)
              (setpropertyvalue ent "BackgroundFillColor" 4)
              (setpropertyvalue ent "UseBackgroundColor" 0)
            )
            (setpropertyvalue ent "BackgroundFill" 0)
          )
        )
        (progn
          (if (= kWord "ON")
            (progn
              (setpropertyvalue ent "Dimtfill" 2)
              (setpropertyvalue ent "Dimtfillclr" 4)
            )
            (setpropertyvalue ent "Dimtfill" 0)
          )
        )
      )
    )
  )

 (princ)
)

;; Function used to output property name and value to the Command Line
(defun outputPropValue (propName propValue / )
  (terpri)
  (prompt (strcat propName ": "))
  (princ propValue)
 (princ)
)

(prompt "\nType BFILL to use the background fill command.")

Sincerely,
  Lee