The GetXXX Methods

The GetXXX methods get specific types of data from the user. These methods make AutoCAD pause until the user supplies a value at the command prompt or picks a point in the drawing window. If the user supplies the wrong type of data, such as typing a string when a number is needed, AutoCAD displays a message at the command prompt that tells them to reenter the data.

The GetKeyword Method

The GetKeyword method gets a command line option from the user. You must call InitializeUserInput to establish the list of keywords before you use this method. It returns the keyword the user entered exactly as the keyword list specified it. If you want, you can include a prompt to display on the command line while the function waits for user input. This method has the following syntax:

strUserKeyWordInput = Object.GetKeyword([Prompt])

This method's Prompt parameter is a string that contains the prompt to display on the command line.

If the user tries to enter a string that's not in the keyword list, AutoCAD displays the error message Invalid option keyword in the command window. AutoCAD then tries to get valid user input by redisplaying the prompt if you specified one or by displaying a blank command line if you didn't. If you allow null input, the user can press Enter to return an empty string.

This example asks the user for an option and then starts the specified command, using the SendCommand method outlined in Appendix A:

Sub TestGetKeyword() Dim strInput As String

With ThisDrawing.Utility

.InitializeUserInput 0, "Line Arc Circle" strInput = .GetKeyword(vbCr & "Command [Line/Arc/Circle]: ") End With

Select Case strInput

Case "Line": ThisDrawing.SendCommand "_Line" & vbCr Case "Arc": ThisDrawing.SendCommand "_Arc" & vbCr Case "Circle": ThisDrawing.SendCommand "_Circle" & vbCr Case Else: MsgBox "You pressed Enter."

End Select

End Sub

The GetString Method

The GetString method gets string values from the user. AutoCAD pauses until the user enters a value. This method has the following syntax:

dblUserStringInput = UtilityObject.GetString(HasSpaces[ ,Prompt]) Table 7-3 lists this method's parameters.

Table 7-3. The GetString Method's Parameters

Name

Type

Description

HasSpaces

Boolean

Specifies whether the user input may contain spaces. If set to True, spaces are valid, and the user must press Enter to terminate the input. If set to False, spaces are not allowed, and the user can terminate the input either by pressing Enter or by entering a space.

Prompt

String

An optional parameter used to display a prompt for input.

This example gets a string from the user, including spaces, and then displays it:

Public Sub TestGetString() Dim strInput As String

With ThisDrawing.Utility strInput = .GetString(True, vbCr & "Enter a string: ") .Prompt vbCr & "You entered '" & strInput & "' " End With End Sub

This method lets the user enter up to 132 characters. Entering more than 132 characters generates the error Method 'GetString' of object 'IAcadUtility' failed, which is unfortunately the same description reported when a user issues a Cancel or Esc. If you need to distinguish between the overflow and the Cancel for this method, consider using the unique exception number instead of the description.

The Getlnteger Method

The GetInteger method gets an integer from the user. AutoCAD waits for the user to input an integer and returns the entered value. This method has the following syntax:

intUserIntegerInput = UtilityObject.GetInteger([Prompt])

This method has one parameter, Prompt, a string. Optionally use it to specify a prompt for input.

The user may enter either an integer in the range -32,768 to +32,767 or a keyword (see "The GetInput Method" later in the chapter for more information). If the user tries to enter any other value, AutoCAD returns the error message Requires an integer value or option keyword and asks the user to enter another value. Here's an example of GetInteger:

Public Sub TestGetInteger() Dim intInput As Integer

With ThisDrawing.Utility intInput = .GetInteger(vbCr & "Enter an integer: ") .Prompt vbCr & "You entered " & intInput End With End Sub

This method throws exceptions for null input, keyword entry, and canceled input.

The GetReal Method

The GetReal method is similar to GetInteger but gets floating-point numbers. It returns a value of data type Double.

dblUserRealInput = UtilityObject.GetReal([Prompt])

This method's Prompt parameter, a string, is optional. Use it to specify a prompt for input.

This method accepts any real (double-precision floating-point) value or any previously set keyword. For more about these keywords, see "The GetInput Method" later in this chapter. If the user enters any other value, AutoCAD returns the error message Requires numeric value and asks the user to enter another value. This example retrieves and displays a real value from the user:

