CHAPTER

Introduction to Dialog Control Language (DCL)

Learning Objectives
After completing this chapter, you will be able to: Describe the types of files that control dialog boxes. Define the components of a dialog box. Write a DCL file for a basic dialog box. Write an AutoLISP file to control a dialog box. Associate an action with a dialog box tile. Programmable dialog boxes can be used to completely customize the interface of AutoLISP programs. These dialog boxes allow LISP programs to work like many of AutoCADs built-in functions. Using dialog boxes improves efficiency and reduces data-entry errors. Dialog boxes minimize the amount of typing required by the user. Rather than answering a series of text prompts on the command line, the user selects options from the dialog box. Dialog box fields can be filled in by the user in any order. While the dialog box is still active, the user can revise values as necessary. AutoLISP provides basic tools for controlling dialog boxes, but the dialog box itself must be defined using the Dialog Control Language (DCL). The definition is written to an ASCII file with a .dcl file extension. When creating and editing DCL files, the Visual LISP Editor provides many helpful tools, including color coding. This chapter is only an introduction to DCL. It covers basic DCL file construction and a few common tile types. For more information, refer to the online help documentation.

DCL File Formats

A DCL file is formatted as an ASCII text file with a .dcl file extension. These files can have any valid file name, but a file name with 1 to 8 characters is recommended. Writing DCL is easy. Many of the components of a DCL file are normal English words. The components of a dialog boxsuch as edit boxes, images, and drop-down listsare referred to as tiles. Tiles are defined by specifying various attribute values. Each attribute controls a specific property of the tile, such as size, location, and default values.
Copyright by Goodheart-Willcox Co., Inc.

Chapter 29 Introduction to Dialog Control Language (DCL)

AutoCAD and Its ApplicationsAdvanced 690

Figure 29-1. A portion of the acad.dcl file.

