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:
- 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 ]) 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 ]]) 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 ]) 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 ]]) 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.
