AfraLisp Blog

The AutoLisp/Visual Lisp/VBA Resource Website

AfraLisp Blog

Home Newsletter Utter Rubbish Coding Tips AutoCAD Tips Contact Downloads WAUN

An Introduction to 'acetutil' Functions

The acetutil modules (acetutil.arx, acetutil*.fas) provide a number of utility functions which can be called from LISP.

This documentation covers all functionality present in version 1.37 of acetutil.arx, along with a few functions provided in acetutil.fas. Functions that do not have a specific library designation appear in acetutil.arx.


Entity Functions

acet-ent-geomextents ename)

Returns the geometric extents of the given object.

Arguments
ename

The entity name of an object. 

Return Values
A list containing two points (such as ((1.0 1.0 0.0) (2.0 2.0 0.0))) describing the geometric extents. 


Error Handling Functions

(acet-error-init args)

Error handler.

Note:
This function should be paired with (acet-error-restore) below to encapsulate error handling for LISP functions or commands that may be aborted by the user.

Arguments
args

A list containing up to three elements (described below). 

Arguments are provided in a list to allow for future enhancements. The list can currently be nil or can contain up to three elements: 

A list containing pairs of system variable names along with an initial value for each variable, in the form: 
("sysvar" value "sysvar" value ...) 
The (acet-error-init) function will preserve the initial value of these variables (see (acet-error-restore) below) and then set the new values. 
A flag value indicating whether UNDO should be used as part of the error handling operation. This value can be one of:

  • nil Do not use undo. 
  • 0 Enable Undo and place begin and end marks, but do not issue the UNDO command in the event of an error. 
  • 1 Enable Undo and use the UNDO command in the event of an error. 

A quoted function call that will be executed as part of the error handling operation. A nil argument indicates that no additional error handling is required.

 
Return Values
nil 

