GetDistance Method (ActiveX)

Gets the distance from the prompt line or a selected set of points on the screen.

Supported platforms: Windows only

Signature

VBA:

RetVal = object.GetDistance([Point [, Prompt]])

object

Type: Utility

The object this method applies to.

Point

Access: Input-only; optional

Type: Variant (three-element array of doubles)

The 3D WCS coordinates specifying the base point. If this point is not provided, the user must input two points.

Prompt

Access: Input-only; optional

Type: Variant (string)

The text to display to prompt the user for input.

Return Value (RetVal)

Type: Variant (double or array of doubles)

The distance from the prompt line or a selected set of points on the screen.

Remarks

AutoCAD pauses for user input of a linear distance and sets the return value to the value of the selected distance. The Point parameter specifies a base point in WCS coordinates. The Prompt parameter specifies a string that AutoCAD displays before it pauses. Both Point and Prompt are optional.

The AutoCAD user can specify the distance by entering a number in the current units format. The user can also set the distance by specifying two locations on the graphics screen. AutoCAD draws a rubber-band line from the first point to the current crosshair position to help the user visualize the distance. If the Point parameter is provided, AutoCAD uses this value as the first of the two points.

By default, GetDistance treats Point and the return value as three-dimensional points. A prior call to the InitializeUserInput method can force Point to be two-dimensional, ensuring that this method returns a planar distance.

Regardless of the method used to specify the distance or the current linear units (for example, feet and inches), this method always sets the return value to a double-precision floating-point value.

Examples

VBA:

Sub Example_GetDistance()
    ' This example returns the distance entered by the user.
     
    AppActivate ThisDrawing.Application.Caption
       
    Dim returnDist As Double
    Dim basePnt(0 To 2) As Double
    basePnt(0) = 0#: basePnt(1) = 0#: basePnt(2) = 0#
    
    ' Return the value entered by user. A prompt is provided.
    returnDist = ThisDrawing.Utility.GetDistance(, "Enter distance: ")
    MsgBox "The distance entered was " & returnDist & vbCrLf & _
            "(Enter the next value without prompting.)", , "GetDistance Example"
    
    ' Return the value entered by user. No prompt is provided.
    returnDist = ThisDrawing.Utility.GetDistance()
    MsgBox "The distance entered was " & returnDist, , "GetDistance Example"
    
    ' Return the value entered by user. A base point and prompt are provided.
    returnDist = ThisDrawing.Utility.GetDistance(basePnt, "Enter a distance: ")
    MsgBox "The distance entered was " & returnDist, , "GetDistance Example"
    
End Sub

Visual LISP:

(vl-load-com)
(defun c:Example_GetDistance()
    ;; This example returns the distance entered by the user.
    (setq acadObj (vlax-get-acad-object))
    (setq doc (vla-get-ActiveDocument acadObj))
  
    ;; Return the value entered by user. A prompt is provided.
    (setq returnDist (vla-GetDistance (vla-get-Utility doc) nil "Enter distance: "))
    (alert (strcat "The distance entered was " (rtos returnDist 2) "\n"
            "(Enter the next value without prompting.)"))
    
    ;; Return the value entered by user. No prompt is provided.
    (setq returnDist (vla-GetDistance (vla-get-Utility doc)))
    (alert (strcat "The distance entered was " (rtos returnDist 2)))
    
    ;; Return the value entered by user. A base point and prompt are provided.
    (setq basePnt (vlax-3d-point 0 0 0))
    (setq returnDist (vla-GetDistance (vla-get-Utility doc) basePnt "Enter a distance: "))
    (alert (strcat "The distance entered was " (rtos returnDist 2)))
)