Public Sub TestGetReal() Dim dblInput As Double

With ThisDrawing.Utility dblInput = .GetReal(vbCrLf & "Enter an real: ") .Prompt vbCr & "You entered " & dblInput End With End Sub

This method raises an exception for null input, keyword entry, and canceled input.

The GetPoint Method

The GetPoint method gets a point from the user, either by typing coordinates at the command prompt or by picking points in the drawing area. The return value is a Variant data type and contains a three-element array of doubles holding the point's World Coordinate System (WCS) coordinates. This method has the following syntax:

varUserPointInput = UtilityObject.GetPoint([BasePoint] [,Prompt])

Table 7-4 explains this method's parameters.

Table 7-4. The GetPoint Method's Parameters

Name

Type

Description

BasePoint

Variant

Optional. A three-element array of doubles that specifies an angle vector's first point in WCS.

Prompt

String

Optional. A prompt for input.

The optional BasePoint parameter sets a rubber-band line's start point. This line, which extends to the current crosshair position, can be a useful visual aid to the user during input. This example gets a point from the user and displays its coordinate values:

Public Sub TestGetPoint() Dim varPick As Variant

With ThisDrawing.Utility varPick = .GetPoint(, vbCr & "Pick a point: ") .Prompt vbCr & varPick(0) & "," & varPick(1) End With End Sub

This method raises exceptions for null input, keyword entry, and canceled input.

The GetCorner Method

Given a base point in a rectangle, the GetCorner method gets the diagonally opposing corner point. It returns a Variant data type and contains a three-element array of doubles showing the corner point's WCS coordinates. This method has the following syntax:

varUserCornerInput = UtilityObject.GetCorner(BasePoint [,Prompt])

Table 7-5 explains this method's parameters.

Table 7-5. The GetCorner Method's Parameters

Name

Type

Description

BasePoint

Variant

A three-element array of doubles specifying the rectangle's first corner

in WCS.

Prompt

String

Optional. A prompt for input.

If the user picks a point on the graphic screen, the GetCorner method ignores the point's Z-coordinate and sets it to the current elevation. This example gets a point and then a corner from the user and displays the rectangle's values:

Public Sub TestGetCorner() Dim varBase As Variant Dim varPick As Variant

With ThisDrawing.Utility varBase = .GetPoint(, vbCr & "Pick the first corner: ") .Prompt vbCrLf & varBase(0) & "," & varBase(1) varPick = .GetCorner(varBase, vbLf & "Pick the second: ") .Prompt vbCr & varPick(0) & "," & varPick(1) End With End Sub

This method throws exceptions for null input, keyword entry, and canceled input.

The GetDistance Method

The GetDistance method gets a double from the user. It differs from GetReal in that the user can either type a distance in the current units format or pick the point(s) on the graphics screen. These two methods are otherwise similar, and most people prefer GetDistance because it's more flexible. This method has the following syntax:

dblUserDistanceInput = UtilityObject.GetDistance([BasePoint] [,Prompt]) Table 7-6 explains this method's parameters.

Table 7-6. The GetDistance Method's Parameters

Name

Type

Description

BasePoint

Variant

Optional. A three-element array of doubles specifying a start point from which to begin measuring (in WCS). If you don't provide this parameter, the user must specify two points.

Prompt

String

Optional. A prompt for input.

■ Note This method lets you enter a negative number at the command prompt and returns this negative number. But it calculates the absolute distance between points if you enter it on the graphics screen.

If the user chooses to pick points from the screen, AutoCAD draws a rubber-band line as a visual aid from the base point, or first pick point, to the current crosshair position. By default, the points are 3-D. You may force AutoCAD to calculate a planar distance by first calling InitializeUserInput with a bit code of 16 in OptionBits. This makes AutoCAD ignore the Z-coordinates.

This example code sets the base point to the origin of WCS, prompts the user for input, and then displays the value:

Public Sub TestGetDistance() Dim dblInput As Double Dim dblBase(2) As Double dblBase(0) = 0: dblBase(1) = 0: dblBase(2)

