Example: Quick Overview of Dialog Boxes (DCL)

This example explains how to create a basic dialog box and display it using AutoLISP.

Note: DCL support in AutoLISP is limited to Windows only.

Creating the DCL File

This DCL defines a dialog box labeled Sample Dialog Box that contains a text tile and a single OK button. The DCL resides in a file named hello.dcl.

1. Copy the following code to the clipboard.

   Highlight the DCL code and press Ctrl+C, or right-click and click Copy.

   hello : dialog
   {
     label = "Sample Dialog Box";
     : text {
       label = "Hello, world.";
     }
     ok_only;
   }

2. In the Visual LISP Editor, click File New File.
3. In the new editor window, press Ctrl+V, or right-click and click Paste.
4. Click File Save As. In the Save-as dialog box, Save As Type drop-down list, select DCL Source Files. In the File Name field, enter hello.dcl. Browse to a location to store the DCL file and click Save.
   Note: Make sure the DCL file is saved to one of the folders in the AutoCAD Support File Search Path.

Displaying the dialog box and responding to the user pressing OK

1. Copy the following code to the clipboard.
   Highlight the DCL code and press Ctrl+C, or right-click and click Copy.

   (defun C:HELLO ( / dcl_id )
     (setq dcl_id (load_dialog "hello.dcl")) ; Load the DCL file.
     (if (not (new_dialog "hello" dcl_id))   ; Initialize the dialog.
       (exit)                                ; Exit if this does not work.
     )
     (start_dialog)                          ; Display the dialog box.
     (unload_dialog dcl_id)                  ; Unload the DCL file.
    (princ)
   )

2. In the Visual LISP Editor, click File New File.
3. In the new editor window, press Ctrl+V, or right-click and click Paste.
4. Click File Save As. In the Save-as dialog box, Save As Type drop-down list, select Lisp Source Files. In the File Name field, enter hello.lsp. Browse to a location to store the LSP file and click Save.
   Note: Make sure the LSP file is saved to one of the folders in the AutoCAD Support File Search Path.
5. Click Tools Load Text in Editor.
6. In AutoCAD, at the Command prompt, enter hello and press Enter.
7. In Sample Dialog Box, click OK.

The following explains line by line what the AutoLISP program does:

• Line 1 – Defines a command named HELLO with a local variable of dcl_id.
• Line 2 – Loads the DCL file into memory with the load_dialog function. The load_dialog function returns a DCL identification number. You need this to identify the dialog in subsequent function calls.
• Lines 3-5 – Initializes the dialog box with the new_dialog function. The dialog box name and DCL identification number are passed as arguments.

  With other dialog boxes, you would also set up tile values, lists, and images. This DCL example above uses a predefined tile named ok_only, so you do not have to initialize the tile unless you want to override its default values. The ok_only tile also has an action named done_dialog assigned to it. If the user presses the OK button, AutoCAD passes the done_dialog call to your AutoLISP application and ends the dialog.

• Line 6 – Control of the dialog is passed to AutoCAD for display with the start_dialog function.
• Line 7 – Removes the dialog from memory after the finishes responding to it with the unload_dialog function.
• Line 8 – Exists the command quietly.
• Line 9 – Ends the definition of the HELLO command.

  For the sake of simplicity, no error processing is included in this example.

Note that the start_dialog call remains active until the user selects a tile (usually a button) whose associated action expression calls done_dialog. The done_dialog call can be issued explicitly by the tile. The done_dialog call is also issued by the selected tile if its is_cancel attribute is set to true.

Caution: In theory, the dialog box facility takes control of input at the time you call start_dialog, but the operating system takes control when you call new_dialog. This has no effect on writing programs. However, if you invoke these functions interactively (at the AutoCAD Command prompt), you must enter them as one statement. Enclose them within a progn or another function. If you do not, the interactive call to new_dialog can freeze the screen. Calling new_dialog and start_dialog interactively can be useful during debugging.