Tutorial Overview

In this tutorial for "Getting Started with Dcl Dialogs", there are examples of all of the basic dcl tiles with an accompanying AutoLISP program to load and control the dialogs. The approach is learning by examples. In this document the dialogs with the green title bars have active html menu selections. The dialogs with the blue title bars are only the dialog examples for the tutorial.

This tutorial is intended for all AutoLISP programmers, from the novice to the advanced. The more advanced programmers will find DclCalcs very beneficial while designing dialogs. Its algorithms for calculating heights and widths verses pixels and incremental changes to tiles, greatly speeds up the design process. It reduces a lot of the estimating and guess work required to finally find a height or width that works for what you are designing. If you have ever attempted to design a list_box with only 5 or 10 lines and have wasted way too much time and still couldn’t find a height that worked, DclCalcs will show you all of the lines that are skipped within a reasonable range.

Among the main topics of interest covered in this tutorial is moving back and next through a series of dialogs and retaining all of the previous dialog information. Another topic of interest is to be able to exit a dialog, and have the user select an object, and then return to the dialog and display the information regarding the object selected.

Additional utilities are included labeled with the comment ";*Included" at the end of the line. Among these utilities are functions for the edit_box and popup_list to only accept integers or real numbers as input from the users. For the popup_list, an alternative to adding to a list by typing in a new value as in VBA, the "Other" option has been added as a solution.

ViewDcl is also included in this tutorial. ViewDcl is a very useful utility for viewing dialogs within dcl files, as you are designing them or just need to view or compare other dialogs. If this type of utility is not part or your preferred AutoLISP and Dialog editor, it is a great utility to have. It can be run on the command line without loading any editor.

In addition to the AutoLISP and Dialogs covered in this tutorial you can refer to the Support Functions and Support Dialogs within the accompanying AutoLISP and Dialogs files, MyDialogs.lsp and MyDialogs.dcl. In consideration that some users may already have files named DclDialogs, I chose the name MyDialogs. It is my intention, that once you download these files, they’re yours to edit and modify and call your own.

My Dialogs Download Files

Introduction to AutoLISP

There are two basic types of AutoLISP functions, the Command type and the Function type. The function name for the Command type is preceded with a "c:". The Command type is typically run from the command line by typing in the name of the function. It may also be run by typing the "c:" and the function name enclosed in parentheses. i.e. (c:fun1). This method is used to call a Command function within another function. The Function type is always enclosed in parentheses any may include various arguments after the function name, depending on the requirements of the function. i.e. (fun2 "text" 123.4) or (fun3). The Command type does not have arguments passed to it, but may prompt the user for input instead. If a function name is preceded with "c:" and it has required arguments, it can only be run as a Function type enclosed in parentheses. In this case the "c:" is usually omitted.

AutoLISP functions may include Local and Global variables. Local variables are in memory while the function is running and are cleared when the function ends. Global variables are variables that are set and not declared as Local in a function. They remain in memory after the function ends and in the drawing environment until the drawing is closed.

The typical first line of a Command type function may look like one of the following:

(defun c:fun4 ( ) ; No Local variables declared.
(defun c:fun5 (/ cnt pt) ; Two Local variable are declared after the forward slash "/".

This is also how Local variables are declared in the Function type functions.
The typical first line of a Function type function may look like one of the following:

(defun fun6 ( ) ; No Arguments and no Local variables declared.
(defun fun7 (text num) ; Two Arguments and no Local variables declared.
(defun fun9 (/ cnt pt) ; Two Local variables declared after the forward slash "/".
(defun fun8 (text num / cnt pt) ; Two Arguments and two Local variables declared.

The forward slash "/" separates the arguments from the local variables. The code for a sub Function can be included within another Function. It may be declared Local by including its Function name in the list of Local variables as in the following example:

(defun fun10 (x y / ss fun11)
  (defun fun11 ( ) . . .

Both the Command types and the Function types can return a value, if the last line or the last segment of code can be evaluated. i.e. (setq xyz (c:fun12)) or (setq xyz (fun13))

In the above examples both c:fun12 and fun13 apparently have included a return value as the last line or the last segment of code. Typically only the Functions types are designed to return a value. To suppress the nil echoed to the command line after running a Command type, include a (princ) as the last line of the function.

Dcl stands for Dialog Control Language. Dcl is a descriptive and interpretive language within AutoCAD. It’s generally controlled by AutoLISP functions to interact with the end user to gather information and data in the AutoCAD environment. The syntax of Dcl is based upon defining basic tiles. Tiles are the items or groups of items in a dialog, such as an edit_box or a radio_row. A dialog includes the dialog box and all of the tiles within it.

Similar to other languages that use parenthesis "()" to enclose functions and segments of code, Dcl uses curly braces "{}" as its method for enclosing dialog definitions and the properties and attributes of tiles. The syntax for attributes and values is separated by an equal sign "=" and ending with a semicolon ";". For example: attribute = value;

Dcl is an extremely case-sensitive language. All of the names within the syntax of the language must be lower case. The case of all labels and keys defined in the Dcl file by the programmer, must match the exact case of all calls from within AutoLISP to control and retrieve tile information. For example, a key named "Data_Box" can not be accessed using "data_BOX", as the case is not the same. Also note, that the text string for labels for keys may only contain letters, numbers, dashes and underscores.

As with AutoLISP, the Dcl filename may be different that any of the names of the dialog definitions within. If a dialog definition is copied or moved to another Dcl file, remember to change the call to load_dialog to the new Dcl filename within the AutoLISP function. Also, if a dialog definition is renamed, change the dialog name for the call to new_dialog as well.

Dcl provides a way of auditing during the design process and checking for errors. At audit_level = 3; Dcl provides the most comprehensive help and hints and finds redundant attribute information. If you are alerted to view the Acad.dce file for further information, use the included "Dce" function to view the file. You may include the following line in your Dcl file during the design and development stage to benefit from Dcl audit help and hints.

dcl_settings : default_dcl_settings { audit_level = 3; }

This is a brief introduction to Dcl dialogs. For further information refer to the related AutoCAD Help topics and books on the subject. There are also several websites that may provide additional information relating to Dcl Dialogs.

My Dialogs Menu

My First

My Alert 1

My Alert 2

My Bold Text

//---------------------------------------------------------------------------------------------------------
// MyBoldText
// Note: The widths were determined by the example and will need to be changed
// as per your requirements.
//---------------------------------------------------------------------------------------------------------
MyBoldText : dialog {
  label = " My Bold Text";
  spacer;
  : text {
    key = "Text1";
    label = "";//Text1$ from lsp file
    width = 18;
    fixed_width_font = true;
  }
  : image {
    key = "ImageText2";//ImageText2$ from lsp file
    width = 24;
    height = 1.28;//Height is Ok per font
    fixed_width = true;
    fixed_height = true;
    aspect_ratio = 1;
    color = -15;//-15 is dialog color
  }
  spacer;
  ok_only;
}//MyBoldText

;----------------------------------------------------------------------------------------------------------
; c:MyBoldText - Two methods of displaying bold text
; Syntax: MyBoldText
;----------------------------------------------------------------------------------------------------------
(defun c:MyBoldText (/ Dcl_Id%)
  (princ "\nMyBoldText")(princ)
  ; Load Dialog
  (setq Dcl_Id% (load_dialog "MyDialogs.dcl"))
  (new_dialog "MyBoldText" Dcl_Id%)
  ; Set Dialog Initial Settings
  (set_tile "Text1" "This is just text.")
  (set_tile "ImageText2" "This is image text.")
  ; Dialog Actions
  (start_dialog)
  ; Unload Dialog
  (unload_dialog Dcl_Id%)
  (princ)
);defun c:MyBoldText

My Ok Cancel

//---------------------------------------------------------------------------------------------------------
// MyOkCancel
// Customize Ok Cancel buttons and group them together and specify their widths
//---------------------------------------------------------------------------------------------------------
MyOkCancel : dialog {
  label = " My Ok Cancel";
  spacer;
  : row {
    fixed_width = true;
    alignment = centered;
    : ok_button {
      width = 11;
    }
    : cancel_button {
      width = 11;
    }
  }
}//MyOkCancel

;----------------------------------------------------------------------------------------------------------
; c:MyOkCancel - Customize Ok Cancel buttons and then princ the Return# you
; choose to associate with the buttons pressed.
; Syntax: MyOkCancel
;----------------------------------------------------------------------------------------------------------
(defun c:MyOkCancel (/ Dcl_Id% Return#)
  (princ "\nMyOkCancel")(princ)
  ; Load Dialog
  (setq Dcl_Id% (load_dialog "MyDialogs.dcl"))
  (new_dialog "MyOkCancel" Dcl_Id%)
  ; Dialog Actions
  (action_tile "accept" "(done_dialog 1)");You can change the default Return#
  (action_tile "cancel" "(done_dialog 0)")
  (setq Return# (start_dialog))
  ; Unload Dialog
  (unload_dialog Dcl_Id%)
  (princ "\n")(princ Return#);Optional
  (princ)
);defun c:MyOkCancel

My Yes No

//---------------------------------------------------------------------------------------------------------
// MyYesNo
// Note: The width for the Text1 key was determined by the syntax example and
// will need to be changed as per your requirements. Also note that the buttons
// for Yes and No, the added fixed_width = true;.
//---------------------------------------------------------------------------------------------------------
MyYesNo : dialog {
  key = "Title";
  label = "";//Title$ from lsp file
  spacer;
  : text {
    key = "Text1";
    label = "";//Question$ from lsp file
    width = 35.0;
    alignment = centered;
  }
  spacer;
  : row {
    fixed_width = true;
    alignment = centered;
    : button {
      key = "Yes";
      label = "&Yes";
      is_default = true;
      width = 7.92;
      fixed_width = true;
    }
    : button {
      key = "No";
      label = "&No";
      is_cancel = true;
      width = 7.92;
      fixed_width = true;
    }
  }
}//MyYesNo

;----------------------------------------------------------------------------------------------------------
; MyYesNo - Question dialog with one question line
; Arguments: 2
;   Title$ = Dialog Title
;   Question$ = Question line
; Syntax: (MyYesNo " My Yes No" "Do you like creating programs in AutoLISP?")
;----------------------------------------------------------------------------------------------------------
(defun MyYesNo (Title$ Question$ / Answer$ Dcl_Id% Return#)
  (princ "\nMyYesNo")(princ)
  ; Load Dialog
  (setq Dcl_Id% (load_dialog "MyDialogs.dcl"))
  (new_dialog "MyYesNo" Dcl_Id%)
  ; Set Dialog Initial Settings
  (set_tile "Title" Title$)
  (set_tile "Text1" Question$)
  ; Dialog Actions
  (action_tile "Yes" "(done_dialog 1)")
  (action_tile "No" "(done_dialog 0)")
  (setq Return# (start_dialog))
  ; Unload Dialog
  (unload_dialog Dcl_Id%)
  (if (= Return# 1)
    (setq Answer$ "Yes")
    (setq Answer$ "No")
  );if
  (princ "\n")(princ Answer$)(princ);Optional
  Answer$
);defun MyYesNo

My Next / My Back