acad_snap : dialog { label = "Drawing Aids"; : row { : column { : boxed_column { label = "Modes"; : toggle { label = "&Ortho"; key = "ortho"; } : toggle { label = "Solid &Fill"; key = "fill"; }

Dialog definition Label attribute adds a text string

Key attribute identifies a text string that associates the dialog tile with an AutoLISP function

When writing a DCL file, you do not use parentheses as you do with AutoLISP. When defining a dialog box or tile, all of the required attributes are placed within {braces}. As with AutoLISP programs, indentation helps to separate individual elements, making the file more readable. Comments are preceded by two forward slashes (//). Semicolons are used at the end of an attribute definition line. To view an example of DCL code, open the acad.dcl and base.dcl files in a text editor. These two files are found in the users \Support folder, not the AutoCAD \Support folder. A portion of the acad.dcl file is shown in Figure 29-1.

CAUTION
The base.dcl le contains standard prototype denitions. The acad.dcl le contains denitions for dialog boxes used by AutoCAD. Do not edit either one of these les! Altering them can cause AutoCADs built-in dialog boxes to crash.

AutoLISP and DCL

A DCL file simply defines a dialog box. The dialog box cannot actually do anything without a controlling application. AutoLISP is frequently used to control dialog sessions. This section shows examples using the AutoLISP dialog-handling functions. In order to display a dialog box, the controlling AutoLISP application must first load the dialog definition. The AutoLISP (load_dialog) function loads the specified dialog definition file: (load_dialog "file name.dcl") The file name is enclosed in quotation marks. The (load_dialog) function returns a positive integer that identifies the loaded DCL file. If the attempted load was unsuccessful, a negative integer is returned. The next step is to activate a specific dialog box definition contained within the DCL file. The AutoLISP (new_dialog) function activates the dialog box specified, where dlgname is the name of the dialog box: (new_dialog dlgname dcl_id) This function is case sensitive. Suppose the dialog definition is named main. Specifying Main or MAIN will not activate this dialog box since the text string does not exactly match. The dcl_id argument represents the integer value returned by (load_dialog). This value is often assigned to a variable, as you will see later. The (new_dialog) function also supports additional, optional arguments, which are not discussed here.
Copyright by Goodheart-Willcox Co., Inc.

Chapter 29 Introduction to Dialog Control Language (DCL)

AutoCAD and Its ApplicationsAdvanced 691

To actually begin accepting input from the user, the AutoLISP (start_dialog) function must be used:
(start_dialog)

This function has no arguments. It allows input to be received from the dialog box initialized by the previous (new_dialog) expression. With these basic AutoLISP functions, it is possible to display the dialog box shown in Figure 29-2. You will create this dialog box in the next section. After the AutoLISP program is written and saved, it can be loaded into AutoCAD using the load function or the APPLOAD command. Enter the controlling AutoLISP application named EXAMPLE1.LSP as follows.
(setq EX1_DCL_ID (load_dialog "EXAMPLE1.DCL")) (if (not (new_dialog "main" EX1_DCL_ID)) (exit) ) (start_dialog)

Now, take a closer look at the controlling code for this dialog box:
(setq EX1_DCL_ID (load_dialog "EXAMPLE1.DCL")) (if (not (new_dialog "main" EX1_DCL_ID)) (exit) ) (start_dialog)

This expression loads the dialog definition found in EXAMPLE1.DCL and assigns the value returned by (load_dialog) to the variable EX1_DCL_ID.
(setq EX1_DCL_ID (load_dialog "EXAMPLE1.DCL")) (if (not (new_dialog "main" EX1_DCL_ID)) (exit) ) (start_dialog)

If (new_dialog) is unable to activate the specified dialog box for any reason, the expression in the next three lines exits (terminates) the application. This is an important safety feature. In many cases, loading an incorrect or incomplete definition can cause your system to lock up and may require the system to be rebooted.
(setq EX1_DCL_ID (load_dialog "EXAMPLE1.DCL")) (if (not (new_dialog "main" EX1_DCL_ID)) (exit) ) (start_dialog)

The last expression opens the dialog box indicated by the previous (new_dialog) expression. Once the descriptions within a specific DCL file are no longer needed, they can be removed from memory using the AutoLISP (unload_dialog) function.
(unload_dialog dcl_id)

Do not unload a dialog definition until your application is finished using the DCL file. Otherwise, your application may fail to properly function.
Figure 29-2. A sample custom dialog box.

Text item

Title bar Predefined button

Copyright by Goodheart-Willcox Co., Inc.

Chapter 29 Introduction to Dialog Control Language (DCL)

AutoCAD and Its ApplicationsAdvanced 692

DCL Tiles
Your work in AutoCAD has provided you with a good background in how dialog boxes function. By now, you should be familiar with the use of buttons, edit boxes, radio buttons, and list boxes. This will be helpful as you design dialog interfaces for your AutoLISP programs. DCL tiles are used individually or combined into structures called clusters. For example, a series of button tiles can be placed in a column tile to control the arrangement of the buttons in the dialog box. The primary tile is the dialog box itself. The best way to begin understanding the format of a DCL file is to study a simple dialog box definition. The following DCL code defines the dialog box shown in Figure 29-2.
main : dialog { label = "Dialog Box Example 1"; : text_part { value = "This is an example."; } ok_only; }

Now, take a closer look at the definition of this dialog box. The dialog definition is always the first tile definition.
main : dialog { label = "Dialog Box Example 1"; : text_part { value = "This is an example."; } ok_only; }

Everything within the braces defines the features of the dialog box. The word main indicates the name of the dialog box within the code. This name is referenced by the controlling AutoLISP application. A colon (:) precedes all tile callouts. In the case of a dialog tile, the colon separates the name from the tile callout.
main : dialog { label = "Dialog Box Example 1"; : text_part { value = "This is an example."; } ok_only; }

The label attribute of the dialog tile controls the text that appears in the title bar of the dialog box. The line is terminated with a semicolon. All attribute lines must be terminated with a semicolon.
main : dialog { label = "Dialog Box Example 1"; : text_part { value = "This is an example."; } ok_only; }

Copyright by Goodheart-Willcox Co., Inc.

Chapter 29 Introduction to Dialog Control Language (DCL)

AutoCAD and Its ApplicationsAdvanced 693

The text_part tile allows placement of text items in a dialog box. The value attribute is used to specify the text that is displayed. Just as with the dialog tile, all of the attributes are defined between braces.
main : dialog { label = "Dialog Box Example 1"; : text_part { value = "This is an example."; } ok_only; }

There are many predefined tiles and subassemblies in the base.dcl file. A subassembly is a cluster of predefined tiles, such as ok_cancel and ok_help. The ok_only tile places an OK button at the bottom of the dialog box, as shown in Figure 29-2. The statement is not preceded by a colon because it is not a specific definition. This line is terminated with a semicolon, just like an attribute. Braces are not required because the statement is a reference to a predefined tile, rather than a tile definition. Once you have defined a dialog box, the definition must then be saved in a DCL file. For this example, the dialog definition above should be saved in the file EXAMPLE1.DCL. This is treated as any other support file and should be saved in the AutoCAD support path. For examples of other DCL functions, look at the Viewpoint Presets dialog box shown in Figure 29-3. Various tiles of this dialog box are identified with the corresponding
Figure 29-3. Some of the tile definitions and attributes associated with the Viewpoint Presets dialog box (this dialog box is no longer defined by a DCL file).
ddvpoint : dialog { aspect_ratio = 0; label = "Viewpoint Presets"; fixed_height = true; fixed_width = true; : column { : row { : text { label = "Set Viewing Angles"; key = "ddvp_header"; } } : row { fixed_width = true; fixed_height = true; : image_button { alignment = top; fixed_width = true; fixed_height = true; key = "ddvp_image"; width = 39; height = 12; color = 0; is_tab_stop = false; } } : row { : button { label = "Set to Plan View"; key = "ddvp_set_plan"; mnemonic = "V"; } } }
Copyright by Goodheart-Willcox Co., Inc.

: row { : radio_row { : radio_button { label = "Absolute to WCS"; key = "ddvp_abs_wcs"; mnemonic = "W"; value = "1"; } : radio_button { label = "Relative to UCS"; key = "ddvp_rel_ucs"; mnemonic = "U"; } } }

spacer_1; ok_cancel_help_errtile; }

: row { : edit_box { label = "From: X Axis:"; mnemonic = "A"; key = "ddvp_val_x"; fixed_width = true; edit_width = 6; } : edit_box { label = "XY Plane:"; mnemonic = "P"; key = "ddvp_val_xyp"; fixed_width = true; edit_width = 6; } }

Chapter 29 Introduction to Dialog Control Language (DCL)

AutoCAD and Its ApplicationsAdvanced 694

DCL code needed to define the tile. In older releases of AutoCAD, this dialog box was defined by a stand-alone DCL file named ddvpoint.dcl. However, this DCL file no longer exists as the dialog box is now defined by a different method.

Exercise 29-1
Complete the exercise on the student website.
www.g-wlearning.com/CAD

Associating Functions with Tiles

Most tiles can be associated with actions. These actions vary from run-time error checking to performing tasks outside of the dialog box session. The (action_tile) AutoLISP function provides the basic means of associating tiles with actions.
(action_tile "key" "action-expression")

The key references the attribute assigned in the DCL file. The action-expression is the AutoLISP expression performed when the action is called. When the desired action requires a large amount of AutoLISP code, it is best to define a function to perform the required tasks. This function is then called within the action-expression. Both the key and action-expression arguments are supplied as text strings. In order to access a specific tile from AutoLISP, the key of the tile must be referenced. The key is specified as an attribute in the DCL file. Tiles that are static (no associated action) do not require keys. Any tile that must be referenced in any way such as setting or retrieving a value, associating an action, or enabling/disabling the tilerequires a key. The next example changes the previous dialog box by adding a button that displays the current time when picked. The new or changed DCL code is shown in color. Save this file as EXAMPLE2.DCL.
main : dialog { label = "Dialog Box Example 2"; : text_part { value = ""; key = "time"; } : button { key = "update"; label = "Display Current Time"; mnemonic = "C"; } ok_only; }

Copyright by Goodheart-Willcox Co., Inc.

Chapter 29 Introduction to Dialog Control Language (DCL)

AutoCAD and Its ApplicationsAdvanced 695

Notice the addition of a key attribute to the text_part tile. This allows access by the AutoLISP application while the dialog box is open. Another addition is the button tile. A key attribute is provided in the button tile so an association can be created in the AutoLISP program with an action-expression argument. The label attribute provides the text displayed on the button. The mnemonic attribute underlines the specified letter within the label to allow keyboard access. The AutoLISP application used to manage this dialog session is as follows. Save the program as EXAMPLE2.LSP.
(setq EX2_DCL_ID (load_dialog "EXAMPLE2.DCL")) (if (not (new_dialog "main" EX2_DCL_ID)) (exit) ) (defun UPDTILE () (setq CDVAR (rtos (getvar "CDATE") 2 16) CDTXT (strcat "Current Time: " (substr CDVAR 10 2) ":" (substr CDVAR 12 2) ":" (substr CDVAR 14 2) ) ) (set_tile "time" CDTXT) ) (UPDTILE) (action_tile "update" "(UPDTILE)") (start_dialog)

The dialog box displayed by this code is shown in Figure 29-4. The time button displays the current time when the button is picked. The mnemonic character is displayed once the [Alt] key is pressed. Note: Some AutoLISP functions not covered in this text are used in the above programming to retrieve and display the current time. Commands that change the display or require user input (outside of the dialog box interface) cannot be used while a dialog box is active. These AutoLISP functions cannot be used with DCL:
command entdel entmake entmod entsel entupd getangle getcorner getdist getint getkword getorient getpoint getreal getstring graphscr grclear grdraw grread grtext grvecs menucmd nentsel osnap prompt redraw ssget (interactive) textpage textscr

Exercise 29-2
Complete the exercise on the student website.
www.g-wlearning.com/CAD

Figure 29-4. The dialog box defined by

EXAMPLE2.DCL

and controlled by
EXAMPLE2.LSP. Mnemonic attribute is underlined
Copyright by Goodheart-Willcox Co., Inc.

Label attribute from button tile

Chapter 29 Introduction to Dialog Control Language (DCL)

AutoCAD and Its ApplicationsAdvanced 696

Working with DCL

There are many types of DCL tiles available. You can provide edit boxes for users to directly enter information, such as numeric or text information. You can create lists and drop-down lists to allow users to choose from preset selections. You can also add buttons to provide a simple means of initiating an action. Images can be used to enhance dialog boxes. For example, you can place company or personal logos in your dialog boxes. An interactive image, such as the one that appears in the Viewpoint Presets dialog box shown in Figure 29-3, can also be used. Tools such as text tiles, sliders, and clusters are used to control the layout of tiles in a dialog box. A wide variety of attributes are available for controlling the appearance and function of a dialog session. In addition, several AutoLISP functions are provided to control your dialog session. You can disable or enable tiles and change the active tile. It is even possible to change the value or state of a tile based on an entry in another tile. You have already seen two examples of dialog boxes created using DCL and AutoLISP. The following sections provide two additional applications that use various dialog boxes. Study these examples for additional insight into the creation of dialog boxes. Be sure to have an appropriate reference handy, such as the online documentation, to look up DCL and AutoLISP terms. You can adapt or modify these programs to produce dialog sessions of your own.

Dialog Example 3
Create the following DCL and AutoLISP programs. Save the programs as
EXAMPLE3.DCL and EXAMPLE3.LSP. Then, load the AutoLISP program file. To open the dialog box, type DRAW. The dialog box is shown in Figure 29-5. ;EXAMPLE3.LSP ;This file displays the dialog box defined in EXAMPLE3.DCL and begins the ; selected drawing command as specified by the user. ; (defun C:DRAW (/ EX3_DCL_ID) (setq EX3_DCL_ID (load_dialog "EXAMPLE3.DCL")) (if (not (new_dialog "draw" EX3_DCL_ID)) (exit) ) (action_tile "line" "(setq CMD $key) (done_dialog)") (action_tile "circle" "(setq CMD $key) (done_dialog)") (action_tile "arc" "(setq CMD $key) (done_dialog)") (action_tile "cancel" "(setq CMD nil) (done_dialog)") (start_dialog) (unload_dialog EX3_DCL_ID) (command CMD) )

Figure 29-5. The dialog box displayed using the EXAMPLE3 DCL and LSP files.

Copyright by Goodheart-Willcox Co., Inc.

Chapter 29 Introduction to Dialog Control Language (DCL)

AutoCAD and Its ApplicationsAdvanced 697

//EXAMPLE3.DCL //Defines a dialog box that presents three drawing options to the user. // draw : dialog { label = "Select Drawing Option"; : text_part { label = "Select object type to draw: "; } : row { : button { key = "line"; label = "Line"; mnemonic = "L"; fixed_width = true; } : button { key = "circle"; label = "Circle"; mnemonic = "C"; fixed_width = true; } : button { key = "arc"; label = "Arc"; mnemonic = "A"; fixed_width = true; } : button { key = "cancel"; label = "Cancel"; is_cancel = true; fixed_width = true; } } }

Copyright by Goodheart-Willcox Co., Inc.

Chapter 29 Introduction to Dialog Control Language (DCL)

AutoCAD and Its ApplicationsAdvanced 698

Dialog Example 4
This example allows you to select a new current layer from a drop-down list in a dialog box. Save the files as EXAMPLE4.DCL and EXAMPLE4.LSP. Then, load the AutoLISP file. To access the dialog box, type GOFOR. The dialog box is shown in Figure 29-6.
;;EXAMPLE4.LSP ;; (defun CHECKOUT () (setq LD (tblsearch "LAYER" (nth (atoi (get_tile "lyr_pop")) LL)) LN (cdr (assoc 2 LD)) LS (cdr (assoc 70 LD)) ) (if (and (/= 1 LS) (/= 65 LS) ) (progn (setvar "CLAYER" (nth (atoi (get_tile "lyr_pop")) LL)) (done_dialog) ) (alert "Selected layer is frozen!") ) ) (defun C:GOFOR () (setq EX4_DCL_ID (load_dialog "EXAMPLE4.DCL")) (if (not (new_dialog "fourth" EX4_DCL_ID)) (exit)) (start_list "lyr_pop") (setq LL '() NL (tblnext "LAYER" T) IDX 0 ) (while NL (if (= (getvar "CLAYER") (cdr (assoc 2 NL))) (setq CL IDX) (setq IDX (1+ IDX)) ) (setq LL (append LL (list (cdr (assoc 2 NL)))) NL (tblnext "LAYER") ) ) (mapcar 'add_list LL) (end_list) (set_tile "lyr_pop" (itoa CL)) (action_tile "lyr_pop" "(if (= $reason 4) (mode_tile \"accept\" 2))") (action_tile "accept" "(CHECKOUT)") (start_dialog) (unload_dialog EX4_DCL_ID) (princ) )

Figure 29-6. The dialog box displayed using the EXAMPLE4 DCL and LSP files.
Copyright by Goodheart-Willcox Co., Inc.

Chapter 29 Introduction to Dialog Control Language (DCL)

AutoCAD and Its ApplicationsAdvanced 699

//EXAMPLE4.DCL // Presents a list of layers to the user. fourth : dialog { label = "Select Layer"; : popup_list { label = "New Current Layer:"; mnemonic = "N"; key = "lyr_pop"; allow_accept = true; width = 32; } ok_cancel; }

Chapter Test
Answer the following questions. Write your answers on a separate sheet of paper or complete the electronic chapter test on the student website.
www.g-wlearning.com/CAD

1. What are the two types of files that must be created to construct a functioning dialog box? 2. When referring to a dialog box, what is a tile? 3. When defining a dialog or tile, inside of which character are all of the required attributes for a tile definition placed? 4. Which symbol indicates a comment inside of a DCL file? 5. Write the appropriate notation for the first line of a DCL file that defines a dialog box named Test. 6. Write the appropriate notation in a DCL file that defines the text in the title bar of a dialog box named Select Application. 7. Write the notation in a DCL file for defining a cluster of four buttons labeled OK, Next, Cancel, and Help. 8. Write the notation that would appear in a LSP file that loads a dialog file named PICKFILE. 9. What is a key in a DCL file? 10. Write the proper DCL file notation for the first line that identifies a button.

Copyright by Goodheart-Willcox Co., Inc.

Chapter 29 Introduction to Dialog Control Language (DCL)

AutoCAD and Its ApplicationsAdvanced 700

Drawing Problems
1. Create a dialog box that contains the following items. Write the required DCL and AutoLISP files. A. Title barDialog Box Test B. LabelThis is a test. C. Contains an OK button

2. Create a dialog box that contains the following items. Write the required DCL and AutoLISP files. A. Title barDate B. LabelCurrent Date: C. Action buttonDisplay Current Date D. Contains an OK button

3. Create a dialog box that performs the following tasks. Then, write the required DCL and AutoLISP files. A. Displays the current date. B. Displays the current time. C. Contains buttons to display and update current date and time. D. Displays the current drawing name. E. Contains an OK button.

Copyright by Goodheart-Willcox Co., Inc.

Chapter 29 Introduction to Dialog Control Language (DCL)

AutoCAD and Its ApplicationsAdvanced 701

Drawing Problems - Chapter 29