Example
(acet-error-init '(("CMDECHO" 0) 1 (if ename (redraw ename 4)) ) )


(acet-error-restore)

Reset error handling. 

This function restores the values saved by the matching call to (acet-error-init). It should be called after all user input has been completed. This function ends with a (princ) call for a quiet finish. 

Return Values
nil

Library: acetutil.fas 


File Functions

(acet-file-attr filename [attr])

Gets or sets the protection attributes of a specified file or directory.

Arguments
filename: Name of the file or directory. 
attr: If provided, a combination of one or more attribute flags. 

Return Values
Returns the new or existing attributes, or -1 on error.

Note:
The following pre-defined constants are provided:
1 = Acet:READONLY
2 = Acet:HIDDEN
4 = Acet:SYSTEM
16 = Acet:DIRECTORY
32 = Acet:ARCHIVE

Library: acetutil.arx 


(acet-file-chdir directory)

Changes the current working directory.

Arguments
directory: New directory name. 

Return Values
Returns a string containing the expanded name of the new current working directory.

Library: acetutil.arx 


(acet-file-copy from to [force])

Copy a file.

Arguments
from: Name of file to copy. 
to: Name of new file. 
force: If provided and non-nil, forces any existing file to be overwritten. 

Return Values
Returns T on success.

Note:
This function will not overwrite read-only files. The read-only flag can be cleared with (acet-file-attr).

Library: acetutil.arx 


(acet-file-cwd)

Returns the current working directory.

Return Values
A string containing the current working directory name.

Library: acetutil.arx 


(acet-file-dir pattern [attributes] [starting-directory])

Locate files.

Arguments
pattern: A file specification, which may include wildcards and/or a directory name. 
attributes: If provided, contains a bitmap of file attributes to match (see (acet-file-attr). 
starting-directory: If provided, this function will also search subdirectories for files that match pattern: (which can also contain a directory name). Uses the current working directory (see (acet-file-cwd)) if a relative path is provided. 

Return Values
A list of matching file names, or nil if no matching files are found.

Library: acetutil.arx 


(acet-file-mkdir directory)

Creates a new directory.

Arguments
directory: New directory name. 

Return Values
Returns T on success.

Library: acetutil.arx 


(acet-file-move from to)

Moves or renames files.

Arguments
from: Original file name or location. 
to: New file name or location. 

Return Values
Returns T on success.

Library: acetutil.arx 


(acet-file-remove filespec [force])

Deletes one or more files.

Arguments
filespec: File specification, which may include wildcards. 
force: If provided and non-nil, indicates that even read-only files should be deleted. 

Return Values
The number of files removed.

Library: acetutil.arx 


(acet-file-rmdir directory)

Changes the current working directory.

Arguments
directory: Name of directory to remove. 

Return Values
Returns T on success.

Library: acetutil.arx 


Help Functions

(acet-help [topic])

Display a help page.

Arguments
topic: A keyword that identifies the help page to display. If not supplied, the Table of Contents will be displayed. 

Return Values
nil 


(acet-help-trap command [topic [file]])

Install a F1 key monitor.

Arguments
command: The name of the command to monitor, as would be passed to (setfunhelp). 
topic: The topic name in the help file. If this argument is nil or not supplied, any help trap attached to command will be released. 
file: The name of the help file to use. If not provided, acet.chm is used. 

Return Values
T if successful. 


Initialization File Functions

(acet-ini-get inifile [section [key [default]]])

Retrieve data from INI file.

Arguments
inifile: Name of the INI file to search. 
section: Section name within the INI file. 
key: Key name within the section. 
default: Default value to return if key cannot be located. 

Return Values
The return value depends on the parameters provided. If only inifile is given, this function returns a list of section names (or nil if inifile cannot be opened). If a section name is given, a list of key names will be returned. If a key is given, returns the value associated with the key (or default, if the key cannot be located). Returns nil if no information can be found. 


(acet-ini-set inifile section [key [value]])

Write data to INI file.

Arguments
inifile: Name of the INI file to modify. 
section: A string containing the name of the section for the given data. If the section does not exist, it will be created. 
key: A string containing the name of the key to be associated with a value. If the key does not exist in the given section, it will be created. If this parameter is not given, the entire section (including all entries within the section) will be deleted. 
value: A string to be assigned to key. If this parameter is not given, the key will be deleted. 

Return Values
T on success.


Registry Functions

(acet-reg-del key [name])

Delete key or value from Registry.

Arguments
key: Key name to delete. Will not delete subkeys. 
name: If given, value name to delete. 

Return Values
T on success. 


(acet-reg-get key [name])

Return value from Registry.

Arguments
key: Key name to retrieve. 
name: If given, value name to retrieve. 

Return Values
The selected value, or nil if the entry cannot be located. 


(acet-reg-prodkey)

Return current product key.

Return Values
The current product key (Registry path for the current installation). 


(acet-reg-put key [name value])

Write a Registry key or value.

Arguments
key: Key name to use. 
name: If given, value name to write. 
value: If given, value to assign to name. 

Return Values
T on success. 


Selection Set Functions

(acet-ss-drag-move ss pt [prompt] [highlight [cursor]])

Drag a selection set to change location.

Arguments
ss: The selection set to drag. 
pt: The base point. 
prompt: A message to display before dragging is started. 
highlight: If given, causes a rubber-band line to be drawn from pt to the current cursor position while dragging; this parameter can be nil to draw a rubber-band line in the inverse of the screen color, or non-nil to draw a highlighted line. 
cursor: The cursor form to display while dragging (0=crosshairs, 1=no cursor, 2=target). 

Return Values
Normally returns the selected point, but will honor initget settings and can return arbitrary text or keywords. Returns nil if the dragging operation is aborted.

Note:
The acet-ss-drag-move function does not move the selection set, but allows selection of a new position while showing how the result will appear. 


(acet-ss-drag-rotate ss pt [prompt] [highlight [cursor]])

Drag a selection set to change rotation.

Arguments
ss: The selection set to drag. 
pt: The base point. 
prompt: A message to display before dragging is started. 
highlight: If given, causes a rubber-band line to be drawn from pt to the current cursor position while dragging; this parameter can be nil to draw a rubber-band line in the inverse of the screen color, or non-nil to draw a highlighted line. 
cursor: Gives the cursor form to display while dragging (0=crosshairs, 1=no cursor, 2=target). 

Return Values
The selected rotation value, or nil if dragging is aborted.

Note:
The acet-ss-drag-rotate function does not rotate the selection set, but allows selection of a rotation value while showing how the result will appear. 


(acet-ss-drag-scale ss pt [prompt] [highlight [cursor]])

Drag a selection set to change scale.

Arguments
ss: The selection set to drag. 
pt: The base point. 
prompt: A message to display before dragging is started. 
highlight: If given, causes a rubber-band line to be drawn from pt to the current cursor position while dragging; this parameter can be nil to draw a rubber-band line in the inverse of the screen color, or non-nil to draw a highlighted line. 
cursor: Gives the cursor form to display while dragging (0=crosshairs, 1=no cursor, 2=target). 

Return Values
The selected scale factor, or nil if dragging is aborted.

Note:
The acet-ss-drag-scale function does not scale the selection set, but allows selection of a scaling factor while showing how the result will appear. 


String Functions

acet-str-collate left right [matchCase])

Compare for sort order.

Arguments
left, right: The two strings to compare. 
matchCase: If provided and non-nil, indicates that case sensitive comparison should be used. Normally case is ignored. 

Return Values
Returns -1, 0 or 1 to indicate relative sorting order (left < right, left == right and left > right, respectively). Displays a usage message if either of the first two arguments are not strings.

Note:
The acet-str-collate function uses multibyte comparison appropriate for the current codepage. 


(acet-str-equal left right [matchCase])

Compare strings for equality.

Arguments
left, right: The two strings to compare. 
matchCase: If provided and non-nil, indicates that case sensitive comparison should be used. Normally case is ignored. 

Return Values
Returns T if the strings are identical, otherwise nil. Also returns nil if either of the first two arguments are not strings. Displays a usage message if less than two arguments are supplied.

Note:
The acet-str-equal function uses multibyte comparison appropriate for the current codepage. 


(acet-str-find find string [ignoreCase [useRegExp]])

Find substring in string.

Arguments
find: The substring to locate. 
string: The string to search. 
ignoreCase: If provided and non-nil, indicates that case insensitive comparisons should be performed. 
useRegExp: If provided and non-nil, indicates that regular expressions should be used for searching. 

This function uses the following definitions for regular expressions: 

. Matches any single character. 
* Postfix. Preceeding item 0 or more times. 
+ Postfix. Preceeding item 1 or more times. 
^ Matches empty string at beginning of text. 
$ Matches empty string at end of text. 
[chars] Matches any character in the given class. If the first character is ^, match any character not in the given class. A range of character may be specified by first-last, as in [A-Z] to specify upper case alphabetic characters. 
\( Mark the beginning of a subexpression. 
\) Mark the end of a subexpression. 
\digit Matches a repeat of the text matched earlier by the subexpression inside the nth opening parenthesis. Subexpressions may also be referenced in replace strings. 


Return Values
The 1-based index if found, or nil if not found. 


(acet-str-format format [arg ...])

Format a message with embedded arguments.

Arguments
format: A string containing plain text and argument specifiers. Argument insertions appear in the format string as the percent (%) character followed by an argument number. 
arg ...: A list of argument values to be converted and inserted. Only INT, REAL and STR arguments can be converted. Other argument types must be converted to one of these three. REAL arguments are converted using the current LUNITS and LUPREC values; you may wish to first use the (angtos) or (rtos) functions for proper display. 

Return Values
A string with appropriate substitutions. 

Example
The call: 
(acet-str-format "%1/%2 or %2/%1." "one" "two")

will return the string: 
"one/two or two/one."


(acet-str-replace find replace string [ignoreCase [useRegExp [count]]])

Replace one substring with another.

Arguments
find: The substring to locate. 
replace: The replacement substring. 
string: The string to search. 
ignoreCase: If provided and non-nil, indicates that case insensitive comparisons should be performed. 
useRegExp: If provided and non-nil, indicates that regular expressions should be used for searching. 
count: The number of times to perform the replacement in string. If count is zero or not supplied then all occurrences are replaced. 

This function uses the following definitions for regular expressions: 

. Matches any single character. 
* Postfix. Preceeding item 0 or more times. 
+ Postfix. Preceeding item 1 or more times. 
^ Matches empty string at beginning of text. 
$ Matches empty string at end of text. 
[chars] Matches any character in the given class. If the first character is ^, match any character not in the given class. A range of character may be specified by first-last, as in [A-Z] to specify upper case alphabetic characters. 
\( Mark the beginning of a subexpression. 
\) Mark the end of a subexpression. 
\digit Matches a repeat of the text matched earlier by the subexpression inside the nth opening parenthesis. Subexpressions may also be referenced in replace strings. 


Return Values
Returns the resultant string with replacements (if any) made. 


(acet-str-wcmatch string pattern [matchCase])

Performs a wild-card match similar to (wcmatch), but allows control over case sensitivity.

Arguments
string: The string to search. 
pattern: The wildcard pattern to match. See (wcmatch) for details. 
matchCase: If provided and non-nil, indicates that case sensitive comparison should be used. 

Return Values
T if string and pattern match. 


System Functions

(acet-sys-beep sound)

Make a noise.

Arguments
sound: A sound selector value. Can be one of:
-1: Standard beep using computer speaker
 0: SystemDefault
16: SystemHand
32: SystemQuestion
48: SystemExclamation
64: SystemAsterisk 

Return Values
nil 


(acet-sys-command shell-command)

Run a command in a shell. Waits for the shell to complete execution before returning.

Arguments
shell-command: A string containing the command to execute. 

Return Values
An integer containing the exit code from the shell command, or -1 on error. 


(acet-sys-foreground)

Forces AutoCAD's main window to be the topmost window and to receive focus.

Return Values
nil 


(acet-sys-keystate keycode)

Check state of virtual key.

Arguments
keycode: The code for the virtual key to test. 

Return Values
The status of the specified virtual key:

If the high-order bit is 1, the key is down; otherwise, it is up.
If the low-order bit is 1, the key is toggled. A key, such as the CAPS LOCK key, is toggled if it is turned on. The key is off and untoggled if the low-order bit is 0. A toggle key's indicator light (if any) on the keyboard will be on when the key is toggled, and off when the key is untoggled.


(acet-sys-lasterr)

Report last error.

Return Values
Returns the error code of the last error encountered by routines in the acetutil library.


(acet-sys-procid)

Returns the current process identifier.

Return Values
The current process identifier. 


(acet-sys-sleep msecs)

Delay, allowing other processes to run.

Arguments
msecs: The (minimum) number of milliseconds to release control. 

Return Values
nil

Note:
The system may delay the current process for more than the requested amount of time. 


(acet-sys-spawn flags command [argument ...])

Execute an external program.

Arguments
flags: A bitmap of flags indicating how the external program should be executed. Supported flags:
1 = wait for the program to complete
2 = run program minimized 
command: A string containing the name of the external program. 
argument ...: A set of arguments to be passed to the external program. 

Return Values
If this function waits for program completion the return value is the exit code from the program, otherwise the return value is the process ID for the new process. See (acet-sys-term) and (acet-sys-wait)


(acet-sys-term processID)

Terminate the given process.

Arguments
processID: The process ID of the process to terminate. 

Return Values
T on success. 


(acet-sys-wait processID [time])

Wait for a process to complete.

Arguments
processID: The process ID for the sub-process. 
time If given, the number of milliseconds to wait. 

Return Values
The exit code from the given process, or -1 if an error occurred or time expired. 


User Interface Functions

(acet-ui-message message [caption [type]])

Displays a message box.

Arguments
message: A text string containing the message to display. Multiple lines may be separated by ' ' characters. 
caption: If provided, the caption for the dialog. Defaults to "Error". 
type: If provided, a bitmap of various flags used to achieve different effects. 
The following type flags are available: 

Base types
0 = Acet:OK
1 = Acet:OKCANCEL
2 = Acet:ABORTRETRYIGNORE
3 = Acet:YESNOCANCEL
4 = Acet:YESNO
5 = Acet:RETRYCANCEL

Icons
16 = Acet:ICONSTOP
32 = Acet:ICONQUESTION
48 = Acet:ICONWARNING
64 = Acet:ICONINFORMATION

Default buttons
0 = Acet:DEFBUTTON1
256 = Acet:DEFBUTTON2
512 = Acet:DEFBUTTON3
768 = Acet:DEFBUTTON4

Return Values
Returns one of the following values: 

1 = Acet:IDOK
2 = Acet:IDCANCEL
3 = Acet:IDABORT
4 = Acet:IDRETRY
5 = Acet:IDIGNORE
6 = Acet:IDYES
7 = Acet:IDNO
8 = Acet:IDCLOSE
9 = Acet:IDHELP

Library: acetutil.arx 


(acet-ui-pickdir [message [startDir [caption]]])

Displays a directory selection dialog.

Arguments
message: If provided, a message to be displayed in the space above the directory tree control. 
startDir: If provided, the initial directory to be selected. 
caption: If provided, the dialog caption. 

Return Values
A string containing the name of the selected directory, or nil if the dialog was canceled.

Library: acetutil.arx 


(acet-ui-progress [label [max]])
(acet-ui-progress current)


Display progress meter.

Arguments
label: If provided, a text string that will appear as a label for the progress meter. 
max: If provided, the maximum value in the range to be displayed (starting with 0). 
current: If provided, gives the current value, which should be less than max; positive values are absolute while negative values increment the current position. 

If no parameters are provided, the progress meter is removed. 

Return Values
The return value depends on the action performed: 
Initialize: returns T if successful, otherwise NIL. 
Update: returns current. 
Restore: returns NIL. 
Example:

;; init meter
(acet-ui-progress "Working:" (length theList))
;; process each item
(foreach item theList
;; perform action
(doSomethingTo item)
;; update meter by one item
(acet-ui-progress -1)
)
;; kill meter
(acet-ui-progress)


Library: acetutil.arx 


(acet-ui-status [message [caption]])

Displays a modeless status dialog.

Arguments
message: If provided, a text string to be displayed in the dialog. 
caption: If provided, a text string to be used as the dialog caption. 

If no parameters are provided, the dialog is hidden. 

Return Values
nil

Note:
The status dialog may be moved by the user. It will remember it's position and contents during the current session.

Library: acetutil.arx 


(acet-ui-txted [text [caption [note]]])

Display a multi-line text editing dialog.

Arguments
text: If provided, a text string to be displayed as the initial contents. Lines can be separated with "\r\n" sequences. 
caption: If provided, text to be used as the dialog caption. 
note: If provided, an additional text string to be displayed above the text editing control. 

Return Values
A string containing the text contents if the user presses the OK button, or nil if the user presses the Cancel button.

Library: acetutil.arx 


Utility Functions

(acet-util-ver)

Identify module version.

Return Values
Returns a REAL value containing the current version number of the acetutil.arx library.


 
The AutoLisp/Visual Lisp/VBA Resource Website

Copyright © 1999-Perpetuity by AfraLisp

All rights reserved.
Information in this document is subject to change without notice.
Site created and maintained by Kenny Ramage

The AutoLisp/Visual Lisp/VBA Resource Website