AutoLISP DCL Functions

by Kenny Ramage

Function Description
(action_tile key action- Assigns an action to evaluate the user selected specif tile in a
expression) dialog box
(add_list string) Adds or modifies a string in the currently active dialog box list
(client_data_tile key Associates application-managed data with a dialog box tile
clientdata)
(dimx_tile key) and Retrieves the dimensions of a tile in dialog box units
(dimy_tile key)
(done_dialog [status]) Terminates a dialog box

If you specify the optional status argument, it must be a positive

integer, which start_dialog will return instead of returning 1 for OK
or 0 for Cancel. The meaning of any status value greater than 1
depends on your application.
(end_image) Ends creation of the currently active dialog box image

This function is the complement of (start_image)

(end_list) Ends processing of the currently active dialog box list

This function is the complement of (start_list)

(fill_image x1 y1 wid hgt Draws a filled rectangle in the currently active dialog box
color) image tile

The fill_image function must be used between start_image and

end_image calls. The color parameter is an AutoCAD color number
or one of the logical color numbers shown in the following table.

Symbolic names for the color attribute :

Color ADI
Description
number mnemonic
Current background of the
-2 BGLCOLOR
AutoCAD graphics screen
-15 DBGLCOLOR Current dialog box background color
Current dialog box foreground color
-16 DFGLCOLOR
(text)
-18 LINELCOLOR Current dialog box line color

The first (upper-left) corner of the rectangle is located at (x1,y1)

 and the second (lower-right) corner is located the relative distance
(wid,hgt) from the first corner (wid and hgt must be positive
values). The origin (0,0) is the upper-left corner of the image. You
can obtain the coordinates of the lower-right corner by calling the
dimension functions dimx_tile and dimy_tile.
(get_attr key attribute) Retrieves the DCL value of a dialog box attribute

The key argument is a string that specifies the tile and is case
sensitive. The attribute argument specifies the name of the attribute
as it appears in the tile's DCL description. Both the key and
attribute arguments are strings. The value returned is the attribute's
initial value as specified in its DCL description; it does not reflect
changes to the state of the tile that come about with user input or
set_tile calls. Returns the attribute value as a string.
(get_tile key) Retrieves the current run-time value of a dialog box tile

The key argument is a string that specifies the tile and is case
sensitive. It returns the tile's value as a string.
(load_dialog dclfile) Loads a DCL file

The dclfile argument is a string that specifies the DCL file to load.
If the dclfile argument does not specify a file extension, .dcl is
assumed. Returns a positive integer value (dcl_id) if successful,
and returns a negative integer if it can't open the file. The dcl_id is
used as a handle in subsequent new_dialog and unload_dialog calls.

The load_dialog function searches for files according to the

AutoCAD library search path.

This function is the complement of unload_dialog. An application

can load multiple DCL files with multiple load_dialog calls.
(mode_tile key mode) Sets the mode of a dialog box tile

The key argument is a string that specifies the tile and is case
sensitive. The mode argument is an integer value. The mode
argument values are described in the following table.

Mode argument values :

Value Description
0 Enable tile
1 Disable tile
2 Set focus to tile
3 Select edit box contents
4 Flip image highlighting on or off
(new_dialog dlgname Begins a new dialog box and displays it, and can also specify a
dcl_id [action [screen-pt]]) default action

The dlgname argument is a string that specifies the dialog box, and
dcl_id identifies the DCL file (you must have obtained its value
from the load_dialog call).

The action argument, which must be specified if you specify

screen-pt, is a string that contains an AutoLISP expression to use as
the default action. If you don't want to define a default action, pass
action as the empty string (""). The screen-pt argument is a 2D
point list that specifies the X,Y location of the dialog box on the
screen. The point usually specifies the upper-left corner of the
dialog box, but this is platform dependent, as is the system of units
in which the location is specified. If you pass the point as '(-1 -
1), the dialog box is opened in the default position (the center of
the AutoCAD graphics screen).

If new_dialog succeeds, it returns T; otherwise it returns nil.

Your application must call new_dialog before it calls start_dialog.

