The user-input or acedGetxxx() functions pause for the user to enter data of the indicated type, and return the value in a result argument. The application can specify an optional prompt to display before the function pauses.
The following functions behave like user-input functions: acedEntSel(), acedNEntSelP(), acedNEntSel(), and acedDragGen().
The following table briefly describes the user-input functions.
|
User-input function summary |
|
|---|---|
|
Function Name |
Description |
|
acedGetInt |
Gets an integer value |
|
acedGetReal |
Gets a real value |
|
acedGetDist |
Gets a distance |
|
acedGetAngle |
Gets an angle (oriented to 0 degrees as specified by the ANGBASE variable) |
|
acedGetOrient |
Gets an angle (oriented to 0 degrees at the right) |
|
acedGetPoint |
Gets a point |
|
acedGetCorner |
Gets the corner of a rectangle |
|
acedGetKword |
Gets a keyword (see the description of keywords later in this section) |
|
acedGetString |
Gets a string |
With some user-input functions such as acedGetString(), the user enters a value on the AutoCAD prompt line. With others such as acedGetDist(), the user either enters a response on the prompt line or specifies the value by selecting points on the graphics screen.
If the screen is used to specify a value, AutoCAD displays rubber-band lines, which are subject to application control. A prior call to acedInitGet() can cause AutoCAD to highlight the rubber-band line (or box).
The acedGetKword() function retrieves a keyword. Keywords are also string values, but they contain no white space, can be abbreviated, and must be set up before the acedGetKword() call by a call to acedInitGet(). All user-input functions (except acedGetString()) can accept keyword values in addition to the values they normally return, provided acedInitGet() has been called to set up the keywords. User-input functions that accept keywords can also accept arbitrary text (with no spaces).
The AutoCAD user cannot respond to a user-input function by entering an AutoLISP expression.
The user-input functions take advantage of the error-checking capability of AutoCAD. Trivial errors (such as entering only a single number in response to acedGetPoint()) are trapped by AutoCAD and are not returned by the user-input function. The application needs only to check for the conditions shown in the following table.
|
Return values for user-input functions |
|
|---|---|
|
Code |
Description |
|
RTNORM |
User entered a valid value |
|
RTERROR |
The function call failed |
|
RTCAN |
User entered ESC |
|
RTNONE |
User entered only ENTER |
|
RTREJ |
AutoCAD rejected the request as invalid |
|
RTKWORD |
User entered a keyword or arbitrary text |
The RTCAN case enables the user to cancel the application's request by pressing ESC. This helps the application conform to the style of built-in AutoCAD commands, which always allow user cancellation. The return values RTNONE and RTKWORD are governed by the function acedInitGet(): a user-input function returns RTNONE or RTKWORD only if these values have been explicitly enabled by a prior acedInitGet() call.