AfraLISP - Learn AutoLISP for AutoCAD productivity

AutoLISP DCL Functions

by Kenny Ramage

Function Description
(action_tile key action-expression)

Assigns an action to evaluate the user selected specif tile in a dialog box

(add_list string)

Adds or modifies a string in the currently active dialog box list

(client_data_tile key clientdata)

Associates application-managed data with a dialog box tile

(dimx_tile key) and (dimy_tile key)

Retrieves the dimensions of a tile in dialog box units

(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 color)

Draws a filled rectangle in the currently active dialog box 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 numberADI mnemonicDescription
-2BGLCOLORCurrent background of the AutoCAD graphics screen
-15DBGLCOLORCurrent dialog box background color
-16DFGLCOLORCurrent dialog box foreground color (text)
-18LINELCOLORCurrent 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 :
ValueDescription
0Enable tile
1Disable tile
2Set focus to tile
3Select edit box contents
4Flip image highlighting on or off
(new_dialog dlgname dcl_id [action [screen-pt]])

Begins a new dialog box and displays it, and can also specify a 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(sldname)

Displays an AutoCAD slide in the currently active dialog box 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 [index]])

Starts the processing of a list in the list box or in the pop-up list 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 :
ValueDescription
1Change selected list contents
2Append new list entry
3Delete 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 color)

Draws a vector in the currently active dialog box image

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 numberADI mnemonicDescription
-2BGLCOLORCurrent background of the AutoCAD graphics screen
-15DBGLCOLORCurrent dialog box background color
-16DFGLCOLORCurrent dialog box foreground color (for text)
-18LINELCOLORCurrent 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).