All dialog box initialization - such as setting tile values, creating
images or lists for list boxes, and associating actions with specific
tiles (with the use of action_tile) - must take place after the
new_dialog call and before the start_dialog call.

The default action is evaluated when the user picks an active tile
that doesn't have an action or callback explicitly assigned to it by
action_tile or in DCL.

Note Always check the status new_dialog returns. Calling

start_dialog when the new_dialog call failed can have
unpredictable results.
(set_tile key value) Sets the value of a dialog box tile

The key argument is a string that specifies the tile, and value is a
string that names the new value to assign (initially set by the value
attribute).
sldname or libname Displays an AutoCAD slide in the currently active dialog box
(sldname) image tile

(slide_image x1 y1 wid hgt sldname)

The slide can be a slide file (.sld) or a slide in a slide library file
(.slb): the sldname argument specifies it as you would specify it for
 the VSLIDE command or for a menu file.

The first (upper-left) corner of the slide - its insertion point - is

located at (x1,y1), and the second (lower-right) corner is located at
the relative distance (wid,hgt) from the first (wid and hgt must be
positive values). The origin (0,0) is the upper-left corner of the
image. You obtain the coordinates of the lower-right corner by
calling the dimension functions (dimx_tile and dimy_tile).
(start_dialog) Displays a dialog box and begins accepting user input

You must first initialize the dialog box by a previous new_dialog

call. The dialog box remains active until an action expression or
callback function calls done_dialog. Usually done_dialog is
associated with the tile whose key is "accept" (typically the OK
button) and the tile whose key is "cancel" (typically the Cancel
button).

The start_dialog function has no arguments. It returns the optional

status passed to done_dialog. The default value is 1 if the user
pressed OK, 0 if the user pressed Cancel, or -1 if all dialog boxes
were terminated with term_dialog. But if done_dialog is passed an
integer status greater than 1, start_dialog returns this value, whose
meaning depends on the application.
(start_image key) Starts the creation of an image in the dialog box tile

Subsequent calls to fill_image, slide_image, and vector_image

affect this image until the application calls end_image. The key
argument is a string that specifies the dialog box tile. The key
argument is case sensitive.

Note: Do not use the set_tile function between start_image and

end_image function calls.
(start_list key [operation Starts the processing of a list in the list box or in the pop-up list
[index]]) dialog box tile

The key argument is a string that specifies the dialog box tile. The
key argument is case sensitive. The operation argument is an
integer value whose meaning is summarized in the following table.

List box codes for start_list :

Value Description
1 Change selected list contents
2 Append new list entry
3 Delete old list and create new list (the default)
 The index argument is ignored unless the start_list call begins a
change operation (1), in which case index indicates the list item to
change by the subsequent add_list call. The index is zero based. If
you don't specify operation, it defaults to 3 (create new list), and if
you specify operation but not index, the index defaults to 0.

Subsequent calls to add_list affect the list started by start_list until

the application calls end_list.

Note Do not use the set_tile function between start_list and end_list
function calls.
(term_dialog) Terminates all current dialog boxes as if the user had canceled
each of them

If an application is terminated while any DCL files are open,

AutoCAD automatically calls term_dialog. This function is used
mainly for aborting nested dialog boxes. The term_dialog function
always returns nil.
(unload_dialog dcl_id) Unloads a DCL file

Unloads the DCL file associated with dcl_id (which was obtained
from a previous new_dialog call). Always returns nil.
(vector_image x1 y1 x2 y2 Draws a vector in the currently active dialog box image
color)
This function draws a vector in the currently active dialog box
image (opened by start_image) from the point (x1,y1) to (x2,y2).
The color parameter is an AutoCAD color number or one of the
logical color numbers shown in the following table.

Symbolic names for the color attribute :

Color ADI
Description
number mnemonic
Current background of the
-2 BGLCOLOR
AutoCAD graphics screen
-15 DBGLCOLOR Current dialog box background color
Current dialog box foreground color
-16 DFGLCOLOR
(for text)
-18 LINELCOLOR Current dialog box line color

The origin (0,0) is the upper-left corner of the image. You can
obtain the coordinates of the lower-right corner by calling the
dimension functions (dimx_tile and dimy_tile).