With ThisDrawing.Utility dblInput = .GetDistance(dblBase, vbCr & .Prompt vbCr & "You entered " & dblInput End With End Sub

This method raises an exception for null input, keyword entry, and canceled input.

The GetAngle Method

Use the GetAngle to get an angle, in radians, from the user. The user may either type the angle at the command prompt or pick point(s) on the screen. VBA ignores the points' Z-coordinates. It measures the angle counterclockwise with respect to the ANGBASE system variable's current value. This method has the following syntax:

dblUserAngleInput = UtilityObject.GetAngle([BasePoint] [,Prompt])

"Enter a distance: ")

Table 7-7 explains this method's parameters.

Table 7-7. The GetAngle Method's Parameters

Name

Type

Description

BasePoint

Variant

Optional. A three-element array of doubles specifying an angle vector's first point in WCS. If not provided, the user must specify two points to specify the angle on the graphics screen.

Prompt

String

Optional. A prompt for input.

This method returns the angle in radians regardless of the current setting of the DIMAUNIT angular units system variable or the angular unit type the user entered. In this way, it acts in a similar manner to the Utility object's AngleToReal conversion method.

This example sets the angular units to degrees and then retrieves and displays an angle from the user:

Public Sub TestGetAngle() Dim dblInput As Double

ThisDrawing.SetVariable "DIMAUNIT", acDegrees

With ThisDrawing.Utility dblInput = .GetAngle(, vbCr & "Enter an angle: ") .Prompt vbCr & "Angle in radians: " & dblInput End With End Sub

This method throws exceptions for null input, keyword entry, and canceled input.

The GetOrientation Method

The GetOrientation method is similar to GetAngle, except that the angle returned is always measured from the east, or three o'clock, regardless of the ANGBASE system variable setting. This method has the following syntax:

dblUserOrientationInput = UtilityObject.GetOrientation([BasePoint] [,Prompt]) Table 7-8 explains this method's parameters.

Table 7-8. The GetOrientation Method's Parameters

Name

Type

Description

BasePoint

Variant

Optional. A three-element array of doubles specifying an angle vector's first point in WCS. If not provided, the user must specify two points if they want to specify the angle on the graphics screen.

Prompt

String

Optional. A prompt for input.

This method throws an exception for both null input and keyword entry if allowed and supplied.

The Getlnput Method

As mentioned in the discussion of GetKeyword, you can use seven other input methods in conjunction with the keywords set using InitializeUserInput:

• GetInteger

• GetDistance

• GetOrientation

When these methods have keywords and they are executed, the user can enter the data type requested or choose one of the available keywords. Because each of these input methods returns a specific data type, each can't also return the keyword string. Instead, the input methods use an exception with the description User input is a keyword to signal the presence of a keyword. Unless null input is disabled, VBA uses this same exception to indicate null input, such as when the user simply presses Enter at the input prompt.

Your code must handle the exception, or the program will stop and display an error message. After detecting this exception, use GetInput to retrieve the keyword before calling any other GetXXX method. The GetInput method takes no parameters. It returns either a string containing the keyword in InitializeUserInput or an empty string in the case of null input.

StrUserKeywordInput = UtilityObject.GetInput()

As shown in the previous examples, it is not necessary to call the GetInput method after the GetXXX methods when no keywords are offered to the user. If called independently, this method returns an empty string.

The following code retrieves either an integer or a keyword from the user. It uses GetInteger to demonstrate the GetInput method, but the technique is identical for each of the six other input methods:

Public Sub TestGetInput() Dim intInput As Integer Dim strInput As String

On Error Resume Next ' handle exceptions inline

With ThisDrawing.Utility strInput = .GetInput() .InitializeUserInput 0, "Line Arc Circle"

intInput = .GetInteger(vbCr & "Integer or [Line/Arc/Circle]: ")

If Err.Description Like "*error*" Then

.Prompt vbCr & "Input Cancelled" ElseIf Err.Description Like "*keyword*" Then strInput = .GetInput() Select Case strInput

