AttachExternalReference Method (ActiveX)

Attaches an external reference (xref) to the drawing.

Supported platforms: Windows only

Signature

VBA:

RetVal = object.AttachExternalReference(PathName, Name, InsertionPoint, XScale, YScale, ZScale, Rotation, Overlay [, Password])

object

Type: Block, ModelSpace, PaperSpace

The objects this method applies to.

PathName

Access: Input-only

Type: String

The full path and file name of the drawing to be referenced.

Name

Access: Input-only

Type: String

The name for the xref to be created.

InsertionPoint

Access: Input-only

Type: Variant (three-element array of Doubles)

The 3D WCS coordinates specifying the point at which an ExternalReference instance is inserted into the drawing. The insertion point in the current drawing is aligned with the point defined by the AutoCAD BASE system variable in the referenced file.

XScale

Access: Input-only

Type: Double

The X scaling factor for the xref instance.

YScale

Access: Input-only

Type: Double

The Y scaling factor for the xref instance.

ZScale

Access: Input-only

Type: Double

The Z scaling factor for the xref instance.

Rotation

Access: Input-only

Type: Double

The rotation angle for the xref instance. This angle is specified in radians.

Overlay

Access: Input-only

Type: Boolean

• True: The xref instance is an overlay.
• False: The xref instance is an attachment.

Password

Access: Input-only; optional

Type: Variant

; optional

Return Value (RetVal)

Type: ExternalReference

The newly created ExternalReference object.

Remarks

Like Block objects, attached ExternalReference objects can be nested. If another person is editing the drawing to be referenced, the drawing attached is based on the most recently saved version.

If the referenced file is missing or corrupt, its data is not displayed in the current drawing.

Examples

VBA:

Sub Example_AttachExternalReference()
    ' This example displays all the blocks in the current drawing
    ' before and after adding an external reference.
    '
    ' This example uses the "city map.dwg" found in the Sample
    ' directory. If you do not have this drawing, or if it is 
    ' in a different directory, insert a valid path and file name
    ' for the PathName variable below.
    
    Dim InsertPoint(0 To 2) As Double
    Dim insertedBlock As AcadExternalReference
    Dim tempBlock As AcadBlock
    Dim msg As String, PathName As String
    
    ' Define external reference to be inserted
    InsertPoint(0) = 1: InsertPoint(1) = 1: InsertPoint(2) = 0
    PathName = "c:\program files\autocad\sample\city map.dwg"
    
    ' Display current Block information for this drawing
    GoSub ListBlocks
    
    ' Add the external reference to the drawing
    Set insertedBlock = ThisDrawing.ModelSpace.AttachExternalReference(PathName, "XREF_IMAGE", InsertPoint, 1, 1, 1, 0, False)
        
    ThisDrawing.Application.ZoomAll
    
    ' Display new Block information for this drawing
    GoSub ListBlocks
    
    Exit Sub

ListBlocks:
    msg = vbCrLf    ' Reset message
    
    For Each tempBlock In ThisDrawing.Blocks
        msg = msg & tempBlock.name & vbCrLf     ' Add Block to list
    Next
    
    MsgBox "The current blocks in this drawing are: " & msg
    
    Return
End Sub

Visual LISP:

(vl-load-com)
(defun c:Example_AttachExternalReference()
    ;; This example displays all the blocks in the current drawing
    ;; before and after adding an external reference.
    ;;
    ;; This example uses the "STAIR1.dwg" found in the Sample
    ;; directory. If you do not have this drawing, or if it is 
    ;; in a different directory, insert a valid path and file name
    ;; for the PathName variable below.
    (setq acadObj (vlax-get-acad-object))
    (setq doc (vla-get-ActiveDocument acadObj))
    
    ;; Define external reference to be inserted
    (setq InsertPoint (vlax-3d-point 1 1 0))
    (setq pathName (findfile ".\\Sample\\Sheet Sets\\Architectural\\Res\\STAIR1.dwg"))
    
    ;; Display current Block information for this drawing
    (setq msg "")
    (vlax-for tempBlock (vla-get-Blocks doc)
        (setq msg (strcat msg (vla-get-Name tempBlock) "\n"))     ;; Add Block to list
    )
    
    (alert (strcat "The current blocks in this drawing are: " msg))
    
    ;; Add the external reference to the drawing
    (setq modelSpace (vla-get-ModelSpace doc))  
    (setq insertedBlock (vla-AttachExternalReference modelSpace pathName "XREF_IMAGE" InsertPoint 1 1 1 0 :vlax-false))
        
    (vla-ZoomAll acadObj)
    
    ;; Display new Block information for this drawing
    (setq msg "")
    (vlax-for tempBlock (vla-get-Blocks doc)
        (setq msg (strcat msg (vla-get-Name tempBlock) "\n"))     ;; Add Block to list
    )
    
    (alert (strcat "The current blocks in this drawing are: " msg))
)