Case "Line": ThisDrawing.SendCommand "_Line" & vbCr Case "Arc": ThisDrawing.SendCommand "_Arc" & vbCr Case "Circle": ThisDrawing.SendCommand "_Circle" & vbCr Case Else: .Prompt vbCr & "Null Input entered" End Select

Else

.Prompt vbCr & "You entered " & intInput End If End With

End Sub

This example first sets the keywords using InitializeUserInput and then uses an input method to get the user's input. Because the code sets keywords, the input method either returns an integer or throws an exception when the user enters a keyword. If there was an exception and it contains the word error, this code displays a cancel message. Otherwise, if the exception contains the word keyword, the code uses GetInput to retrieve the keyword and takes an appropriate action based on the keyword. If no exception was thrown, this code uses the Integer value the GetInteger method returned.

A bug causes GetInput to return the keyword from earlier calls to InitializeUserInput when the user enters null input at a later input method that takes keywords. The following code demonstrates the problem. Choose any option at the first input prompt and then press Enter for the second input. In case the user enters a keyword, the second call to GetInput should return a null—but instead it returns the keyword you selected in the previous input.

Public Sub TestGetInputBug()

On Error Resume Next ' handle exceptions inline

With ThisDrawing.Utility

'' first keyword input .InitializeUserInput 1, "Alpha Beta Ship" .GetInteger vbCr & "Option [Alpha/Beta/Ship]: " MsgBox "You entered: " & .GetInput()

'' second keyword input - hit Enter here .InitializeUserInput 0, "Bug May Slip" .GetInteger vbCr & "Hit enter [Bug/May/Slip]: " MsgBox "GetInput still returns: " & .GetInput() End With End Sub

Because null and keyword input throw the same exceptions, GetInput's return value is the only way to determine which the user entered. But because of this odd persistence of the previous keyword entry, no sure way exists to determine whether the user entered a keyword or nothing at all.

The following code demonstrates a partial workaround for this problem. The technique is to grab the existing keyword from GetInput before calling InitializeUserInput for the second GetXXX method. If, after getting input from the user, the newly entered keyword matches the previous keyword, it's possible that the user entered a null.

Public Sub TestGetInputWorkaround() Dim strBeforeKeyword As String Dim strKeyword As String

On Error Resume Next ' handle exceptions inline

With ThisDrawing.Utility

'' first keyword input .InitializeUserInput 1, "This Bug Stuff" .GetInteger vbCrLf & "Option [This/Bug/Stuff]: " MsgBox "You entered: " & .GetInput()

'' get lingering keyword strBeforeKeyword = .GetInput()

'' second keyword input - press Enter .InitializeUserInput 0, "Make Life Rough" .GetInteger vbCrLf & "Hit enter [Make/Life/Rough]: " strKeyword = .GetInput()

'' if input = lingering, it might be null input If strKeyword = strBeforeKeyword Then

MsgBox "Looks like null input: " & strKeyword

Else

MsgBox "This time you entered: " & strKeyword End If End With

End Sub

The GetEntity Method

Use the GetEntity method to select an AutoCAD object by letting the user pick an entity from the graphics screen.

■ Note Because the user may type L for the last entity in the drawing window, this method can return an invisible entity or an entity that's on a frozen layer. However, in 2005 and 2006, AutoCAD will select the last visible entity.

This method has the following syntax: UtilityObject.GetEntity PickedEntity, PickedPoint[, Prompt] Table 7-9 explains this method's parameters.

Table 7-9. TheGetEntity Method's Parameters

Name

Type

Description

PickedEntity

AcadEntity object

Output. Returns a reference to the drawing object that the user picked.

Output. A three-element array of doubles that specifies the point by which the entity was picked in WCS.

Optional. A prompt for input.

PickPoint

Variant

Prompt

String

This example gets an entity from the user and displays the point's object type and coordinates:

Public Sub TestGetEntity() Dim objEnt As AcadEntity Dim varPick As Variant

On Error Resume Next

With ThisDrawing.Utility

.GetEntity objEnt, varPick, vbCr & "Pick an entity: " If objEnt Is Nothing Then 'check if object was picked. .Prompt vbCrLf & "You did not pick as entity" Exit Sub End If

.Prompt vbCr & "You picked a " & objEnt.ObjectName .Prompt vbCrLf & "At " & varPick(0) & "," & varPick(1) End With End Sub

GetEntity raises an error if the input is null, such as when there is no entity at the picked point, or if the user presses Enter without selecting an entity. The example checks for this condition to avoid the error.

The GetSubEntity Method

Use the GetSubEntity method in place of GetEntity when you need to obtain subentity information based on the user's selection. A subentity is an entity that another entity contains, such as an entity in a block or a vertex entity contained in polylines. This method lets the user pick an entity or subentity from the graphics screen and returns details about that entity and any object that contains it.

■ Note Like GetEntity, this method can return an entity even if it is not currently visible or is on a frozen layer because the user can type L to select the last entity in the drawing window. However, in 2005 and 2006, AutoCAD will select the last visible entity.

This method has the following syntax: UtilityObject.GetSubEntity PickedEntity, PickPoint, Matrix, Context[, Prompt] Table 7-10 explains this method's parameters.

Table 7-10. TheGetSubEntity Method's Parameters

Name

Type

Description

PickedEntity

PickPoint

Matrix

Context

Prompt

AcadEntity object

Variant

Variant

Variant

String

Output. Returns a reference to the drawing object that the user picked.

Output. A three-element array of doubles that specifies an angle vector's first point in WCS.

Output. Returns a four-by-four element array of doubles that holds the selected entity's translation matrix.

Output. Returns an array of long integers holding the ObjectIds for each parent block containing the selected entity, if the entity is in a block.

Optional. A prompt for input.

The Matrix output parameter is the selected entity's Model to World Transformation Matrix. It is a composite of all the transformations involved in the entity's visible representation. Imagine a line stored in a block, which is also stored in a block. The Matrix output parameter encapsulates each scale, rotation, and translation involved in the nested line's display. You can use it to translate points from the internal Model Coordinate System (MCS) to WCS.

The Context output parameter is an array of the ObjectIds for any objects that contain the selected entity. For the example line, this would be an array of two ObjectIds, one for each nesting level of the containing blocks. To get information about each containing entity, use the ObjectIdToObject method of the Document object to convert the ObjectId to an object reference.

The following example uses the Prompt method to display information about the selected entity and any containing entities. Try it on a variety of entities, including those nested in blocks.

Public Sub TestGetSubEntity() Dim objEnt As AcadEntity Dim varPick As Variant Dim varMatrix As Variant Dim varParents As Variant Dim intI As Integer Dim intJ As Integer Dim varID As Variant

With ThisDrawing.Utility

'' get the subentity from the user

.GetSubEntity objEnt, varPick, varMatrix, varParents, _ vbCr & "Pick an entity: "

'' print some information about the entity .Prompt vbCr & "You picked a " & objEnt.ObjectName .Prompt vbCrLf & "At " & varPick(0) & "," & varPick(1)

'' dump the varMatrix

If Not IsEmpty(varMatrix) Then

.Prompt vbLf & "MCS to WCS Translation varMatrix:"

'' format varMatrix row For intI = 0 To 3

'' format varMatrix column For intJ = 0 To 3

.Prompt "(" & varMatrix(intI, intJ) & ")" Next intJ

.Prompt "]" Next intI .Prompt vbLf End If

'' if it has a parent nest If Not IsEmpty(varParents) Then

.Prompt vbLf & "Block nesting:"

'' traverse most to least deep (reverse order)

For intJ = UBound(varParents) To LBound(varParents) Step -1

'' indent output

'' parent object ID varID = varParents(intJ)

'' parent entity

Set objEnt = ThisDrawing.ObjectIdToObject(varID)

'' print info about parent

.Prompt objEnt.ObjectName & " : " & objEnt.Name Next intJ .Prompt vbLf End If .Prompt vbCr End With End Sub

GetSubEntity throws an exception if the input is null, such as when there is no entity at the picked point or when the user presses Enter without selecting an entity.

Figure 7-3 shows the result of picking a line that forms part of a block reference named Window.

Figure 7-3. The TestGetSubEntity command line output

Was this article helpful?

0 0

Post a comment